---
title: "Install Secret Agent"
description: "Install Aerospike Secret Agent on Linux using package managers like dpkg/rpm or via Docker containers."
---

# Install Secret Agent

> For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt)
> 
> All documentation pages available in markdown.

This page describes how to install Aerospike Secret Agent on Linux or with a Docker container. For an overview of what Secret Agent does and how it fits into your Aerospike deployment, see the [Secret Agent overview](https://aerospike.com/docs/database/tools/secret-agent).

## Deployment recommendations

-   Start Secret Agent before Aerospike Database. Aerospike requests secrets during startup, so Secret Agent must be running and ready to respond.
-   Run one Secret Agent process per Aerospike node to avoid creating a single point of failure. While multiple Aerospike nodes can share a single Secret Agent process, this is not recommended for production deployments.
-   Secret Agent can run on the same host as Aerospike Database or on a separate host. When both run on the same host, you can use [UDS](https://aerospike.com/docs/database/tools/secret-agent/listener/uds) for lower-overhead communication.

## Install on Linux

### Package locations

When you install the Secret Agent package using a package manager, the executable is placed in `/usr/local/bin/`. The default configuration file is at `/etc/aerospike-secret-agent/config.yaml`, and the `systemd` service file is at `/etc/systemd/system/aerospike-secret-agent.service`.

#### Relocate RPM packages

The following command relocates `etc`, `var`, and `usr` directories to `/foosa`:

```plaintext
rpm --relocate /=/foosa/ --badreloc -Uvh aerospike-secret-agent-VERSION_NUMBER-1.x86_64.rpm
```

### Installation steps

1.  [Download](https://aerospike.com/download/?software=oandm-secret_agent) the Secret Agent package.
    
2.  Install the package to create a `systemd` daemon.
    
    Use one of the following commands based on your package manager:
    
    -   [dpkg](#tab-panel-2850)
    -   [rpm](#tab-panel-2851)
    
    Terminal window
    
    ```bash
    dpkg -i aerospike-secret-agent_VERSION_NUMBER-1_amd64.deb
    ```
    
    Terminal window
    
    ```bash
    rpm -i aerospike-secret-agent-VERSION_NUMBER-1.x86_64.rpm
    ```
    
    Replace _`VERSION_NUMBER`_ with the Secret Agent version number (for example, `1.3.0`), and adjust the architecture as needed (`amd64` or `arm64`). As of Secret Agent 1.3.0, package names are platform-independent. The filenames contain version and architecture only. Previous releases followed a different filename syntax: `aerospike-secret-agent-VERSION_NUMBER-1.DISTRIBUTION.ARCHITECTURE.rpm/deb`. See the [Secret Agent download page](https://aerospike.com/download/oandm/secret_agent/) for details and download links.
    
3.  Edit the Secret Agent configuration file to match your environment.
    
    The following example fetches secrets from AWS Secrets Manager.
    
    -   For GCP Secret Manager, see the [GCP configuration guide](https://aerospike.com/docs/database/tools/secret-agent/secret-manager/gcp).
    -   For HashiCorp Vault, see the [HashiCorp Vault configuration guide](https://aerospike.com/docs/database/tools/secret-agent/secret-manager/vault).
    
    ```yaml
    service:
    
      tcp:
    
        endpoint: 0.0.0.0:3005
    
    secret-manager:
    
      aws:
    
        region: us-west-1
    
        resources:
    
          TestingSecret: arn:aws:secretsmanager:us-west-1:999999999999:secret:TestingSecret-tN6s2j
    
          NodeSecret: arn:aws:secretsmanager:us-west-1:999999999999:secret:NodeSecret-tN6s2j
    
    log:
    
      level: info
    ```
    
    See the [configuration template](https://aerospike.com/docs/database/tools/secret-agent/template) for all available options.
    
4.  Start Secret Agent before starting Aerospike Database.
    
    Terminal window
    
    ```bash
    systemctl start aerospike-secret-agent
    ```
    
    Secret Agent runs as root by default when started as a `systemd` service. To run Secret Agent as a non-root user, edit the `systemd` service file (`/etc/systemd/system/aerospike-secret-agent.service`). Set the `User` and `Group` options in the `[Service]` section:
    
    ```plaintext
    [Unit]
    
    Description=Aerospike Secret Agent
    
    Wants=network.target
    
    After=network-online.target
    
    [Service]
    
    EnvironmentFile=-/etc/environment
    
    ExecStart=/usr/local/bin/aerospike-secret-agent --config-file /etc/aerospike-secret-agent/config.yaml
    
    User=aerospike
    
    Group=aerospike
    
    [Install]
    
    WantedBy=default.target
    ```
    

## Install with Docker

Aerospike provides a [Secret Agent Docker image](https://hub.docker.com/r/aerospike/aerospike-secret-agent) on Docker Hub.

1.  Pull the Secret Agent Docker image.
    
    Terminal window
    
    ```bash
    docker pull aerospike/aerospike-secret-agent
    ```
    
2.  Start the Secret Agent container.
    
    Mount a local directory containing the Secret Agent configuration file, TLS certificates, and any secret manager credential files as a volume to make them accessible from the container.
    
    The following command starts Secret Agent using a configuration file at `~/secretagent/config.yaml`:
    
    Terminal window
    
    ```bash
    docker run -d --name aerospike-secret-agent -v ~/secretagent:/secretagent aerospike/aerospike-secret-agent --config-file /secretagent/config.yaml
    ```
    
3.  Verify that Secret Agent is running.
    
    Terminal window
    
    ```bash
    docker ps
    ```
    
    Expected output:
    
    ```plaintext
    CONTAINER ID   IMAGE                              COMMAND                  CREATED         STATUS        PORTS     NAMES
    
    19a2f22d8a7d   aerospike/aerospike-secret-agent   "/app/aerospike-secr…"   2 seconds ago   Up 1 second             aerospike-secret-agent
    ```
    
4.  Configure the Aerospike Database configuration file to connect to Secret Agent.
    
    Set the [`secrets-address-port`](https://aerospike.com/docs/database/reference/config#service__secrets-address-port) parameter in the Aerospike configuration:
    
    ```plaintext
    service {
    
    ...
    
    secrets-address-port aerospike-secret-agent 3005
    
    ...
    
    }
    ```
    
    For details, see [Integrating with secrets management services](https://aerospike.com/docs/database/manage/security/secrets/#connecting-to-aerospike-secret-agent).
    
5.  Pull the Aerospike Database Enterprise Edition image.
    
    Terminal window
    
    ```bash
    docker pull aerospike/aerospike-server-enterprise
    ```
    
6.  Start the Aerospike Database container.
    
    Terminal window
    
    ```bash
    docker run -d --name aerospike-server -v ~/myfiles/:/etc/aerospike/ -e "FEATURE_KEY_FILE=/etc/aerospike/features.conf" aerospike/aerospike-server-enterprise --config-file /etc/aerospike/aerospike.conf
    ```
    
7.  Verify that both containers are running.
    
    Terminal window
    
    ```bash
    docker ps
    ```
    
    Expected output:
    
    ```plaintext
    CONTAINER ID   IMAGE                                   COMMAND                  CREATED         STATUS         PORTS           NAMES
    
    0f3829cbb6c4   aerospike/aerospike-secret-agent        "/app/aerospike-secr…"   8 minutes ago   Up 8 minutes                   aerospike-secret-agent
    
    96063fd95597   aerospike/aerospike-server-enterprise    "/usr/bin/as-tini-st…"   9 minutes ago   Up 9 minutes                   aerospike-server
    ```
    
    For more information about running Aerospike in Docker, see [Install on macOS and Windows with Docker](https://aerospike.com/docs/database/install/docker).
    

### Troubleshooting

To diagnose errors, check the logs of the respective containers:

Terminal window

```bash
docker logs aerospike-secret-agent
```

Terminal window

```bash
docker logs aerospike-server
```