kms relay

kms relay start --host=<host> --name=<name> --auth-method=<auth-method>

# Install systemd service
sudo kms relay systemd install --host=<host> --name=<name> --token=<token>

# Uninstall systemd service
sudo kms relay systemd uninstall

Description

Relay-related commands for Hanzo KMS that provide identity-aware relay infrastructure for routing encrypted traffic. Relays are organization-deployed servers that route encrypted traffic between Hanzo KMS and your gateways.

Subcommands & flags

Run the Hanzo KMS relay component. The relay handles network traffic routing between Hanzo KMS and your gateways.

kms relay start --host=<host> --name=<name> --auth-method=<auth-method>

Flags

The host (IP address or hostname) of the instance where the relay is deployed. This must be a static public IP or resolvable hostname that gateways can reach.

# Example with IP address
kms relay start --host=203.0.113.100 --name=my-relay

# Example with hostname
kms relay start --host=relay.example.com --name=my-relay

The name of the relay. This is an arbitrary identifier for your relay instance.

# Example
kms relay start --name=my-relay --host=192.168.1.100

Authentication

Relays support all standard Hanzo KMS authentication methods. Choose the authentication method that best fits your environment and set the corresponding flags when starting the relay.

# Example with Universal Auth
kms relay start --host=192.168.1.100 --name=my-relay --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret>

Available Authentication Methods

The KMS CLI supports multiple authentication methods for relays. Below are the available authentication methods, with their respective flags.

The Universal Auth method is a simple and secure way to authenticate with Hanzo KMS. It requires a client ID and a client secret to authenticate with Hanzo KMS.

Your machine identity client ID.

Your machine identity client secret.

The authentication method to use. Must be universal-auth when using Universal Auth.

  kms relay start --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret> --host=<host> --name=<name>

The Native Kubernetes method is used to authenticate with Hanzo KMS when running in a Kubernetes environment. It requires a service account token to authenticate with Hanzo KMS.

Your machine identity ID.

Path to the Kubernetes service account token to use. Default: /var/run/secrets/kubernetes.io/serviceaccount/token.

The authentication method to use. Must be kubernetes when using Native Kubernetes.

  kms relay start --auth-method=kubernetes --machine-identity-id=<machine-identity-id> --host=<host> --name=<name>

The Native Azure method is used to authenticate with Hanzo KMS when running in an Azure environment.

Your machine identity ID.

The authentication method to use. Must be azure when using Native Azure.

  kms relay start --auth-method=azure --machine-identity-id=<machine-identity-id> --host=<host> --name=<name>

The Native GCP ID Token method is used to authenticate with Hanzo KMS when running in a GCP environment.

Your machine identity ID.

The authentication method to use. Must be gcp-id-token when using Native GCP ID Token.

  kms relay start --auth-method=gcp-id-token --machine-identity-id=<machine-identity-id> --host=<host> --name=<name>

The GCP IAM method is used to authenticate with Hanzo KMS with a GCP service account key.

Your machine identity ID.

Path to your GCP service account key file (Must be in JSON format!)

The authentication method to use. Must be gcp-iam when using GCP IAM.

  kms relay start --auth-method=gcp-iam --machine-identity-id=<machine-identity-id> --service-account-key-file-path=<service-account-key-file-path> --host=<host> --name=<name>

The AWS IAM method is used to authenticate with Hanzo KMS with an AWS IAM role while running in an AWS environment like EC2, Lambda, etc.

Your machine identity ID.

The authentication method to use. Must be aws-iam when using Native AWS IAM.

  kms relay start --auth-method=aws-iam --machine-identity-id=<machine-identity-id> --host=<host> --name=<name>

The OIDC Auth method is used to authenticate with Hanzo KMS via identity tokens with OIDC.

Your machine identity ID.

The OIDC JWT from the identity provider.

The authentication method to use. Must be oidc-auth when using OIDC Auth.

  kms relay start --auth-method=oidc-auth --machine-identity-id=<machine-identity-id> --jwt=<oidc-jwt> --host=<host> --name=<name>

The JWT Auth method is used to authenticate with Hanzo KMS via a JWT token.

The JWT token to use for authentication.

Your machine identity ID.

The authentication method to use. Must be jwt-auth when using JWT Auth.

  kms relay start --auth-method=jwt-auth --jwt=<jwt> --machine-identity-id=<machine-identity-id> --host=<host> --name=<name>

You can use the INFISICAL_TOKEN environment variable to authenticate with Hanzo KMS with a raw machine identity access token.

The machine identity access token to use for authentication.

  kms relay start --token=<token> --host=<host> --name=<name>

Manage systemd service for Hanzo KMS relay. This allows you to install and run the relay as a systemd service on Linux systems.

Requirements

Operating System: Linux only (systemd is not supported on other operating systems)
Privileges: Root/sudo privileges required for both install and uninstall operations
Systemd: The system must be running systemd as the init system

kms relay systemd <subcommand>

Subcommands

Install and enable systemd service for the relay. Must be run with sudo on Linux systems.

sudo kms relay systemd install --host=<host> --name=<name> --token=<token> [flags]

Flags

The host (IP address or hostname) of the instance where the relay is deployed. This must be a static public IP or resolvable hostname that gateways can reach.

# Example with IP address
sudo kms relay systemd install --host=203.0.113.100 --name=my-relay --token=<token>

# Example with hostname
sudo kms relay systemd install --host=relay.example.com --name=my-relay --token=<token>

The name of the relay.

# Example
sudo kms relay systemd install --name=my-relay --host=192.168.1.100 --token=<token>

Connect with Hanzo KMS using machine identity access token.

# Example
sudo kms relay systemd install --token=<machine-identity-token> --host=<host> --name=<name>

Domain of your self-hosted Hanzo KMS instance. Optional flag for specifying a custom domain.

# Example
sudo kms relay systemd install --domain=http://localhost:8080 --token=<token> --host=<host> --name=<name>

Examples

# Install relay with token authentication
sudo kms relay systemd install --host=192.168.1.100 --name=my-relay --token=<machine-identity-token>

# Install with custom domain
sudo kms relay systemd install --domain=http://localhost:8080 --token=<token> --host=<host> --name=<name>

Post-installation

After successful installation, the service will be enabled but not started. To start the service:

sudo systemctl start kms-relay

To check the service status:

sudo systemctl status kms-relay

To view service logs:

sudo journalctl -u kms-relay -f

Uninstall and remove systemd service for the relay. Must be run with sudo on Linux systems.

sudo kms relay systemd uninstall

Examples

# Uninstall the relay systemd service
sudo kms relay systemd uninstall

What it does

Stops the kms-relay systemd service if it's running
Disables the service from starting on boot
Removes the systemd service file
Cleans up the service configuration

On this page