# Deploy with Linux
This page walks you through how to deploy Keeper Endpoint Privilege Manager (EPM) on Linux systems. It explains how to install and start the agent, connect it to your Keeper environment, understand how privilege control integrates with sudo, and validate that everything is working correctly.
## Overview
On Linux, Keeper EPM works a little differently than on Windows or macOS.
Instead of integrating with a graphical system, it integrates directly with **sudo** using something called **PAM (Pluggable Authentication Modules)**.
* Keeper controls **who can run privileged commands**
* It can require:
* MFA
* Approval
* Justification
* All without changing how users normally use the command line
### Supported Linux Versions
Keeper EPM supports major distributions, including:
* Ubuntu 22.04+
Always validate compatibility for your distribution.
## How You Can Deploy It
You have several deployment options depending on your environment. Manual installation is best suited for testing, while scripts provide a flexible approach for automation. For larger environments, configuration management tools such as Ansible, Chef, or Puppet are typically the best choice, enabling consistent deployment at scale.
Regardless of the method used, the deployment process follows the same core steps: install the agent, start the service, register the device, and optionally enable sudo enforcement through PAM.
### Deployment Packages (Recommended)
The easiest way to deploy Keeper on Linux is by using a deployment package from the Keeper Admin Console. This package includes the Linux installer (either `.deb` or `.rpm`), a registration token, and configuration details needed for onboarding. This is the standard and recommended method for distributing the agent.
#### Package Handling
After downloading the deployment package, extract the ZIP file and use the appropriate installer for your distribution. Use the `.deb` package for Debian or Ubuntu systems, and the `.rpm` package for RHEL or CentOS environments.
#### Before You Start (Prerequisite Checklist)
Make sure you have:
* A Keeper tenant with EPM enabled
* A **registration token**
* The Linux installer package
* **Root or sudo access**
* Network access (HTTPS on port 6889 by default)
## Installing the Agent
{% stepper %}
{% step %}
**Download & Unpack**
```
curl -o KeeperPrivilegeManagerLinux.zip "https://keepersecurity.com/pam/pedm/core/latest/KeeperPrivilegeManagerLinux.zip"
unzip KeeperPrivilegeManagerLinux.zip
cd linux
```
{% endstep %}
{% step %}
**Install the Agent**
Install the package based on your Linux distribution. (Where "N.N.N-NN" is the version number)
**Debian / Ubuntu**
```
sudo dpkg -i keeper-privilege-manager_N.N.N-NN_amd64.deb
```
**RHEL / CentOS**
```
sudo rpm -i keeper-privilege-manager-N.N.N-NN.aarch64.rpm
```
The agent installs to:
```
/opt/keeper/
```
{% endstep %}
{% step %}
**Optional: Install GNOME Agent UI**
For customers using Linux systems running GNOME, the Keeper user interface is available as an extension.
Ensure GNOME Shell is installed on the endpoint:
```
sudo apt install -y gnome-shell-extension-prefs
or
keepersudo apt install -y gnome-shell-extension-prefs
(if Keeper is already installed)
```
Open the GNOME Extensions app (`gnome-extensions-app`) or Extension Manager from the system menu and toggle all options "ON".
The Keeper EPM icon will then appear in the system tray or top bar, providing access to agent status and controls.
The full UI is available on Linux just like Windows and macOS devices.
{% endstep %}
{% step %}
**Start the Service**
Keeper runs as a background service using **systemd**.
Start it:
Enable it at startup:
```
keepersudo systemctl enable keeper-privilege-manager
```
Check status:
```
keepersudo systemctl status keeper-privilege-manager
```
Expected:
```
active (running)
```
{% endstep %}
{% step %}
**Check That It’s Healthy**
Verify the agent is working:
```
curl -k https://localhost:6889/health
```
This confirms the service is running and responsive.
{% endstep %}
{% step %}
**Register the Device**
Now connect the Linux machine to your Keeper environment.
```
keepersudo /opt/keeper/sbin/Jobs/bin/KeeperRegistrationHelper/KeeperRegistrationHelper --token="YOUR_TOKEN_HERE"
```
This step allows the device to receive policies and report back.
Check registration:
```
curl -k https://localhost:6889/api/Keeper/registration
```
Expected:
* Agent is registered
* Deployment ID is present
{% endstep %}
{% step %}
**(Optional) Deploy at Scale**
For large environments, use tools like:
* Ansible
* Puppet
* Chef
**Example Script**
```
#!/bin/bash
# Install package
dpkg -i keeper-privilege-manager*.deb
# Start service
systemctl start keeper-privilege-manager
# Wait for startup
sleep 20
# Register device
/opt/keeper/sbin/Jobs/bin/KeeperRegistrationHelper/KeeperRegistrationHelper --token="YOUR_TOKEN_HERE"
```
This is the typical pattern used in automation tools.
{% endstep %}
{% step %}
**Validate Deployment**
After deployment, verify everything is working.
**Service is running**
```
keepersudo systemctl status keeper-privilege-manager
```
**Health check works**
```
curl -k https://localhost:6889/health
```
**Device is registered**
Check the Keeper Client about screen by clicking on the Client and then selecting "About".
**Plugins are running (optional)**
```
ps -ef | grep [K]eeper
```
Expected:
* KeeperAPI running
* KeeperPolicy running
**Test sudo enforcement (if enabled)**
```
keepersudo ls /root
```
Depending on your policy, you may see:
* MFA prompt
* Approval request
* Allowed or denied execution
{% endstep %}
{% endstepper %}
### What Happens After Installation
After installation, the agent is placed in `/opt/keeper/` and the service starts via systemd. The device begins collecting system data and synchronizes policies from Keeper. No user disruption occurs until policies are actively enforced.
#### **Linux sudo usage**
After installation, Keeper modifies the PAM module on the device to wrap `sudo`. Any usage of the `sudo` command is delegated to `keepersudo`.
See the [Command Line Policy](https://docs.keeper.io/endpoint-privilege-manager/policies/policy-types/command-line-policy-type.md) documentation for configuration and usage instructions.
#### **Updating**
To update the Agent that has already been registered:
```
curl -o KeeperPrivilegeManagerLinux.zip "https://keepersecurity.com/pam/pedm/core/latest/KeeperPrivilegeManagerLinux.zip"
unzip KeeperPrivilegeManagerLinux.zip
cd linux
keepersudo dpkg -i keeper-privilege-manager_*.deb
```
To identify which version is running:
```
dpkg -l keeper-privilege-manager
```
## **Uninstall on Linux**
Uninstalling the Keeper agent varies based on the platform and the install method used above.
Ubuntu / Debian-based distributions:
```
keepersudo apt remove -y keeper-privilege-manager
```
To remove and purge all configuration file:
```
keepersudo apt purge -y keeper-privilege-manager
```
RPM-based distributions:
```
keepersudo rpm -e keeper-privilege-manager
```
On RHEL / Rocky / Alma / CentOS / Oracle Linux:
```
keepersudo yum remove -y keeper-privilege-manager
or:
keepersudo dnf remove -y keeper-privilege-manager
```
To manually register an agent that has already been installed, the below can be invoked:
### Default Behavior After Deployment
After deployment, the agent starts in Monitor mode, where policies are evaluated but not actively enforced. This allows you to safely test and validate behavior before enabling enforcement.
## Logs (For Troubleshooting)
To view logs, navagate to Keeper's logs directory:
```
/opt/keeper/sbin/Plugins/bin/KeeperLogger/Log/KeeperLoggerYYYYMMDD.log
```
## What the User Experiences
From a user’s perspective, installation is typically silent and does not change their normal workflow. When policies apply, they may see prompts when using `sudo`, such as for MFA or approval. Otherwise, everything continues to work as usual, keeping the experience natural while adding an additional layer of security.
## Important Notes & Common Adjustments
#### PAM is Critical
PAM integration is essential for enforcing command-line policies on Linux. If PAM is not enabled, `sudo` activity will not be controlled, and policies will not be applied.
#### Sudo Behavior Changes
After deployment, `sudo` behavior may be controlled by policy and can require MFA, require approval, or be restricted depending on how policies are configured.
#### Protect Your Token
Registration tokens should not be stored in plain text and should instead be managed using secure configuration or secret management tools. Tokens should also be rotated as needed to reduce the risk of exposure.
#### Service Timing
If registration fails, it may be because the service is not yet fully initialized. In these cases, increasing the delay before running the registration command—such as from 20 seconds to 40 or more—can help ensure the service is ready.
#### Lifecycle Note
To remove or reconfigure the agent, uninstall the package using the appropriate command (`rpm -e` or `dpkg -r`), and re-run the registration process if needed.
## Troubleshooting
### Service Not Running
If the service is not running, check the system logs using:
```
journalctl -u keeper-privilege-manager
```
### Device Not Registering
If a device is not registering, verify that the registration token is correct, check network connectivity, and ensure that the Keeper service is running before attempting registration.
### Sudo Policies Not Working
If sudo policies are not working as expected, confirm that PAM integration is enabled, verify that the configuration has been applied correctly, and check that the appropriate policies are assigned to the device.
### Policies Not Syncing
If policies are not syncing, confirm that the device is successfully registered, check connectivity to the Keeper backend, and verify that the KeeperAPI plugin is running.
## Summary
Deploying Keeper EPM on Linux allows you to:
* Enforce least privilege using **sudo**
* Add MFA, approval, and justification to command-line actions
* Secure servers and developer environments
Keeper integrates directly with native Linux controls, so you get **strong security without changing how users work**.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.keeper.io/keeperpam/endpoint-privilege-manager/deployment/deploy-with-linux.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.