env_vars.md

<- Back to Index

Configuration Variables

All configuration variables can either be set directly via the command line as environment variables, or can be added to the config file config/lrsql.json as a JSON object property.

Logger

Env Var	Config	Description	Default
LRSQL_LOG_LEVEL	logLevel	The logging level to use. Can be ALL, TRACE, DEBUG, INFO, WARN, ERROR or OFF	INFO

Database

Env Var	Config	Description	Default
LRSQL_DB_TYPE	dbType	The DBMS that lrsql will use. Currently supports sqlite, and postgres/postgresql. The default value used depends on the main entry point used, e.g. lrsql.sqlite.main will use sqlite by default, so overriding the default is not recommended.	Varies
LRSQL_DB_NAME	dbName	The name of the database. Should be set to :memory: for SQLite in-memory mode.	example
LRSQL_DB_HOST	dbHost	The host that the database will run on. Not supported by SQLite.	0.0.0.0
LRSQL_DB_PORT	dbPort	The port that the database will run on. Not supported by SQLite.	5432 (PG)
LRSQL_DB_PROPERTIES	dbProperties	Optional additional DB properties. Must be a string of key-val pairs that follow URL query parameter syntax (e.g. key1=value1&key2=value2). Any & character not used as a separator must be percent encoded. Supported properties will depend on the DBMS.	Not set
LRSQL_DB_JDBC_URL	dbJdbcUrl	Optional JDBC URL; this will override the above properties if set. URL syntax will depend on the DBMS.	Not set
LRSQL_DB_USER	dbUser	The DB user. Optional.	Not set
LRSQL_DB_PASSWORD	dbPassword	The DB password. Optional.	Not set
LRSQL_DB_SCHEMA	dbSchema	The DB schema. Optional.	Not set
LRSQL_DB_CATALOG	dbCatalog	The DB catalog. Optional.	Not set

Connection

HikariCP Properties

The following environment variables are aliases for HikariCP properties. All of these variables (except for poolName) have default values that are already set, which may vary depending on the DBMS. All temporal values are in milliseconds.

Env Var	Config	Default	Valid Values
LRSQL_POOL_AUTO_COMMIT	poolAutoCommit	true	true/false
LRSQL_POOL_KEEPALIVE_TIME	poolKeepaliveTime	0†	≥ 10000 or 0, less than poolMaxLifetime
LRSQL_POOL_CONNECTION_TIMEOUT	poolConnectionTimeout	3000	≥ 250
LRSQL_POOL_IDLE_TIMEOUT	poolIdleTimeout	600000	≥ 10000 or 0
LRSQL_POOL_VALIDATION_TIMEOUT	poolValidationTimeout	5000	≥ 250, less than poolConnectionTimeout
LRSQL_POOL_INITIALIZATION_FAIL_TIMEOUT	poolInitializationFailTimeout	1	Any integer
LRSQL_POOL_MAX_LIFETIME	poolMaxLifetime	1800000 or 0**	≥ 30000 or 0
LRSQL_POOL_MINIMUM_IDLE	poolMinimumIdle	1* or 10***	≥ 0
LRSQL_POOL_MAXIMUM_SIZE	poolMaximumSize	1* or 10***	≥ 1
LRSQL_POOL_ISOLATE_INTERNAL_QUERIES	poolIsolateInternalQueries	false	true/false
LRSQL_POOL_LEAK_DETECTION_THRESHOLD	poolLeakDetectionThreshold	0†	≥ 2000 or 0
LRSQL_POOL_TRANSACTION_ISOLATION	poolTransactionIsolation	Not set	JDBC Connection constant (e.g. TRANSACTION_SERIALIZABLE)
LRSQL_POOL_NAME	poolName	Not set	Any string

* SQLite default. ** SQLite in-memory default. *** Postgres default. † The property is set to be disabled by default.

NOTE 1: SQLite uses different defaults for poolMinimumIdle and poolMaximumSize than Postgres due to issues with multi-threading with those DBMSs. Setting poolMaximumSize to values other than 1 will potentially cause exceptions when running concurrent operations.

NOTE 2: SQLite, while in in-memory mode, automatically deletes the database whenever the connection is removed, which can occur if a connection is closed and poolMaxLifetime is exceeded. Thus, poolMaxLifetime is set to 0, denoting infinite connection lifetime, for convenience.

NOTE 3: None of the DBMSs that SQL LRS currently supports allow for TRANSACTION_NONE as a poolTransactionIsolation value.

Metric Reporting via JMX

The following config var is to activate metrics reporting via JMX.

Env Var	Config	Description	Default
LRSQL_POOL_ENABLE_JMX	poolEnableJmx	Activate metrics reporting via JMX.	false

Unlike the previous vars, which are one-to-one with HikariCP properties, the following sets multiple such properties:

• registerMbeans is set in order to activate JMX reporting.
• allowPoolSuspension is set to true to allow for user control over connection pools.
• metricRegistry is set to be a Codahale/Dropwizard MetricRegistry instance.

Missing options?

You may have noted that some options are not available:

• connectionTestQuery is not recommended for JDBC4 (which all of our DBMS implementations use).
• readOnly will cause the SQL LRS to not work if set to true.
• connectionInitSql is set automatically by the SQL LRS system (e.g. to run pragmas in SQLite).
• driverClassName and dataSource would clash with SQL LRS's approach to setting the JDBC driver, which is via an URL.
• healthCheckRegistry cannot easily report via JMX, and most of its information should be covered by metricRegistry anyways.
• threadFactory and scheduledExecutor are Java instances that should only be used in specific execution environments.

Tuning

The following options are used for advanced database performance tuning and may affect DB schema and performance. Use with caution.

Env Var	Config	Description	Default
LRSQL_ENABLE_JSONB	enableJsonb	(Postgres Only) This option switches the JSON fields (including xapi_statment.payload) to JSONB datatype. Enabling this option increases the speed of some external JSON-based queries such as from a BI or reporting platform, but decreases statement write throughput. Be advised that changing this setting on a large existing database may result in a very long next startup time (possibly minutes) as all previous data gets converted.	false

LRS

Env Var	Config	Description	Default
LRSQL_ADMIN_USER_DEFAULT	adminUserDefault	The username of the account that seeds the account table, ie. added to the table upon initialization. Optional but should be set in order to create other accounts. NOTE: Not subject to username length and character requirements.	Not set
LRSQL_ADMIN_PASS_DEFAULT	adminPassDefault	The password of the account that seeds the account table. Optional but should be set in order to create other accounts. NOTE: Not subject to password length and character requirements. Please choose a secure password.	Not set
LRSQL_API_KEY_DEFAULT	apiKeyDefault	The public API key that seeds the credential table. Optional, and is ignored if no seed admin account is set.	Not set
LRSQL_API_SECRET_DEFAULT	apiSecretDefault	The secret API key that seeds the credential table. Optional, and is ignored if no seed admin account is set.	Not set
LRSQL_STMT_GET_DEFAULT	stmtGetDefault	The default limit value in a statement query. Queries default to this value if not explicitly set.	50
LRSQL_STMT_GET_MAX	stmtGetMax	The maximum allowed limit value for a statement query. If an explicit limit value exceeds this value, it will be overridden.	50
LRSQL_AUTHORITY_TEMPLATE	authorityTemplate	The filepath to the Statement authority template file, which describes how authorities are constructed during statement insertion. If the file is not found, the system defaults to a default authority function.	config/authority.json.template (Filepath)
LRSQL_AUTHORITY_URL	authorityUrl	The URL that is set as the authority-url value when constructing an authority from a template.	http://example.org
LRSQL_OIDC_AUTHORITY_TEMPLATE	oidcAuthorityTemplate	Like LRSQL_AUTHORITY_TEMPLATE, but only used when forming an authority from an OIDC access token.	config/oidc_authority.json.template (Filepath)
LRSQL_OIDC_SCOPE_PREFIX	oidcScopePrefix	An optional prefix prepended to OIDC scope. For example, setting this to lrs: would change the expected all scope to lrs:all	""
LRSQL_STMT_RETRY_LIMIT	stmtRetryLimit	The number of times to retry a statement post transaction before failing.	10
LRSQL_STMT_RETRY_BUDGET	stmtRetryBudget	The max amount of time allowed for statement POST transaction retries before failing (ms).	1000
LRSQL_ENABLE_REACTIONS	enableReactions	Whether or not to enable statement reactions.	false
LRSQL_REACTION_BUFFER_SIZE	reactionBufferSize	Number of pending reactions to allow. Additional reactions will be dropped with a warning message.	10000

NOTE: LRSQL_STMT_RETRY_LIMIT and LRSQL_STMT_RETRY_BUDGET are used to mitigate a rare scenario where specific Actors or Activities are updated many times in large concurrent batches. In this situation the DBMS can encounter locking and these settings are used to allow retries that eventually write all the conflicting transactions, but may incur performance degradation. If you are experiencing this situation the first step would be to look at why your data needs to rewrite specific Actors or Activities rapidly with different values, which could potentially solve it at the source. If the issue cannot be avoided by data design alone, another possible solution is reducing batch sizes to decrease or eliminate locks. As a last resort, increasing these settings will at least ensure the statements get written but as mentioned may incur a slowdown in concurrent throughput.

Webserver

Host & Ports

Env Var	Config	Description	Default
LRSQL_ENABLE_HTTP	enableHttp	Whether HTTP is enabled or not (as opposed to HTTPS, which is always enabled).	true
LRSQL_ENABLE_HTTP2	enableHttp2	Whether HTTP/2 is supported or not.	true
LRSQL_HTTP_HOST	httpHost	The host that the webserver will run on.	0.0.0.0
LRSQL_HTTP_PORT	httpPort	The HTTP port that the webserver will be open on.	8080
LRSQL_SSL_PORT	sslPort	The HTTPS port that the webserver will be open on.	8443
LRSQL_URL_PREFIX	urlPrefix	The prefix of the webserver URL path, e.g. the prefix in http://0.0.0.0:8080/xapi is /xapi. Used when constructing the more value for multi-statement queries. (Note: Only applies to LRS xapi endpoints, not admin/ui endpoints)	/xapi
LRSQL_PROXY_PATH	proxyPath	This path modification is exclusively for use with a proxy, such as apache or nginx or a load balancer, where a path is added to prefix the entire application (such as https://www.mysystem.com/mylrs/xapi/statements). This does not actually change the routes of the application, it informs the admin frontend where to look for the server endpoints based on the proxied setup, and thus must be used in conjunction with a third party proxy. If used, the value must start with a leading / but not end with one (e.g. /mylrs is valid, as is /mylrs/b but /mylrs/ is not). Use with caution.	Not Set

TLS/SSL Certificate

Env Var	Config	Description	Default
LRSQL_KEY_FILE	keyFile	The path to the Java Keystore file that contains the key pair and credentials, which are used for HTTPS as well as JWT signing and verification.	config/keystore.jks
LRSQL_KEY_ALIAS	keyAlias	The alias of the private key.	lrsql_keystore
LRSQL_KEY_PASSWORD	keyPassword	The password protecting the keystore. It is highly recommended that you override the default value.	lrsql_pass
LRSQL_KEY_PKEY_FILE	keyPkeyFile	Private key in PEM format	config/server.key.pem
LRSQL_KEY_CERT_CHAIN	keyCertChain	Comma separated PEM files for cert. See the TLS/HTTPS section below.	config/server.crt.pem,config/cacert.pem (Filepaths)
LRSQL_KEY_ENABLE_SELFIE	keyEnableSelfie	Boolean, whether or not to enable self-signed cert generation.	true

JWT Config

Env Var	Config	Description	Default
LRSQL_JWT_EXP_TIME	jwtExpTime	The amount of time, in seconds, after a JWT is created when it expires. Since JWTs are not revocable, this this time should be short (i.e. one hour or less).	3600 (one hour)
LRSQL_JWT_EXP_LEEWAY	jwtExpLeeway	The amount of time, in seconds, before or after the expiration instant when a JWT should still count as un-expired. Used to compensate for clock desync. Applied to both LRS and OIDC tokens.	1 (one second)
LRSQL_JWT_NO_VAL	jwtNoVal	(DANGEROUS!) This flag removes JWT Token Validation and simply accepts token claims as configured by the associated variables below. It is extremely unlikely that you need this as it is for very specific proxy-overwrite authentication scenarios, and it poses a serious threat to system security if enabled.	false
LRSQL_JWT_NO_VAL_UNAME	jwtNoValUname	(DANGEROUS! See LRSQL_JWT_NO_VAL) This variable configures which claim key to use for the username when token validation is turned off.	Not Set
LRSQL_JWT_NO_VAL_ISSUER	jwtNoValIssuer	(DANGEROUS! See LRSQL_JWT_NO_VAL) This variable configures which claim key to use for the issuer when token validation is turned off.	Not Set
LRSQL_JWT_NO_VAL_ROLE_KEY	jwtNoValRoleKey	(DANGEROUS! See LRSQL_JWT_NO_VAL) This variable configures which claim key to look in for the role when token validation is turned off.	Not Set
LRSQL_JWT_NO_VAL_ROLE	jwtNoValRole	(DANGEROUS! See LRSQL_JWT_NO_VAL) This variable configures what role must be present in the key above when token validation is turned off.	Not Set
LRSQL_JWT_NO_VAL_LOGOUT_URL	jwtNoValLogoutUrl	(DANGEROUS! See LRSQL_JWT_NO_VAL) This variable specifies a logout URL that the client will redirect to on user logout when token validation is turned off.	Not Set
LRSQL_JWT_COMMON_SECRET	jwtCommonSecret	This variable serves as a secret key with which JWTs are signed. If this is unspecified, sql-lrs generates its own key, but when running multiple instances of sql-lrs behind load balancer, they need to accept each others' JWTs, meaning they need to be working from a common key. This is a secret and should be secured as such. It should be between 32 and 64 characters.	Not Set

OIDC

This section is for optionally configuring OIDC Authentication/Authorization through a compatible third party access / identity management provider such as Keycloak. These variables have no effect if the first one, LRSQL_OIDC_ISSUER, is not set.

Env Var	Config	Description	Default
LRSQL_OIDC_ISSUER	oidcIssuer	OIDC Issuer address used for discovery. Will enable OIDC if present.	Not set
LRSQL_OIDC_AUDIENCE	oidcAudience	Optional OIDC audience for token claim verification.	Not set
LRSQL_OIDC_CLIENT_ID	oidcClientId	An optional OIDC client ID for the SQL LRS Admin SPA. If provided, along with the LRSQL_OIDC_ISSUER and LRSQL_OIDC_AUDIENCE variables, will enable OIDC access to the Admin UI.	Not Set
LRSQL_OIDC_CLIENT_TEMPLATE	oidcClientTemplate	An optional template to modify LRS Admin UI client OIDC configuration.	Not Set
LRSQL_OIDC_VERIFY_REMOTE_ISSUER	oidcVerifyRemoteIssuer	Verify on startup that the issuer in remote configuration matches LRSQL_OIDC_ISSUER.	true
LRSQL_OIDC_ENABLE_LOCAL_ADMIN	oidcEnableLocalAdmin	Whether or not to enable local administrative account authentication, login and management when LRSQL_OIDC_ISSUER is set.	false

ClamAV Virus Scanning

This section is for optionally configuring ClamAV antivirus scanning for inbound files.

Env Var	Config	Description	Default
LRSQL_ENABLE_CLAMAV	enableClamav	Whether or not to enable ClamAV antivirus scanning.	false
LRSQL_CLAMAV_HOST	clamavHost	ClamAV Daemon Host	localhost
LRSQL_CLAMAV_PORT	clamavPort	ClamAV Daemon Port	3310

CORS

Env Var	Config	Description	Default
LRSQL_ALLOW_ALL_ORIGINS	allowAllOrigins	Determines whether to enable CORS. When false, it will not allow all origins, it will only allow either LRSQL_HTTP_HOST (for both HTTPS and HTTP ports) or if LRSQL_ALLOWED_ORIGINS is set that will override.	false
LRSQL_ALLOWED_ORIGINS	allowedOrigins	This is a list of allowed origins which overrides the defaults. As an ENV it should be written as a comma separated list with no spaces. In JSON config it can be written directly as an array, e.g. ["http://myhost:myport", "https://anotherhost"]	Not Set

Browser Security Headers

These config vars enable and configure browser security response headers from the server. In all cases, not setting them results in no corresponding header, setting them to "[default]" results in a generic server default (specified below), and any other string manually overrides the header value.

Env Var	Config	Header Name	[default] value
LRSQL_SEC_HEAD_HSTS	secHeadHsts	Strict-Transport-Security	max-age=31536000; includeSubdomains
LRSQL_SEC_HEAD_FRAME	secHeadFrame	X-Frame-Options	DENY
LRSQL_SEC_HEAD_CONTENT_TYPE	secHeadContentType	X-Content-Type-Options	nosniff
LRSQL_SEC_HEAD_XSS	secHeadXss	X-Xss-Protection	1; mode=block
LRSQL_SEC_HEAD_DOWNLOAD	secHeadDownload	X-Download-Options	noopen
LRSQL_SEC_HEAD_CROSS_DOMAIN	secHeadCrossDomain	X-Permitted-Cross-Domain-Policies	none
LRSQL_SEC_HEAD_CONTENT	secHeadContent	Content-Security-Policy	object-src 'none'; script-src 'unsafe-inline' 'unsafe-eval' 'strict-dynamic' https: http:;

Admin Features

Env Var	Config	Description	Default
LRSQL_ENABLE_ADMIN_DELETE_ACTOR	enableAdminDeleteActor	Whether or not to enable the route and UI for deleting actors and related documents	false
LRSQL_ENABLE_ADMIN_UI	enableAdminUi	Whether or not to serve the administrative UI at /admin	true
LRSQL_ENABLE_ADMIN_STATUS	enableAdminStatus	Whether or not to serve admin system status data that queries the database.	true
LRSQL_ENABLE_STMT_HTML	enableStmtHtml	Whether or not HTML data is returned in the LRS HTTP response if the Accept type is specified as text/html. If false disables HTML rendering regardless of Accept type.	true
LRSQL_ADMIN_LANGUAGE	adminLanguage	Allows override of default RFC5646 language code (en-US). May require that you add new language map entries to resources/lrsql/localization/language.json to add a new language.	en-US

<- Back to Index