Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Server Configuration Reference

The Flopsar Server is configured through a single file, settings.toml, written in TOML. This page documents every option the file accepts, its type, its default value, and the formats it understands, together with the environment variables that affect how the server starts.

File location and generation

By default the server reads settings.toml from /etc/flopsar/.

A settings.toml populated with the default values can be generated by the server, which is the recommended starting point for a new deployment. Every option below is shown with the default that this generated file contains, so that you only need to change the values relevant to your environment.

Options that are omitted from the file fall back to their default value. You do not need to specify every option; a minimal file that sets only the data directory, the certificate paths, and the master key is sufficient for a working deployment.

How paths are resolved

Three options accept file paths: ssl.cert, ssl.key, and master_key.value (when the provider is file). Each is resolved as follows:

  • An absolute path (one beginning with /) is used as-is.

  • A relative path is resolved relative to an ssl subdirectory located next to the settings.toml file. For example, with the default cert = "server.crt", the server looks for <config-directory>/ssl/server.crt.

Value formats

Several options use string-encoded values with specific formats:

  • Byte sizes (max_ext_size, logger.max_size) are written as a number and a unit, for example "1.00 MiB", "512.00 KiB", or "50.00 MiB". Binary units (KiB, MiB, GiB) are supported.

  • Durations (req_timeout, archive.retention) use a human-readable format, for example "3m", "90s", "72h", or "3days".

  • Time of day (archive.start_at) uses a 24-hour HH:MM:SS format with an optional fractional part, for example "03:00:00.0".

  • IP addresses (*.server_ip) are IPv4 literals; "0.0.0.0" binds to all IPv4 interfaces.

  • Booleans are the TOML literals true and false.

Environment variables

Three environment variables affect server startup independently of settings.toml:

  • FLOPSAR_HOME — the path to the server's data directory, where collected data is stored. This determines where the server reads and writes its working data.

  • FLOPSAR_EULA — must be set to accept for the server to start. This records acceptance of the Flopsar End-User License Agreement, available at https://eula.flopsar.com. If it is not set to accept, the server refuses to start.

  • The master key environment variable — when master_key.provider is env, the variable named by master_key.value must contain the master key as 64 hexadecimal characters. See Master key.

General options

These options appear at the top level of the file, before any [section] header.

name

  • Type: string

  • Default: "My environment"

A human-readable name for this Flopsar environment, shown in the workstation. Use it to distinguish environments, for example "Production" or "Staging".

xstack_maxsize

  • Type: integer

  • Default: 3000

The maximum size of the execution stack retained per monitored transaction. Larger values capture deeper call trees at the cost of more memory and storage. Lower it if agents report very deep stacks that you do not need to retain in full.

req_timeout

  • Type: duration string

  • Default: "3m"

The timeout applied to requests handled by the server. Requests that exceed this duration are aborted.

max_ext_size

  • Type: byte-size string

  • Default: "1.00 MiB"

The maximum size of a plugin jar file that the server will accept and store.

[master_key]

The master key protects sensitive data managed by the server. Protecting this key is the operator's responsibility; see Cryptography & Key Management for the full procedure for generating, storing, backing up, and rotating it.

provider

  • Type: string, one of file or env

  • Default: file

Determines where the server reads the master key from. With file, the key is read from the file named by value. With env, the key is read from the environment variable named by value.

value

  • Type: string

  • Default: "master.key"

When the provider is file, this is the path to the key file, resolved as described in How paths are resolved; the file must contain exactly 32 bytes. When the provider is env, this is the name of the environment variable that holds the key, which must contain 64 hexadecimal characters (32 bytes).

[agent]

The endpoint on which the server listens for connections from Flopsar agents.

server_ip

  • Type: IP address

  • Default: "0.0.0.0"

The address on which the server listens for agent connections. The default binds to all IPv4 interfaces.

server_port

  • Type: integer (1–65535)

  • Default: 9000

The TCP port on which the server listens for agent connections.

[ui_srv]

The endpoint that serves the HTTPS API and the Flopsar Workstation.

server_ip

  • Type: IP address

  • Default: "0.0.0.0"

The address on which the API and workstation are served.

server_port

  • Type: integer (1–65535)

  • Default: 9443

The TCP port on which the API and workstation are served.

ssl

  • Type: boolean

  • Default: true

Whether the API and workstation endpoint uses TLS. Leaving this enabled is strongly recommended; the certificate and key are configured in the [ssl] section.

[otlp]

Settings for OpenTelemetry (OTLP) ingestion. The server can receive telemetry over both HTTP and gRPC.

enable

  • Type: boolean

  • Default: true

Whether OTLP ingestion is enabled at all. When set to false, neither the HTTP nor the gRPC OTLP endpoint is opened, which reduces the server's attack surface if you do not use OTLP.

[otlp.http]

The OTLP/HTTP endpoint.

  • server_ip — IP address. Default "0.0.0.0".

  • server_port — integer. Default 4318.

[otlp.grpc]

The OTLP/gRPC endpoint.

  • server_ip — IP address. Default "0.0.0.0".

  • server_port — integer. Default 4317.

  • ssl — boolean. Default false.

Security note. otlp.grpc.ssl defaults to false, meaning the OTLP/gRPC endpoint is unencrypted by default. For any deployment where OTLP traffic leaves the host or crosses an untrusted network, enable TLS on this endpoint. See Hardening Checklist.

[ssl]

The certificate and private key used for TLS on the API/workstation endpoint.

cert

  • Type: string (path)

  • Default: "server.crt"

Path to the PEM-encoded server certificate, resolved as described in How paths are resolved.

key

  • Type: string (path)

  • Default: "server.pem"

Path to the PEM-encoded private key, resolved as described in How paths are resolved. Protect this file with restrictive filesystem permissions.

[logger]

Server logging configuration. For the distinction between operational logs and the security audit log, see [audit] and Logging, Monitoring & Audit Trail.

backend

  • Type: string, one of Local or Syslog

  • Default: Local

Where logs are written. Local writes to local, rotating log files. Syslog forwards logs to the system syslog facility, which is the recommended option when forwarding to a SIEM.

max_size

  • Type: byte-size string

  • Default: "50.00 MiB"

The maximum size of a single log file before it is rotated. Applies to the Local backend.

max_files

  • Type: integer

  • Default: 5

The number of rotated log files to retain. Applies to the Local backend.

[audit]

enabled

  • Type: boolean

  • Default: true

Whether the security audit log is enabled. When enabled, the server records security-relevant events such as logins, permission changes, and configuration changes. Keeping this enabled is recommended and supports the logging requirement described in Logging, Monitoring & Audit Trail.

[archive]

Controls automatic retention management of stored data. The procedure runs once per day at the configured time.

enable

  • Type: boolean

  • Default: false

Whether the daily retention procedure runs. When false, data is retained indefinitely and must be managed by other means.

policy

  • Type: string, one of purge or archive

  • Default: purge

What the retention procedure does with data older than the retention period. purge permanently deletes it. archive writes it to a dated ZIP file in the data directory's archive folder before removing it from the live store.

start_at

  • Type: time-of-day string

  • Default: "03:00:00.0"

The local time of day at which the daily retention procedure runs.

retention

  • Type: duration string

  • Default: "72h"

Data older than this duration is purged or archived when the procedure runs. For example, "3days" or "168h". Setting an appropriate retention period supports the data-minimization and storage-limitation considerations described in Privacy & Data Handling.

[compression]

Controls compression of stored data.

parameters

  • Type: boolean

  • Default: false

Whether captured parameter data is compressed before storage.

exceptions

  • Type: boolean

  • Default: false

Whether captured exception data is compressed before storage.

[pass_policy]

The password policy applied to local user accounts. When disabled, no complexity requirements are enforced.

Where authentication is delegated to an external identity provider over LDAP, the provider's own policy applies instead. See Authentication and Hardening Checklist.

enable

  • Type: boolean

  • Default: true

Whether the password policy is enforced. When false, the remaining options in this section have no effect.

min_len

  • Type: integer

  • Default: 7

The minimum number of characters a password must contain.

digits

  • Type: boolean

  • Default: false

Whether a password must contain at least one digit.

capital_letters

  • Type: boolean

  • Default: false

Whether a password must contain at least one uppercase letter (A–Z).

special_chars

  • Type: boolean

  • Default: false

Whether a password must contain at least one special character — that is, a character that is neither alphanumeric nor whitespace.

forbidden_chars

  • Type: string

  • Default: ""

A set of characters that a password must not contain. Each character in this string is forbidden. Leave empty to impose no character restrictions.

Complete example with default values

The following settings.toml shows every option at its default value. The data directory is supplied separately through the FLOPSAR_HOME environment variable, and EULA acceptance through FLOPSAR_EULA=accept.

Last updated