Systemd Service Settings
This appendix documents the systemd service configuration for the Posit Chronicle server and agent on Linux virtual machines. These settings control how Chronicle runs as a system service.
This documentation applies only to VM deployments. For Kubernetes deployments, use the official Helm chart instead.
Modifying service settings
Chronicle uses systemd service units to manage the server and agent as system services. To modify service settings, use the systemctl edit command. This command creates a drop-in override file:
Terminal
# Edit server service settings
sudo systemctl edit chronicle
# Edit agent service settings
sudo systemctl edit chronicle-agentThis opens an editor where you can add override settings in the following files: - /etc/systemd/system/chronicle.service.d/override.conf (server) - /etc/systemd/system/chronicle-agent.service.d/override.conf (agent)
After saving changes, restart the service to apply them:
Terminal
# Restart server
sudo systemctl restart chronicle
# Restart agent
sudo systemctl restart chronicle-agentServer service settings
The Chronicle server service is defined in /usr/local/lib/systemd/system/chronicle.service. The following settings can be customized using systemctl edit chronicle.
Memory limits
The server is configured with memory limits to prevent excessive resource consumption.
MemoryHigh
When the service exceeds this memory threshold, the kernel aggressively reclaims memory from the process. This setting provides a soft limit that allows temporary spikes while encouraging the process to stay within bounds.
Type: memory size (e.g., 512M, 2G)
Default: 2G
MemoryMax
The absolute maximum memory the service can use. If the service exceeds this limit, the kernel terminates it. This should be set higher than MemoryHigh to allow for some buffer.
Type: memory size (e.g., 1G, 3G)
Default: 3G
Example
### Editing /etc/systemd/system/chronicle.service.d/override.conf
[Service]
MemoryHigh=4G
MemoryMax=6GUser
User
The system user account under which the Chronicle server process runs. This user must have appropriate permissions to access the configuration file and data storage locations.
Type: string (username)
Default: posit-chronicle
The installation process automatically creates the posit-chronicle user. If you want to run chronicle using a different user account, you must create that user account.
Example
### Editing /etc/systemd/system/chronicle.service.d/override.conf
[Service]
User=custom-chronicle-userRestart behavior
Restart
Controls whether systemd should automatically restart the service if it exits. The always policy ensures the service restarts regardless of exit status, exit code, or whether it was stopped manually.
Type: string (no, always, on-success, on-failure, on-abnormal, on-abort, on-watchdog)
Default: always
Directories
StateDirectory
The directory name (relative to /var/lib/) where persistent state and data files are stored. Systemd creates this directory with appropriate permissions if it doesn’t exist.
Type: string (directory name)
Default: posit-chronicle
This results in data being stored at /var/lib/posit-chronicle/. The LocalStorage.Location configuration setting in the Chronicle configuration file can override this location.
See the Advanced Server Configuration appendix for details on the LocalStorage.Location setting.
RuntimeDirectory
The directory name (relative to /run/) for runtime files such as sockets and PID files. Systemd creates this directory on service start and removes it on service stop.
Type: string (directory name)
Default: posit-chronicle
Agent service settings
The Chronicle agent service is defined in /usr/local/lib/systemd/system/chronicle-agent.service. The following settings can be customized using systemctl edit chronicle-agent.
Memory limits
The agent is configured with lower memory limits than the server, as it typically requires fewer resources.
MemoryHigh
When the service exceeds this memory threshold, the kernel aggressively reclaims memory from the process.
Type: memory size (e.g., 256M, 512M)
Default: 512MB
MemoryMax
The absolute maximum memory the agent can use. If the agent exceeds this limit, the kernel terminates it.
Type: memory size (e.g., 384M, 768MB)
Default: 768MB
Example
### Editing /etc/systemd/system/chronicle-agent.service.d/override.conf
[Service]
MemoryHigh=256M
MemoryMax=384MUser
User
The system user account under which the Chronicle agent process runs.
Type: string (username)
Default: not set (runs as root)
By default, the agent runs as root to ensure it can read product configuration files. However, you can configure the agent to run as a non-root user if you provide the necessary configuration manually and ensure the user has appropriate permissions.
If you configure the agent to run as a non-root user, you must manually configure the agent with the required settings, as it will not be able to automatically detect the Posit product configuration. See the Advanced Agent Configuration appendix for details.
The installation process creates the posit-chronicle-agent user, which can be used for this purpose.
Example
### Editing /etc/systemd/system/chronicle-agent.service.d/override.conf
[Service]
User=posit-chronicle-agentRestart Behavior
Restart
Controls whether systemd should automatically restart the agent if it exits.
Type: string (no, always, on-success, on-failure, on-abnormal, on-abort, on-watchdog)
Default: always
RestartSec
The time to wait before restarting the agent after it exits. This prevents rapid restart loops and allows time for the products (Posit Workbench, Posit Connect) to start up before the Chronicle agent.
Type: time duration (seconds, or with suffix like 5s, 1min)
Default: 5
Rate limiting
The agent service includes rate limiting to prevent excessive restart attempts if the service is failing.
StartLimitBurst
The number of start attempts allowed within the StartLimitIntervalSec time window. If the service exceeds this limit, systemd will not attempt to start the service again until the interval resets.
Type: integer (number of attempts)
Default: 5
StartLimitIntervalSec
The time window (in seconds) for counting start attempts. If StartLimitBurst attempts occur within this window, systemd stops trying to start the service.
Type: time duration (seconds, or with suffix like 60s, 5min)
Default: 60
Together, these settings mean the agent can be started 5 times within 60 seconds before systemd gives up.
Environment variables
EnvironmentFile
A file containing environment variables to load when starting the agent. The - prefix means the file is optional and won’t cause an error if it doesn’t exist.
Type: file path
Default: -/etc/default/chronicle-agent
This file can be used to set environment variables such as CHRONICLE_SERVER_ADDRESS or other configuration values that override settings in the agent configuration file.
Example
Create /etc/default/chronicle-agent with environment variables:
/etc/default/chronicle-agent
CHRONICLE_SERVER_ADDRESS=http://chronicle-server:5252Directories
StateDirectory
The directory name (relative to /var/lib/) where persistent state files are stored.
Type: string (directory name)
Default: posit-chronicle-agent
RuntimeDirectory
The directory name (relative to /run/) for runtime files such as sockets and PID files.
Type: string (directory name)
Default: posit-chronicle-agent
Additional resources
For more information about systemd service configuration, see the systemd documentation.
For Chronicle-specific application configuration (not systemd settings), see: - Advanced Server Configuration for Chronicle server settings - Advanced Agent Configuration for Chronicle agent settings