Skip to main content
Version: 4.33

Linux agent installation and configuration

Overview​

This guide provides comprehensive instructions for installing and uninstalling the Redtrust agent in Linux environments. It provides authenticated user with access to signing certificates stored in the Redtrust server and in a connected HSM for use with PKCS#11-compatible signing tools. This guide is intended for system administrators or anyone responsible for deploying and configuring Redtrust.

Background​

The agent works unattended: once configured, it runs transparently without requiring user interaction. It also supports multiple concurrent users and is multi-server, because the server configuration is associated with each user. This allows each person to connect to a different Redtrust server without interfering with other users on the system. The agent is designed for local-user authentication and does not include a graphical interface, certificate preselection, or web navigation features. It also focuses strictly on key use, so certificates that require a PIN or specific usage constraints are not supported.

Before you start​

The agent supports these distributions:

  • Debian 11 and 12
  • Red Hat 8 and 9
  • Ubuntu 22.04 and 23.10
note

If you use another Linux distribution, Redtrust provides standalone agent builds that bundle the .NET runtime. If you use one of these, install the correct .NET runtime for your system. See Microsoft’s documentation on Linux distributions.

Step 1: Install the agent​

To install the agent, run the following commands.

  1. Update all installed packages.
sudo apt update && sudo apt upgrade
  1. Install the system dependencies.
sudo apt install libcurl4 dotnet-runtime-8.0 aspnetcore-runtime-8.0 libssl3 libsqlite3-0 opensc -y
  1. Install the Redtrust package you need (check the Debian or Ubuntu version in the filename).
sudo apt install  PATH_TO_REDTRUST_PACKAGE

For example:

sudo apt install  ./agent/amd64_ubuntu22.04_keyfactor-agent-4.20.0-457bb50-Standalone.deb

You can verify the installation by running this command.

systemctl status KeyfactorService.service
● KeyfactorService.service - Long running KeyfactorService service/daemon created by Keyfactor.
    Loaded: loaded (/etc/systemd/system/KeyfactorService.service; enabled; vendor preset: enabled)
    Active: active (running) since Tue 2024-01-30 16:22:33 UTC; 20min ago
Main PID: 5472 (KeyfactorServic)
    Tasks: 15 (limit: 4668)
    Memory: 40.9M
        CPU: 960ms
    CGroup: /system.slice/KeyfactorService.service
            └─5472 /usr/local/keyfactor/service/KeyfactorService

Step 2: Configure the agent​

  1. After installing the agent, configure some parameters.

    keyfactor-setup hostname=[IP_OR_HOSTNAME] clientid=[CLIENT_ID] username=[USERNAME] password=[PASSWORD] loglevel=[LOGLEVEL]

    For example, the command for a user cris@local.users in agent01.example.com is:

    keyfactor-setup hostname=agent01.example.com clientid=T4N3r2WBbvKfyYe8/z+SVW5N= username=cris@local.users password=ChangeMe123 loglevel=LOW

    LOGLEVEL will determine the amount of detail to include in the logs and the valid values are NONE, LOW and HIGH.

  2. To verify the configuration, you can run the following test.

    keyfactor-setup test

    Alternatively, check the details of the configuration you just stored.

    keyfactor-setup show
info

You can leave the password parameter empty and set it later. When you enter it afterward, the password will be masked (shown as *) instead of being displayed.

note

Run this command to find details of the parameters and operations available:

keyfactor-setup

Step 3: Verify the installation​

Unlike Windows, Linux does not provide a centralized certificate store. Because of this, when an application needs to use certificates, you must specify the location of the Redtrust PKCS#11 library when launching it.

To test that the agent works correctly, you need to make sure the PKCS#11 module is working.

  1. Install the pkcs11-tool utility.

    sudo apt install opensc

  2. Now you can test that the Redtrust PKCS#11 module is installed and working correctly.

    pkcs11-tool --module /usr/lib/libkeyfactorpkcs11.so -t

  3. List the certificates available to the user you configured.

    pkcs11-tool --module /usr/lib/libkeyfactorpkcs11.so --list-objects --type cert

Log files​

If you experience issues during installation or while the Linux agent is running, the logs stored in /tmp/ can help you understand what actions the agent performed and which components were involved.

The agent writes two types of log files:

  • Service logs /tmp/KeyfactorService*: The agent creates one service log per day. These files capture the agent’s core activity.
  • PKCS11 logs /tmp/keyfactor-*: Each application that uses the PKCS11 interface generates its own log file. These logs help you identify how external programs interact with the agent.

To view all available log files, run:

ls -la /tmp/*[Kk]eyfactor*

Uninstallation​

To uninstall the Redtrust agent, run the following command.

sudo dpkg --remove keyfactor-agent​
sudo apt remove --purge keyfactor-agent​

Next steps​

How to sign documents with AutoFirma using Redtrust unattended agent