SxServer Installation and Configuration on Linux

This document describes the steps required to install and configure SxServer on a Linux system.

Prerequisites

Installation

SxServer will be installed in /opt/soiree. A ‘soiree’ user will be created to run SxServer, and it will be given ownership and read/write access to some files and directories in /opt/soiree.

  1. Run the following commands as root to create the required folder structure:
    mkdir /opt/soiree
    cd /opt/soiree
    mkdir apps
    mkdir jdbclibs
    mkdir security
    mkdir var
    mkdir var/log
    mkdir config-server
    mkdir config-db
  2. Run the following commands as root to create the soiree user and give it ownership of /opt/soiree/var:
    useradd soiree
    chown -R soiree:soiree /opt/soiree/var

    The /opt/soiree/var directory contains all of the files that will be modified while SxServer is running, such as log files and persisted sessions.

  3. Download SxServer for Linux from the Soiree Downloads Page. For purposes of this guide, we’ll assume that the file you downloaded is named sxserver-4.2.0.zip. Run the following commands as root to extract SxServer and symlink it to /opt/soiree/sxserver:
    cd /opt/soiree
    unzip sxserver-4.2.0.zip
    ln -s sxserver-4.2.0 sxserver
    chmod 755 sxserver/bin/*.sh
  4. Copy a ServerConfiguration.xml file into the server configuration folder /opt/soiree/config-server. Modify the contents of ServerConfiguration.xml as necessary to configure the server for your environment.
  5. Copy a logback.xml file into the server configuration folder /opt/soiree/config-server.
  6. Set the SOIREE_HOME environment variable to /opt/soiree:
    export SOIREE_HOME=/opt/soiree

    You may wish to add the line above to an appropriate file (such as /etc/environment) so that it will be set automatically when you log in.

Database Connections

Soiree applications contain datasources that perform database I/O. Every datasource is bound to a connection ID. SxServer must be configured to map the connection IDs to physical databases.

You must create an XML configuration file for each physical database and place the files in the /opt/soiree/config-db directory.

Tip
You don’t need to create the XML configuration files from scratch! You can use the Soiree Plugin to create/edit a Database Connection item in Eclipse and then click the “Export as XML…” button in the top-right corner of the editor.

The following example assumes that:

  • You have a single MySQL database with a configuration file at /opt/soiree/config-db/mysql-prod.xml.
  • Your application has three unique connection IDs named
    com.seronix.soiree.connection.System,
    com.seronix.soiree.connection.ConsoleJournal, and
    com.example.connection.Application.

To map those connection IDs to the MySQL database, you must create a dbconnection.map file at /opt/soiree/config-db/dbconnection.map.

The map may contain multiple lines. Each line consists of a connection ID followed by an equals sign and the database configuration filename. For example:

com.seronix.soiree.connection.System=mysql-prod.xml
com.seronix.soiree.connection.ConsoleJournal=mysql-prod.xml
com.example.connection.Application=mysql-prod.xml

Database Drivers (JDBC)

You must provide SxServer with a JDBC driver for each database used by your applications. JDBC drivers can be downloaded from database vendors’ web sites and usually come in the form of one or more .jar files. Put the jar files in the /opt/soiree/jdbclibs directory. When SxServer starts it will automatically load all of the JDBC drivers it finds in that directory.

TLS Configuration

SxServer may be configured to encrypt clientserver communications using TLS. Encryption is recommended for all production servers. If you do not enable TLS then sensitive information, including usernames and passwords, may be transmitted in clear text between the client and the server.

When you configure TLS you will be dealing with keys and certificates. Keys are public/private key pairs for public-key encryption. Certificates are signed by a certificate authority and validate that a given public key belongs to an organization. For more information on certificates and public key encryption, see Wikipedia’s Public-key_encryption and Public_key_certificate articles.

SxServer is a Java application and uses a Java Key Store (“keystore”) to store its keys and certificates. Java SE includes a command-line program named keytool that you will use to manage SxServer’s keystore. When invoking keytool, make sure you are using the keytool from the same version of Java that is being used to start SxServer.

To configure TLS, you must create a keystore that contains your server’s key, your server’s certificate, and your certificate authority’s intermediate certificate(s).

Finally, edit the properties in /opt/soiree/config-server/ServerConfiguration.xml as follows. Set the serverKeyPassword and serverKeyStorePassword to the passwords you entered when you exported the PKCS12 file and created the keystore.

<tlsConfiguration>
...
    <tlsEnabled>true</tlsEnabled>
...
    <serverKeyStorePath>/opt/soiree/security/sxserver.keystore</serverKeyStorePath>
...
    <serverKeyStorePassword>firstSecret</serverKeyStorePassword>
    <serverKeyPassword>secondSecret</serverKeyPassword>
...
</tlsConfiguration>

You have created a keystore and configured SxServer to use TLS. You must restart SxServer for the changes to take effect.

To verify that TLS is working, visit the following url in a web browser (substituting your server’s hostname and port) and review the browser’s https security report:

https://foo.example.com:port/serverControl/heartbeat

You can also look for a line like this on the console when the server starts:

c.s.s.SxServer [main] Soiree SxServer v4.2.0 is now accepting connections on foo.example.com:443 using protocols ssl-http/1.1 http/1.1

If you are running SxServer on port 443, you may wish to use Qualys SSL Labs’ server test to get an in-depth report on your TLS configuration.

How to bind SxServer to port 80 or 443

SxServer normally runs as a non-privileged user (such as the ‘soiree’ user) that is created for the sole purpose of running the server. While that is good for security, it causes problems if you want to bind SxServer to port 80 or 443 because only privileged users (i.e. root) can bind to ports < 1024. To work around that problem you can enable SxServer's setuid feature and start SxServer as root. SxServer will bind to the port and then use a system call to set its process's effective user ID and group to that of a non-privileged user before it begins accepting connections. To enable the setuid feature: 1. Shut down SxServer. 2. Edit $SOIREE_HOME/sxserver/bin/startserver.sh. Change the value of START_SCRIPT_USER at the top of the script from 'soiree' to 'root'. Note that this script will be overwritten when SxServer is upgraded, so remember to make this change again if you upgrade your server in the future! 3. Edit $SOIREE_HOME/config-server/ServerConfiguration.xml. Set <setuidEnabled>true</setuidEnabled> and set <serverPort>443</serverPort> to the port of your choice. If your non-privileged user or group is something other than ‘soiree’ you should edit those values in the <setuidConfiguration> section as well.

4. From now on run startserver.sh as root.

Once setuid is enabled you will see lines like this on the console when the server starts:

c.s.s.SxServer [main] Setuid is enabled. SxServer is starting as user root and will run as user ‘soiree’ (uid 503) and group ‘soiree’ (uid 504) with umask ‘002’ after binding to port 443.
c.s.s.SxServer [main] Starting jetty 9.2.10.v20150310
o.e.j.s.SetUIDListener [main] Setting umask=02
o.e.j.s.SetUIDListener [main] Opened [email protected]{SSL-HTTP/1.1}{foo.example.com:443}
o.e.j.s.SetUIDListener [main] Setting GID=504
o.e.j.s.SetUIDListener [main] Setting UID=503