Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Monitoring Gateway events and integrating with your SIEM
KeeperPAM supports integration with your SIEM provider to provide real-time event logging and monitoring of all privileged access management activity. In the Keeper Admin Console, alerts can also be configured based on any event.
For more information on activating SIEM integration from the Keeper Enterprise guide:
See
Push over 200 different event types to any connected SIEM provider
Send alerts to email, SMS, Webhook, Slack or Microsoft Teams on any event trigger
Run custom reports from the Keeper Admin Console or Keeper Commander CLI
Events related to KeeperPAM include:
Starting and stopping sessions, tunnels, remote browser isolation
Gateway lifecycle (online, offline, added/removed)
Connection lifecycle (creation, editing and deleting PAM resources)
As a KeeperPAM administrator, it is useful to receive alerts related to Gateway actions, such as when a Gateway goes offline (in case of server outage or system restart).
From the Admin Console, go to Reporting & Alerts > Alerts > select Event Types and set the recipient information.
Event alert details will include the name and UID of the affected Keeper gateway.
Email alerts contain event information
Sharing the Keeper Gateway with other admins
Keeper Gateways are essential when configuring PAM features such as rotation and connections on PAM resources. Keeper provides KSM Application Sharing from the vault UI and Keeper Commander CLI.
Gateways are tied to Keeper Secrets Manager (KSM) applications. Only users who have access to a KSM application can view and select its associated Gateway when configuring PAM Record Types. Without sharing, only the owner of the KSM application can use the Gateway for PAM configuration.
Sharing the KSM application (and thus the Gateway) allows other administrators or team members to independently configure and manage PAM resources. This is critical when multiple users in your organization are responsible for managing privileged access.
Note: Gateways are automatically shared when the associated KSM application is shared.
When you share the KSM application, you also share access to the associated Gateway.
To share the KSM application:
From the vault, open the KSM Application you want to share
Edit the Application
Navigate to the "Users" tab
In the search bar, enter the user’s email address
Add the user to the application.
For more information, visit this page.
Once the gateway is shared through the KSM application, users who now have access can configure PAM resources using that gateway.
Advanced configuration of the Keeper gateway with Keeper Vault custom fields
When setting up Rotation in your Keeper Vault, you store the credentials of your assets involved in rotation on their corresponding PAM Record Types. On these record types, you are able to create custom fields.
The additional gateway configurations will be defined with these custom fields on the PAM Record Types. The Keeper Gateway will then adjust its behavior based on the defined configurations.
The following tables lists all the possible configurations with custom fields:
Shell
Text
None
Allows you to specify a custom shell path that the Gateway will use when executing rotation and post-rotation scripts. This gives you control over the environment in which these scripts run.
Example Value: C:\MY\SHELL
NOOP
Text
False
Allows you to control whether the Gateway performs the primary rotation operation or proceeds directly to execution of the post-rotation script.
If set to True the Gateway will skip the rotation process and proceed directly in executing the post-rotation script(s).
Example Value: True
Kerberos
Text
False
Specifically designed for WinRM connections using Kerberos authentication.
By default, the Gateway automatically decides whether to use Kerberos based on certain rules, and If these conditions are met, the Gateway will attempt to use Kerberos for WinRM. However, if you encounter issues with this automatic detection, setting this field to True will override the default behavior and force the Gateway to use Kerberos for WinRM.
Example Value: True
Private Key Type
Text
ssh-rsa
Gateway Version 1.3.4+
This custom field pertains to the type or algorithm of the private key stored in a record.
When adding a private key to a record, users do not need to take any additional action regarding its type or algorithm. The system is designed to automatically recognize and use the same algorithm as the existing private key during the rotation process. If the algorithm in use is ECDSA, the key size will also be preserved during the rotation.
Available Options if needed to overwrite the key type:
ssh-rsa (Note: 4096 bits)
ssh-dss (Note: 1024 bit, obsolete) ecdsa-sha2-nistp256
ecdsa-sha2-nistp384
ecdsa-sha2-nistp521
ssh-ed25519
Private Key Rotate
Text
True
Gateway Version 1.3.4+
TRUE - (Default) If the custom field doesn't exist, the private key will be rotated if it exists.
FALSE - The private key won't be rotated, even if it exists. Users should pick this if they wish to retain the private key in the record without any rotations.
Note:
The custom fields values are not case-sensitive.
Creating a Keeper Gateway
In order to install and setup a Keeper Gateway device, you need to have a few resources set up:
Shared Folders to hold the PAM Resources (Machines, Databases, Users, etc)
Keeper Secrets Manager application
PAM Configuration
To simplify the process, we have a new Gateway wizard which creates all of the necessary components. Or, you can run each step individually.
The fastest way to create a Gateway and associated resources is using the Gateway Wizard. From the Web Vault or Desktop App, click on Create New > Gateway.
The below link describes how to create a sandbox environment in just a few steps:
To set up a Keeper Gateway manually using the Keeper Secrets Manager application resources, follow these steps.
In the Keeper Web Vault or Desktop App user interface, create a Shared Folder. This Shared Folder will contain the PAM resource records.
Navigate to the "Secret Managers" tab on the left and click on "Create Application" to create a KSM application
In the prompted window:
Enter the name of your KSM application
Choose the Shared Folder
Set the Record Permissions for Application to "Can Edit"
Click on "Generate Access Token" and then click on "OK"
You can safely ignore the first One-Time Access Token generated for the newly created KSM application. When creating a Keeper Gateway device, a different One-Time Access Token will be created.
You can also create a Gateway and configuration file from the Commander CLI. The below CLI commands will create a Secrets Manager application, shared folders and other resources before creating a Gateway instance.
To initialize a Gateway for or native install methods, the one-time token method is used:
To initialize a Gateway using , the base64 configuration is provided as GATEWAY_CONFIG environment variable as described in the instructions.
Instructions for installing Keeper Gateway on Windows
This document contains information on how to install, configure, and update the Keeper Gateway on Windows.
Prior to proceeding with this document, make sure you .
The latest Keeper Gateway for Windows is downloaded from here:
You can run the service under system privilege or use a service account.
Upon installation of the service, select "Enter a Keeper One-Time Access Token" and supply the token provided by when you on the Vault. After installation, the service will automatically start up and register with the Keeper cloud.
If you are upgrading an existing Gateway, un-check the "Enter a Keeper One-Time Access Token" so that the existing configuration is maintained.
The default installation location is the following:
Install Windows service - Installs the gateway as a Windows service.
Use service account - Use the , otherwise the account installing the gateway will be used.
Start Windows service - Start the Keeper Gateway service immediately after installation
Enable automatic updates
Turn on debug logging - Enable on the gateway log files. NOT recommended for production environments. Only use this when debugging with Keeper support.
Remove Keeper Gateway configuration and logs from previous installations
If "Use service account" is specified you will be prompted to enter the valid credentials of the desired service account:
The final step prior to successfully installing the Keeper Gateway as service is to enter the Token provided from the Keeper Vault.
After clicking "Next", click "Install" in the next screen to install the Keeper Gateway.
After installing and running the Keeper Gateway as a service, this service can be accessed and easily managed within the Windows Services Manager as "Keeper Gateway Service".
The Keeper Gateway configuration file contains a set of tokens that includes encryption keys, client identifiers, and tenant server information used to authenticate and decrypt data from the Keeper Secrets Manager APIs. This configuration file is created from the One-Time Access Token generated when you .
If the Keeper Gateway is installed and running as a service, the gateway configuration file is stored in the following location:
If the Keeper Gateway is installed locally and not running as a service, the gateway configuration file is stored in the following location:
Logs that contain helpful debugging information are automatically created and stored on the local machine.
If the gateway is running as a service, the gateway log files are stored in the following location:
If the gateway is not running as a service, the gateway log files are stored in the following location:
To activate verbose logging:
Go to Windows Services > Keeper Gateway > Properties
Stop the service
Set the "Start parameters" to: --debug or -d
Start the service by clicking on "Start" Do not click "OK" without first starting the service as it will not persist the Parameter setting
To update the Keeper Gateway, stop the service, install the latest version and then start the service.
Run the latest Keeper Gateway installer
During installation DO NOT select "Enter a Keeper One-Time Access Token".
Select "Enable automatic updates" during the installer process to ensure that your Keeper Gateway is automatically updated when there are new versions available.
To monitor the Gateway service, you can configure health checks that expose its operational status. These checks are useful for Docker orchestration, load balancing, and automated monitoring. See the for full setup details and examples.
This section provides instructions for performing a silent installation of the Keeper Gateway on Windows systems. Silent installation allows the setup process to run in the background without displaying any user interface or messages.
To install the Keeper Gateway silently, use the following command in your command prompt or script:
Replace <TOKEN> with the token provided in the Keeper Vault when creating the Keeper Gateway.
If you have previously installed Keeper Gateway and wish to use the existing configuration, you can bypass the token entry by using:
To generate a log file during the installation process, use the following option and specify the desired log file path:
If you prefer to run the Keeper Gateway under a specific Windows service account, use the following options to specify the account details:
Replace <ACCOUNT USERNAME> and <ACCOUNT PASSWORD> with the credentials of the service account you intend to use.
To enable the Auto Updater feature, allowing Keeper Gateway to automatically check for and apply updates, use the following option:
To uninstall the service:
Uninstall Keeper Gateway from "Add and remove programs"
If desired, delete the private configuration .json file
secrets-manager app create "My Infrastructure"mkdir -uf "My Infrastructure"
mkdir -sf -a "My Infrastructure/Resources"
mkdir -sf -a "My Infrastructure/Users"secrets-manager share add --app "My Infrastructure" --secret <Resources folder UID>
secrets-manager share add --app "My Infrastructure" --secret <Users folder UID>pam gateway new -n "My Demo Gateway" -a "My Infrastructure"pam gateway new -n "My Demo Gateway" -a "My Infrastructure" -c b64
C:\ProgramFiles (x86)\Keeper Gateway\<version>C:\ProgramData\KeeperGateway\config\gateway-config.jsonC:\Users\<User>\.keeper\gateway-config.jsonC:\ProgramData\KeeperGateway\logs\C:\Users\<User>\.keeper\logs\keeper-gateway_windows_x86_64.exe /verysilent /suppressmsgboxes /norestart /token=<TOKEN>/existingconfig=1/log=<Optional log file>/mergetasks="service/account" /serviceuser=<ACCOUNT USERNAME> /servicepass=<ACCOUNT PASSWORD>/autoupdate=1
Instructions for installing Keeper Gateway on Docker
This document contains information on how to install, configure, and update your Keeper Gateway on Docker. The Keeper Gateway container is built upon the base image of Rocky Linux 8 and it is hosted in DockerHub.
A Linux host with a x86 AMD processor for all PAM capabilities
docker and docker compose installed (see Docker Install for help)
A new Gateway deployment can be created by clicking on Create New > Gateway from the Web Vault or Desktop App.
You can also create a Gateway and configuration file from the Commander CLI:
pam gateway new -n "<Gateway Name>" -a <Application Name or UID> -c b64The Application names and UIDs can be found with secrets-manager app list
Keeper provides 2 ways of setting up the Gateway:
Keeper's automatic installer will set up the environment for you.
Create a new Gateway with either the Gateway Wizard or using Keeper Secrets Manager for the Docker Operating System.
You will be provided with an installation command to paste into your Linux host.
If you prefer to set up the Docker environment yourself, follow the instructions below.
A Docker Compose file is provided through the Vault UI. Typically this file would be saved in your local environment as docker-compose.yml in your preferred folder. An example is below:
services:
keeper-gateway:
platform: linux/amd64
image: keeper/gateway:latest
shm_size: 16g
restart: unless-stopped
security_opt:
- seccomp:docker-seccomp.json
- apparmor:gateway-apparmor-profile
environment:
ACCEPT_EULA: Y
GATEWAY_CONFIG: XXXXXXXXXXXXXXXXXThe shm_size is a critical parameter. We recommend maximizing this value to at least half of the available server memory. Production gateways should have as much memory and CPU allocated as possible. When using remote browser isolation sessions, Chromium uses a lot of memory for each process.
The only required environment variable setting is GATEWAY_CONFIG which is the resulting base64-encoded configuration provided by Keeper when creating a Gateway.
The file called docker-seccomp.json needs to be downloaded and placed in the same folder as your Docker Compose file.
Download File or:
curl -O https://raw.githubusercontent.com/Keeper-Security/KeeperPAM/refs/heads/main/gateway/docker-seccomp.jsonThe file called gateway-apparmor-profile needs to be placed in the same folder as your Docker Compose file.
Download File or:
curl -O https://raw.githubusercontent.com/Keeper-Security/KeeperPAM/refs/heads/main/gateway/gateway-apparmor-profileActivate the apparmor config
sudo apparmor_parser -r gateway-apparmor-profile
sudo cp gateway-apparmor-profile /etc/apparmor.d/When running the latest version of the Keeper Gateway, you'll see the output in the logs like below:
docker compose logs keeper-gatewayOn the Vault UI in the Secrets Manager > Applications > Gateways screen, the Gateway will show Online.
docker compose up -ddocker compose stopdocker compose restartdocker compose exec keeper-gateway bashIn the docker-compose.yml file, ensure that a restart policy is enabled. For example:
services:
keeper-gateway:
restart: unless-stoppedAdding the "restart: unless-stopped" or "restart: always" parameter in the docker-compose.yml file will assign a restart policy to the environment.
If you would like to force the host operating system to automatically start the Keeper Gateway on a Docker installation, follow these steps (Linux host).
First, create a file /etc/systemd/system/keeper-gateway.service
[Unit]
Description=Keeper Gateway Docker Compose
Requires=docker.service
After=docker.service
[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/path/to/install
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
User=myusername
Group=docker
[Install]
WantedBy=multi-user.targetNOTE:
Replace /path/to/install with the path to your docker-compose.yml
Replace myusername user with your user running Docker
Replace docker group with your defined group
Ensure the binary path for ExecStart and ExecStop are correct
Then enable the service:
sudo systemctl daemon-reload
sudo systemctl enable keeper-gateway.service
sudo systemctl start keeper-gateway.serviceImportant: Ensure that the apparmor file is loaded up and available on reboot
sudo apparmor_parser -r gateway-apparmor-profile
sudo cp gateway-apparmor-profile /etc/apparmor.d/After a reboot, verify that it's running:
systemctl status keeper-gatewayIf you need to enable verbose debug logs on the Gateway, enable debug logging by adding the below environment section variables to your Docker Compose file:
services:
keeper-gateway:
.....
environment:
KEEPER_GATEWAY_LOG_LEVEL: "debug" # logs for gateway
LOG_LEVEL: "debug" # logs for guacdAfter changing the log level, apply the changes to the docker
docker compose up -dTail the logs of the Keeper Gateway using this command:
docker compose logs -f keeper-gatewayExecuting the following command will update the Keeper Gateway container to the latest version and restart the service:
docker compose pull
docker compose up -dTo monitor the Gateway service, you can configure health checks that expose its operational status. These checks are useful for Docker orchestration, load balancing, and automated monitoring. See the Health Check section for full setup details and examples.
Over time, as new versions of the Gateway are deployed, old Docker images may accumulate on the host server. This can consume a significant amount of disk space. To ensure smooth operation and avoid storage issues, we recommend periodically checking your available disk space and removing unused Docker images.
To view your current disk usage, run the following command on your Keeper Gateway server:
df -hThis command displays available disk space on all mounted filesystems in a human-readable format. Pay particular attention to the partition where Docker stores its data (typically /var/lib/docker).
If you notice the disk space running low (for example, more than 80–90% full), it’s a good idea to clean up old Docker images.
When you update the Keeper Gateway, Docker keeps older images on your system. To remove all unused Docker images, you can use the following command:
docker image prune -aThe -a flag ensures that all unused images are deleted (not just dangling ones).
You may be prompted to confirm the action — type y when prompted.
Example output:
WARNING! This will remove all images without at least one container associated to them.
Are you sure you want to continue? [y/N] y
Deleted Images:
...
Total reclaimed space: 4.8GBThis operation safely removes old images that are no longer used by any running containers.
DockerHub listing: https://hub.docker.com/r/keeper/gateway
Quick reference for Installing Docker and Docker Compose on Linux
Storing and protecting the Keeper Gateway Configuration using AWS KMS
If the Keeper Gateway is installed on an AWS EC2 Instance, the corresponding Gateway configuration file can be protected and stored in AWS Secrets Manager. This method eliminates the need for storing a configuration file on the instance, and instead stores the configuration file with AWS KMS protection.
AWS KMS is a fully managed service that makes it easy for you to create and control the cryptographic keys used to encrypt and decrypt your data. The service is integrated with other AWS services, making it easier to encrypt data and manage keys. You will need a AWS KMS key as part of this process, and it is recommended that you follow the principle of least privilege when assigning permissions to this key.
In order to use AWS KMS to protect the Gateway configuration secrets, you need to install the Keeper Gateway on an EC2 instance which assumes an IAM Role. This works on either Docker or Linux install methods.
From the Keeper Vault, go to Secrets Manager > Applications and select the application configured with your Gateway. Then select the Gateways tab and select "Provision Gateway".
Select the Gateway initialization method of "Configuration" and click Next.
Alternatively, you can generate a One-Time Access Token and then use the Keeper Gateway's "gateway ott-init" command:
gateway ott-init [ONE-TIME-TOKEN]In either case, you'll be provided with a base64 encoded configuration. Save this for the next step.
From the AWS Console, go to the Secrets Manager and create a new secret.
Select "Other type of secret"
Select Plaintext and paste the entire base64 value there.
Click Next.
Enter a Secret Name and a description then click Next, Next and Store.
The EC2 instance role needs to be assigned a policy which provides read access to the specific AWS Secrets Manager key. As an example:
{
"Sid": "SecretsManagerPermissions",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": "arn:aws:secretsmanager:us-west-1:XXX:secret:XXX"
}From the EC2 instance, the below command will confirm the policy has been applied:
aws secretsmanager get-secret-value --secret-id YourSecretName --query SecretString --output textFor Docker installations, remove the GATEWAY_CONFIG entry and add AWS_KMS_SECRET_NAME with the value containing the name of the secret from the AWS secrets manager.
services:
keeper-gateway:
platform: linux/amd64
image: keeper/gateway:latest
shm_size: 2g
security_opt:
- seccomp:./docker-seccomp.json
- apparmor=./guacd-apparmor-profile
environment:
ACCEPT_EULA: Y
AWS_KMS_SECRET_NAME: "YourSecretName"Then update the service with the new environment:
docker compose pull
docker compose down
docker compose up -dOpen the Keeper Gateway service unit file:
/etc/systemd/system/keeper-gateway.service
Modify the "ExecStart" line as seen below, replacing YourSecretName with your assigned name.
ExecStart=/bin/bash -c "/usr/local/bin/gateway start --service --aws-kms-secret-name="YourSecretName" --log-to-stdout"Apply changes to the service:
sudo systemctl daemon-reload
sudo systemctl restart keeper-gatewayIf there are any errors starting up, they can be seen through this command:
systemctl status keeper-gateway.serviceInstallation and setup of the Keeper Gateway
The Keeper Gateway is a service that is installed on any Docker, Linux or Windows machine in order to execute rotation, discovery, connection and tunneling. A single Gateway can be used to communicate with any target infrastructure, both on-prem and cloud. Typically, customers deploy a Keeper Gateway in each environment that is being managed.
The Keeper Gateway offers different feature capabilities based on the underlying operating system and hardware. We recommend using Docker on a Linux or Windows host with x86 CPUs for full feature support and ease of management.
Docker (Linux or Windows host w/ x86)
All features supported
Linux (RHEL 8, Rocky Linux 8)
All features supported
Docker (Linux host on ARM)
No Remote Browser Isolation
Linux Binary Install (Ubuntu, Debian)
No Remote Browser Isolation
Limited connection protocols
Windows Binary Install
No Remote Browser Isolation
No database connections
Note: EL9 which includes Rocky Linux 9 and RHEL 9 support is coming soon.
System requirements vary based on the number of simultaneous user sessions and the types of connections being established. As the volume of simultaneous connections grows, scaling CPU and memory resources becomes essential. In particular, remote browser isolation (RBI) launches a headless Chromium instance for each session. If you anticipate a high number of RBI sessions, ensure the system is scaled to meet these demands.
For a testing or sandbox a minimum of 2 CPUs with 8GB of memory and 10GB of storage is required. In a production environment, increase to at least 4 CPUs with 16GB of memory. Scale the number of CPUs and memory as the number of simultaneous sessions increases.
The Keeper Gateway generates encryption keys and a local Secrets Manager configuration that is used to authenticate with the Keeper cloud. The location depends on the context in which the Gateway is being run. It can be installed to the local user or installed as a service.
Login to the Keeper Web Vault or Desktop App (version 17.1 or newer required)
Click on Secrets Manager on the left side
Create a new Secrets Manager Application or select existing application
Click on the "Gateways" tab and click "Provision Gateway"
Select Docker, Linux or Windows install method
Install the Keeper Gateway using the provided method
During the creating of a Keeper Gateway using a one-time token method for Linux and Windows, you have the choice to select "Lock external WAN IP Address of device for initial request". This will additionally IP lock the Gateway in addition to the authentication and encryption built into the service.
Based on your Operating System, refer to the corresponding guide on installing the Keeper Gateway:
If you are installing on an EC2 instance in AWS, the Keeper Gateway can be configured to use the instance role for pulling its configuration from AWS Secrets Manager. Detailed instructions on this setup can be found here.
When sharing a KSM application with other users, the following permissions can be assigned:
Member
Can view the application and use the gateways associated with the application
Shared folders assigned to a KSM application are accessible by the devices and gateways associated with the application. When sharing a KSM application with another user, if the user does not already have access to the shared folders associated with the application, those folders will be automatically shared with the user.
The level of access the user receives to these shared folders depends on their assigned role in the application:
If the user is added as a "Member":
The user receives the "No User Permissions" shared folder permissions
If the user already had access to any of the shared folders before being added to the KSM application, their existing folder permissions remain unchanged and are not overwritten.
Records can be directly assigned to a KSM application via Keeper Commander secrets-manager app share command.
When sharing a KSM application with another user, if the user does not already have access to the records associated with the application, those records will be automatically shared with the user. The level of access the user receives to these records is "View Only".
Note: Adding individual records to a KSM application requires using Keeper Commander.
Removing a user from the KSM application does not revoke their permissions from the shared folders. Folder access must be manually removed if desired.
The Keeper Gateway establishes outbound-only connections and does not require any inbound firewall rules. The following outbound connections must be allowed:
Keeper Cloud (keepersecurity.[com|eu|com.au|jp|ca|us])
TLS Port 443
Communicates with Keeper Cloud to access target infrastructure via native protocols (e.g., SSH, RDP)
Keeper Router (connect.keepersecurity.[com|eu|com.au|jp|ca|us])
TLS Port 443
Communicates with Keeper Router to establish secure, real-time WebSocket connections
Keeper KRelay Server (krelay.keepersecurity.[com|eu|com.au|jp|ca|us])
TCP and UDP opened on Port 3478 Outbound access to TCP and UDP ports 49152 through 65535
Facilitates secure and encrypted relay connections between end-user's vault and target systems via the Gateway
The Gateway preserves zero knowledge by performing all encryption and decryption of data locally. Keeper Secrets Manager APIs are used to communicate with the Keeper cloud.
Keeper Gateway SHA256 hashes for the latest version are published at the below location:
https://keepersecurity.com/pam/latest.txt
Calculating and verifying the checksum:
sha256sum keeper-gateway_linux_x86_64
cat keeper-gateway_X.X.X_SHA256SUMS | grep keeper-gateway_linux_x86_64Get-FileHash -Algorithm SHA256 keeper-gateway_windows_x86_64.exe | Format-List
Get-Content keeper-gateway_X.X.X_SHA256SUMS | Select-String keeper-gateway_windows_x86_64.exeInstructions for installing and configuring the Auto Updater for the Keeper Gateway.
Automatic updates of the Keeper Gateway can be enabled on Linux and Windows installations through Keeper's Auto Updater feature. The Auto Updater makes periodic checks to update your Keeper Gateway to the latest version.
We recommend enabling the Auto Updater to ensure you receive the most recent security and functionality enhancements. The Auto Updater verifies all Keeper Gateway downloads by checking the GPG signature of hash value, which are then utilized to checksum each file.
Ensure that you have administrative privileges on the system.
Version 1.4.0 or later of Keeper Gateway is required.
On Docker based installations, the best way to update the container is running the below commands from a cron job or your CI/CD tools.
As an example, create a file called update_gateway.sh that contains:
#!/bin/bash
set -e # Exit immediately if a command fails
# Navigate to the directory containing your docker-compose.yml file
cd /path/to/your/docker-compose-directory
# Pull the latest image and update the Gateway container
docker compose pull
docker compose up -d keeper-gatewayMake the script executable:
chmod +x update_gateway.shEdit the crontab:
crontab -eAdd a line to schedule the script. For example, to run it every day at 3 AM:
0 3 * * * /path/to/update_gateway.sh >> /var/log/update_gateway.log 2>&1Execute the following command to download and run the KeeperPAM installer with auto update enabled.
The --autoupdate parameter activates the auto updater in addition to the Keeper Gateway.
curl -fsSL https://keepersecurity.com/pam/install | \
sudo bash -s -- --autoupdateActivate the Auto Updater on an existing installation by executing the following Keeper Gateway command:
sudo keeper-gateway autoupdate enableVerify Installation (Optional)
Verify that the Auto Updater has been installed successfully by executing the following Keeper Gateway command:
sudo keeper-gateway autoupdate statusDownload and run the latest version of the Gateway installer.
During installation, check the box "Enable automatic updates".
This setup option will create a new Task Scheduler task for updating the Gateway.
Existing Gateway
Open a command prompt as Administrator.
Install Auto Updater with the following Keeper Gateway command:
keeper-gateway autoupdate enableVerify Installation (Optional)
Open a command prompt as Administrator.
Verify that Auto Updater has been installed successfully by executing the following Keeper Gateway command:
keeper-gateway autoupdate statusEnsure that you have administrative privileges on the system.
Version 1.4.0 or later of Keeper Gateway is required.
Check the Auto Updater status by executing the following Keeper Gateway command:
sudo keeper-gateway autoupdate statusOpen a command prompt as Administrator
Check the Auto Updater status by executing the following Keeper Gateway command:
keeper-gateway autoupdate statusEdit the crontab that runs Auto Updater.
sudo crontab -eHere is an example of the default crontab entry that checks for updates every hour:
0 * * * * /usr/local/bin/keeper-gateway-update --trustThe first part 0 * * * * is the crontab expression which will cause execution to occur every hour at 0 minutes.
The second part is the update command keeper-gateway-update
The option --trust causes explicit trust of the Keeper Gateway GPG public key for verification of downloaded install files.
Configure the update frequency and other settings with the following steps:
Run taskschd.msc to open Windows Task Scheduler.
In the left pane double-click on Task Scheduler Library -> Keeper -> Gateway -> AutoUpdate to show the Auto Updater Task.
In the upper middle pane double-click on the AutoUpdate Task with the name of the current version and click on the Triggers menu tab.
Click Edit... to change when the Auto Updater checks for a new update to install. The default is to "Repeat task every 1 hour indefinitely" as shown below.
Ensure that you have administrative privileges on the system.
Version 1.4.0 or later of Keeper Gateway is required.
Remove Auto Updater by executing the following Keeper Gateway command:
sudo keeper-gateway autoupdate disableRemove Auto Updater with the following steps:
Open a command prompt as Administrator.
Remove Auto Updater with the following Keeper Gateway command:
keeper-gateway autoupdate disablekeeper-gateway autoupdate statusTo assist with diagnosing issues or monitoring the status of updates, the Gateway Auto Updater generates two types of logs. These logs are subject to rotation policies to avoid overuse of disk space.
Log Location
All log files for Linux are located in /var/log/keeper-gateway
Log Files
Update Logs:
Any logs generated during an update will be timestamped and stored as update_YYYY-MM-DD_HH-MM-SS.log.
Last Update Check:
The file last-update-check.log contains information regarding the most recent check for updates.
The log files for the Gateway Auto Updater are located in \ProgramData\KeeperGateway\install
Log Files
Update Logs:
Any logs generated during an update will be timestamped and stored as YYYY-MM-DD_HH-MM-SS.log
Last Update Check:
The file last-update-check.log contains information regarding the most recent check for updates.
Instructions for installing Keeper Gateway on Linux with native packages
This document contains information on how to install, configure, and update your Keeper Gateway on Linux with native packages.
Prior to proceeding with this document, make sure you created a Gateway device.
For full capabilities, use Rocky Linux 8, RHEL 8 or Alma Linux 8.
If you cannot use one of these Linux flavors, please install using the Docker method
Executing the following command will install the Keeper Gateway, and run it as a service:
curl -fsSL https://keepersecurity.com/pam/install | \
sudo bash -s -- --token XXXXXXReplace XXXXX with the One-Time Access Token provided from creating the Keeper Gateway
The gateway will be installed in the following location:
/usr/local/bin/keeper-gatewayAn alias gateway is also created in the same directory
gateway -> /usr/local/bin/keeper-gatewayFor managing the Keeper Gateway as a service, the following are created during the Gateway installation:
A keeper-gateway folder
A keeper-gw user
keeper-gateway folder
The keeper-gateway folder contains the gateway configuration file and is created in the following location:
/etc/keeper-gatewaykeeper-gw user
During the gateway installation, a new user, keeper-gw, is created and added to the sudoers list in /etc/sudoers.d/.
The keeper-gw user is the owner of the keeper-gateway folder and runs the gateway service. This is required when performing rotations on the gateway service and performing post-execution scripts.
The following commands can be executed to start, restart, or stop the Keeper Gateway as a service:
sudo systemctl start keeper-gateway
sudo systemctl restart keeper-gateway
sudo systemctl stop keeper-gatewayThe Keeper Gateway configuration file contains a set of tokens that includes encryption keys, client identifiers, and tenant server information used to authenticate and decrypt data from the Keeper Secrets Manager APIs. This configuration file is created from the One-Time Access Token generated when you created the Gateway.
If the Keeper Gateway is installed and running as a service, the gateway configuration file is stored in the following location:
/etc/keeper-gateway/gateway-config.jsonIf the Keeper Gateway is installed locally and not running as a service, the gateway configuration file is stored in the following location:
<User>/.keeper/gateway-config.jsonLogs that contain helpful debugging information are automatically created and stored on the local machine.
If the Gateway is running as a service, the log files are stored in the following location:
/var/log/keeper-gateway/If the Gateway is not running as a service, the log files are stored in the following location:
<User>/.keeper/logs/To add verbose debug logging, modify this file:
/etc/systemd/system/keeper-gateway.serviceand add the -d flag to the "gateway start" command, e.g:
ExecStart=/bin/bash -c "/usr/local/bin/gateway start --service -d --config-file /etc/keeper-gateway/gateway-config.json"Apply changes to the service:
sudo systemctl daemon-reload
sudo systemctl restart keeper-gatewayTailing the Logs
sudo journalctl -u keeper-gateway.service -fExecuting the following command will update the Keeper Gateway to the latest version:
curl -fsSL https://keepersecurity.com/pam/install | sudo bash -s --Configure your Keeper Gateway installation to automatically check for updates, ensuring it stays up-to-date with the latest version.
Executing the following command will uninstall the Keeper Gateway:
curl -fsSL https://keepersecurity.com/pam/uninstall | sudo bash -s --To monitor the Gateway service, you can configure health checks that expose its operational status. These checks are useful for Docker orchestration, load balancing, and automated monitoring. See the Health Check section for full setup details and examples.
The Keeper Gateway establishes outbound-only connections and does not require any inbound firewall rules. The following outbound connections must be allowed:
The Gateway preserves zero knowledge by performing all encryption and decryption of data locally. Keeper Secrets Manager APIs are used to communicate with the Keeper cloud.
Keeper Gateway SHA256 hashes for the latest version are published at the below location:
Calculating and verifying the checksum:
The Keeper Gateway establishes outbound-only connections and does not require any inbound firewall rules. The following outbound connections must be allowed:
Keeper Cloud (keepersecurity.[com|eu|com.au|jp|ca|us])
TLS Port 443
Communicates with Keeper Cloud to access target infrastructure via native protocols (e.g., SSH, RDP)
Keeper Router (connect.keepersecurity.[com|eu|com.au|jp|ca|us])
TLS Port 443
Communicates with Keeper Router to establish secure, real-time WebSocket connections
Keeper KRelay Server (krelay.keepersecurity.[com|eu|com.au|jp|ca|us])
TCP and UDP opened on Port 3478 Outbound access to TCP and UDP ports 49152 through 65535
Facilitates secure and encrypted relay connections between end-user's vault and target systems via the Gateway
The Gateway preserves zero knowledge by performing all encryption and decryption of data locally. Keeper Secrets Manager APIs are used to communicate with the Keeper cloud.
Keeper Cloud (keepersecurity.[com|eu|com.au|jp|ca|us])
TLS Port 443
Communicates with Keeper Cloud to access target infrastructure via native protocols (e.g., SSH, RDP)
Keeper Router (connect.keepersecurity.[com|eu|com.au|jp|ca|us])
TLS Port 443
Communicates with Keeper Router to establish secure, real-time WebSocket connections
Keeper KRelay Server (krelay.keepersecurity.[com|eu|com.au|jp|ca|us])
TCP and UDP opened on Port 3478 Outbound access to TCP and UDP ports 49152 through 65535
Facilitates secure and encrypted relay connections between end-user's vault and target systems via the Gateway
sha256sum keeper-gateway_linux_x86_64
cat keeper-gateway_X.X.X_SHA256SUMS | grep keeper-gateway_linux_x86_64Get-FileHash -Algorithm SHA256 keeper-gateway_windows_x86_64.exe | Format-List
Get-Content keeper-gateway_X.X.X_SHA256SUMS | Select-String keeper-gateway_windows_x86_64.exe
Monitoring the Keeper Gateway using health checks
This document describes the health check functionality implemented for the KeeperPAM Gateway. Health checks provide essential monitoring capabilities that solve several common operational challenges.
Health Checks provide the following benefits:
Allow load balancers to automatically remove unhealthy instances from rotation and add them back when they recover.
Integrate with monitoring systems (Prometheus, Nagios, Datadog, etc.) to provide automated alerting and dashboards showing gateway health across your infrastructure.
Enable automated monitoring scripts and orchestration tools to detect failures and trigger recovery procedures without human intervention.
The health check service is disabled by default. You must activate it as documented in the next sections.
The below configuration enables a basic health check service on the binary and Docker installation methods. More advanced configuration is also available as documented below.
Start the gateway with health check enabled:
gateway start --health-checkOnly after the gateway is running with health check enabled, you can check its health:
gateway health-checkIf you get an error like "Could not connect to health check server", it means you haven't enabled the health check properly.
If you see "Exception No such command 'keeper-gateway.exe'", you're using the wrong command syntax. Always use "gateway" as the command name.
Modify the docker-compose.yml file to enable health checks:
Add KEEPER_GATEWAY_HEALTH_CHECK_ENABLED
Add the healthcheck section with the desired check intervals
keeper-gateway:
...
environment:
...
KEEPER_GATEWAY_HEALTH_CHECK_ENABLED: 'true'
healthcheck:
test:
- CMD
- /usr/local/bin/keeper-gateway
- health-check
interval: 30s
timeout: 10s
retries: 3
start_period: 60s
...
restart: unless-stoppedAfter changing the docker-compose file, pick up the changes and restart the container:
docker compose up -dIf the container name is keeper-gateway, a one-line bash command to find the service status can be found like this:
docker inspect --format='{{.State.Health.Status}}' keeper-gatewayIf you don't know the container name, this script will give it to you:
docker ps --filter "status=running" --format "{{.Names}} {{.Image}}" | grep keeper-gateway | awk '{print $1}'Here's an example of checking the health with a bash command:
$ docker inspect --format='{{.State.Health.Status}}' my-gateway-container
healthyThe below complete bash script can be added to your watchdog services to check service status and automatically restart the container if it's unhealthy. Replace /path/to/ with the proper path.
#!/bin/bash
LOGFILE="/path/to/keeper-watchdog.log"
# Find running container matching keeper-gateway
CONTAINER_NAME=$(docker ps --filter "status=running" --format "{{.Names}} {{.Image}}" | grep keeper-gateway | awk '{print $1}')
if [ -z "$CONTAINER_NAME" ]; then
echo "$(date): No running keeper-gateway container found." >> "$LOGFILE"
else
# Get health status
HEALTH=$(docker inspect --format='{{.State.Health.Status}}' "$CONTAINER_NAME")
if [ "$HEALTH" != "healthy" ]; then
echo "$(date): $CONTAINER_NAME is $HEALTH. Restarting..." >> "$LOGFILE"
docker restart "$CONTAINER_NAME"
else
echo "$(date): $CONTAINER_NAME is healthy." >> "$LOGFILE"
fi
fi
# Trim log file to last 100 lines
tail -n 100 "$LOGFILE" > "$LOGFILE.tmp" && mv "$LOGFILE.tmp" "$LOGFILE"To schedule this health check on a Linux system, it can be added to the cron
crontab -eAdd to the crontab to watch every minute...
* * * * * /path/to/watchdog.shThe below section provides detailed configuration for customization of the health checks in different environments.
Basic HTTP
gateway start --health-check
gateway health-check
curl http://127.0.0.1:8099/health
HTTP with Auth
gateway start --health-check --health-check-auth-token mytoken
gateway health-check --token mytoken
curl -H "Authorization: Bearer mytoken" http://127.0.0.1:8099/health
HTTPS (SSL)
gateway start --health-check --health-check-ssl --health-check-ssl-cert /path/cert.pem --health-check-ssl-key /path/key.pem
gateway health-check --ssl
curl -k https://127.0.0.1:8099/health
HTTPS with Auth
gateway start --health-check --health-check-ssl --health-check-ssl-cert /path/cert.pem --health-check-ssl-key /path/key.pem --health-check-auth-token mytoken
gateway health-check --ssl --token mytoken
curl -k -H "Authorization: Bearer mytoken" https://127.0.0.1:8099/health
Custom Port
gateway start --health-check --health-check-port 8443
gateway health-check --port 8443
curl http://127.0.0.1:8443/health
Custom Host
gateway start --health-check --health-check-host 0.0.0.0
gateway health-check --host 0.0.0.0
curl http://0.0.0.0:8099/health
Production Setup
gateway start --health-check --health-check-host 0.0.0.0 --health-check-port 8443 --health-check-ssl --health-check-ssl-cert /etc/ssl/cert.pem --health-check-ssl-key /etc/ssl/key.pem --health-check-auth-token $(cat /etc/secrets/token)
gateway health-check --host 0.0.0.0 --port 8443 --ssl --token $(cat /etc/secrets/token)
curl -k -H "Authorization: Bearer $(cat /etc/secrets/token)" https://0.0.0.0:8443/health
Simple Status
gateway health-check --ssl --token mytoken
Returns OK: Gateway is running and connected (exit code 0) or CRITICAL: ... (exit code 1)
Detailed Info
gateway health-check --ssl --token mytoken --info
Key=value pairs suitable for monitoring scripts
JSON Format
gateway health-check --ssl --token mytoken --json
Full JSON response matching HTTP endpoint
Check if server is running
curl http://127.0.0.1:8099/health
Connection success or "Connection refused"
Test SSL connectivity
curl -k https://127.0.0.1:8099/health
SSL handshake success or SSL error
Test authentication
curl -k -H "Authorization: Bearer wrongtoken" https://127.0.0.1:8099/health
{"error": "Invalid authentication token"}
Check server binding
curl http://0.0.0.0:8099/health
Success if bound to 0.0.0.0, failure if bound to 127.0.0.1
The CLI health check provides detailed error messages to help diagnose issues:
Authentication Errors (HTTP 401)
CRITICAL: Authentication failed when connecting to https://127.0.0.1:8099/health
ERROR: Invalid or missing authentication token.
Possible fixes:
1. Check if auth token is required:
curl -k https://127.0.0.1:8099/health
2. Provide the correct auth token:
gateway health-check --ssl --token YOUR_TOKEN
3. Check gateway startup logs for the configured tokenConnection Errors
CRITICAL: Could not connect to health check server at http://127.0.0.1:8099/health
ERROR: Connection failed.
Possible causes:
1. Health check server is not running
2. Wrong host/port combination
3. Network connectivity issues
4. SSL/non-SSL mismatch
Troubleshooting steps:
1. Verify gateway is running with health check enabled:
gateway start --health-check
2. Check if server is using SSL:
gateway health-check --ssl
3. Verify host and port:
Current: 127.0.0.1:8099
4. Test with curl:
curl http://127.0.0.1:8099/healthSSL Certificate Errors
CRITICAL: SSL error connecting to health check server at https://127.0.0.1:8099/health
ERROR: SSL certificate validation failed.
Possible causes:
- Self-signed certificate (try curl with -k flag)
- Invalid certificate path
- Certificate expiredThe Gateway health check is implemented using Bottle, a lightweight WSGI micro web-framework for Python. Bottle was chosen for the following advantages:
Minimal dependency (single file, ~60KB in size)
Enhanced security over the built-in Python HTTP server
Proper request routing and handling
Better error management
Thread safety
Production-ready with minimal overhead
You can check the gateway's health from the command line:
gateway health-checkThis command returns:
Exit code 0 if the gateway is healthy
Exit code 1 if the gateway is not running or not healthy
Text output indicating the status (OK/CRITICAL/WARNING)
For detailed output in a machine-parsable format (one key=value pair per line):
gateway health-check -iFor JSON format output (matching the HTTP endpoint format):
gateway health-check -jIf your health check server is using SSL:
gateway health-check --sslIf your health check server requires authentication:
gateway health-check --ssl --token your_auth_tokenIf your health check server is running on a non-default port:
gateway health-check --port 8123If your health check server is running on a different host:
gateway health-check --host 10.0.0.5The detailed output includes:
Gateway version
Connection status
WebSocket metrics (when available)
Process information (in background mode)
This makes it suitable for monitoring scripts and cron jobs.
Note: The CLI health check command requires the HTTP health check server to be running. If the health check server is not running, the command will return an error message suggesting to enable the health check server.
The gateway includes a secure HTTP health check endpoint that can be enabled with environment variables or command line arguments.
The health check server can be configured using environment variables or command line arguments:
Environment Variables
KEEPER_GATEWAY_HEALTH_CHECK_ENABLED
Enable HTTP health check (1, true, yes)
Disabled
KEEPER_GATEWAY_HEALTH_CHECK_PORT
Port for HTTP server
8099
KEEPER_GATEWAY_HEALTH_CHECK_HOST
Host address to bind to
127.0.0.1
KEEPER_GATEWAY_HEALTH_CHECK_AUTH_TOKEN
Authentication token for requests
None
KEEPER_GATEWAY_HEALTH_CHECK_USE_SSL
Enable SSL (1, true, yes)
Disabled
KEEPER_GATEWAY_HEALTH_CHECK_SSL_CERT
Path to SSL certificate
None
KEEPER_GATEWAY_HEALTH_CHECK_SSL_KEY
Path to SSL private key
None
Command Line Arguments
When starting the gateway, you can also use these command line arguments:
--health-check Enable the health check server
--health-check-port INT Port for the health check server (default: 8099)
--health-check-host STRING Host address to bind to (default: 127.0.0.1)
--health-check-auth-token Auth token for the health check server
--health-check-ssl Enable SSL for the health check server
--health-check-ssl-cert Path to SSL certificate
--health-check-ssl-key Path to SSL private keyCommand line arguments take precedence over environment variables when both are specified.
Example Commands
Basic health check with default settings:
gateway start --health-checkCustom port and authentication token:
gateway start --health-check --health-check-port 9000 --health-check-auth-token mysecrettokenBind to all interfaces (only in secure environments):
gateway start --health-check --health-check-host 0.0.0.0Enable SSL with certificate and key:
gateway start --health-check --health-check-ssl --health-check-ssl-cert /path/to/cert.pem --health-check-ssl-key /path/to/key.pemComplete example with all options:
gateway start --health-check --health-check-port 8443 --health-check-host 10.0.0.5 --health-check-auth-token mysecrettoken --health-check-ssl --health-check-ssl-cert /path/to/cert.pem --health-check-ssl-key /path/to/key.pemWhen enabled, the HTTP health check endpoint will be available at:
http://localhost:8099/healthOr with SSL:
https://localhost:8099/healthThe endpoint returns:
HTTP 200 if the gateway is healthy
HTTP 503 if the gateway is not healthy
JSON response with details:
{
"status": "healthy",
"message": "Gateway is running and connected",
"details": {
"timestamp": 1742849941,
"version": 1,
"connection_status": "connected",
"websocket": {
"uptime_seconds": 85,
"uptime_human": "1m 25s",
"last_ping_received_seconds_ago": 10,
"latency_ms": 75,
"last_ping_sent_timestamp": 1742850455,
"last_pong_received_timestamp": 1742850455
}
}
}The response includes:
status: Overall health status ("healthy" or "unhealthy")
message: Human-readable description of the status
details: Detailed information about the gateway
timestamp: Current server timestamp
version: API version
connection_status: Current connection status ("connected", "disconnected", etc.)
websocket: WebSocket connection metrics
uptime_seconds: WebSocket connection uptime in seconds
uptime_human: Human-readable uptime (e.g., "1m 25s")
last_ping_received_seconds_ago: Seconds since the last ping was received
latency_ms: Round-trip latency of the last ping-pong in milliseconds
last_ping_sent_timestamp: Unix timestamp when the last ping was sent
last_pong_received_timestamp: Unix timestamp when the last pong was received
Example Responses
Healthy Gateway:
{
"status": "healthy",
"message": "Gateway is running and connected",
"details": {
"timestamp": 1742849941,
"version": 1,
"connection_status": "connected",
"websocket": {
"uptime_seconds": 85,
"uptime_human": "1m 25s",
"last_ping_received_seconds_ago": 10,
"latency_ms": 75,
"last_ping_sent_timestamp": 1742850455,
"last_pong_received_timestamp": 1742850455
}
}
}Unhealthy Gateway:
{
"status": "unhealthy",
"message": "Gateway is not properly connected (status: reconnecting)",
"details": {
"timestamp": 1742850874,
"version": 1,
"connection_status": "reconnecting",
"websocket": {
"uptime_seconds": 1018,
"uptime_human": "16m 58s",
"last_ping_received_seconds_ago": 324,
"latency_ms": 77
}
}
}Note that some metrics like latency_ms, last_ping_sent_timestamp, and last_pong_received_timestamp may not always be present in the response. The availability of these metrics depends on the current state of the WebSocket connection and the timing of ping/pong messages.
The health check reflects the current state of the WebSocket connection, but there may be a delay in status updates.
Delayed Status Updates
When connectivity is lost, it may take up to 2 minutes for the health check to report an "unhealthy" status, as the gateway attempts to reconnect. Similarly, when connectivity is restored, it may take up to 2 minutes for the health check to reflect a "healthy" status.
This latency is intentional and allows the gateway to attempt reconnection without immediately reporting failures for transient connectivity issues.
The HTTP health check includes the following security features:
Authentication: When KEEPER_GATEWAY_HEALTH_CHECK_AUTH_TOKEN is set, requests must include the token in the Authorization header:
Authorization: Bearer <token>SSL/TLS: When SSL is enabled, all communication is encrypted. You must provide a valid certificate and private key.
Localhost binding: The server binds to localhost only by default, not exposing the endpoint over the network.
Security Headers: The health check server adds the following security headers to responses:
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Content-Security-Policy: default-src 'none'
Rate Limiting: Automatic rate limiting is applied to non-localhost connections (60 requests per minute per IP).
Information Protection: When the server is bound to a non-localhost address, sensitive information is automatically redacted from the response.
Forced SSL: SSL is automatically enforced when binding to non-localhost interfaces.
The health check server is configured to support a wide range of clients by:
Using secure TLS defaults (TLS 1.2+ minimum) for maximum security
Supporting modern cipher suites for strong encryption
Automatically handling protocol negotiation for HTTP and HTTPS
For clients that support modern TLS versions, use standard curl commands:
curl -k -H "Authorization: Bearer your_token" https://localhost:8099/healthWhen running Keeper Gateway inside Docker, special configuration may be required to expose the health check to the host or external systems:
Binding to 0.0.0.0
The health check server must bind to 0.0.0.0 to be reachable outside the container.
127.0.0.1 restricts access to within the container only.
SSL Enforcement
When using 0.0.0.0, Keeper Gateway forces SSL to protect health check data.
You must provide a valid certificate and key or the server will not start.
Authentication Requirement
If binding to 0.0.0.0, you must also specify an AUTH_TOKEN to secure the endpoint.
Docker Compose Example
services:
keeper-gateway:
image: keeper/gateway:latest
ports:
- "8099:8099"
volumes:
- ./certs:/certs:ro
environment:
KEEPER_GATEWAY_HEALTH_CHECK_ENABLED: true
KEEPER_GATEWAY_HEALTH_CHECK_HOST: "0.0.0.0"
KEEPER_GATEWAY_HEALTH_CHECK_PORT: 8099
KEEPER_GATEWAY_HEALTH_CHECK_USE_SSL: true
KEEPER_GATEWAY_HEALTH_CHECK_SSL_CERT: /certs/healthcheck.crt
KEEPER_GATEWAY_HEALTH_CHECK_SSL_KEY: /certs/healthcheck.key
KEEPER_GATEWAY_HEALTH_CHECK_AUTH_TOKEN: mysecrettokenGenerate a Self-Signed Certificate
mkdir -p certs
openssl req -x509 -nodes -days 365 \
-newkey rsa:2048 \
-keyout certs/healthcheck.key \
-out certs/healthcheck.crt \
-subj "/CN=localhost"Test the Endpoint from the Host
curl -k -H "Authorization: Bearer mysecrettoken" https://localhost:8099/health# Enable HTTP health check
export KEEPER_GATEWAY_HEALTH_CHECK_ENABLED=true
export KEEPER_GATEWAY_HEALTH_CHECK_PORT=8099
export KEEPER_GATEWAY_HEALTH_CHECK_AUTH_TOKEN=mysecrettoken
# Start the gateway
gateway startOr using command line arguments:
gateway start --health-check --health-check-port 8099 --health-check-auth-token mysecrettokenFor testing or internal use, you can generate self-signed certificates to enable SSL/TLS encryption:
# Generate a private key
openssl genrsa -out healthcheck.key 2048
# Generate a certificate signing request (CSR)
openssl req -new -key healthcheck.key -out healthcheck.csr -subj "/CN=localhost"
# Generate a self-signed certificate (valid for 365 days)
openssl x509 -req -days 365 -in healthcheck.csr -signkey healthcheck.key -out healthcheck.crt
# Set the environment variables
export KEEPER_GATEWAY_HEALTH_CHECK_ENABLED=true
export KEEPER_GATEWAY_HEALTH_CHECK_USE_SSL=true
export KEEPER_GATEWAY_HEALTH_CHECK_SSL_CERT=/path/to/healthcheck.crt
export KEEPER_GATEWAY_HEALTH_CHECK_SSL_KEY=/path/to/healthcheck.key
export KEEPER_GATEWAY_HEALTH_CHECK_PORT=8443 # Typical HTTPS port
export KEEPER_GATEWAY_HEALTH_CHECK_AUTH_TOKEN=mysecrettoken
# Start the gateway
gateway startOr using command line arguments:
gateway --health-check --health-check-port 8443 --health-check-ssl --health-check-ssl-cert /path/to/healthcheck.crt --health-check-ssl-key /path/to/healthcheck.key --health-check-auth-token mysecrettoken startWhen using self-signed certificates, your HTTP client will need to be configured to trust the certificate or ignore SSL verification (not recommended for production).
This endpoint can be used with monitoring systems like:
Prometheus with blackbox exporter
Nagios/Icinga
Zabbix
Datadog
AWS CloudWatch
Any monitoring system that can perform HTTP checks
A very useful capability of the Keeper Gateway is being able to open connections and tunnels to the host machine. By adding the extra_hosts section to your docker compose file with a value of host.docker.internal:host-gateway, you can open sessions directly to the host.
Example docker compose with the Gateway container:
services:
keeper-gateway:
platform: linux/amd64
image: keeper/gateway:latest
shm_size: 16g
restart: always
extra_hosts:
- "host.docker.internal:host-gateway"
security_opt:
- seccomp:./docker-seccomp.json
- apparmor=./gateway-apparmor-profile
environment:
ACCEPT_EULA: Y
GATEWAY_CONFIG: xxxxxxxxEnabling this option allows you to establish a Connection to the host. For example, to open an SSH connection:
Create a PAM User record with the SSH private key
Create a PAM Machine record with the hostname to host.docker.internal and port 22
Activate the SSH connection in PAM settings referencing the PAM User
If you use KeeperPAM to SSH over to the host service, you can upgrade the container by running the container update of the gateway in the background:
docker compose pull
nohup docker compose up -d keeper-gateway &