OS4X Core main configuration file

Main configuration file

OS4X's main configuration file defines be basic information about database connectivity and some other, really basic information which cannot reside in the database.

Position

All OS4X binaries search the configuration file at

/etc/os4x.conf

but they are all aware of searching this file at a given position. For this position information, nearly all binaries have the parameter "-C" (beware of the uppercase!). Example:

$ /opt/os4x/bin/os4xrd -C /opt/os4x/os4x.conf

This example searches the config file at the given position "/opt/os4x/os4x.conf".

In addition, all running OS4X binaries set the environment variable "OS4X_CFGFILE", which is also interpreted by all binaries. An alternative way to the above example could then be:

$ export OS4X_CFGFILE=/opt/os4x/os4x.conf
$ /opt/os4x/bin/os4xrd

Content

The configuration file contains textual information in the format "key=value", where no space must be existant between key, the character "=" and the corresponding value. Lines beginning with a hash sign ("#") are comments and will not be taken into account. Example:

# comment 
KEY=VALUE

Variables

Illegal defintions are:

KEY = VALUE    <- whitespaces after key name and before value
KEY =VALUE     <- whitespace after key name
KEY= VALUE     <- whitespace before value

The following variables are available.

DB_HOST

Mandatory.

Resolvable hostname or IP address of the databse server. In case of MySQL, special rules apply: if the value "localhost" is used, the MySQL client library tries to connect via a compiled in socket connection, if no socket is configured. In this case, if you have any problems connecting to MySQL, examine your syslog output and check the socket availability. As a workaround, "127.0.0.1" can be configured for a forced TCP/IP connection to localhost.

DB_USER

Mandatory.

Username for the database connection. In case of MySQL, if no username is configured (left empty), the user running the program is being used.

DB_PASS

Mandatory.

Password for the database connection. Empty connection passwords are not officially supported, but may work.

DB_NAME

Mandatory.

• MySQL: Name of the database.
• DB2: Name of the database instance.

DB_SCHEMA

Optional.

• PostgreSQL: Name of the database schema. If not set, the database name is used as schema name (default).

DB_SOCKET

Optional. Absolute path to the socket file for communication. Only valid for MySQL.

DB_PORT

Mandatory.

TCP/IP port number for communication with the database server.

TABLEPREFIX

Mandatory.

Prefix of all OS4X tables. In shared database environment (where only one database is available) it's handy to have a configurable prefix for all tables. Default:

os4x_

(beware of the underscore as a last character).

MYSQLCLIENT

Optional.

Absolute path to the MySQL client tool used for backup and restore reasons.

PSQL

Optional.

Absolute path to the PostgreSQL client tool "psql" used for backup and restore reasons.

SERVERID

Optional.

ID of the OS4X server in a cluster environment. Every OS4X server should have its own server ID, given by you.

DBTYPE

Optional.

Type of database connected to. Starting with OS4X 3 Core, possible values are:

• MYSQL
• DB2
• SQLITE
• POSTGRESQL

If left empty, "MYSQL" is assumed for compatibility reasons with OS4X 2 Core.

DB_PERSISTANT_CONNECTION

Optional.

For a persistant database connection for every OS4X process, you may set this configuration value to the numerical value "1":

DB_PERSISTANT_CONNECTION=1

At the moment only effective with "DBTYPE=DB2".

CLIENTD_OVERRIDDEN_HOST

If you want OS4X Webaccess to connect to an alternative OS4X client daemon (possibly on a remote server), set here the resolvable hostname or IP address of the server. All OS4X client daemon communication (i.e. authentification, job generation) will take place on this server.

WEBACCESS_UPLOAD_DIRECTORY

If you want a special upload directory used for this OS4X Webaccess instance, you can configure it here.

This feature is mainly used when installing OS4X Webaccess on a remote server (i.e. remote co-location). The same directory name must exist on the host running the OS4X client daemon for job generation. In most common cases, this is done by mounting the same directory with the exact name from the remote server on the host running the OS4X client daemon.

MySQL TLS connection parameters

Since OS4X release 2021-08-10, encrypted database connections are supported. MySQL started with version 5.7 to support encrypted connections via TLS. Please follow their online documentation about valid configuration values for i.e. protocols and cipher support: https://dev.mysql.com/doc/refman/en/encrypted-connection-protocols-ciphers.html TLS secured connections are only available over network links, not via socket file. Use the IP address "127.0.0.1" instead of "localhost" if you want to connect via TLS to your local database. Beware that you may need to open listener ports in your database server.

DB_TLS_VERSION

Required: The variable DB_TLS_VERSION defines an optional description of the used communication encryption standard, which is provided in the MySQL/MariaDB handshake. The following values are possible:

• TLSv1
• TLSv1.1
• TLSv1.2
• TLSv1.3

or a mix of it, like:

• TLSv1.2,TLSv1.1,TLSv1

DB_TLS_CIPHER

Required: If you want to use encrypted database connections, you have to define any supported cipher. Refer to the list of supported ciphers of your database server.

DB_TLS_KEY

Optional: The absolute path to your readable key file.

DB_TLS_CERT

Optional: The absolute path to your readable certificate file in PEM format.

DB_TLS_CA

Optional: The absolute path to your CA chain certificate file in PEM format.

DB_TLS_CAPATH

Optional: The absolute path where allowed CA chain elements are saved as PEM formatted files, linked against their hash of the subject. Copied from the manpage https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_default_verify_paths.html:

If CApath is not NULL, it points to a directory containing CA certificates in PEM format. The files each contain one CA certificate. The files are looked up by the CA subject name hash value, which must hence be available. If more than one CA certificate with the same name hash value exist, the extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search is performed in the ordering of the extension number, regardless of other properties of the certificates. Use the c_rehash utility to create the necessary links.

Examples

The following examples show various settings: locale and remote databases, socket connects, the possible database types and persistant connections.

local MySQL server via socket

DB_HOST=localhost
DB_USER=os4x
DB_PASS=os4x
DB_NAME=os4x
DB_SOCKET=/var/lib/mysql.sock
DB_PORT=3306
TABLEPREFIX=os4x_
MYSQLCLIENT=/usr/local/mysql/bin/mysql

remote MySQL server and remote OS4X client daemon, using a different upload directory

DB_HOST=192.168.1.23
DB_USER=os4x
DB_PASS=os4x
DB_NAME=os4x
DB_PORT=3306
TABLEPREFIX=os4x_
MYSQLCLIENT=/usr/local/mysql/bin/mysql
CLIENTD_OVERRIDDEN_HOST=192.168.21.2
WEBACCESS_UPLOAD_DIRECTORY=/opt/os4x/upload_remote_location

remote DB2

DB_HOST=db2
DB_USER=db2inst1
DB_PASS=db2
DB_NAME=swan_hl
DB_PORT=50000
TABLEPREFIX=os4x_
DBTYPE=DB2

remote DB2 with persistant connections and configured server ID

DB_HOST=db2
DB_USER=db2inst1
DB_PASS=db2
DB_NAME=swan_hl
DB_PORT=50000
TABLEPREFIX=os4x_
DBTYPE=DB2
DB_PERSISTANT_CONNECTION=1
SERVERID=5