Configuration File

Note

Please note that changes to the configuration file will only take effect after the Management service is restarted. To restart it, you can either use Windows Service Manager (look for ScaleOut Management REST Service) or use the start/stop commands from a command prompt using the service name: soss_mgt_rest

{
        "Net": {
                "Mode": "local",
                "UnixSocketName": "",
                "Cors": true,
                "CorsOrigins": [],
                "Addr": "localhost",
                "Port": 4000,
                "TLS": {
                        "Enabled": false,
                        "TLSPublicCertificateFilePath": "/path/to/tls-public.pem",
                        "TLSPrivateKeyFilePath": "/path/to/tls-private.pem"
                },
                "Auth": {
                        "AuthMode": "deny",
                        "HtdigestFilePath": ".htdigest",
                        "DigestRealm": "ScaleOut REST API",
                        "Password": "",
                        "WindowsDomain": "",
                        "JWTPublicCertificateFilePath": "/path/to/jwt-public.pem",
                        "JWTPrivateKeyFilePath": "/path/to/jwt-private.pem"
                }
        },
        "Runtime": {
                "NumCPUs": 0
        },
        "MaxHandlePoolSize": 5
}

The following properties can be modified in this file when configuring the ScaleOut Management REST Service:

Net.Mode

Specifies which mode the ScaleOut Management REST Service should receive requests. May be one of the following options:

  • “local” (default). The ScaleOut Management REST Service runs using its built-in web server.

  • “tcp”. The ScaleOut Management REST Service runs using FastCGI via TCP.

  • “unix”. The ScaleOut Management REST Service runs using FastCGI via Unix Domain Socket (see Net.UnixSocketName).

  • “stdio”. The ScaleOut Management REST Service runs using FastCGI via Standard I/O.

This setting may be overridden by the “-mode” command line argument.

Net.UnixSocketName

Used only when Net.Mode is set to unix. Specifies the name of the Unix Domain Socket when running as a FastCGI module. This setting may be overridden by the “unix” command line argument. Otherwise, this property is ignored.

Net.Cors

Specifies whether the ScaleOut Management REST Service should accept script-based requests from other origins (e.g., XMLHttpRequest, fetch(), jQuery.ajax, etc.). This setting may be overridden by the “-cors” command line argument. Default: false.

Net.CorsOrigins

Used only when Net.Cors is set to true. Specifies a list of CORS Origins to be accepted in cross-origin requests. If not specified, then all origins are allowed. Default: (no value).

Net.Addr

Specifies the TCP address to listen on. May be one of the following options:

  • “localhost” (default). Accept only incoming connections from the same host.

  • IPv4 address, e.g., “10.0.2.100”. Accept only incoming connections to the specified address.

  • “” (empty string). Accept incoming connections from any source.

Note

When allowing external connections we strongly recommend using TLS to prevent authentication details, such as account passwords, from being intercepted. We also strongly recommend against enabling remote connections when AuthMode is set to “allow”.

Net.Port

The TCP port to listen on. This setting may be overridden by the “-port” command line argument. Default: 4000.

Net.TLS.Enabled

Specifies whether to support Transport Layer Security (TLS) to allow encrypted connections to clients. Default: false.

Net.TLS.TLSPublicCertificateFilePath

Specifies the path to the public certificate file from a public/private key pair. The file must contain PEM encoded data. Default: (no value).

Net.TLS.TLSPrivateKeyFilePath

Specifies the path to the private key file from a public/private key pair. The file must contain PEM encoded data. Default: (no value).

Net.Auth.AuthMode

Specifies which authentication provider should be used when determining access to the web management console and the ScaleOut Management REST Service. May be one of the following options:

  • “deny” (default). Access to the ScaleOut Management REST Service (and the web management console) is denied. Accessing the web console will display a message informing the user of this fact. In this mode, all other Net.Auth.* properties are ignored.

  • “allow” (no authentication). Access to the ScaleOut Management REST Service is unrestricted; no username or password is required for any operation. Exercise extreme caution if allowing external connections. In this mode, all other Net.Auth.* properties are ignored.

  • “password” (shared password authentication, insecure). Users and service clients will be prompted for a single shared password. The password is compared against the plain-text value in the Net.Auth.Password property. Insert the password of your choice as plaintext into the Net.Auth.Password property in the JSON file. You may need to escape reserved JSON string characters like backslashes. This option stores the password in plain-text and is strongly discouraged! This option is provided only for convenience if you are unable to generate bcrypt hashes; the use of “hashedpassword” is encouraged instead.

  • “hashedpassword” (shared password authentication). Users and service clients will be prompted for a single shared password. The password is hashed using bcrypt and compared against the hashed value in the Net.Auth.Password property. Insert the password of your choice as a bcrypt hashed value into the Net.Auth.Password property in the JSON file.

  • “windows” (Windows user account authentication). Users are authenticated using Windows user account authentication. The Net.Auth.WindowsDomain property may be optionally specified to restrict authentication only against the specified Windows domain. No authorization checks are currently performed, so authenticated non-administrator users will be able to perform the same ScaleOut management tasks as administrators. This option is not available on Linux. The Net.Auth.Password property is ignored.

  • “pam” (Linux Pluggable Authentication Module). Users are authenticated using the Linux PAM API similar to Windows user account authentication. No authorization checks are currently performed, so any authenticated user will be able to perform the same ScaleOut management tasks as root. This option is not available on Windows. The Net.Auth.Password property is ignored.

  • “digest” (HTTP Digest Authentication). Users are authenticated using HTTP Digest Authentication against users in the specified Net.Auth.DigestRealm specified in the htdigest file specified by Net.Auth.HtdigestFilePath.

Note

The Net.Auth.JWTPublicCertificateFilePath and Net.Auth.JWTPrivateKeyFilePath must be set for any mode that is not “allow” (unrestricted access), “digest”, or “deny” (no access allowed at all).

Net.Auth.Password

Used only when Net.Auth.AuthMode is set to password or hashedpassword. If the authentication mode is set to password, the value in this property is the plain-text password used for shared password authentication. If the authentication mode is set to hashedpassword, the value in this property is the bcrypt hash of the shared password used for authentication. Otherwise, this property is ignored. Default: (no value).

Net.Auth.WindowsDomain

Used only when Net.Auth.AuthMode is set to windows. If specified, user logon attempts will be authenticated against the specified Windows domain; otherwise, attempts will be validated against local accounts. Default: (no value).

Net.Auth.JWTPublicCertificateFilePath

Specifies the path to the public key file from a public/private key pair used to sign and verify the JWT bearer-tokens used by the ScaleOut Management REST Service for authentication. The file must contain PEM encoded data. Required if ``Net.Auth.Mode`` is “password”, “hashedpassword”, “windows”, or “pam”. Default: (no value).

Net.Auth.JWTPrivateKeyFilePath

Specifies the path to the private key file from a public/private key pair used to sign and verify the JWT bearer-tokens used by the ScaleOut Management REST Service for authentication. The file must contain PEM encoded data. Default: (no value).

Note

There are many ways to generate public/private key pair certificates. As an example using OpenSSL: openssl genrsa -out rsa-private-key.pem 2048 for the private key, and openssl rsa -in rsa-private-key.pem -out rsa-public-key.pem -pubout -outform PEM for the public key. Generating advanced public/private key pair certificates is outside the scope of this document.

Auth.DigestRealm

Used only when Net.Auth.AuthMode is set to digest. Specifies the realm to display and use during digest authentication. Default: “ScaleOut REST API”.

Auth.HtdigestFilePath
Used only when Net.Auth.AuthMode is set to digest. Specifies the path to the digest authentication file. The file must contain usernames, realms, and hashed passwords for authentication in the Apache htdigest format.

Default: “.htdigest”.

Runtime.NumCPUs

The number of logical CPU cores that the service may use to process requests. If 0, the service will default to using the number of logical cores that are available on the host system. Default: 0.

MaxHandlePoolSize

The maximum number of concurrent, open connections to the ScaleOut service that may be used by the REST service’s internally-managed connection pool. This pool is grown as needed (on demand), and the number of connections will not exceed the specified size. If the REST service receives a request while all connection handles are in use by other requests, the request will be queued and will wait until a connection becomes available in the pool. Default: 5.

Troubleshooting

In case you misconfigure your configuration file, the Management service may fail to start. For instance, if you pick the authentication mode Windows but omit the required JWT key pair, the service won’t be able to start. In such cases, you may want to try a debug mode to get more information about the reason the service is not starting.

net stop soss_mgt_rest
soss_mgt_rest.exe -cmd debug -mode local -port 4000

The output of this command should provide enough context to fix the configuration file.