Linux archive without root

Install the Licensing Gateway Service (LGS) from a .tar.gz archive on hosts that don’t allow third-party packages or services that run as root. The LGS runs as a systemd user service under an ordinary account, and keeps its data in the account’s home directory. An administrator prepares the host once. After that, you install, run, and upgrade the LGS without root.

The LGS writes nothing to /var or /tmp, needs no user namespaces, and runs with SELinux enforcing. If your hosts allow system packages, use Linux DEB and RPM packages instead, which are easier to install and update.

Prerequisite

The archive requires x86-64 Linux with glibc 2.28 or later:

• RHEL, Rocky Linux, or AlmaLinux 8 or later
• Debian 10 or later
• Ubuntu 20.04 or later

The examples use the following locations:

• Program: /opt/pdftools-lgs/VERSION_NUMBER/, with /opt/pdftools-lgs/current pointing at the active version. Keep it outside /home, which hardened hosts often mount with noexec.
• Settings: /opt/pdftools-lgs/current/appsettings.json.
• Database: ~/.local/state/pdftools-lgs/pls.db, encrypted.
• Logs: ~/.local/state/log/pdftools-lgs/, also available with journalctl --user -u pdftools-lgs.

Prepare the host

An administrator prepares the host once. The examples use lgs as the account that runs the LGS. If you choose another name, replace lgs in the following commands.

1. Install the libraries the LGS needs. On RHEL, Rocky Linux, and AlmaLinux:

   sudo dnf install libicu openssl-libs libstdc++ zlib ca-certificates

   On Debian and Ubuntu, use apt. The libicu and libssl package names differ per release. On Ubuntu 24.04:

   sudo apt install libicu74 libssl3t64 libstdc++6 zlib1g ca-certificates

   Minimal installations often lack ICU (International Components for Unicode), and without it the LGS stops immediately.
2. Create the account:

   sudo useradd -m lgs

3. Create the program folder, owned by the account:

   sudo mkdir -p /opt/pdftools-lgs
   sudo chown lgs:lgs /opt/pdftools-lgs

4. Enable lingering so that the LGS starts at boot without anyone logging in:

   sudo loginctl enable-linger lgs

5. Open TCP port 9999 for Pdftools products on other machines, for example with firewalld:

   sudo firewall-cmd --permanent --add-port=9999/tcp
   sudo firewall-cmd --reload

   On hosts without firewalld, open the port with the firewall tool that the host uses.
6. Give the machine a permanent hostname. Replace HOST_NAME with the name of the machine:

   sudo hostnamectl set-hostname HOST_NAME

   The LGS binds its database to the machine identity, which includes the hostname. For details, refer to Before you change the machine identity.

Install the LGS

Install the LGS as the account that runs it.

Prerequisites

You’re logged in as the lgs account. After sudo -iu lgs, set the variable that systemctl --user needs. Set it again after each new sudo -iu lgs, for example before an upgrade:

export XDG_RUNTIME_DIR=/run/user/$(id -u)

Install and start the LGS

The last two steps need a connection to the Pdftools Licensing Service. For full offline mode, skip them and continue with Use full offline mode.

1. Download the pdftools-licensing-gateway-linux-x64.tar.gz archive and its checksum file.
2. Verify the download:

   sha256sum -c pdftools-licensing-gateway-linux-x64.tar.gz.sha256

   The command prints OK for an intact archive.
3. Find the version number, which is part of the name of the folder in the archive:

   tar -tzf pdftools-licensing-gateway-linux-x64.tar.gz | head -1

   For example, pdftools-licensing-gateway-1.3.1400/ stands for version 1.3.1400.
4. Unpack the archive into a folder for this version, and point current at it. Replace VERSION_NUMBER in all three commands with the version number from the previous step:

   mkdir -p /opt/pdftools-lgs/VERSION_NUMBER
   tar -xzf pdftools-licensing-gateway-linux-x64.tar.gz -C /opt/pdftools-lgs/VERSION_NUMBER --strip-components=1
   ln -sfn VERSION_NUMBER /opt/pdftools-lgs/current

5. Install the service definition:

   mkdir -p ~/.config/systemd/user
   sed "s|@INSTALL_DIR@|/opt/pdftools-lgs/current|g" /opt/pdftools-lgs/current/pdftools-lgs.service > ~/.config/systemd/user/pdftools-lgs.service

6. Start the service, and set it to start at boot:

   systemctl --user daemon-reload
   systemctl --user enable --now pdftools-lgs

7. Borrow a license key:

   /opt/pdftools-lgs/current/ptl add "LICENSE_KEY_VALUE"

   Replace LICENSE_KEY_VALUE with your license key, and keep the quotes. Without them, the shell reads the angle brackets of a Pdftools SDK key as a redirection.
8. Check the connection to the Pdftools Licensing Service:

   /opt/pdftools-lgs/current/ptl status

Configure the LGS

To change a setting, edit /opt/pdftools-lgs/current/appsettings.json, and then run systemctl --user restart pdftools-lgs. For the available settings, review Configure the LGS and Configure a forward proxy. Don’t set DataDirectory or LogFilePath, which the service definition sets. If you configure a proxy password, restrict the file with chmod 600 /opt/pdftools-lgs/current/appsettings.json.

Use full offline mode

In full offline mode, the LGS machine has no connection to the Pdftools Licensing Service. You transfer the activation tokens between the LGS machine and a machine with internet access, for example on a USB flash drive.

To set up full offline mode:

1. On the LGS machine, set "IsOfflineMode": true in /opt/pdftools-lgs/current/appsettings.json.
2. On the LGS machine, restart the service:

   systemctl --user restart pdftools-lgs

3. On a machine with internet access, unpack the same archive as an ordinary user:

   mkdir -p ~/lgs-courier
   tar -xzf pdftools-licensing-gateway-linux-x64.tar.gz -C ~/lgs-courier --strip-components=1

   The machine with internet access only needs ptl. Don’t install the service on it. If it mounts home directories with noexec, unpack the archive into another folder.

To activate and deactivate license keys, follow Activate license keys offline. Wherever that page uses ptl, run /opt/pdftools-lgs/current/ptl on the LGS machine and ~/lgs-courier/ptl on the machine with internet access.

Upgrade the LGS

Install each version in its own folder, so that you can switch back if needed.

1. Unpack the new archive into a folder for its version. Replace NEW_VERSION_NUMBER in this and the following steps with the version number of the new archive:

   mkdir -p /opt/pdftools-lgs/NEW_VERSION_NUMBER
   tar -xzf pdftools-licensing-gateway-linux-x64.tar.gz -C /opt/pdftools-lgs/NEW_VERSION_NUMBER --strip-components=1

2. Copy your settings to the new version:

   cp -p /opt/pdftools-lgs/current/appsettings.json /opt/pdftools-lgs/NEW_VERSION_NUMBER/

   The -p option keeps the file permissions, such as a chmod 600.
3. Point current at the new version:

   ln -sfn NEW_VERSION_NUMBER /opt/pdftools-lgs/current

4. Install the service definition from the new version, which can change between versions, and restart the service:

   sed "s|@INSTALL_DIR@|/opt/pdftools-lgs/current|g" /opt/pdftools-lgs/current/pdftools-lgs.service > ~/.config/systemd/user/pdftools-lgs.service
   systemctl --user daemon-reload
   systemctl --user restart pdftools-lgs

The database and the logs stay in the home directory. To switch back, point current at the previous folder, and then repeat the last step.

Uninstall the LGS

Return your license keys before you uninstall the LGS, with /opt/pdftools-lgs/current/ptl remove-all, or in full offline mode as described in Deactivate a license key. Each borrowed license key counts against your license until you return it.

To uninstall the LGS as the lgs account:

1. Stop and disable the service:

   systemctl --user disable --now pdftools-lgs

2. Remove the service definition:

   rm ~/.config/systemd/user/pdftools-lgs.service
   systemctl --user daemon-reload

3. Remove the program files:

   rm -rf /opt/pdftools-lgs/*

4. Optional: Remove the database and the logs:

   rm -rf ~/.local/state/pdftools-lgs ~/.local/state/log/pdftools-lgs

An administrator can then disable lingering with sudo loginctl disable-linger lgs, and remove the account and the /opt/pdftools-lgs folder.

Before you change the machine identity

The LGS encrypts its database with a key derived from the identity of the machine it runs on. That identity includes the hostname and the hardware (MAC) addresses of the network adapters, so the database works only on that machine. If the hostname or a MAC address changes, the LGS can’t open its database and doesn’t start. Its log then shows SQLite Error 26: 'file is not a database'. The license keys it borrowed stay registered to the old identity until they expire.

The following changes alter the machine identity:

• Renaming the machine
• Replacing a network adapter
• Recreating or moving a virtual machine that gets its MAC address assigned automatically

Give virtual machines a fixed MAC address. To change the identity of a machine that runs the LGS:

1. Return all license keys:
   • DEB and RPM packages: sudo ptl remove-all.
   • Archive: /opt/pdftools-lgs/current/ptl remove-all.
   • Full offline mode: Deactivate each license key as described in Deactivate a license key.
2. Rename the machine or change its network adapters.
3. Reset the LGS database, as described in Reset the LGS database.
4. Borrow or activate the license keys again.

If the identity already changed and the LGS doesn’t start, choose the case that applies:

• You can change the hostname or MAC address back: Change it back, so that the LGS starts again. Then follow the preceding steps.
• You can’t change it back: Reset the LGS database, and then borrow or activate the license keys again. The license keys in the old database stay registered until they expire.

Reset the LGS database

Reset the database only after you return the license keys, or when the LGS can’t open its database. If you remove a database that still holds license keys, those keys stay registered until they expire.

To reset the LGS database:

1. Stop the LGS:
   • DEB and RPM packages: sudo systemctl stop pdftools-lgs.
   • Archive: systemctl --user stop pdftools-lgs.
2. Remove the database and its SQLite side files:
   • DEB and RPM packages: sudo rm -f /var/lib/pdftools/lgs/pls.db{,-wal,-shm,-journal}.
   • Archive: rm -f ~/.local/state/pdftools-lgs/pls.db*.
3. Start the LGS, which creates a new, empty database:
   • DEB and RPM packages: sudo systemctl start pdftools-lgs.
   • Archive: systemctl --user start pdftools-lgs.

Troubleshooting

The following issues are common:

• Failed to connect to bus: XDG_RUNTIME_DIR isn’t set. Refer to Prerequisites.
• The LGS stops at logout or doesn’t start after a reboot: Lingering isn’t enabled. Check it with loginctl show-user lgs -p Linger.
• Couldn't find a valid ICU package installed on the system: ICU is missing. Install the libraries as described in Prepare the host.
• SQLite Error 26: 'file is not a database': The machine identity changed since the LGS created its database. Refer to Before you change the machine identity.