mongo/docs/server-parameters.md

Server Parameters

Mongo database and router servers (i.e., mongod and mongos) provide a number of configuration options through server parameters. These parameters allow users to configure the behavior of the server at startup or runtime. For instance, logLevel is a server parameter that configures the logging verbosity.

How to define new parameters

Parameters are defined by the elements of the server_parameters section of an IDL file. The IDL machinery will parse these files and generate C++ code, and corresponding header files where appropriate. The generated code will self-register server parameters with the runtime.

Consider logLevel parameter from parameters.idl for example:

...
server_parameters:
  ...
  logLevel:
    description: "Specifies the verbosity of logging"
    set_at: ["startup", "runtime"]
    cpp_class:
      name: LogLevelServerParameter
      override_set: true
  ...

This defines a server parameter called logLevel, which is settable at startup or at runtime, and declares a C++ class for the parameter (i.e., LogLevelServerParameter). Refer to the Server Parameters Syntax documentation for the complete IDL syntax.

How to change a defined parameter

Users can set or modify a server parameter at startup and/or runtime, depending on the value specified for set_at. For instance, logLevel may be set at both startup and runtime, as indicated by set_at (see the above code snippet).

At startup, server parameters may be set using the --setParameter command line option. At runtime, the setParameter command may be used to modify server parameters. See the setParameter documentation for details.

How to get the value provided for a parameter

Server developers may retrieve the value of a server parameter by:

• Accessing the C++ expression that corresponds to the parameter of interest. For example, reading from serverGlobalParams.quiet returns the current value for quiet.
• Registering a callback to be notified about changes to the server parameter (e.g., onUpdateFTDCFileSize for diagnosticDataCollectionFileSizeMB).

Database users may use the getParameter command to query the current value for a server parameter.

Server Parameters Syntax

The following shows the IDL syntax for declaring server parameters. Field types are denoted in each section. For details regarding string or expression map, see that section below.

server_parameters:
  "nameOfParameter": # string
    set_at: # string or list of strings
    description: # string
    cpp_vartype: # string
    cpp_varname: # string
    cpp_class: # string (name field) or map
      name: # string
      data: # string
      override_ctor: # bool
      override_set: # bool
    redact: # bool
    test_only: # bool
    default: # string or expression map
    deprecated_name: # string or list of strings
    on_update: # string
    condition:
      expr: # C++ bool expression, runtime evaled
      constexpr: # C++ bool expression, compile-time eval
      preprocessor: # C preprocessor condition
    validator: # Map containing one or more of the below
      lt: # string or expression map
      gt: # string or expression map
      lte: # string or expression map
      gte: # string or expression map
      callback: # string

Each entry in the server_parameters map represents one server parameter. The name of the parameter must be unique across the server instance. More information on the specific fields:

• set_at (required): Must contain one or both of the values startup and/or runtime. If runtime is specified along with cpp_varname, then decltype(cpp_varname) must refer to a thread-safe storage type, specifically: AtomicWord<T>, AtomicDouble, std::atomic<T>, or boost::synchronized<T>.

• description (required): Free-form text field currently used only for commenting the generated C++ code. Future uses may preserve this value for a possible {listSetParameters:1} command or other programmatic and potentially user-facing purposes.

• cpp_vartype: Declares the full storage type. If cpp_vartype is not defined, it may be inferred from the C++ variable referenced by cpp_varname.

• cpp_varname: Declares the underlying variable or struct member to use when setting or reading the server parameter. If defined together with cpp_vartype, the storage will be declared as a global variable, and externed in the generated header file. If defined alone, a variable of this name will assume to have been declared and defined by the implementer, and its type will be automatically inferred at compile time. If cpp_varname is not defined, then cpp_class must be specified.

• cpp_class: Declares a custom ServerParameter class in the generated header using the provided string, or the name field in the associated map. The declared class will require an implementation of setFromString(), and optionally set(), append(), and a constructor. See Specialized Server Parameters below.

• default: String or expression map representation of the initial value.

• redact: Set to true to replace values of this setting with placeholders (e.g., for passwords).

• test_only: Set to true to disable this set parameter if enableTestCommands is not specified.

• deprecated_name: One or more names which can be used with the specified setting and underlying storage. Reading or writing a setting using this name will result in a warning in the server log.

• on_update: C++ callback invoked after all validation rules have completed successfully and the new value has been stored. Prototype: Status(const cpp_vartype&);

• condition: Up to three conditional rules for deciding whether or not to apply this server parameter. preprocessor will be evaluated first, followed by constexpr, then finally expr. If no provided setting evaluates to false, the server parameter will be registered.

• validator: Zero or many validation rules to impose on the setting. All specified rules must pass to consider the new setting valid. lt, gt, lte, gte fields provide for simple numeric limits or expression maps which evaluate to numeric values. For all other validation cases, specify callback as a C++ function or static method. Note that validation rules (including callback) may run in any order. To perform an action after all validation rules have completed, on_update should be preferred instead. Callback prototype: Status(const cpp_vartype&);

Any symbols such as global variables or callbacks used by a server parameter must be imported using the usual IDL machinery via globals.cpp_includes. Similarly, all generated code will be nested inside the namespace defined by globals.cpp_namespace. Consider the following for example:

global:
  cpp_namespace: "mongo"
  cpp_includes:
    - "mongo/db/free_mon/free_mon_mongod.h"

server_parameters:
  cloudFreeMonitoringEndpointURL:
    ...
    validator:
      callback: "onValidateFreeMonEndpointURL" # The callback is declared in "free_mon_mongod.h"

Specialized Server Parameters

When cpp_class is specified on a server parameter, a child class of ServerParameter will be created in the gen.h file named for either the string value of cpp_class, or if it is expressed as a dictionary, then cpp_class.name. A cpp_class directive may also contain:

server_parameters:
  someParameter:
    cpp_class:
      name: string # Name to assign to the class (e.g., SomeParameterImpl)
      data: string # cpp data type to add to the class as a property named "_data"
      override_ctor: bool # True to allow defining a custom constructor, default: false
      override_set: bool # True to allow defining a custom set() method, default: false

override_ctor: If false, the inherited constructor from the ServerParameter base class will be used. If true, then the implementer must provide a {name}::{name}(StringData serverParameterName, ServerParameterType type) constructor. In addition to any other work, this custom constructor must invoke its parent's constructor.

override_set: If false, a default Status {name}::set(const BSONElement& val) implementation will be provided which invokes setFromString() using val.String(), handling exceptions due to invalid BSON field types as appropriate. If true, the implementer must provide these methods.

If param.redact was specified as true, then a standard append method will be provided which injects a placeholder value. If param.redact was not specified as true, then an implementation must be provided with the following signature:

Status {name}::append(OperationContext*, BSONObjBuidler&, const std::string&);

Lastly, a setFromString method must always be provided with the following signature:

Status {name}::setFromString(const std::string& value);

Each server parameter encountered will produce a block of code to run at process startup similar to the following:

/**
 *  Iteration count to use when creating new users with
 *  SCRAM-SHA-1 credentials
 */
MONGO_COMPILER_VARIABLE_UNUSED auto* scp_unique_ident = [] {
    using T = decltype(saslGlobalParams.scramSHA1IterationCount);
    constexpr auto setAt = ServerParameterType::kStartupAndRuntime;
    auto ret = new IDLServerParameterWithStorage<T>(
            "scramIterationCount",
            saslGlobalParams.scramSHA1IterationCount, setAt);
    ret->addBound<predicate::GTE>(5000);
    return ret;
}();

Any additional validator and callback would be set on ret as determined by the server parameter configuration block.

String or Expression Map

The default and implicit fields above, as well as the gt, lt, gte, and lte validators accept either a simple scalar string which is treated as a literal value, or a yaml map containing an attribute called expr, which must be a string containing an arbitrary C++ expression to be used as-is. Optionally, an expression map may also include the is_constexpr: false attribute, which will suspend enforcement of the value being a constexpr.

For example, consider:

server_parameters:
  connPoolMaxInUseConnsPerHost:
    ...
    cpp_varname: maxInUseConnsPerHost
    default:
      expr: std::numeric_limits<int>::max()
    ...

Here, the server parameter's default value is the evaluation of the C++ expression std::numeric_limits<int>::max(). Additionally, since default was not explicitly given the is_constexpr: false attribute, it will be round-tripped through the following lambda to guarantee that it does not rely on runtime information.

[]{ constexpr auto value = <expr>; return value; }()