Run Chronicle on Linux virtual machines

Chronicle’s agent and server both run on all Linux distributions supported by Posit, which are detailed on our platform support page.

Install the server

It is recommended that you run the Chronicle server on a machine with a minimum of:

  • 1 CPU
  • 1 GB of RAM
  • 15 GB of disk storage

You can either provision a dedicated machine for the Chronicle server or run it on one of the existing nodes for simplicity.

Depending on your Linux distribution, you will need to install an .rpm or .deb package in one of two ways:

  1. Configure the machine to download packages from Posit’s official repositories, which will also get you updates automatically. Detailed steps to achieve this are available for both .rpm and .deb packages. You must complete these steps before proceeding.

  2. Perform one-off manual download and installations, which is simpler initially but requires manual upgrades going forward.

Once you have decided on one of these options, run the following commands on the machine to install the Chronicle server:

Terminal
sudo dnf install posit-chronicle
Terminal
sudo apt install posit-chronicle
Terminal
curl -O https://dl.posit.co/public/pro/rpm/any-distro/any-version/x86_64/posit-chronicle-2025.05.1-1.x86_64.rpm
sudo dnf install posit-chronicle-2025.05.1-1.x86_64.rpm
Terminal
curl -O https://dl.posit.co/public/pro/deb/any-distro/pool/any-version/main/p/po/posit-chronicle_2025.05.1/posit-chronicle_2025.05.1_amd64.deb
sudo apt install ./posit-chronicle_2025.05.1_amd64.deb

The Chronicle server installation will automatically create a user called posit-chronicle. This user account is used to manage necessary access to the filesystem for socket management and local storage of data files and reports (if enabled).

Verifying the Server Installation

Verify the installation by ensuring that the service is running:

Terminal
chronicle status

See the chronicle status documentation for detailed information about the output of this command.

Configure the server

The Chronicle server has a small number of configuration options. The most frequently changed options include:

  • The port that the server will accept connections on. By default, the server uses post 5252. This port must be network accessible from all Posit servers running the Chronicle Agent.

  • The location where the server stores the collected data. Chronicle currently supports writing data to a local directory (the default) or to AWS S3.

This configuration involves editing the /etc/posit-chronicle/posit-chronicle.gcfg file created during the installation process. You can modify the Chronicle server configuration by editing this file. For example, persistent data is written to /var/lib/posit-chronicle/data by default. You can change it to /opt/posit-chronicle with the following:

/etc/posit-chronicle/posit-chronicle.gcfg
[HTTP]
Listen = :5252

[LocalStorage]
Enabled = true
Location = /opt/posit-chronicle

(The server also respects the StateDirectory setting in the systemd unit file.)

Once you have made these edits, be sure to restart the Chronicle server via systemd to have the changes take effect:

Terminal
sudo systemctl restart chronicle

Configuring HTTPS

When the server is running on a Linux server or VM, it listens over HTTP by default. This means that a Chronicle agent would send metrics data to the Chronicle server without encryption.

To send this traffic securely over HTTPS instead, you have two options:

  • Run the Chronicle server behind a reverse proxy that handles HTTPS on its behalf; or

  • Enable native HTTPS support, which requires TLS certificate and key files.

Configuring a reverse proxy is beyond the scope of this guide but will usually be easier if you already have one in front of your supported professional product installation.

To enable Chronicle server’s native HTTPS support, you must modify the configuration file. For example:

/etc/posit-chronicle/posit-chronicle.gcfg
[HTTPS]
Listen = :443
Key = "path/to/ssl.key"
Certificate = "path/to/ssl.crt"
Note

By default, the agent assumes you are using a self-signed TLS certificate.

If you have a CA-signed certificate, you can configure agents so that certificate-related errors are detected.

Install the agent

Important

Before installing the agent, ensure that metrics have been enabled on the Posit products. See Prerequisites for details.

The Chronicle agent is designed to run alongside a supported professional product, so be sure to take the following steps on each of those machines.

Depending on your Linux distribution, you will need to install an .rpm or .deb package in one of two ways:

  1. Configure the machine to download packages from Posit’s official repositories, which will also get you updates automatically. Detailed steps to achieve this are available for both .rpm and .deb packages. You must complete these steps before proceeding.

  2. Perform one-off manual download and installations, which is simpler initially but requires manual upgrades going forward.

Once you have decided on one of these options, run the following commands on each machine to install the Chronicle agent:

Terminal
sudo dnf install posit-chronicle-agent
Terminal
sudo apt install posit-chronicle-agent
Terminal
curl -O https://dl.posit.co/public/pro/rpm/any-distro/any-version/x86_64/posit-chronicle-agent-2025.05.0-1.x86_64.rpm
sudo dnf install posit-chronicle-agent-2025.05.0-1.x86_64.rpm
Terminal
curl -O https://dl.posit.co/public/pro/deb/any-distro/pool/any-version/main/p/po/posit-chronicle-agent_2025.05.0/posit-chronicle-agent_2025.05.0_amd64.deb
sudo apt install ./posit-chronicle-agent_2025.05.0_amd64.deb

The Chronicle agent installation will automatically create a user called posit-chronicle-agent. This user account may be used on hosts running Workbench as the associated user account to a defined Workbench admin API key.

Verifying the Agent Installation

Verify the installation by ensuring that the service is running:

Terminal
chronicle-agent status

See the chronicle-agent status documentation for detailed information about the output of this command. The chronicle status command can also be used on the host running the Chronicle server to verify that the agent is reporting data correctly.

Important

By default, the Chronicle agent expects that a single supported professional product is running on the same machine. It may refuse to start and require further configuration if it cannot find a running instance of one of these products.

Configure the agent

Agent configuration options are stored in the /etc/posit-chronicle-agent/posit-chronicle-agent.gcfg file created during installation.

Setting the user which the agent should use

By default, the agent is run as the root user, but an alternate user can be provided for the agent to run as.

The agent will only be able to automatically detect the configuration for the Posit Team product it is running alongside if it has read access to the configuration file for that product:

  • /etc/rstudio/rserver.conf for Workbench
  • /etc/rstudio-connect/rstudio-connect.gcfg for Connect

If you would prefer for the agent to run as a user without access to these configuration files, you will need to manually configure the agent. Detailed instructions can be found in the Advanced Agent Configuration appendix. The following configurations must be set, even if the desired value is the same as the default value:

Product Minimal Required Agent Configuration
Connect Connect.MetricsURL, Connect.ServerURL
Workbench Workbench.MetricsURL

To set an alternate user that the agent should use:

  1. Edit the service configuration with sudo systemctl edit chronicle-agent
  2. Add the [Service] and User lines in the example below. In this example, we use the posit-chronicle-agent to run the agent, which is available on any host with the agent installed, but you can use another user as well.
### Editing /etc/systemd/system/chronicle-agent.service.d/override.conf
### Anything between here and the comment below will become the new contents of the file

[Service]
User=posit-chronicle-agent

### Lines below this comment will be discarded

### /usr/local/lib/systemd/system/chronicle-agent.service
# [Unit]
# Description=Posit Chronicle Agent
# After=network-online.target
# Wants=network-online.target
#
# [Service]
# Type=simple
# ExecStart=/usr/local/bin/chronicle-agent
# Restart=always
# EnvironmentFile=-/etc/default/chronicle-agent
# StateDirectory=posit-chronicle-agent
# RuntimeDirectory=posit-chronicle-agent
#
# [Install]
# WantedBy=multi-user.target
  1. Save the file.
  2. Restart the agent with sudo systemctl restart chronicle-agent to apply the change.
  3. To confirm that the agent is running with the selected user, run ps -A -o pid,user,comm | grep chronicle

Configure Chronicle Server address

If the server is not installed on the same machine as the agent, or the server is not running with the default configuration, then the agent must be configured with the address of the Chronicle Server to which it should send metrics.

/etc/posit-chronicle-agent/posit-chronicle-agent.gcfg
[Server]
Address = "http://localhost:5252"

Configure Connect API Key

To collect additional data available from Posit Connect, you need a Connect administrator to provision a Connect API key with the Administrator role.

Add the API key to the [Connect] section of the agent configuration file:

/etc/posit-chronicle-agent/posit-chronicle-agent.gcfg
[Connect]
APIKey = "ABCDEFGHIJKLMNO"

Configure Workbench API Key

To collect additional data available from Posit Workbench 2024.12.0 or later, generate an Admin API Key for the posit-chronicle-agent user.

Terminal
rstudio-server generate-api-token admin 'Posit Chronicle Agent' posit-chronicle-agent --read-only

Add the API key to the [Workbench] section of the agent configuration file:

/etc/posit-chronicle-agent/posit-chronicle-agent.gcfg
[Workbench]
APIKey = "xe9MU4VzZvJM1uM8WDBulvOEd3RRadlM"

See the Advanced Agent Configuration appendix for additional agent configuration options.

Updating Chronicle Server and Agent

If you followed the one-off manual download and installation track above, you can use the same process to install updates at a later time.

If you configured your machine to download packages from Posit’s official repositories, you can use your OS provided package manager to update both the Chronicle server and agent.

Installed Posit Chronicle products can be updated to the latest released version in a bulk operation with all other installed packages by using the standard package update commands:

Terminal
sudo dnf check-update
sudo dnf update
Terminal
sudo apt update
sudo apt upgrade

If you want to update only the Chronicle server or agent to its latest release, you can do so with these commands (In this example and those that follow, the package name will be either posit-chronicle if you are updating the server or posit-chronicle-agent if you are updating the agent):

Terminal
sudo dnf check-update
sudo dnf update {{package-name}}
Terminal
sudo apt update
sudo apt install --only-upgrade {{package-name}}

If you want to update to a specific version of the Chronicle server or agent, you can use these commands. The first command will allow you to determine what versions are available. The second command will install the specified version.

Terminal
sudo dnf check-update
dnf list available {{package-name}}
sudo dnf install {{package-name}}-{{version}}
Terminal
sudo apt update
apt-cache policy {{package-name}}
sudo apt install {{package-name}}={{version}}

For a specific example, the following command could be used to discover and install the 2024.01.1 version of the Posit Chronicle agent:

Terminal
sudo dnf check-update
dnf list available posit-chronicle-agent
sudo dnf install posit-chronicle-agent-2024.01.1
Terminal
sudo apt update
apt-cache policy posit-chronicle-agent
sudo apt install posit-chronicle-agent=2024.01.1
Back to top