envsubst Command in Linux

The envsubst command, a lesser-known yet powerful utility in Linux, is a true asset for developers and system administrators who frequently deal with shell scripts and configuration files. This command stands out for its ability to substitute environment variables within text files with their actual values, making it an indispensable tool for automating and streamlining workflows.

The envsubst command is a powerful utility for processing templates and configuration files by substituting the values of environment variables.

Here is a comprehensive guide to the options available with the envsubst command −

Understanding envsubst Command in Linux
Syntax of envsubst Command in Linux
Examples of envsubst Command in Linux

Understanding envsubst Command in Linux

The envsubst command is a powerful tool for substituting environment variables within text files. It's particularly useful for creating dynamic configuration files or scripts based on environment-specific values. At its core, envsubst reads a string of text, identifies placeholders for environment variables, and replaces them with the corresponding values.

It's part of the GNU gettext package and is particularly useful when dealing with templates or initialization files that require dynamic content insertion. This command is part of the GNU gettext package and is widely used in scripting and development environments to dynamically update files with environmental data.

Syntax of envsubst Command in Linux

While envsubst doesn't have a plethora of options like many other Linux commands, it does offer a few crucial ones to fine-tune its behavior. At its core, envsubst searches the input for patterns of the form $VARIABLE or ${VARIABLE} and replaces them with the corresponding variable's value. It's important to note that envsubst only recognizes exported variables.

The basic syntax of the command is as follows −

envsubst [OPTION] [SHELL-FORMAT]

Options

No options: Substitutes all environment variables found in the standard input.
-v, --variables=SHELL-FORMAT: Specifies the variables to substitute. This is useful when you only want to replace specific variables.
envsubst primarily operates on standard input and output.
The -v or --variables option provides granular control over variable substitution.
The SHELL-FORMAT argument offers flexibility in specifying variables.

Examples of envsubst Command in Linux

Now, let’s go through some examples to better understand the working of the envsubst command in Linux −

Basic Usage of SHELL-FORMAT
Selective Substitution
Handling Multiple Variables
Specifying Variables
Specifying Variables for Substitution
Reading Input from Standard Input
Writing Output to Standard Output
Handling Unset Variables
Handling Symbolic Links
Complex Variable Substitution
Combining with Other Commands
Substituting All Environment Variables
Configuration File Preparation

Basic Usage of SHELL-FORMAT

The SHELL-FORMAT argument is a string that lists the variables you want to substitute. It uses the same syntax as shell variable references, such as $VARIABLE or ${VARIABLE}.

envsubst < input_file > output_file

This command reads the content of input_file, replaces all occurrences of environment variables (like $VARIABLE or ${VARIABLE}) with their corresponding values, and writes the result to output_file.

Selective Substitution

envsubst allows for selective substitution, where only specified variables are replaced. This is done using the SHELL-FORMAT argument, which takes a pattern list of the variables to be substituted.

Create a template file (config.template) −

sudo nano config.template

DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=my_database

Handling Multiple Variables

You can handle multiple variables by creating a delimited list within the SHELL-FORMAT argument. This flexibility allows for precise control over which variables are substituted and which are left as-is.

Let’s create a configuration file (config.conf) using envsubst −

envsubst < config.template > config.conf

The simplest form of using envsubst is to pipe in a string or file that contains environment variable references. For example −

$ export GREETING="Hello, World!"
$ echo 'The greeting is: $GREETING' | envsubst

This would produce the following output −

Specifying Variables

You can explicitly list the variables to substitute using the -v or --variables option −

envsubst -v HOST PORT < config.template > config.conf

Specifying Variables for Substitution

One of the key features of envsubst is the ability to specify which variables should be substituted. This is done using the SHELL-FORMAT argument, which allows users to list the variables they want to replace. For instance, if you only want to substitute the FOO variable, you would use −

envsubst '$FOO' < input_file

It's crucial to use single quotes around the SHELL-FORMAT to prevent the shell from substituting the variable before envsubst is called.

Reading Input from Standard Input

Instead of a file, you can provide the input directly on the command line −

echo "${USER} lives in ${HOME}" | envsubst

Writing Output to Standard Output

To avoid creating an intermediate file, use redirection −

envsubst < config.template > /etc/myapp/config

Handling Unset Variables

By default, envsubst removes references to unset variables. To keep them, use the --no-unset option −

envsubst --no-unset < config.template > config.conf

Handling Symbolic Links

To prevent following symbolic links, use the --no-symlink option −

envsubst --no-symlink < config.template > config.conf

Complex Variable Substitution

envsubst supports shell-style variable expansion, including −

Default values: $VARIABLE:-default_value
Alternate values: $VARIABLE:=${OTHER_VARIABLE}
Arithmetic expansion: $(( 1 + 2 ))

Combining with Other Commands

You can combine envsubst with other commands for more complex transformations −

envsubst < config.template | sed 's/foo/bar/g' > output.conf

Let's consider a practical example where you have a template file named welcome.txt with the following content −

Hello user $USER in $DESKTOP_SESSION. It's time to say $HELLO!

After exporting the HELLO variable with a value of "good morning" and running envsubst, the output would be −

Hello user joe in Lubuntu. It's time to say good morning!

If you unset the HELLO variable and run envsubst again, the $HELLO pattern would be replaced with an empty string.

Substituting All Environment Variables

To substitute all environment variables found in a file, you can use the following command structure −

envsubst "$(printf '${%s} ' $(env | cut -d'=' -f1))" < config.conf

This command will replace all the environment variables in the input_file with their current values.

Configuration File Preparation

Imagine preparing a configuration file for an application that requires database credentials. You could have a template file with placeholders for DB_USER and DB_PASS, and use envsubst to fill in those values before deploying the application.

The envsubst command also provides options to output the variables occurring in SHELL-FORMAT with the -v or --variables flag.

For help and version information, you can use the -h or --help and -V or --version flags, respectively.

envsubst --help

Conclusion

The envsubst command is a testament to the flexibility and power of the Linux operating system. Its ability to seamlessly integrate environment variables into various files makes it a valuable tool for anyone looking to automate and simplify their system administration and development tasks. By mastering the envsubst command, you can significantly reduce the complexity of managing configurations across different environments and systems.

The envsubst command is a versatile tool that simplifies the process of managing configuration files and templates by allowing dynamic substitution of environment variables. Whether you're a system administrator or a developer, understanding how to effectively use envsubst can streamline your workflows and make your scripts more maintainable.

Print Page