Overview

This section will cover additional configurations to modify the Keeper Gateway's default behavior.

Advanced Configurations

• Storing Gateway Configuration in AWS KMS

• Gateway Configuration with Custom Fields

• Proxy Configuration

Overview

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.

Platforms Supported

Platform Specific Capabilities

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.

Note: EL9 which includes Rocky Linux 9 and RHEL 9 support is coming soon.

System Requirements

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.

Installation Steps

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:

Additional Installation Configurations

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 .

Overview

This document contains information on how to install, configure, and update your Keeper Gateway on Linux with native packages.

Prerequisites

• Prior to proceeding with this document, make sure you .

• 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

Installation

Install Command

Executing the following command will install the Keeper Gateway, and run it as a service:

• Replace XXXXX with the One-Time Access Token provided from creating the Keeper Gateway

Installation Location

The gateway will be installed in the following location:

An alias gateway is also created in the same directory

Gateway Service Management

For 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:

keeper-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.

Managing the Gateway Service

The following commands can be executed to start, restart, or stop the Keeper Gateway as a service:

Keeper Gateway Configuration File

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:

Keeper Gateway Log files

Logs 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:

If the Gateway is not running as a service, the log files are stored in the following location:

Verbose Logging

To add verbose debug logging, modify this file:

and add the -d flag to the "gateway start" command, e.g:

Apply changes to the service:

Tailing the Logs

Updating

Executing the following command will update the Keeper Gateway to the latest version:

Auto Update

Configure your Keeper Gateway installation to automatically check for updates, ensuring it stays up-to-date with the latest version.

Uninstalling

Executing the following command will uninstall the Keeper Gateway:

Health Checks

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.

Overview

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.

Using the Gateway Wizard

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:

• Quick Start: Sandbox

Using Keeper Secrets Manager

To set up a Keeper Gateway manually using the Keeper Secrets Manager application resources, follow these steps.

Using Commander CLI

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.

Create an Application

secrets-manager app create "My Infrastructure"

Create Folders

mkdir -uf "My Infrastructure"
mkdir -sf -a "My Infrastructure/Resources"
mkdir -sf -a "My Infrastructure/Users"

Share the KSM app to the Shared Folders

secrets-manager share add --app "My Infrastructure" --secret <Resources folder UID>
secrets-manager share add --app "My Infrastructure" --secret <Users folder UID>

Create a Gateway

To initialize a Gateway for Linux or Windows native install methods, the one-time token method is used:

pam gateway new -n "My Demo Gateway" -a "My Infrastructure"

To initialize a Gateway using Docker, the base64 configuration is provided as GATEWAY_CONFIG environment variable as described in the Docker Installation instructions.

pam gateway new -n "My Demo Gateway" -a "My Infrastructure" -c b64

Overview

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

Features

• 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 CLI

KeeperPAM Events

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)

Recommended Alerts

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

Overview

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 Key Management Service (KMS) Key

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.

Prerequisites

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.

• Docker Installation

• Linux Installation

Generate a Configuration

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.

Create Secret in AWS Secrets Manager

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.

Assign Policy to Instance Role

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"
}

Confirming Access

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 text

Configuration of the Keeper Gateway

Docker Install Method

For 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 -d

Linux Install Method

Open 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-gateway

If there are any errors starting up, they can be seen through this command:

systemctl status keeper-gateway.service

Overview

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.

Why is Gateway Sharing Needed?

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.

Sharing KSM applications

When you share the KSM application, you also share access to the associated Gateway.

To share the KSM application:

1. From the vault, open the KSM Application you want to share

2. Edit the Application

3. Navigate to the "Users" tab

4. In the search bar, enter the user’s email address

5. Add the user to the application.

For more information, visit this .

User Permissions

Outcomes

Once the gateway is shared through the KSM application, users who now have access can configure PAM resources using that gateway.

Advanced Gateway Configuration with 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:

Note:

• The custom fields values are not case-sensitive.

Overview

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.

Prerequisites

• A Linux host with a x86 AMD processor for all PAM capabilities

• docker and docker compose installed (see Docker Install for help)

Create a Gateway

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 b64

The Application names and UIDs can be found with secrets-manager app list

Installation Options

Keeper provides 2 ways of setting up the Gateway:

• Auto Docker Installation

• Manual Installation

Option 1: Auto Docker Installation

Keeper's automatic installer will set up the environment for you.

docker compose up -d

Option 2: Manual Docker Installation

If you prefer to set up the Docker environment yourself, follow the instructions 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: XXXXXXXXXXXXXXXXX

curl -O https://raw.githubusercontent.com/Keeper-Security/KeeperPAM/refs/heads/main/gateway/docker-seccomp.json

curl -O https://raw.githubusercontent.com/Keeper-Security/KeeperPAM/refs/heads/main/gateway/gateway-apparmor-profile

sudo apparmor_parser -r gateway-apparmor-profile
sudo cp gateway-apparmor-profile /etc/apparmor.d/

docker compose up -d

Logging

When running the latest version of the Keeper Gateway, you'll see the output in the logs like below:

docker compose logs keeper-gateway

On the Vault UI in the Secrets Manager > Applications > Gateways screen, the Gateway will show Online.

Gateway Service Management

Starting the service

docker compose up -d

Stopping the service

docker compose stop

Restarting the service

docker compose restart

Connecting to the Gateway container

docker compose exec keeper-gateway bash

Starting the Gateway Automatically on Reboot

In the docker-compose.yml file, ensure that a restart policy is enabled. For example:

services:
  keeper-gateway:
    restart: unless-stopped

Adding 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.target

NOTE:

• 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.service

Important: 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-gateway

Debugging

If 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 guacd

After changing the log level, apply the changes to the docker

docker compose up -d

Tail the logs of the Keeper Gateway using this command:

docker compose logs -f keeper-gateway

Updating

Executing the following command will update the Keeper Gateway container to the latest version and restart the service:

docker compose pull
docker compose up -d

Health Checks

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.

Network Configuration

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.

Managing Disk Space

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.

Checking Disk Space Usage

To view your current disk usage, run the following command on your Keeper Gateway server:

df -h

This 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.

Cleaning 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 -a

• The -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.8GB

This operation safely removes old images that are no longer used by any running containers.

References:

• DockerHub listing: https://hub.docker.com/r/keeper/gateway

• Quick reference for Installing Docker and Docker Compose on Linux

Overview

This document contains information on how to install, configure, and update the Keeper Gateway on Windows.

Prerequisite

Prior to proceeding with this document, make sure you .

Installation

The latest Keeper Gateway for Windows is downloaded from here:

You can run the service under system privilege or use a service account.

New Installs

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.

Upgrading

If you are upgrading an existing Gateway, un-check the "Enter a Keeper One-Time Access Token" so that the existing configuration is maintained.

Installation Location

The default installation location is the following:

Setup Options

• 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

Specifying the Keeper Gateway Service Account

If "Use service account" is specified you will be prompted to enter the valid credentials of the desired service account:

One-Time Access Token

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.

Gateway Service Management

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".

Configuration File

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:

Log files

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:

Verbose Logging

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

Updating

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".

Auto Updates

Select "Enable automatic updates" during the installer process to ensure that your Keeper Gateway is automatically updated when there are new versions available.

Health Checks

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.

Silent Install

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.

Configuration Options

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:

Windows Service Account

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.

Auto Updater

To enable the Auto Updater feature, allowing Keeper Gateway to automatically check for and apply updates, use the following option:

Uninstalling

To uninstall the service:

• Uninstall Keeper Gateway from "Add and remove programs"

• If desired, delete the private configuration .json file

Overview

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.

Auto Updater Installation

Prerequisites

• Ensure that you have administrative privileges on the system.

• Version 1.4.0 or later of Keeper Gateway is required.

Docker

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:

Make the script executable:

Edit the crontab:

Add a line to schedule the script. For example, to run it every day at 3 AM:

Linux

New Gateway

Execute 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.

Existing Keeper Gateway

Activate the Auto Updater on an existing installation by executing the following Keeper Gateway command:

Verify Installation (Optional)

Verify that the Auto Updater has been installed successfully by executing the following Keeper Gateway command:

Windows

New Gateway

• Download 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:

Verify Installation (Optional)

• Open a command prompt as Administrator.

• Verify that Auto Updater has been installed successfully by executing the following Keeper Gateway command:

Auto Updater Status

Prerequisites

• Ensure that you have administrative privileges on the system.

• Version 1.4.0 or later of Keeper Gateway is required.

Status on Linux

Check the Auto Updater status by executing the following Keeper Gateway command:

Status on Windows

• Open a command prompt as Administrator

• Check the Auto Updater status by executing the following Keeper Gateway command:

Auto Updater Configuration

Configuration on Linux

Edit the crontab that runs Auto Updater.

Here is an example of the default crontab entry that checks for updates every hour:

• The 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.

Configuration on Windows

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.

Auto Updater Removal

Prerequisites

• Ensure that you have administrative privileges on the system.

• Version 1.4.0 or later of Keeper Gateway is required.

Removal on Linux

Remove Auto Updater by executing the following Keeper Gateway command:

Removal on Windows

Remove Auto Updater with the following steps:

• Open a command prompt as Administrator.

• Remove Auto Updater with the following Keeper Gateway command:

Troubleshooting

Check the status of the Auto Update

Logging in the Gateway Auto Updater

To 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.

Linux

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.

Windows

Log Location

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.

Overview

In enterprise environments, network security policies may require internet traffic to flow through a corporate proxy server. Keeper Gateway supports standard HTTP/HTTPS proxy configuration through environment variables and command-line parameters, ensuring compatibility with corporate network architectures.

When proxy support is enabled, the Gateway routes all outbound connections through the specified proxy server, including:

• WebSocket connections to Keeper servers

• HTTP/HTTPS API calls

• Health check endpoints

• Version verification requests

• TURN credential requests

Supported Proxy Types

Keeper Gateway supports the following proxy configurations:

• HTTP Proxy - Standard HTTP proxy servers (e.g., Squid, Apache Traffic Server)

• HTTPS Proxy - Secure proxy connections with TLS

• Authenticated Proxies - Proxies requiring username/password authentication

• Bypass Lists - Exclude specific domains or IP addresses from proxy routing

Configuration Methods

You can configure proxy settings using either environment variables or command-line parameters. Command-line parameters take precedence over environment variables.

Option 1: Environment Variables

Environment variables provide a standard way to configure proxy settings across all network-aware applications. These variables are recognized by most networking tools and libraries.

Supported Environment Variables

Keeper Gateway recognizes the following environment variables (in order of precedence):

1. HTTPS_PROXY or https_proxy - Primary proxy configuration (recommended)

2. HTTP_PROXY or http_proxy - Fallback proxy configuration

3. NO_PROXY or no_proxy - Bypass list for excluded hosts

Setting Environment Variables

Linux/macOS:

export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.local"

Windows (Command Prompt):

set HTTPS_PROXY=http://proxy.company.com:8080
set NO_PROXY=localhost,127.0.0.1,.local

Windows (PowerShell):

$env:HTTPS_PROXY="http://proxy.company.com:8080"
$env:NO_PROXY="localhost,127.0.0.1,.local"

With Authentication

Include credentials in the proxy URL:

export HTTPS_PROXY="http://username:[email protected]:8080"

Option 2: Command-Line Parameters

Command-line parameters provide additional flexibility and override environment variables when both are present.

Available Parameters

Docker Deployment with Proxy

When deploying Keeper Gateway in Docker, configure proxy settings in your docker-compose.yml file.

Docker Compose Configuration

Add proxy environment variables to your Gateway service:

services:
  keeper-gateway:
    platform: linux/amd64
    image: keepersecurityinc/gateway:latest
    environment:
      GATEWAY_CONFIG: <your-gateway-config>

      # Proxy Configuration
      HTTP_PROXY: http://proxy:3128
      HTTPS_PROXY: http://proxy:3128
      NO_PROXY: localhost,127.0.0.1,db-mysql,server-ssh,server-rdp

    networks:
      - internal-network
    depends_on:
      - proxy

Air-Gapped Docker Environment Example

For complete network isolation, deploy the Gateway with a dedicated proxy container:

networks:
  # Internal network with NO internet access
  airgapped-internal-network:
    internal: true
    ipam:
      config:
        - subnet: 10.99.0.0/24

  # Public network (proxy only)
  public-internet-network:
    driver: bridge

services:
  # HTTP Proxy (bridges networks)
  proxy:
    platform: linux/amd64
    image: ubuntu/squid:latest
    networks:
      - airgapped-internal-network
      - public-internet-network
    ports:
      - "3128:3128"
    volumes:
      - ./squid.conf:/etc/squid/squid.conf:ro

  # Keeper Gateway (air-gapped)
  keeper-gateway:
    platform: linux/amd64
    image: keepersecurityinc/gateway:latest
    environment:
      GATEWAY_CONFIG: <your-gateway-config>
      HTTP_PROXY: http://proxy:3128
      HTTPS_PROXY: http://proxy:3128
      NO_PROXY: localhost,127.0.0.1,internal-service
    networks:
      - airgapped-internal-network  # NO public-internet-network
    depends_on:
      - proxy

In this configuration:

• Gateway container has no direct internet access (only on internal: true network)

• All internet traffic must flow through the proxy container

• Proxy container bridges the air-gapped and public networks

• Internal services (databases, application servers) bypass the proxy

Configuration Priority

When multiple configuration sources are present, Keeper Gateway applies settings in the following priority order (highest to lowest):

1. Individual command-line parameters (--proxy-host, --proxy-port, etc.)

2. --proxy-url command-line parameter

3. HTTPS_PROXY environment variable

4. https_proxy environment variable

5. HTTP_PROXY environment variable

6. http_proxy environment variable

For bypass lists:

1. --no-proxy command-line parameter

2. NO_PROXY environment variable

3. no_proxy environment variable

Proxy URL Format

Proxy URLs follow standard URI syntax:

[scheme://][username:password@]hostname:port

Examples

Basic HTTP proxy:

http://proxy.company.com:8080

HTTPS proxy:

https://proxy.company.com:8080

Authenticated proxy:

http://username:[email protected]:8080

Proxy with special characters in password:

http://user:p%40ssw0rd%[email protected]:8080

Note: URL-encode special characters in usernames and passwords using percent-encoding (e.g., @ becomes %40, ! becomes %21).

NO_PROXY Bypass List

The NO_PROXY setting allows you to exclude specific hosts from proxy routing. This is useful for:

• Internal services on the same network

• Local resources that don't require proxy access

• Services that cannot work through a proxy

Bypass List Format

The bypass list is a comma-separated list of:

• Exact hostnames: localhost, internal-server

• IP addresses: 127.0.0.1, 192.168.1.100

• Domain suffixes: .internal.com, .local (matches all subdomains)

Examples

Basic bypass list:

NO_PROXY=localhost,127.0.0.1

With domain suffixes:

NO_PROXY=localhost,127.0.0.1,.corp.internal,.local

Docker internal services:

NO_PROXY=localhost,127.0.0.1,db-mysql,server-ssh,server-rdp,server-vnc

Verification and Testing

Step 1: Verify Configuration

After starting the Gateway with proxy configuration, check the logs for confirmation:

INFO - Applying proxy configuration: proxy.company.com:8080
INFO - Using proxy for WebSocket: proxy.company.com:8080

Step 2: Test Proxy Connectivity

Before starting the Gateway, verify proxy accessibility:

Linux/macOS:

curl -x http://proxy.company.com:8080 https://keepersecurity.com

Windows (PowerShell):

Invoke-WebRequest -Uri https://keepersecurity.com -Proxy http://proxy.company.com:8080

If the proxy requires authentication:

curl -x http://username:[email protected]:8080 https://keepersecurity.com

Overview

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.

Simple Health Check Configuration

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.

Activating Health Check - Binary Install method

Start the gateway with health check enabled:

gateway start --health-check

Only after the gateway is running with health check enabled, you can check its health:

gateway health-check

If 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.

Activating Health Check - Docker Install method

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-stopped

After changing the docker-compose file, pick up the changes and restart the container:

docker compose up -d

If 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-gateway

If 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
healthy

The 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 -e

Add to the crontab to watch every minute...

* * * * * /path/to/watchdog.sh

Advanced Healthcheck Configuration Examples

The below section provides detailed configuration for customization of the health checks in different environments.

Output Format Examples

Troubleshooting Commands

Error Messages and Troubleshooting

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 token

Connection 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/health

SSL 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 expired

Implementation

The 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

CLI Health Check

You can check the gateway's health from the command line:

gateway health-check

This 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 -i

For JSON format output (matching the HTTP endpoint format):

gateway health-check -j

If your health check server is using SSL:

gateway health-check --ssl

If your health check server requires authentication:

gateway health-check --ssl --token your_auth_token

If your health check server is running on a non-default port:

gateway health-check --port 8123

If your health check server is running on a different host:

gateway health-check --host 10.0.0.5

The 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.

HTTP Health Check

The gateway includes a secure HTTP health check endpoint that can be enabled with environment variables or command line arguments.

Configuration

The health check server can be configured using environment variables or command line arguments:

Environment Variables

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 key

Command line arguments take precedence over environment variables when both are specified.

Example Commands

Basic health check with default settings:

gateway start --health-check

Custom port and authentication token:

gateway start --health-check --health-check-port 9000 --health-check-auth-token mysecrettoken

Bind to all interfaces (only in secure environments):

gateway start --health-check --health-check-host 0.0.0.0

Enable 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.pem

Complete 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.pem

Usage

When enabled, the HTTP health check endpoint will be available at:

http://localhost:8099/health

Or with SSL:

https://localhost:8099/health

Response Format

The 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.

Status Update Delays

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.

Security

The HTTP health check includes the following security features:

1. Authentication: When KEEPER_GATEWAY_HEALTH_CHECK_AUTH_TOKEN is set, requests must include the token in the Authorization header:

   Copy

   Authorization: Bearer <token>

2. SSL/TLS: When SSL is enabled, all communication is encrypted. You must provide a valid certificate and private key.

3. Localhost binding: The server binds to localhost only by default, not exposing the endpoint over the network.

4. 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'

5. Rate Limiting: Automatic rate limiting is applied to non-localhost connections (60 requests per minute per IP).

6. Information Protection: When the server is bound to a non-localhost address, sensitive information is automatically redacted from the response.

7. Forced SSL: SSL is automatically enforced when binding to non-localhost interfaces.

TLS Compatibility

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/health

Docker-Specific Configuration Requirements

When 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: mysecrettoken

Generate 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

Example Linux Configuration

# 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 start

Or using command line arguments:

gateway start --health-check --health-check-port 8099 --health-check-auth-token mysecrettoken

Self-Signed SSL Certificates

For 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 start

Or 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 start

When using self-signed certificates, your HTTP client will need to be configured to trust the certificate or ignore SSL verification (not recommended for production).

Monitoring Integration

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