Externally Sourced Configuration File Values
On this page
- Use the
__rest
Expansion Directive - Use the
__exec
Expansion Directive - Expansion Directives Reference
- Output the Configuration File with Resolved Expansion Directive Values
New in version 4.2.
MongoDB supports using expansion directives in configuration files to load externally sourced values. Expansion directives can load values for specific configuration file options or load the entire configuration file. Expansion directives help obscure confidential information like security certificates and passwords.
copycopied
storage:
dbPath: "/var/lib/mongo"
systemLog:
destination: file
path: "/var/log/mongodb/mongod.log"
net:
bindIp:
__exec: "python /home/user/getIPAddresses.py"
type: "string"
trim: "whitespace"
digest: 85fed8997aac3f558e779625f2e51b4d142dff11184308dc6aca06cff26ee9ad
digest_key: 68656c6c30303030307365637265746d796f6c64667269656e64
tls:
mode: requireTLS
certificateKeyFile: "/etc/tls/mongod.pem"
certificateKeyFilePassword:
__rest: "https://myrestserver.example.net/api/config/myCertKeyFilePassword"
type: "string"
digest: b08519162ba332985ac18204851949611ef73835ec99067b85723e10113f5c26
digest_key: 6d795365637265744b65795374756666
- If the configuration file includes the
__rest
expansion, on Linux/macOS, the read access to the configuration file must be limited to the user running themongod
/mongos
process only. - If the configuration file includes the
__exec
expansion, on Linux/macOS, the write access to the configuration file must be limited to the user running themongod
/mongos
process only.
To use expansion directives, you must specify the --configExpand
command-line option with the complete list of expansion directives used:
copycopied
mongod --config "/path/to/config/mongod.conf" --configExpand "rest,exec"
If you omit the --configExpand
option or if you do not specify the complete list of expansion directives used in the configuration file, the mongod
/mongos
returns an error and terminates. You can only specify the --configExpand
option on the command line.
Use the __rest
Expansion Directive
The __rest
expansion directive loads configuration file values from a REST
endpoint. __rest
supports loading specific values in the configuration file or loading the entire configuration file.
- Specific Value
- Full Configuration File
The following configuration file uses the __rest
expansion directive to load the setting net.tls.certificateKeyFilePassword
value from an external REST
endpoint:
copycopied
storage:
dbPath: "/var/lib/mongo"
systemLog:
destination: file
path: "/var/log/mongodb/mongod.log"
net:
bindIp: 192.51.100.24,127.0.0.1
tls:
mode: requireTLS
certificateKeyFile: "/etc/tls/mongod.pem"
certificateKeyFilePassword:
__rest: "https://myrestserver.example.net/api/config/myCertKeyFilePassword"
type: "string"
File Permission
If the configuration file includes the
__rest
expansion, on Linux/macOS, the read access to the configuration file must be limited to the user running themongod
/mongos
process only.Expansion Parsing
To parse the
__rest
blocks, start themongod
/mongos
with the--configExpand "rest"
option.Themongod
/mongos
issues aGET
request against specified URL. If successful, themongod
/mongos
replaces the value ofcertificateKeyFilePassword
with the returned value. If the URL fails to resolve or if theREST
endpoint returns an invalid value, themongod
/mongos
throws an error and terminates.
IMPORTANT
The value returned by the specified REST
endpoint cannot include any additional expansion directives. The mongod
/mongos
does not perform additional processing on the returned data and will terminate with an error code if the returned data includes additional expansion directives.
Use the __exec
Expansion Directive
The __exec
expansion directive loads configuration file values from a shell or terminal command. __exec
supports loading specific values in the configuration file or loading the entire configuration file.
- Specific Value
- Full Configuration File
The following example configuration file uses the __exec
expansion directive to to load the setting net.tls.certificateKeyFilePassword
value from the output of a shell or terminal command:
copycopied
storage:
dbPath: "/var/lib/mongo"
systemLog:
destination: file
path: "/var/log/mongodb/mongod.log"
net:
bindIp: 192.51.100.24,127.0.0.1
TLS:
mode: requireTLS
certificateKeyFile: "/etc/tls/mongod.pem"
certificateKeyFilePassword:
__exec: "python /home/myUserName/getPEMPassword.py"
type: "string"
File Permission
If the configuration file includes the
__exec
expansion, on Linux/macOS, the write access to the configuration file must be limited to the user running themongod
/mongos
process only.Expansion Parsing
To parse the
__exec
blocks, start themongod
/mongos
with the--configExpand "exec"
option.Themongod
/mongos
attempts to execute the specified operation. If the command executes successfully, themongod
/mongos
replaces the value ofcertificateKeyFilePassword
with the returned value. If the command fails or returns an invalid value for the configuration file setting, themongod
/mongos
throws an error and terminates.
IMPORTANT
The data returned by executing the specified __exec
string cannot include any additional expansion directives. The mongod
/mongos
does not perform additional processing on the returned data and will terminate with an error code if the returned data includes additional expansion directives.
Expansion Directives Reference
__rest
The
__rest
expansion directive loads configuration file values from aREST
endpoint.__rest
supports loading specific values in the configuration file or loading the entire configuration file. Themongod
/mongos
then starts using the externally sourced values as part of its configuration.The__rest
expansion directive has the following syntax:To specify aREST
endpoint for a specific configuration file setting or settings:copycopied<some configuration file setting>: __rest: "<string>" type: "string" trim: "none|whitespace" digest: "<string>" digest_key: "<string>"
To specify aREST
endpoint for the entire configuration file:copycopied__rest: "<string>" type: "yaml" trim: "none|whitespace"
If specifying the entire configuration file viaREST
endpoint, the expansion directive and its options must be the only values specified in the configuration file.__rest
takes the following fields:FieldTypeDescription__reststringRequired The URL against which themongod
/mongos
issues aGET
request to retrieve the externally sourced value.For non-localhostREST
endpoints (e.g. aREST
endpoint hosted on a remote server),__rest
requires encrypted (https://
) URLs where both the host machine and the remote server support TLS 1.1 or later.If theREST
endpoint specified in the URL requires authentication, encode credentials into the URL with the standard RFC 3986 User Information format.For localhostREST
endpoints (e.g. aREST
endpoint listening on the host machine),__rest
allows unencrypted (http://
) URLs.IMPORTANTThe value returned by the specifiedREST
endpoint cannot include any additional expansion directives. Themongod
/mongos
does not perform additional processing on the returned data and will terminate with an error code if the returned data includes additional expansion directives.type
stringOptional Controls how__rest
parses the returned value from the specified URL.Possible values are:string
(Default)Directs__rest
to parse the returned data as a literal string. If specifyingstring
, the entire__rest
block and supporting options must be nested under the field for which you are loading externally sourced values.yaml
Directs__rest
to parse the returned data as ayaml
formatted file. If specifyingyaml
, the__rest
block must be the only content in the configuration file. Themongod
/mongos
replaces the configuration file contents with theyaml
retrieved from the REST resource.trim
stringOptional Specifywhitespace
to direct__rest
to trim any leading or trailing whitespace, specifically occurrences of" "
,"\r"
,"\n"
,"\t"
,"\v"
, and"\f"
. Defaults tonone
, or no trimming.digeststringOptional. The SHA-256 digest of the expansion result.If specified, you must also specify the digest_key.digest_keystringOptional. The hexadecimal string representation of the secret used to calculate the SHA-256 digest.If specified, you must also specify the digest.NOTEIf the configuration file includes the__rest
expansion, on Linux/macOS, the read access to the configuration file must be limited to the user running themongod
/mongos
process only.To enable parsing of the__rest
expansion directive, start themongod
/mongos
with the--configExpand "rest"
option.For examples, see Use the __rest Expansion Directive.__exec
The
__exec
expansion directive loads configuration file values from the output of a shell or terminal command.__exec
supports loading specific values in the configuration file or loading the entire configuration file. Themongod
/mongos
then starts using the externally sourced values as part of its configuration.The__exec
expansion directive has the following syntax:To specify a shell or terminal command for a specific configuration file setting or settings:copycopied<some configuration file setting>: __exec: "<string>" type: "string" trim: "none|whitespace"
To specify a a shell or terminal command for the entire configuration file:copycopied__exec: "<string>" type: "yaml" trim: "none|whitespace"
If specifying the entire configuration file via a terminal or shell command, the expansion directive and its options must be the only values specified in the configuration file.__exec
takes the following fields:FieldTypeDescription__exec
stringRequired The string which themongod
/mongos
executes on the terminal or shell to retrieve the externally sourced value.On Linux and OSX hosts, execution is handled via POSIXpopen()
. On Windows hosts, execution is handled via the process control API.__exec
opens a read-only pipe as the same user that started themongod
ormongos
.IMPORTANTThe data returned by executing the specified command cannot include any additional expansion directives. Themongod
/mongos
does not perform additional processing on the returned data and will terminate with an error code if the returned data includes additional expansion directives.type
stringOptional Controls how__exec
parses the value returned by the executed command.Possible values are:string
(Default )Directs__exec
to parse the returned data as a literal string. If specifyingstring
, the entire__exec
block and supporting options must be nested under the field for which you are loading externally sourced values.yaml
Directs__exec
to parse the returned data as ayaml
formatted file. If specifyingyaml
, the__exec
block must be the only content in the configuration file. Themongod
/mongos
replaces the configuration file contents with theyaml
retrieved from the executed command.trim
stringOptional Specifywhitespace
to direct__exec
to trim any leading or trailing whitespace, specifically occurrences of" "
,"\r"
,"\n"
,"\t"
,"\v"
, and"\f"
. Defaults tonone
, or no trimming.digeststringOptional. The SHA-256 digest of the expansion result.If specified, you must also specify the digest_keydigest_keystringOptional. The hexadecimal string representation of the secret used to calculate the SHA-256 digest.If specified, you must also specify the digestNOTEIf the configuration file includes the__exec
expansion, on Linux/macOS, the write access to the configuration file must be limited to the user running themongod
/mongos
process only.To enable parsing of the__exec
expansion directives, start themongod
/mongos
with the--configExpand "exec"
option.For examples, see Use the __exec Expansion Directive.
Output the Configuration File with Resolved Expansion Directive Values
You can test the final output of a configuration file that specifies one or more expansion directives by starting the mongod
/mongos
with the --outputConfig
option. A mongod
/mongos
started with --outputConfig
outputs the resolved YAML configuration document to stdout
and halts. If any expansion directive specified in the configuration file returns additional expansion directives, the mongod
/mongos
throws an error and terminates.
WARNING
The --outputConfig
option returns the resolved values for any field using an expansion directive. This includes any private or sensitive information previously obscured by using an external source for the configuration option.
For example, the following configuration file mongod.conf
contains a __rest
expansion directive:
copycopied
storage:
dbPath: "/var/lib/mongo"
systemLog:
destination: file
path: "/var/log/mongodb/mongod.log"
net:
port:
__rest: "https://mongoconf.example.net:8080/record/1"
type: string
The string recorded at the specified URL is 20128
If the configuration file includes the __rest
expansion, on Linux/macOS, the read access to the configuration file must be limited to the user running the mongod
/mongos
process only.
Start the mongod
with the --configExpand "rest"
and --outputConfig
options:
copycopied
mongod -f mongod.conf --configExpand rest --outputConfig
The mongod
outputs the following to stdout
before terminating:
copycopied
config: mongod.conf
storage:
dbPath: "/var/lib/mongo"
systemLog:
destination: file
path: "/var/log/mongodb/mongod.log"
net:
port: 20128
outputConfig: true