Environment Variables¶

Environment Inheritance¶

Chaperone provides extensive control over environment variables as they are passed from the parent (often the container technology, like Docker), and eventually down to individual services.

Fig. 1 Chaperone Environment Management

As shown in Fig. 1, Chaperone controls the environment at two levels, and with three separate directives:

1. Chaperone creates a “global” settings environment which consists of environment variables inherited from the parent environment, modified by the three environment directives env_inherit, env_set, and env_unset.
2. Each service can further modify the resulting environment using the same directives, and the changes apply only to the environment of the selected service.

In each case, Chaperone processes each set of directives in the same way:

1. The new environment is initialized based upon the setting of env_inherit, a list of patterns. If not specified, Chaperone assumes all environment variables will be inherited.
2. Then, Chaperone sets any new environment variables specified by env_set.
3. Finally, any environment variables specified by env_unset are removed if they exist.

Environment Variable Expansion¶

Environment variable directives (as well as some others), can contain bash-inspired[1] environment variable expansions, as indicated below:

$(ENVVAR) or ${ENVVAR}

Expands to the specified environment variable. If the environment variable is not defined, the expansion text is not replace and will appear as is.

$(ENVVAR:-default)

Inserts the environment variable if it is present, otherwise, expands to the string specified by default (which can be blank).

$(ENVVAR:+ifpresent)

Inserts ifpresent if the environment variable is defined, otherwise inserts the empty string.

$(ENVVAR:_default)

Inserts the empty string if the environment variable is defined, otherwise inserts default. (This is the opposite of the previous :+ operation.)

$(ENVVAR:?error-message)

Inserts the environment variable, or stops Chaperone with the specified error-message if the variable is not defined.

$(ENVVAR:|present-val|absent-val)

If the environment variable is defined, then inserts the expansion of present-val, otherwise inserts the expansion of absent-val.

$(ENVVAR:|check-val|equal|notequal)

Compares the expanded value of ENVVAR to check-val using case-insensitive filename glob matching rules. If they match, then inserts equal otherwise inserts notequal. For example, you can use a match expression of [ty]* to match any value which starts with ‘t’ or ‘y’.

$(ENVVAR:/regex/repl/[i])

Expands the named environment variable, then performs a regular expression substitution using regex with the replacement string repl. If either contains slashes, they must be escaped using a backslash. The optional flags can be set to i if case-insensitive matching is required. Parenthesized groups in regex can be referred to in the replacement as \n where ‘n’ is zero to refer to the entire matched string, or 1-n to specify the group number.

$(`shell-command`)

Executes the specified shell command and inserts the resulting output. Note that the shell command may contain references to other environment variables.

The forms above are patterned after bash and can be useful in cases where defaults are required. For example, if you wanted to specify the user for a service in the event no user was otherwise specified:

sample.service: {
  uid: "$(USER:-www-data)"
  ...
}

The above would expand to the value of USER if it exists, otherwise would expand to www-data. Not all directives support environment expansion. When it is supported, it will be explicitly indicated in the reference documentation for the directive (for example, the service directory directive).

settings: {
  env_set: {
    'MY_NAME': '$(_CHAP_SERVICE)',
    'HAS_NOTIFY_SOCKET': '$(NOTIFY_SOCKET:+1)',
    'PATH': '/service-bins/$(MY_NAME):$(PATH)',
  }
}

Backtick Expansion¶

Chaperone supports backtick expansion similar to most command shells. Backtick expansion can be used wherever environment variables can be used (denoted by the $ENV symbol in the directive documentation). Any valid system command can be included, and the output will be substituted for the backtick expression. For example, to set an environment variable to the default gateway (normally the Docker bridged network):

 settings: {
   env_set: {
     "GATEWAY_IP": "`ip route | awk '/default/ { print $3 }'`"
   }
}

Backtick expansions are not intended to be a general-purpose shell escape, but intended for situations (like the example) where some system information needs to be collected for configuration purposes. Specifically, backtick expansion have the following characteristics:

• Backticks will be processed after all dependent environment variables are expanded.
• Expansions are done only once, even if they are present in multiple locations. Thus, the backtick expression `date` will expand to the same value no matter how many times it is used.
• The environment passed to the backtick command will be the initial chaperone environment before any directives are processed.
• Backtick expansions will be performed as the user specified by the uid and gid relevant to the section where the backtick expansion is used.

However, note that backtick expansions may include references to other environment variables, such as:

settings: {
  env_set: {
    "LOCALDATE": "`TZ=${TZ} date`",
    "TZ": "America/Los_Angeles",
  }

Note in the above that the TZ variable will be expanded first (if necessary) before the backtick expression.

Chaperone also supports a special syntax when backtick expansion is the only desired outcome of a variable insertion. The following two methods are equivalent:

env_set: {
  "HOSTNAME1": "$(`hostname -s`)",
  "HOSTNAME2": "`hostname -s`",
}

This alternate syntax is primarily useful in the envcp utiltiy since backticks are not expanded in bare text as they are within Chaperone directives.