How to use the command 'envsubst' (with examples)

The command envsubst is a powerful tool used to replace environment variables within shell format strings. This command reads input, typically from a file or standard input, processes the content to substitute environment variable placeholders with their actual values, and writes the output to standard output or a specified file. Variables intended for substitution must be specified in either ${var} or $var format. This tool is particularly useful in scripting and automation tasks where dynamic content generation is essential. envsubst is part of the GNU gettext package, offering handy functionality for anyone who deals with configuration files or scripts that require dynamic environmental configuration.

Use case 1: Replacing environment variables in stdin and output to stdout

Code:

echo '$HOME' | envsubst

Motivation:

In many scenarios, especially when running on different machines or environments, the actual path for a user’s home directory is required. This command is handy when you want a quick inline substitution without writing to a file. For example, when displaying configuration information or generating dynamic prompts in shell scripts.

Explanation:

• echo '$HOME': This command outputs the literal string $HOME to the standard output (stdout). The single quotes ensure that $HOME is not interpolated by the shell, but rather passed as-is to envsubst.
• |: This pipe operator takes the output from the left-hand side command (echo) and feeds it as input to the right-hand side command (envsubst).
• envsubst: This command takes the piped input, looks for any environment variable placeholders (e.g., $HOME), and substitutes them with their current values.

Example Output:

If the environment variable HOME is /home/user, the above command might output:

/home/user

Use case 2: Replacing environment variables in an input file and output to stdout

Code:

envsubst < path/to/input_file

Motivation:

When dealing with configuration files containing placeholders for environment variables, it is often necessary to convert these placeholders to their respective values. For instance, deploying applications often involves updating configuration templates to reflect the actual environment.

Explanation:

• envsubst: Invokes the environment substitution command.
• < path/to/input_file: The input redirection operator < feeds the content of path/to/input_file into envsubst. This file typically contains text with placeholders like $VAR_NAME, which will be replaced by their environment variable values.

Example Output:

Consider an input file containing:

Home directory is: $HOME

If the HOME environment variable is set to /home/user, the output will be:

Home directory is: /home/user

Use case 3: Replacing environment variables in an input file and output to a file

Code:

envsubst < path/to/input_file > path/to/output_file

Motivation:

This use case is ideal when generating configuration files that require persistent storage. For example, when preparing a configuration file for a service that will start automatically on boot, it’s beneficial to hard-code the required values into an output file.

Explanation:

• envsubst: Starts the substitution process for environment variables.
• < path/to/input_file: Redirects the input file’s contents to envsubst.
• > path/to/output_file: Redirects the processed output to a specified file, making it persistent and allowing it to be used later by other applications or scripts.

Example Output:

Given an input file with:

Shell used is: $SHELL

And the environment variable SHELL set to /bin/bash, the content of output_file will be:

Shell used is: /bin/bash

Use case 4: Replacing environment variables in an input file from a space-separated list

Code:

envsubst '$USER $SHELL $HOME' < path/to/input_file

Motivation:

There are times when only a specific set of environment variables need to be processed, such as when working with partial templates or when securing information by selectively substituting variables. This selective substitution allows greater control over which environment variables are replaced.

Explanation:

• envsubst '$USER $SHELL $HOME': This specific invocation of envsubst takes an additional argument specifying which variables should be substituted. The variables are listed in a space-separated manner within quotes.
• < path/to/input_file: Directs the contents of the input file to the envsubst command for processing.

Example Output:

For an input file containing:

User: $USER
Directory: $HOME
NonSubbed: $VARIABLE
Default Shell: $SHELL

And the environment variables USER, SHELL, and HOME are respectively set to john, /bin/bash, and /home/john. The substitution will reflect these changes:

User: john
Directory: /home/john
NonSubbed: $VARIABLE
Default Shell: /bin/bash

Conclusion:

The envsubst command is a versatile tool for scriptwriters and system administrators who need to generate dynamic, environment-specific configurations or scripts. Each use case demonstrates a practical application for substituting environment variables, whether the goal is quick inline replacement, processing configuration templates, or managing environment specifics across different deployment scenarios. By understanding and utilizing these examples, one can efficiently tackle diverse automation and configuration challenges.