oml2-server(1)

Store SQLite3 measurement databases for all experiments in the specified directory, when the SQLite3 backend is selected. The default on this system is /usr/local/var/oml2. --data-dir overrides the OML_SQLITE_DIR environment variable. If oml2-server is run with an effective user id that does not have the right to create files in the directory, the server will exit with an error message in its log file. The SQLite3 database file name for an experiment is chosen by appending the suffix ".sq3" to the experiment name.

Specify an external hook program to call on specific events. This hook should take commands on stdin, and write reports on stdout. The hook’s stderr is the same as the oml2-server's. When first started, it should identify itself to the oml2-server by printing the following banner line.

OML HOOK READY

Listen for measurement client connections on the given port. The default port is 3003.

Try to change the server’s user id and group id before starting to serve clients. OML only needs access to a single directory in which it has the right to create the SQLite3 experiment database files, plus the right to open and write to its log file (creating it if necessary). The --user and --group options allow the system administrator to run oml2-server under a non-privileged account, thereby lessening its potential as a security risk. If only --user is given, the gid will be set to the primary group id for the given user. --user and --group accept user and group names as arguments; numeric user and group ids are not supported.

Set the verbosity of log output to level. The level should be an integer from 1 to 4 (1=ERROR, 2=WARNING, 3=INFO, 4=DEBUG). The default log verbosity is 3, INFO.

Set the time, in seconds, after which an idle (i.e., not receiving data) client socket is reaped. This is useful to preserve system resources in the case of long running experiments, intermittent reporting or faulty reporting nodes or network. Defaults to 60s.

Output log messages to file rather than stderr.

Select which database backend to use for storing experiment databases. The default is sqlite which stores databases as SQLite3 files. The other option is postgresql which will attempt to connect to a PostgreSQL database server.

Specify the database server to which the PostgreSQL backend should connect. Defaults to localhost.

Specify the database server port to which the PostgreSQL backend should connect. Values from /etc/services suitable for getservbyname(3) are also accepted. Defaults to postgresql (i.e., use PostgreSQL’s default, which is usually 5432).

Specify the PostgreSQL database user to use when the PostgreSQL backend is selected. The specified user must have the PostgreSQL CREATEDB role so that it can create a new database for each new experiment. Defaults to oml.

$ createuser -U postgres --pwprompt --no-superuser --createdb --no-createrole --no-replication oml

$ psql -U DBADMIN
psql (9.3.2)
Type "help" for help.

DBADMIN=# CREATE USER oml WITH PASSWORD 'oml';
CREATE ROLE
DBADMIN=# ALTER ROLE oml WITH CREATEDB;
ALTER ROLE

Specify the password of the pg-user to connect to the PostgreSQL backend. Defaults to the empty string.

For the PostgreSQL backend, this option gives a way to control the database authentication scheme to use. It is passed to the PostgreSQL connection API with the user name and database name appended. For instance, for an experiment named "myexp" and --pg-user=oml2, a conninfo string of "host=postgres.example.net password=secret" will result in the following being passed to the server:

host=postgres.example.net password=secret user=oml2

oml2-server --pg-user=oml2 "--pg-connect=host=postgres.example.net password=secret"

Write log messages to file.

Print a brief usage message.

Print the version number of oml2-server.

Print a summary of options.

These options control the reporting of runtime metrics over OML. They are documented in liboml2(1). The avaialble MPs are documented in section RUNTIME MEASUREMENT POINTS, below.

This measurement point records client events, and reports their address, remote port, OML node_id, experimental domain, appname, as well as the observed event (e.g., connection or disconnection), and a potential message.

Command the hook to cleanup and terminate. This command has no argument.

New database uri (see DATABASE URI SCHEMES below) has been created ("New" here means that the database didn’t have a start_time metadatum; this is an idiosyncracy of the current code, but this essentially behaves as one would expect). Tasks such as giving permissions to specific user groups can be performed in response to this event.

Database uri was re-opened.

The last client for database uri has now exited and cleanup tasks on the data can be performed.

Create SQLite3 experiment measurement databases in this directory. This environment variable is overridden by the --data-dir command line option.

Log an information message reporting the status of its allocated memory

Gracefully terminate, emptying the buffers and closing client connections.