Configuration

Sirveo is configured via a configuration file, command-line options, or environment variables. If you have access to the binary, the CLI interface is well-documented. See:

$ sirveo --help
$ sirveo server --help

Care is taken that all settings have associated environment variables.

Precedence

When using multiple configuration methods, the following precedence applies:

• CLI options (always wins)
• Environment variables
• Configuration file
• Default values

EULA Acceptance

CLI	Environment variable	Default	Note
--eula-accept	SIRVEO_EULA_ACCEPT	no	Requires a yes value

The EULA is also available via the sirveo legal --eula command.

Logging

CLI	Environment variable	Default	Note
--log-level	SIRVEO_LOG_LEVEL	INFO	[TRACE, DEBUG, INFO, WARN, ERROR ]

Configuration File

CLI	Environment variable	Default	Note
--config-file	SIRVEO_CONFIG_FILE	n/a	See command $ sirveo default-config

To generate a default configuration file, use these commands:

sirveo generate-config > /etc/sirveo/config.json
sirveo generate-config --yml > /etc/sirveo/config.yml
sirveo default-config --help

License

CLI	Environment variable	Default	Note
--license	SIRVEO_LICENSE	none

See licensing for details.

Database

CLI	Environment variable	Default	Note
--db-type	SIRVEO_DB_TYPE	postgres	Only postgres supported
--db-host	SIRVEO_DB_HOST	localhost	Database host address
--db-port	SIRVEO_DB_PORT	5432	Database host port
--db-name	SIRVEO_DB_NAME	sirveo	Database name
--db-user	SIRVEO_DB_USER	admin	Database username
--db-password	SIRVEO_DB_PASSWORD	changeme	Database password
--db-sslmode	SIRVEO_DB_SSLMODE	prefer

The following options are supported by SIRVEO_DB_SSLMODE:

• disable
• allow
• prefer
• require
• verify-ca
• verify-full

Default System User

If enabled, and no user accounts exists on start-up, create a default user account on start-up with these credentials.

CLI	Environment variable	Default	Note
--create-default-user	SIRVEO_CREATE_DEFAULT_USER	false
--default-username	SIRVEO_DEFAULT_USERNAME	admin
--default-password	SIRVEO_DEFAULT_PASSWORD	sirveoadmin

Tip

If --create-default-user is false upon first start-up, no user accounts are created.

Networking

For separating the server’s admin and inbound ports, see network isolation.

HTTP

CLI	Environment variable	Default	Note
--listen-address-admin	SIRVEO_LISTEN_ADDRESS_ADMIN	127.0.0.1:7001
--listen-address-inbound	SIRVEO_LISTEN_ADDRESS_INBOUND	127.0.0.1:7005
--enable-cors	SIRVEO_ENABLE_CORS	false

Sirveo serves it’s admin UI and API on port 7001 by default.

A second port (“inbound”) exposes only flow related features - without the admin UI - on port 7005 by default. This feature is to achieve network separation between public-facing flow/link/webhook URLs, and the administration UI, where/if desired.

To disable the inbound port, set SIRVEO_LISTEN_ADDRESS_INBOUND to an empty string.

If CORS is enabled, the HTTP servers for admin and inbound ports are permissive to CORS requests from browsers.

Caution

SIRVEO_ENABLE_CORS is used for testing in local environments, and should not be used otherwise. This setting will soon be replaced by detailed CORS configuration options.

Note

To bind on all network interfaces, use 0.0.0.0:7001

Client IP Headers

Note

It is important to configure these settings appropriately for your deployment scenario.

CLI	Environment variable	Default	Note
--ip-header-admin string	SIRVEO_IP_HEADER_ADMIN	none
--ip-header-inbound string	SIRVEO_IP_HEADER_INBOUND	none

These settings determine how Sirveo obtains the client IP address of incoming HTTP requests. Resolving the correct client IP’s are important in two places:

• Sirveo logs successful and failed authentications as system events, which contains the client IP address
• Sirveo provides the client IP address to flows, via webhooks and links.

Sirveo is (usually) deployed behind a reverse proxy, in which case the remote IP address of incoming HTTP requests will be the IP of the reverse proxy itself. This is the “real” or “bare” TCP address.

The reverse proxy should be forwarding the upstream client IP address in an HTTP header; typically X-Forward-For, but sometimes provider-specific headers like Do-Connecting-Ip or CF-Connecting-IP. Since IP headers can be spoofed, Sirveo does not trust standard headers, and this behaviour must be explicitly configured, for both admin and inbound HTTP ports (if the latter is enabled).

This value of these settings should be the name of the HTTP request header that contains the upstream client IP address. If the header value contains multiple IP addresses, the left-most IP address is assumed to be the client IP address.

For example, if a Sirveo deployment is behind a reverse proxy or upstream load balance that is configured place the client IP address in a X-Real-Ip request header, and it forwards requests to Sirveo on the inbound port, configure:

SIRVEO_IP_HEADER_INBOUND="X-Real-Ip"

For webhooks and links, request headers are provided as part of flow input data, and can therefore be inspected in flows.

Tip

To test how Sirveo resolves client IP’s, the simplest way is:

• Log in to the UI
• Use the event browser to find the most recent auth.ok system event

Then inspect the event’s data (click on it) to make sure the value is correct.

Note

If a configured Header is not present, Sirveo will fall back to the remote IP that initiates the TCP connection to its HTTP port(s).

External Access

CLI	Environment variable	Default	Note
--url-admin string	SIRVEO_URL_ADMIN	http://127.0.0.1:7001
--url-inbound string	SIRVEO_URL_INBOUND	http://127.0.0.1:7005

Sirveo is typically run behind a reverse proxy, or within a container. These settings tell the server about it’s public/external URLs. The management UI obtains these settings via API, so that certain URLs may be displayed correctly.

For example, if Sirveo’s admin interface listens on 0.0.0.0:7001 inside a Docker container, but it is exposed at https://sirveo.mydomain.io, then you would use:

SIRVEO_LISTEN_ADDRESS_ADMIN="0.0.0.0:7001"
SIRVEO_URL_ADMIN="https://sirveo.mydomain.io"

API Authentication

SIRVEO_JWT_EXPIRY

CLI --jwt-expiry
Config file key jwt_expiry
Default 4h

Determines the expiry time of JWTs issued by the server’s API. Accepts values between 15m and 168h (7 days).

SIRVEO_JWT_SIGNING_SECRET

CLI --jwt-signing-secret
Config file key jwt_signing_secret
Default none

Configures the signing secret used to sign authentication tokens issued by the server’s API. JWTs are signed with HMAC using SHA-512.

If configured, it must contain a hex-encoded value that contains at least 32 bytes, or up to and including 64 bytes. You can generate an appropriate value with OpenSSL:

$ openssl rand -hex 64
6d0851c14b977213af9b3aca3b0795c4826ac5e5a3ad50429436943abbc...

If not provided, the server generates a random 64-byte value when it starts. This behaviour will invalidate any existing JWTs, and require users to re-authenticate on the UI. For this reason, it is usually preferable to configure this value.

Data Retention

SIRVEO_RETENTION_PERIOD_SCHEDULES

CLI --retention-period-schedules
Config file key retention_period_schedules
Default 24h

Completed schedule trigger data will be deleted after this period. Accepts durations like 30m (minutes) or 72h (hours). Setting value to empty string disables retention.

What is “completed” schedule trigger data? Schedule trigger entries which:

• Was created with a schedule node in a flow (not user-defined, cron-based schedules)
• Has executed their target flows (with or without errors)

If enabled (value is not ""), this cleanup process runs when the server synchronizes its internal scheduler, which happens at least every 5 minutes.

Example

Using a value of 48h;

• At T0, flow A runs and creates a new schedule trigger to execute flow B, with a delay of 1h.
• At T1, which is 1h later, the scheduler runs flow B, and the schedule trigger entry is marked as completed.
• At T2, about 48h later, the server deletes the completed schedule trigger entry, which was created in T0, and completed in T1.

In effect, you will have 48h in which to inspect once-off scheduler triggers created by your flows, after those triggers were executed.

SIRVEO_RETENTION_PERIOD_EVENTS

CLI --retention-period-events
Config file key retention_period_events
Default 720h (30 days)

Event data will be deleted after this period. Accepts durations like 30m (minutes) or 72h (hours). Setting value to empty string disables retention.

Telemetry

Important

Please read the telemetry reference before changing these settings.

Do not configure SIRVEO_TELEMETRY_MODE to default or both unless you want to enable sharing opt-in telemetry with us.

The following settings are used to configure and enable telemetry to a custom destination;

Setting	default	note
SIRVEO_TELEMETRY_MODE	disabled	accepts disabled, custom, default, both
SIRVEO_TELEMETRY_URL	none	the destination URL. Required for custom and both
SIRVEO_TELEMTRY_AUTH	none	optional value for bearer token authentication
SIRVEO_TELEMETRY_FREQUENCY	8h	accepts values between 1h and 24h
SIRVEO_TELEMETRY_IDENTIFIER	none	an optional name for the server, for custom mode

Other

CLI	Environment variable	Default	Note
--data-dir	SIRVEO_DATA_DIR	n/a	*

* Data directory, which is unused at this time. Sirveo has no filesystem side-effects.