Configuring the REST API Service

The ScaleOut REST API service runs as a separate 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 REST API, 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 the apache2-utils package on dpkg package management systems and the httpd-tools package on RPM package management systems).

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.

TCP

To use TCP ports, the service executable should be run with the "-tcp" command line argument. E.g., /usr/local/soss/soss_svc_web -tcp. The service will accept FastCGI requests passed to the TCP port specified by Port in the configuration file. See the section on Configuration for more detail on this configuration parameter.

UNIX Sockets

To use named UNIX sockets, the service executable should be run with the "-unix" command line argument, specifying the filesystem pathname to the named socket. E.g., /usr/local/soss/soss_svc_web -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 without any command line arguments. E.g., /usr/local/soss/soss_svc_web. 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 StateServer REST API 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 StateServer REST API 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_web

# 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_web
  <Directory /usr/local/soss/soss_svc_web>
    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_web
  <Directory /usr/local/soss/soss_svc_web>
    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.

ScaleOut Product Suite HelpInstallation