Appendix: SQLstream s-Server Installation Directories

When you install SQLstream s-Server, you need to specify three directory locations:

  • Home directory: the base directory for executable files
  • Catalog directory: the location of the catalog
  • Trace-log directory: the location for the server's trace logs

Although these can be located together, they have different requirements, and may need different types of access depending on how you plan to run the server. See the topic Starting the server and configuration files in this guide for more details

Home directory

The home directory is where the installer puts executable code and configuration files. These files are read-only at run time, and can be shared by multiple instances of the server running at the same time. By default, the installer suggests using the directory /opt/sqlstream/X.Y.Z.nnnn* (where X.Y.Z is the version number of the server and nnnn is the internal build number), but you can put those files anywhere they can be read and executed by users who need to run the server.

Catalog directory

Catalog files contain the definitions of the objects in your system. Those can obviously change during the course of operating the server, and will differ for different instances running on the same code. It can also contain checkpoints of past versions of the catalog. The catalog itself does not change size greatly, but the directory containing it must be writable by the server user. If you are running multiple instances of s-Server on the same machine, each instance needs to have its own catalog directory.

Trace-log directory

The trace-log directory needs to be writable by the server. The size of the trace logs will vary depending on the level of tracing specified in your configuration and the log-rotation strategy you employ. By default the installer sets the trace-log directory to /var/log/sqlstream*.  If you are running multiple instances of s-Server on the same machine, each instance needs to have its own trace log directory.

Configuring Server Directories

All of the server configurations that you choose during the installation are written into configuration files* that the server reads at start-up. You can change or customize server selections by editing these configuration files. The specific files read at server start-up depend on how you start the server. The configuration file takes the format of a Java properties file or a Linux configuration file. It is a text file with each line containing VARIABLE=value. Lines starting with pound signs are ignored as comments.

Here is an example of a SQLstream s-Server configuration file for running as a service.

The sample file should include an entry for an additional variable, as follows:

SQLSTREAM_HOME=/opt/sqlstream/<version>
.1234
SQLSTREAM_CATALOG_DIR=/opt/sqlstream/<version>
/catalog
SQLSTREAM_TRACE_DIR=/var/log/sqlstream
SQLSTREAM_USER=sqlstream
SQLSTREAM_PIDFILE=/var/run/sqlstream/s-serverd.pid
JAVA_HOME=/usr/local/jdk1.8
SQLSTREAM_JVM_PIDFILE=/var/run/sqlstream/jvm.pid

In each case, there are six or seven environment variables you can configure. One variable, SQLSTREAM_USER, applies to running as a service only. Note: $SQLSTREAM_HOME refers to the installation directory for s-Server, such as /opt/sqlstream/.XXX/s-Server. SQLstream s-Server can be run as a service or a normal Linux user. The differences between these options and their use of configuration files are - described below.

Variable Controls
JAVA_HOME This represents the base of a Java Development Kit (JDK) installation to be used for running the server. By default this is the value of JAVA_HOME in the environment the installer was run in.
SQLSTREAM_USER
(service only)
Name of the Linux user that the server runs as. This is only meaningful when the server is run as a service. Otherwise the server runs as the user that starts the server process. If this variable is missing or empty, the server runs as the user root.
SQLSTREAM_HOME Directory that contains the executable, read-only portion of the s-Server installation. This directory should be readable by any user on the system. The same installation can be executed by any number of users, as the server does not overwrite any of these files.
SQLSTREAM_CATALOG_DIR Directory the server will use to hold its catalog files. This needs to be unique for each running instance of the server. The default value is a directory called catalog under $SQLSTREAM_HOME, but that should only be used for a single instance, such as running as a service.
SQLSTREAM_TRACE_DIR Directory where the server will write its trace logs. This needs to be a writable directory with enough room for all the logs the server will write at any given time. The server user needs read, write, and execute permissions on this directory.
SQLSTREAM_PIDFILE The name of a file that will hold the process ID (PID) of the server process started by the s-serverd service. It is only used by s-serverd, and thus is only of interest if one is running the server as a service.
SQLSTREAM_JVM_PIDFILE The name of the file that holds the process ID of the Java Virtual Machine started by any s-Server instance. This variable is distinct from SQLSTREAM_PIDFILE, which contains the process ID of the s-Server script that launched the JVM. If you run multiple instances of s-Server on the same system, you need to assign each instance its own value of SQLSTREAM_JVM_PIDFILE before you start it. This will prevent an instance from overwriting another process's PID file, which would likely result in servers stopping one another's Java processes by mistake.

Starting the server and configuration files

There are three different scenarios for starting the server: running as a system service or daemon, running standalone as the root (administrator) user, and running as an ordinary user. Each option uses configuration files slightly differently.

Running as a Service

When you install the server to run as a service, it will generally be the only SQLstream s-Server running on that computer. The service is controlled by a Linux init script, /etc/init.d/s-serverd. That script looks for its configuration in /etc/default/s-serverd, which the installer creates using the values specified during installation.

Running as a Normal Linux User

When you run the server as a normal (non-root) Linux user, the server first loads the installation default values from the file /etc/sqlstream/environment if it exists. After that, it overrides those with any values found in a user-specific configuration file $HOME/.config/sqlstream/environment. The user can also specify a different file instead of that one by putting its full path name in the environment variable CONFIGFILE.