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
• 1 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:

RPM-based (e.g., RHEL)

Terminal

$ sudo yum install posit-chronicle

Ubuntu

Terminal

$ sudo apt install posit-chronicle

RPM-based (One-off)

Terminal

$ curl -O https://dl.posit.co/public/pro/rpm/any-distro/any-version/x86_64/posit-chronicle-2024.11.0-1.x86_64.rpm
$ sudo yum install posit-chronicle-2024.11.0-1.x86_64.rpm

Ubuntu (One-off)

Terminal

curl -O https://dl.posit.co/public/pro/deb/any-distro/pool/any-version/main/p/po/posit-chronicle_2024.11.0/posit-chronicle_2024.11.0_amd64.deb
sudo apt install ./posit-chronicle_2024.11.0_amd64.deb

Verify the installation by ensuring that the service is running:

Terminal

$ systemctl status chronicle

Configure the server

The Chronicle server has a small number of configuration options. Typically you have to make two choices:

• What URL the agents should use to send data to the server. The Chronicle server runs on <server-ip>:5252 by default.

• Where the server should write 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 and working with systemd. The default configuration is close to the following:

/etc/posit-chronicle/posit-chronicle.gcfg

[HTTP]
Listen = :5252

[LocalStorage]
Enabled = true

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 /tmp/posit-chronicle with the following:

/etc/posit-chronicle/posit-chronicle.gcfg

[HTTP]
Listen = :5252

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

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

You can use AWS S3 for storage instead, provided that the EC2 instance has an appropriate instance profile. For example:

/etc/posit-chronicle/posit-chronicle.gcfg

[LocalStorage]
Enabled = false

[S3Storage]
Enabled = true
Bucket = posit-chronicle
Region = us-east-2

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

Terminal

$ 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 with CHRONICLE_SKIP_TLS_VERIFY=0 so that certificate-related errors are detected.

Install the agent

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:

RPM-based (e.g., RHEL)

Terminal

$ sudo yum install posit-chronicle-agent

Ubuntu

Terminal

$ sudo apt install posit-chronicle-agent

RPM-based (One-off)

Terminal

$ curl -O https://dl.posit.co/public/pro/rpm/any-distro/any-version/x86_64/posit-chronicle-agent-2024.11.0-1.x86_64.rpm
$ sudo yum install posit-chronicle-agent-2024.11.0-1.x86_64.rpm

Ubuntu (One-off)

Terminal

$ curl -O https://dl.posit.co/public/pro/deb/any-distro/pool/any-version/main/p/po/posit-chronicle-agent_2024.11.0/posit-chronicle-agent_2024.11.0_amd64.deb
$ sudo apt install ./posit-chronicle-agent_2024.11.0_amd64.deb

Verify the installation by ensuring that the service is running:

Terminal

$ systemctl status chronicle-agent

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

The agent is designed to require as little configuration as possible, and it should be able to detect product installations in most cases automatically. Because of this, there is no configuration file; a small number of environment variables can be used instead.

Under normal circumstances, the main piece of information you need to provide the agent is the address of the Chronicle server to which it should send metrics. If the Chronicle server is installed on the same machine as the agent and running with the default configuration, this agent configuration is unnecessary.

In order to provide metrics from Connect, you will need a Connect admin to generate an API key for the agent. The agent respects the usual CONNECT_API_KEY environment variable for this API key.

You can set environment variables for the agent by editing the systemd unit with sudo systemctl edit chronicle-agent. In the editor, add or modify the Environment setting in the Service section of the file. For example:

[Service]
Environment=CHRONICLE_SERVER_ADDRESS=https://chronicle.company.internal:5252 CHRONICLE_SKIP_TLS_VERIFY=1

If you would like to avoid editing the systemd unit, you can also put environment variables into a /etc/default/chronicle-agent file. For example:

/etc/default/chronicle-agent

CHRONICLE_SERVER_ADDRESS=https://chronicle.company.internal:5252
CHRONICLE_DISABLE_HOST_METRICS=1
CONNECT_API_KEY=changeme

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:

RPM-based (e.g., RHEL)

Terminal

$ sudo yum check-update
$ sudo yum update

Ubuntu

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):

RPM-based (e.g., RHEL)

Terminal

$ sudo yum check-update
$ sudo yum update {{package-name}}

Ubuntu

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.

RPM-based (e.g., RHEL)

Terminal

$ sudo yum check-update
$ yum list available {{package-name}}
$ sudo yum install {{package-name}}-{{version}}

Ubuntu

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:

RPM-based (e.g., RHEL)

Terminal

$ sudo yum check-update
$ yum list available posit-chronicle-agent
$ sudo yum install posit-chronicle-agent-2024.01.1

Ubuntu

Terminal

$ sudo apt update
$ apt-cache policy posit-chronicle-agent
$ sudo apt install posit-chronicle-agent=2024.01.1