🕵️ Linux Agent
OpenUEM agents are responsible for inspecting your endpoints information and offer additional services like file browsing, package deployment and VNC connections.
1. Debian/Ubuntu
You can install an agent in a Debian 11/Ubuntu 20.04 (or higher) system.
1.1. Download the package
OpenUEM provides a repository for deb packages. You can add the repository following the steps in the Server section.
If you are familiar with Ansible you can use this playbook to automatically configure the repository and skips sections 2 and 3 of this document. You only have to configure the values for the NATS servers, SFTP and VNC proxy ports in the playbook before using it
Alternatively, you can visit the repository and download the .deb package that you need.
If you don’t add the OpenUEM repository to your agent, you won’t be able to update agents from the console
1.2. Install the agent
The agent can be installed from the repository using the following command:
apt install openuem-agent
If you have downloaded the .deb package manually, you can install it using
apt install ./openuem-agent_0.7.0_amd64.deb
Once the installation starts, you’ll have to answer some questions to configure the agent.
First you must introduce the OpenUEM NATS server URL in the format server.your.domain:port (if you use a cluster you must introduce a comma between the servers)
The Agent has an SFTP server used to browse, update or delete files from the console. You must specify the port number (default: 2022). If you set an empty value the SFTP server will not be used.
The Agent can use a VNC Proxy if you install a supported VNC server. If no VNC app is installed this port won't be used. Specify the port number for the proxy (default: 1443). If you set an empty value the VNC proxy will not be used.
If your endpoint has a firewall, you must enable the incoming traffic to the SFTP and VNC Proxy ports from OpenUEM console
If you want that your endpoint is associated to an organization and site that you've created in OpenUEM console (🎯 Version 0.7.0) you can specify the IDs (numbers) for both organization and site, or leave the fields empty to use the default organization and site.
You can get the ID of the organization from the organization's list
You can get the ID of the site from the site's list.
1.3. Agent post-install steps
The agent requires some certificates to secure connections between the agent and the rest of OpenUEM components. You must place the required certificates under the /etc/openuem-agent/certificates folder with administrator privileges. You should find the certificates and private keys in the folder where the OpenUEM Server/Docker was installed.
These are the certificates required by the OpenUEM agent:
- ca.cer, this is the Certification Authority certificate file. You should place the file in
/etc/openuem-agent/certificates/ca.cer - sftp.cer, this is the public part of the SFTP certificate that the console will use to authenticate SFTP connections. You should place the file in
/etc/openuem-agent/certificates/sftp.cer - agent.cer, this is the certificate that allows the agent to connect with the NATS server. You should place the certificate in
/etc/openuem-agent/certificates/agent.cer - agent.key, this is the private key that allows the agent to connect with the NATS server. You should find the file in the folder where the OpenUEM Server/Docker was installed under
/etc/openuem-agent/certificates/agent.key
Once you've copied the required certificates, you must restart the openuem-agent and openuem-agent-updater services:
systemctl restart openuem-agent
systemctl restart openuem-agent-updater
2. RedHat/Fedora/AlmaLinux
You can install an agent in a RedHat based system.
2.1. Download the package
OpenUEM provides a repository for rpm packages. You can add the repository following the steps in the Server section.
Alternatively, you can visit the repository and download the .deb package that you need.
If you don’t add the OpenUEM repository to your agent, you won’t be able to update agents from the console
2.2. Install the agent
The agent can be installed from the repository using the following command:
sudo dnf install -y openuem-agent
You'll have to accept the GPG public key to install the package from OpenUEM repository
If you have downloaded the .rpm package manually, you can install it using
sudo dnf install -y ./openuem-agent-0.7.0-1.x86_64.rpm
2.3. Agent post-install steps
Once the package gets installed you’ll have to edit the /etc/openuem-agent/openuem.ini to configure the agent.
First you must introduce the OpenUEM NATS server URL in the format server.your.domain:port (if you use a cluster you must introduce a comma between the servers)
[NATS]
NATSServers=terminus.openuem.eu:4433
The Agent has an SFTP server used to browse, update or delete files from the console. You must specify the port number (default: 2022). If you set an empty value the SFTP server will not be used.
SFTPPort=
The Agent can use a VNC Proxy if you install a supported VNC server. If no VNC app is installed this port won't be used. Specify the port number for the proxy (default: 1443). If you set an empty value the VNC proxy will not be used.
VNCProxyPort=
If you want the agent to be stored under a specific organization and site, you can use the properties TenantID and SiteID and assign the IDs that are listed in OpenUEM's console. These settings are optional as the agent will be stored under the default organization and site.
TenantID=1
SiteID=1
If your endpoint has a firewall, you must enable the incoming traffic to the SFTP and VNC Proxy ports from OpenUEM console. For example if SFTP port is 2022 and VNC proxy port is 1433:
sudo firewall-cmd --add-port=2022/tcp
sudo firewall-cmd --add-port=1433/tcp
sudo firewall-cmd --runtime-to-permanent
The agent requires some certificates to secure connections between the agent and the rest of OpenUEM components. You must place the required certificates under the /etc/openuem-agent/certificates folder with administrator privileges. You should find the certificates and private keys in the folder where the OpenUEM Server/Docker was installed.
These are the certificates required by the OpenUEM agent:
- ca.cer, this is the Certification Authority certificate file. You should place the file in
/etc/openuem-agent/certificates/ca.cer - sftp.cer, this is the public part of the SFTP certificate that the console will use to authenticate SFTP connections. You should place the file in
/etc/openuem-agent/certificates/sftp.cer - agent.cer, this is the certificate that allows the agent to connect with the NATS server. You should place the certificate in
/etc/openuem-agent/certificates/agent.cer - agent.key, this is the private key that allows the agent to connect with the NATS server. You should find the file in the folder where the OpenUEM Server/Docker was installed under
/etc/openuem-agent/certificates/agent.key
sudo mkdir /etc/openuem-agent/certificates
sudo chown openuem-agent:openuem-agent /etc/openuem-agent/certificates
Once you've copied the required certificates, you must restart the openuem-agent and openuem-agent-updater services:
sudo systemctl enable --now openuem-agent
sudo systemctl enable --now openuem-agent-updater
3. Next steps and troubleshooting
After the agent installation, if everything goes fine you should see the agent in the console's agents' view ready to be admitted
If you don't see the agent in the console something may have gone wrong. You can have a look at the agent's log located at /var/log/openuem-agent/openuem-agent.log. If the connection with the agent is possible, you can use the "Show agent's log" in the console Agents view to see the logs from the console.
In the logs you should find ERROR messages that should explain the problem:
- Maybe your NATS server or the Agent Worker (or both) is not running.
- Maybe you missed to copy a required certificates.
- Maybe you specified the wrong name for the NATS server or the port. You can edit the
/etc/openuem-agent/openuem.inifile and change the domain name or port and restart the OpenUEM Agent service.
If you see an error that says "agent has no IP address, report won't be sent..." you can add an entry specifying the IP Address assigned to the bridge in the Agent section. This is common if your agent is installed on an endpoint that uses a bridge to provide access to the network which is common in servers that host several VMs.
IPAddress = x.x.x.x
Need more help?, Open an issue in GitHub or send a message in Discord!