🐧 Debian/Ubuntu Linux

The OpenUEM server components can be installed on a Debian/Ubuntu machine using .deb packages available in OpenUEM repository.

1. Adding the repository

The Debian/Ubuntu repository and its contents are signed with a GPG public key

To download the public GPG key and add it to the keyring use the following command:

curl -fsSL https://apt.openuem.eu/pgp-key.public | sudo gpg --dearmor -o /usr/share/keyrings/openuem.gpg

Now, to add the repository, run the following command:

echo "deb [arch=amd64 signed-by=/usr/share/keyrings/openuem.gpg] https://apt.openuem.eu stable main" | sudo tee /etc/apt/sources.list.d/openuem.list

Update the repositories:

sudo apt update -y

2. Install OpenUEM server

Start the installation running:

sudo apt install openuem-server

You'll have to answer some questions about configuration

info

This page shows information about the simplest path to installing all OpenUEM components in the same machine. If you prefer to install components on different machines different questions will be asked associated with the component being installed

Select the components that you want to install (press the space bar to toggle selection)

Now, specify the OpenUEM database connection parameters (host, port, user, password and database name)

OpenUEM needs a DNS domain for your organization to resolve agent/endpoint names to IP address. Set the domain name to be used

OpenUEM uses digital certificates to establish secure communication and TLS certificates. Unless you're using your own Certificate Authority, answer yes to this question so OpenUEM creates a Certificate Authority and the required certificates.

If you want to use OpenUEM behind a reverse proxy, set the DNS name that you want to use to access OpenUEM console

Now, you'll have to answer a few questions about your organization. These answers are only used to set values that identify your digital certificates and authenticate your NATS server connection.

It’s time to specify which domain name and port will be used by the NATS server:

If you want to use a NATS cluster, answer Yes to the question. If it's the first time you install OpenUEM or you're not using hundreds of agents, it's better to answer No.

Introduce the domain name and the port used by the OCSP Responder

You'll have to specify the DNS domain name used by the server that hosts the console service, and the ports used by the web server and the authentication server.

If you want to use OpenUEM behind a reverse proxy you must specify the domain name associated with the console service (unless you're letting OpenUEM generate the certificates and have already specified the DNS domain name), and the port used by the reverse proxy to run the authentication service.

The console uses a key to encrypt tokens, please set a complex key (and confirm it in the following question)

If OpenUEM has been selected to generate certificates automatically you've the chance to specify the password that protects the admin user certificate, and the system's username associated with the certificate, so the certificate can be added to this user's browsers certificate store.

Once, all the questions are answered the package will be installed.

warning

Installation may take some minutes if it must generate certificates so if you see that progress stalls for some minutes (generally at 60% or 80%), please be patient as cryptographic operations are heavy, database schema is created, and hundreds of megabytes are copied.

info

A user openuem will be created during the installation. Only this unprivileged user (or root user, of course) will have access to the config file, digital certificates and logs.

3. Next steps and troubleshooting

After the installation finishes, you'll see the following message:

It's time to visit the OpenUEM console in your browser.

Now open https://SERVER_NAME:CONSOLE_PORT (replace the values that you've set during the package configuration) and you should see OpenUEM's console

Finally, log in user your admin certificate and read how to install and add your first agent.

note

If you see any certificates error, OpenUEM should have imported the digital certificates in the right certificate stores of your browser automatically, but if it hadn't been the case, you can import the certificates by yourself

3.1 Services

OpenUEM will install and enable the following services on your server:

• openuem-agent-worker, see Workers for more information
• openuem-cert-manager-worker, see Workers for more information
• openuem-console, see Console for more information
• openuem-nats-service, see NATS for more information
• openuem-notification-worker, see Workers for more information
• openuem-ocsp-responder, see OCSP Responder for more information
• openuem-server-updater, that is responsible for updating the server components from the console

warning

All OpenUEM services will be run under an unprivileged user account called openuem to mitigate risks. Also, these services have been prepared using sudo system-analyze securityto reduce exposure.

The only exception is the openuem-updater-service that requires higher privileges to reinstall OpenUEM components. There’s an open issue to reduce privileges and exposure.

3.2 Configuration

OpenUEM config file is located at /etc/openuem-server/openuem.ini. If you failed to provide the right answer while configuring openuem-server package you can edit this file to fix some settings.

note

This configuration file contains the database password and JWT secret in clear, as it’s needed for OpenUEM components, but please do note that the configuration file can only be read by the openuem user.

3.3 Certificates

Unless you refused during the package configuration OpenUEM should have generated digital certificates. Those certificates should be located at /etc/openuem-server/certificates.

There’s a folder for every required certificate type or, more specifically, for every component type.

Just in case, you’ll find the administrator certificate in the users folder.

3.4 Logs

OpenUEM logs are stored in /var/log/openuem-server and you’ll find a log for every OpenUEM component that has been installed on that server. You’ll need root privileges to see the logs content.

3.5 Reinstalling OpenUEM

If you need to reinstall OpenUEM please proceed like this:

• If you want Debian/Ubuntu to ask you the configuration questions again, please use apt purge openuem-server to uninstall and forget the answers. Otherwise, use apt remove openuem-server
• Drop OpenUEM database tables so the new installation can perform a clean installation of the schema. If you prefer to keep the database, at least remove the user’s table as OpenUEM creates an entry for the admin user’s certificate and that entry must be unique.