Chapter 3. Server Configuration

LogicBlox services can be configured by various config files and with command-line parameters. In general, default configurations are provided within config files that are located in the LogicBlox installation directory (eg., /opt/logicblox). These configuration files should not be changed. Instead, the configuration files under $LB_DEPLOYMENT_HOME/config should be used to override default configurations. If $LB_DEPLOYMENT_HOME is not set, it defaults to $HOME/lb_deployment.

In the following we explain the configuration options for the LogicBlox server components in turn.

3.1. lb-server

The configuration files for lb-server are $LOGICBLOX_HOME/config/lb-server.config and $LB_DEPLOYMENT_HOME/config/lb-server.config. The latter overwrites the default settings specified in the former file. Furthermore, command-line options that are provided when launching the server do overwrite settings in configuration files.

The config file is in a standard ini format structured in sections in which properties are assigned specified values. An example configuration is the following:

[server]
port=5518
adminPort=5519

[workspace]
folder=$LB_DEPLOYMENT_HOME/workspaces

[logging]
file=$LB_DEPLOYMENT_HOME/logs/current/lb-server.log
level=info

To illustrate the customization of these settings: if the configuration file $LB_DEPLOYMENT_HOME/config/lb-server.config contains only the following adjustment of the logging level, then only this setting is customized to perf. For all other settings the defaults specified in $LOGICBLOX_HOME/config/lb-server.config are used.

[logging]
level=perf

In the following, we list configurable properties categorized by the section of the file they occur in.

server

port

Specifies the TCP port on which lb-server is listening. Default: 5518.

adminPort

Specifies the TCP port on which lb-server is listening for admin-commands such as lb status. Default: 5519.

unix_domain_socket

Configures lb-server to listen on the specified Unix domain socket instead of on the regular TCP ports. The lb tool can be used to connect to a unix-domain socket via lb -u /path/to/socket. By default, lb-server listens on TCP ports.

suppress_task_parallelism

When suppress_task_parallelism is set to any value, then the server will not evaluate different rules in parallel. We do not recommend that task parallelism is disabled, but it can be useful for performance analysis. Without task parallelism the duration of separate rules can be measured better and the log is easier to understand. Note that disabling task parallelism does not disable domain parallelism, where a single rule is evaluated in parallel over subsets of the data.

suppress_domain_parallelism

When suppress_domain_parallelism is set to any value, then the server will not evaluate individual rules in parallel by subsetting the data and executing the subsets individually. We do not recommend that domain parallelism is disabled, but it can be useful for performance analysis. It can also be useful in certain high-concurrency situations, where server resources are already maximized. Note that disabling domain parallelism does not disable task parallelism, where different rules are evaluated in parallel.

workspace

folder

Specifies the root folder where all workspace (=database) data is stored. Ideally, this should be on an SSD device with plenty of free space. Default: $LB_DEPLOYMENT_HOME/workspaces.

commit_mode

Default transaction commit mode. Allowed values are diskcommit (the commit doesn't return until the transaction has been durably written to disk) and softcommit (the commit may return before the transaction has been written to disk, so in case of a crash the database may roll back to a previous version). The commit mode can be overriden per transaction using lb's --commit-mode option. Default: softcommit.

replication_mode

Whether transactions are replicated synchronously. (See Section 5.4, “Replication” for information about replication.) If set to synchronous, a disk commit won't return until the transaction has been durably replicated to all connected mirrors. If set to asynchronous, a disk commit may return before the transaction has been replicated.

auto_backup_mode

Versions of the database are automatically tagged for backup and investigation purposes. If set to none, then this facility is disabled. If set to default, then upto 64 database versions are continuously kept according to a strategy that gradually keeps less versions around as the versions get older (a chart of version numbers vs the log of the age of the version will roughly be a straight line). Default: default.

workspace:wsname

You can override the workspace properties listed above (except folder) per workspace by adding a section named workspace:wsname, where wsname is the name of the workspace. For example, the following states that the default commit mode shall be diskcommit for every workspace except foo:

[workspace]
commit_mode=diskcommit

[workspace:foo]
commit_mode=softcommit

logging

file

Specifies the log file location. If file already exists, log data will be appended. This option is not used when systemd is set or inferred to true. The special value - can be used to log to stdout (which only makes sense if the server is not run as a daemon). Default: $LB_DEPLOYMENT/logs/current/lb-server.log.

systemd

If true, log to stderr, use systemd log levels (e.g. <3>) and omit timestamps. If not explicitly set, then the value is inferred from environment variables that are set in the systemd units that we provide.

level

Specifies the default logging level. Allowed logging levels are: error, warning, info, perf, and debug. For a typical deployment scenario, use level=info. To diagnose performance issues, use level=perf. For debugging LogiQL rules, use level=debug.

More fine-grained control can also be achieved by specifying log-scope specific settings. For instance, to use info-level logging by default, but debug-level logging under rule evaluation, one can specify level=info:debug@EvaluateRules.

The log level can also be specified on a per-transaction basis, with the log returned for a transaction at the specified level. The following command will, for example, evaluate the request under the perf level:

lb addblock testworkspace 'x(x)->string(x).' -L --loglevel perf
monitor_rule_time

Specifies the duration in milli-seconds beyond which rules will be logged as long-running. The system will log (at warning level) all rules which take longer to execute. By default, the threshold is 10000 ms. This value can also be adjusted using the environment variable LB_MONITOR_RULE_TIME.

compiler

jvmArgs

Specifies the default JVM arguments for the compiler. Unless jvmServerArgs is set, this is used for both separate compilation and the compiler server. Otherwise, this only applies to separate compilation. Default: -Xmx2000m -Xss2048k.

jvmServerArgs

Specifies the JVM arguments for the lb-compiler server. If this setting is not specified, then jvmArgs is used for the compiler server.

port

Specifies the TCP port on which the compiler is listening. Default: 5520.

adminPort

Specifies the TCP port on which the compiler is listening for admin requests. Default: 5521.

3.2. lb-web

Configuration of lb-web is more complex as it includes security aspects like defining SSL endpoints and configuring user authentication. Available configuration options and suggestions for common configuration scenarios are detailed in the Reference Manual.

3.3. Environment Variables

The following environment variables can be used alongside configuration files to influence aspects of the LogicBlox platform. In general LogicBlox environment variables have the prefix LB_.

3.3.1. Location Of Components

The following variables specify where various components of the LogicBlox platform and dependencies are installed. They are usually set up by sourcing etc/profile.d/logicblox.sh in the LogicBlox directory.

LOGICBLOX_HOME Directory where LogicBlox is installed. For example, /usr/local/logicblox-4.
JAVA_HOME Variable can be used to select a specific Java installation. If not set, the system's standard Java is used.
LB_WEBSERVER_HOME Directory where the lb-web component is installed. Usually, this is in $LOGICBLOX_HOME/lb-web.
LB_WORKFLOW_HOME Directory where the lb-workflow component is installed. Usually, this is in $LOGICBLOX_HOME/lb-workflow.
LB_MEASURE_SERVICE_HOME Directory where the lb-measure service component is installed. Usually, this is in $LOGICBLOX_HOME/measure-service.
LB_WORKBOOK_SERVICE_HOME Directory where the lb-workbook-service component is installed. Usually, this is in $LOGICBLOX_HOME/lb-workbooks.
LB_LIBRARY_PATH Specifies a colon-separated list of directories that are searched for LogiQL libraries. Defaults to $LB_WEBSERVER_HOME/share:$LB_MEASURE_SERVICE_HOME/share.

3.3.2. Configuration Variables

LB_DEPLOYMENT_HOME Directory where workspaces, configuration files, log files, etc. are stored. If not set, this defaults to $HOME/lb_deployment.
LB_LOGDIR Overwrite directory where log-files are written to. Defaults to $LB_DEPLOYMENT_HOME/logs.
LB_TEMPDIR Overwrite directory where temporary files are written to. Defaults to the operating system temporary directory (such as /tmp in Linux).
LB_MEM The LB_MEM variable is used to specify the amount of physical memory to be used by the lb-server for the page buffer pool. The value can be given as a percentage, in megabytes or gigabytes. For example, valid settings are 80% specifying that 80% of the main memory can be used; or 10G or 12500M specifying that 10 GiB or 12500MiB should be used respectively. By default, a heuristic is used which selects little more than half of the available main memory after setting aside 1GB; For machines with more than 32GB of memory, proportionally more memory is used.
LB_PRODUCTION_ENVIRONMENT Should be set to 1 in production environments. Will prevent lb-server from launching lb-compiler if not currently running. In production environments, these devices should be managed by the operating system. This will also suppress logging of some warning messages that are useful only during the development of an application.
LB_CONNECTBLOX_ADMIN When set to 1, workspaces can be deleted via lb and other tools connecting to the lb-server directly without authentication. In production environments, non-trusted clients should not be allowed to directly access the lb-server; this option is thus often enabled.
LB_WEBCLIENT_JVM_ARGS Can be used to configure the JVM arguments of all lb web-client invocations. Example value: -Xmx200m.
LB_WARNING_OPT_LIMIT The runtime may issue warnings called "optional warnings": if the number of such warnings exceeds a limit of ca. 100 per second, then they are suppressed until sufficient time elapses to start showing them again. This environment flag may be set to a value that changes the limit of optional warnings per second. For example, LB_WARNING_OPT_LIMIT=1 will allow only one such warning per second, while LB_WARNING_OPT_LIMIT=0 will suppress them altogether.