Configuring the Client REST Service

The ScaleOut Client REST Service runs as a separate Windows service or Linux daemon. While the REST API service is installed by default, it does not automatically start with the system. When enabled, the service is configured to accept requests from only the loopback address (“localhost” or 127.0.0.1) for security purposes. The soss_svc_rest.json file contains configuration settings used by the ScaleOut Client REST Service, and it must be edited to make the service accessible to remote client machines. An alternative configuration file may by specified with the “-config” command line argument which specifies a file path to the desired configuration file.

Configuration File

{
        "Net": {
                "Mode": "local",
                "UnixSocketName": "",
                "Cors": true,
                "CorsOrigins": "",
                "Addr": "localhost",
                "Port": 4000,
                "TLS": {
                        "Enabled": false,
                        "TLSPublicCertificateFilePath": "",
                        "TLSPrivateKeyFilePath": ""
                },
                "Auth": {
                        "AuthMode": "allow",
                        "Password": "",
                        "WindowsDomain": "",
                        "JwtPublicKeyPath": "/path/to/jwt-public.pem",
                        "JwtPrivateKeyPath": "/path/to/jwt-private.pem"
                }
        },
        "Runtime": {
                "NumCPUs": 0
        },
        "MaxHandlePoolSize": 5
}

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

Net.Mode

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

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

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

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

  • “stdio”. The ScaleOut Client 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 Client 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 “none”.

Net.Port

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

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 ScaleOut Client REST Service. May be one of the following options:

  • “allow” (default) No authentication is performed: Access to the ScaleOut Client 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.

  • “deny” Access to the ScaleOut Client REST Service is denied. 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.

Note

Hashed passwords can be generated using the configUtility (located in the same directory as the configuration file) as follows: configUtility.exe -mode=hashpassword and follow the instructions.

  • “windows” (Windows user account authentication). Users are authenticated using the Win32 LogonUser function. 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 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 Win32’s LogonUser function. No authorization checks are currently performed, so any authenticated user will be able to perform the same 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.JwtPublicKeyPath and Net.Auth.JwtPrivateKeyPath must be set for any mode that is not “allow” (unrestricted access) 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.JwtPublicKeyPath

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 Client REST Service for authentication. The file must contain PEM encoded data. Default: (no value).

Net.Auth.JwtPrivateKeyPath

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 Client REST Service for authentication. The file must contain PEM encoded data. Default: (no value).

Note

The JWT key pair files can be generated using the configUtility (located in the same directory as the configuration file) as follows: configUtility.exe -mode=generatejwtkeys and follow the instructions. You may need to run the program with administrative privileges.

Auth.DigestRealm

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

Auth.HtdigestFile
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.

Running as a FastCGI Application

The ScaleOut Client REST Service can be run as a FastCGI application behind any web server that supports fixed TCP ports, UNIX-style sockets, or standard I/O file descriptors.

Note

Microsoft Internet Information Services (IIS) is currently not supported for FastCGI. If FastCGI usage is required then consider either deploying the REST API service to a Linux host or installing an alternative web server on your Windows system.

TCP

To use TCP ports, the service executable should be run with the “-mode=tcp” command line argument. E.g., /usr/local/soss/soss_svc_rest -mode=tcp. The service will accept FastCGI requests passed to the TCP port specified by Net.Port in the configuration file (or, alternatively, the -port command line argument). See Configuration File for more detail on this configuration parameter.

UNIX Sockets

To use named UNIX sockets, the service executable should be run with the “-mode=stdio” and “-unix” command line arguments, specifying the filesystem pathname to the named socket. E.g., /usr/local/soss/soss_svc_rest -mode=unix -unix=/tmp/myprogram.sock. The service will accept FastCGI requests passed to the named socket.

Standard I/O

To use standard I/O (stdin and stdout), the service executable should be run the “-mode=stdio” command line argument. E.g., /usr/local/soss/soss_svc_rest -mode=stdio. The service will accept FastCGI requests passed to the standard input and output file descriptors.

Example Web Server Configurations

Note

The below samples are provided as a quick start for reference only. Proper configuration of web servers can be complex. If in doubt, consult the product documentation for the web server software.

Nginx Example

To configure the Nginx web server to forward HTTP requests to the ScaleOut Client REST Service as a FastCGI module, a sample virtual host configuration entry may look like the following:

Sample Nginx Configuration.

server {
     listen 80;
     server_name _;
     root /var/www;
     index index.html;

     location ~ / {
          include fastcgi.conf;
          # FastCGI passthru to TCP port 4001 on localhost
          fastcgi_pass 127.0.0.1:4001;

          # Alternatively, to passthru to a UNIX socket at /tmp/nginx4001.socket
          # Uncomment the following line (and comment the above fastcgi_pass directive):
          #fastcgi_pass unix:/tmp/nginx4001.socket;
     }

     try_files $uri $uri.html =404;
}

Note

Nginx does not automatically launch the FastCGI process if the process is not running. Typically, this results in a 502 Bad Gateway error.

Apache HTTP Example

Configuring the Apache HTTP web server to support FastCGI requires the use of a FastCGI module, such as mod_fastcgi or mod_fcgid.

To configure the Apache HTTP web server to forward HTTP requests to the ScaleOut Client REST Service as a FastCGI module, a sample configuration might look like the following:

Sample Apache Configuration.

# Redirect requests from / to the FCGI application
ScriptAlias / /usr/local/soss/soss_svc_rest

# Configuration for mod_fastcgi, if enabled
<IfModule mod_fastcgi.c>
  # Assumes the below directory is writeable by the Apache user!
  FastCgiIpcDir /tmp/fcgi
  FastCgiServer /usr/local/soss/soss_svc_rest
  <Directory /usr/local/soss/soss_svc_rest>
    SetHandler fastcgi-script
  </Directory>
</IfModule>

# Alternative configuration for mod_fcgid, if enabled
<IfModule mod_fcgid.c>
  # Assumes the below directory is writeable by the Apache user!
  FcgidIPCDir /tmp/fcgi
  FcgidWrapper /usr/local/soss/soss_svc_rest
  <Directory /usr/local/soss/soss_svc_rest>
    SetHandler fcgid-script
  </Directory>
</IfModule>

Note

There are many ways to configure FCGI applications. Check the Apache and mod_fastcgi/mod_fcgid documentation for alternatives.