Externally Sourced Configuration File Values

New in version 4.2.

MongoDB supports using expansion directives in configuration filesto load externally sourced values. Expansion directives canload values for specificconfiguration file optionsor load theentire configuration file. Expansion directives help obscureconfidential information like security certificates and passwords.

storage:
  dbPath: "/var/lib/mongod"
systemLog:
  destination: file
  path: "/var/log/mongod/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 __restexpansion, on Linux/macOS, the read access to the configuration file must be limitedto the user running the mongod/mongosprocess only.
• If the configuration file includes the __execexpansion, on Linux/macOS, the write access to the configuration file must belimited to the user running themongod/mongos process only.

To use expansion directives, you must specify the—configExpand command-line optionwith the complete list of expansion directives used:

mongod --config "/path/to/config/mongod.conf" --configExpand "rest,exec"

If you omit the—configExpand option or ifyou do not specify the complete list of expansion directives used inthe configuration file, the mongod/mongos returnsan error and terminates. You can only specify the—configExpand option on thecommand line.

Use the __rest Expansion Directive

The __rest expansion directive loads configurationfile values from a REST endpoint. _rest supports loadingspecific values in the configuration file _or loading the entireconfiguration file.

• Specific Value
• Full Configuration File

The following configuration file uses the__rest expansion directive to load thesetting net.tls.certificateKeyFilePassword value from anexternal REST endpoint:

storage:
  dbPath: "/var/lib/mongod/"
systemLog:
  destination: file
  path: "/var/log/mongod/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 __restexpansion, on Linux/macOS, the read access to the configuration file must be limitedto the user running the mongod/mongosprocess only.
• Expansion Parsing
• To parse the __rest blocks, start the mongod/mongos withthe —configExpand "rest"option.

The mongod/mongos issues a GET request against specifiedURL. If successful, the mongod/mongos replaces the value ofcertificateKeyFilePassword with the returned value. Ifthe URL fails to resolve or if the REST endpointreturns an invalid value, the mongod/mongos throws an error andterminates.

The following configuration file uses the__rest expansion directive to load theconfiguration file from an external REST endpoint. Theexpansion directive and its options must be the only valuesspecified in the configuration file.

__rest: "https://myrestserver.example.net/api/config/fullConfig"
type: "yaml"

• File Permission
• If the configuration file includes the __restexpansion, on Linux/macOS, the read access to the configuration file must be limitedto the user running the mongod/mongosprocess only.
• Expansion Parsing
• To parse the __rest blocks, start the mongod/mongos withthe —configExpand "rest"option.

The mongod/mongos issues a GET request against thespecified URL. If successful, the mongod/mongos parses thereturned configuration yaml file and uses it duringstartup. If the URL fails to resolve or return a properlyformatted yaml file, the mongod/mongos throws an error andterminates.

Important

The value returned by the specified REST endpointcannot include any additional expansion directives. Themongod/mongos does not perform additionalprocessing on the returned data and will terminate with anerror code if the returned data includes additionalexpansion directives.

Use the __exec Expansion Directive

The __exec expansion directive loads configurationfile values from a shell or terminal command. _exec supportsloading specific values in the configuration file _or loading theentire configuration file.

• Specific Value
• Full Configuration File

The following example configuration file uses the__exec expansion directive to to load thesetting net.tls.certificateKeyFilePassword value from the outputof a shell or terminal command:

storage:
  dbPath: "/var/lib/mongod/"
systemLog:
  destination: file
  path: "/var/log/mongod/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 __execexpansion, on Linux/macOS, the write access to the configuration file must belimited to the user running themongod/mongos process only.
• Expansion Parsing
• To parse the __exec blocks, start the mongod/mongos withthe —configExpand "exec"option.

The mongod/mongos attempts to execute the specified operation.If the command executes successfully, the mongod/mongosreplaces the value of certificateKeyFilePassword withthe returned value. If the command fails or returns aninvalid value for the configuration file setting, themongod/mongos throws an error and terminates.

The following example configuration file uses the__exec expansion directive to load theconfiguration file from the output of a shell or terminalcommand. The __exec expansion directiveand its options must be the only values specified in theconfiguration file.

__exec: "python /home/myUserName/getFullConfig.py"
type: "yaml"

• File Permission
• If the configuration file includes the __execexpansion, on Linux/macOS, the write access to the configuration file must belimited to the user running themongod/mongos process only.
• Expansion Parsing
• To parse the __exec blocks, start the mongod/mongos withthe —configExpand "rest"option.

If the command executes successfully, the mongod/mongos parsesthe returned configuration yaml file and uses it duringstartup. If the command fails or returns an invalidyaml file, the mongod/mongos throws an error and terminates.

Important

The data returned by executing the specified __execstring cannot include any additional expansiondirectives. The mongod/mongos does notperform additional processing on the returned data andwill terminate with an error code if the returned dataincludes additional expansion directives.

Expansion Directives Reference

• rest[]($8cf4228e64f1e838.md#configexpansion.rest)
• The __rest expansion directive loads configurationfile values from a REST endpoint. __restsupports loading specific values in the configuration file _or_loading the entire configuration file. The mongod/mongos then startsusing the externally sourced values as part of its configuration.

The __rest expansion directive has the followingsyntax:

• To specify a REST endpoint for a specific configuration filesetting or settings:

<some configuration file setting>:
  __rest: "<string>"
  type: "string"
  trim: "none|whitespace"
  digest: "<string>"
  digest_key: "<string>"

• To specify a REST endpoint for the entire configuration file:

__rest: "<string>"
type: "yaml"
trim: "none|whitespace"

If specifying the entire configuration file via REST endpoint,the expansion directive and its options must be the only valuesspecified in the configuration file.

__rest takes the following fields:

FieldTypeDescription__reststringRequired The URL against which the mongod/mongosissues a GET requestto retrieve the externally sourced value.

For non-localhost REST endpoints (e.g. a REST endpointhosted on a remote server), __restrequires encrypted (https://) URLs where both the hostmachine and the remote server support TLS 1.1 or later.

If the REST endpoint specified in the URL requiresauthentication, encode credentials into the URL with thestandardRFC 3986 User Informationformat.

For localhost REST endpoints (e.g. a REST endpointlistening on the host machine), __restallows unencrypted (http://) URLs.

Important

The value returned by the specified REST endpointcannot include any additional expansion directives. Themongod/mongos does not perform additionalprocessing on the returned data and will terminate with anerror code if the returned data includes additionalexpansion directives.

typestringOptional Controls how __restparses the returned value from the specified URL.

Possible values are:

• string (Default)

Directs __rest to parse the returned dataas a literal string. If specifying string, the entire__rest block and supporting options mustbe nested under the field for which you are loadingexternally sourced values.

• yaml

Directs __rest to parse the returned dataas a yaml formatted file. If specifying yaml, the__rest block must be the only content inthe configuration file. The mongod/mongos replaces theconfiguration file contents with the yaml retrieved fromthe REST resource.trimstringOptional Specify whitespace to direct__restto trim any leading or trailing whitespace, specificallyoccurrences of" ", "\r", "\n", "\t", "\v", and"\f". Defaults to none, 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 thesecret used to calculate the SHA-256 digest.

If specified, you must also specify the digest.

Note

• If the configuration file includes the __restexpansion, on Linux/macOS, the read access to the configuration file must be limitedto the user running the mongod/mongosprocess only.
• To enable parsing of the __rest expansion directive, startthe mongod/mongos with the —configExpand "rest" option.

For examples, see Use the __rest Expansion Directive.

• exec[]($8cf4228e64f1e838.md#configexpansion.exec)
• The __exec expansion directive loads configurationfile values from the output of a shell or terminal command.__exec supports loading specific values in theconfiguration file or loading the entire configuration file. Themongod/mongos then starts using the externally sourced values as part ofits configuration.

The __exec expansion directive has the followingsyntax:

• To specify a shell or terminal command for a specific configurationfilesetting or settings:

<some configuration file setting>:
  __exec: "<string>"
  type: "string"
  trim: "none|whitespace"

• To specify a a shell or terminal command for the entireconfiguration file:

__exec: "<string>"
type: "yaml"
trim: "none|whitespace"

If specifying the entire configuration file via a terminal or shellcommand, the expansion directive and its options must be theonly values specified in the configuration file.

__exec takes the following fields:

FieldTypeDescription_execstring_Required The string which the mongod/mongos executes on theterminal or shell to retrieve the externally sourced value.

On Linux and OSX hosts, execution is handled viaPOSIX popen(). On Windows hosts, execution is handled viathe process control API. __exec opens a read-onlypipe as the same user that started the mongod ormongos.

Important

The data returned by executing the specifiedcommand cannot include any additional expansiondirectives. The mongod/mongos does notperform additional processing on the returned data andwill terminate with an error code if the returned dataincludes additional expansion directives.

typestringOptional Controls how __execparses the value returned by the executed command.

Possible values are:

• string (Default )

Directs __exec to parse the returned dataas a literal string. If specifying string, the entire__exec block and supporting options mustbe nested under the field for which you are loadingexternally sourced values.

• yaml

Directs __exec to parse the returned dataas a yaml formatted file. If specifying yaml, the__exec block must be the only content inthe configuration file. The mongod/mongos replaces theconfiguration file contents with the yaml retrieved fromthe executed command.trimstringOptional Specify whitespace to direct__execto trim any leading or trailing whitespace, specificallyoccurrences of" ", "\r", "\n", "\t", "\v", and"\f". Defaults to none, 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 thesecret used to calculate the SHA-256 digest.

If specified, you must also specify the digest

Note

• If the configuration file includes the __execexpansion, on Linux/macOS, the write access to the configuration file must belimited to the user running themongod/mongos process only.
• To enable parsing of the __exec expansion directives, startthe mongod/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 oneor more expansion directives by starting the mongod/mongos with the—outputConfig option. A mongod/mongosstarted with —outputConfig outputsthe resolved YAML configuration document to stdout and halts. If anyexpansion directive specified in the configuration file returnsadditional expansion directives, the mongod/mongos throws an error andterminates.

Warning

The —outputConfig option returnsthe resolved values for any field using an expansion directive. Thisincludes any private or sensitive information previously obscured byusing an external source for the configuration option.

For example, the following configuration filemongod.conf contains a __rest expansiondirective:

storage:
  dbPath: "/var/lib/mongodb/"
systemLog:
  destination: file
  path: "/var/log/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 __restexpansion, on Linux/macOS, the read access to the configuration file must be limitedto the user running the mongod/mongosprocess only.

Start the mongod with the—configExpand "rest" and—outputConfig options:

mongod -f mongod.conf --configExpand rest --outputConfig

The mongod outputs the following to stdoutbefore terminating:

config: mongod.conf
storage:
  dbPath: "/var/lib/mongodb/"
systemLog:
  destination: file
  path: "/var/log/mongod.log"
net:
  port: 20128
outputConfig: true