Configuring the REST API Service

The ScaleOut REST API service runs as a separate Windows service. 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 REST API service, and it must be edited to make the service accessible to remote client machines.

{
  "Net": {
    "Addr": "localhost",
    "Port": 4001,
    "TLS": {
      "Enabled": false,
      "CertFile": "",
      "KeyFile": ""
    },
    "Auth": {
      "UseDigestAuth": false,
      "DigestRealm": "SOSS REST API",
      "HtdigestFile": ".htdigest"
    }
  },
  "Runtime": {
    "NumCPUs": 0
  },
  "MaxHandlePoolSize": 5
}

The following properties can be modified in this file when configuring the REST API service:

Addr
The TCP address to listen on. An empty string ("") listens on all addressable interfaces. Default: localhost.
Port
The TCP port to listen on. Default: 4001.
TLS.Enabled
Specifies whether to support Transport Layer Security (TLS) to allow encrypted connections to clients. Default: false.
TLS.CertFile
Specifies the path to the public certificate file from a public/private key pair. The file must contain PEM encoded data. Default: (no value).
TLS.KeyFile
Specifies the path to the private key file from a public/private key pair. The file must contain PEM encoded data. Default: (no value).
Auth.UseDigestAuth
Specifies whether to use digest access authentication for HTTP requests. Default: false.
Auth.DigestRealm
Specifies the realm to display and use during digest authentication. Default: "SOSS REST API".
Auth.HtdigestFile
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 SOSS 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 SOSS connection handles are in use by other requests, the request will be queued and will wait until a SOSS connection becomes available in the pool. Default: 5.

Authentication

By setting "Auth.UseDigestAuth" to true, the REST API service will require digest authentication for all clients. The service will use the file pointed to by the path "Auth.HtdigestFile" to authenticate a client’s username and password for the realm defined by "Auth.DigestRealm". The service accepts any valid Apache-formatted .htdigest file, and can be manipulated using any tool which supports that format (such as Apache’s htdigest utility).

Running as a FastCGI Application

The ScaleOut StateServer REST API 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] 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.