ContextQMD
Back to Infisical

infisical relay

docs/cli/commands/relay.mdx

0.159.2512.6 KB
Original Source
<Tabs> <Tab title="Start relay"> ```bash infisical relay start --host=<host> --name=<name> --auth-method=<auth-method> ``` </Tab> <Tab title="Start relay as background daemon (Linux only)"> ```bash # Install systemd service sudo infisical relay systemd install --host=<host> --name=<name> --token=<token> 
# Uninstall systemd service
sudo infisical relay systemd uninstall
```
</Tab> </Tabs>

Description

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

Subcommands & flags

<AccordionGroup> <Accordion title="infisical relay start" defaultOpen="true"> Run the Infisical relay component. The relay handles network traffic routing between Infisical and your gateways.
bash
infisical relay start --host=<host> --name=<name> --auth-method=<auth-method>

Flags

<AccordionGroup> <Accordion title="--host"> 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. 
```bash
# Example with IP address
infisical relay start --host=203.0.113.100 --name=my-relay

# Example with hostname
infisical relay start --host=relay.example.com --name=my-relay
```
</Accordion> <Accordion title="--name"> The name of the relay. This is an arbitrary identifier for your relay instance. 
```bash
# Example
infisical relay start --name=my-relay --host=192.168.1.100
```
</Accordion> </AccordionGroup>

Authentication

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

bash
# Example with Universal Auth
infisical 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 Infisical CLI supports multiple authentication methods for relays. Below are the available authentication methods, with their respective flags.

<AccordionGroup> <Accordion title="Universal Auth"> The Universal Auth method is a simple and secure way to authenticate with Infisical. It requires a client ID and a client secret to authenticate with Infisical. 
  <ParamField query="Flags">
  <Expandable title="properties">
      <ParamField query="client-id" type="string" required>
      Your machine identity client ID.
      </ParamField>
      <ParamField query="client-secret" type="string" required>
      Your machine identity client secret.
      </ParamField>
      <ParamField query="auth-method" type="string" required>
        The authentication method to use. Must be `universal-auth` when using Universal Auth.
      </ParamField>
  </Expandable>
</ParamField>

```bash
  infisical relay start --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret> --host=<host> --name=<name>
```
</Accordion> <Accordion title="Native Kubernetes"> The Native Kubernetes method is used to authenticate with Infisical when running in a Kubernetes environment. It requires a service account token to authenticate with Infisical. 
  <ParamField query="Flags">
  <Expandable title="properties">
      <ParamField query="machine-identity-id" type="string" required>
      Your machine identity ID.
      </ParamField>
      <ParamField query="service-account-token-path" type="string" optional>
        Path to the Kubernetes service account token to use. Default: `/var/run/secrets/kubernetes.io/serviceaccount/token`.
      </ParamField>
      <ParamField query="auth-method" type="string" required>
        The authentication method to use. Must be `kubernetes` when using Native Kubernetes.
      </ParamField>
  </Expandable>

</ParamField>


```bash
  infisical relay start --auth-method=kubernetes --machine-identity-id=<machine-identity-id> --host=<host> --name=<name>
```
</Accordion> <Accordion title="Native Azure"> The Native Azure method is used to authenticate with Infisical when running in an Azure environment. 
<ParamField query="Flags">
  <Expandable title="properties">
      <ParamField query="machine-identity-id" type="string" required>
        Your machine identity ID.
      </ParamField>
      <ParamField query="auth-method" type="string" required>
        The authentication method to use. Must be `azure` when using Native Azure.
      </ParamField>
  </Expandable>
</ParamField>



```bash
  infisical relay start --auth-method=azure --machine-identity-id=<machine-identity-id> --host=<host> --name=<name>
```
</Accordion> <Accordion title="Native GCP ID Token"> The Native GCP ID Token method is used to authenticate with Infisical when running in a GCP environment. 
<ParamField query="Flags">
  <Expandable title="properties">
      <ParamField query="machine-identity-id" type="string" required>
        Your machine identity ID.
      </ParamField>
      <ParamField query="auth-method" type="string" required>
        The authentication method to use. Must be `gcp-id-token` when using Native GCP ID Token.
      </ParamField>
  </Expandable>
</ParamField>



```bash
  infisical relay start --auth-method=gcp-id-token --machine-identity-id=<machine-identity-id> --host=<host> --name=<name>
```
</Accordion> <Accordion title="GCP IAM"> The GCP IAM method is used to authenticate with Infisical with a GCP service account key. 
<ParamField query="Flags">
  <Expandable title="properties">
      <ParamField query="machine-identity-id" type="string" required>
      Your machine identity ID.
      </ParamField>
      <ParamField query="service-account-key-file-path" type="string" required>
        Path to your GCP service account key file _(Must be in JSON format!)_
      </ParamField>
      <ParamField query="auth-method" type="string" required>
        The authentication method to use. Must be `gcp-iam` when using GCP IAM.
      </ParamField>
  </Expandable>
</ParamField>

```bash
  infisical 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>
```
</Accordion> <Accordion title="Native AWS IAM"> The AWS IAM method is used to authenticate with Infisical with an AWS IAM role while running in an AWS environment like EC2, Lambda, etc. 
<ParamField query="Flags">
  <Expandable title="properties">
      <ParamField query="machine-identity-id" type="string" required>
        Your machine identity ID.
      </ParamField>
      <ParamField query="auth-method" type="string" required>
        The authentication method to use. Must be `aws-iam` when using Native AWS IAM.
      </ParamField>
  </Expandable>
</ParamField>

  ```bash
    infisical relay start --auth-method=aws-iam --machine-identity-id=<machine-identity-id> --host=<host> --name=<name>
  ```
</Accordion> <Accordion title="OIDC Auth"> The OIDC Auth method is used to authenticate with Infisical via identity tokens with OIDC. 
<ParamField query="Flags">
  <Expandable title="properties">
      <ParamField query="machine-identity-id" type="string" required>
        Your machine identity ID.
      </ParamField>
      <ParamField query="jwt" type="string" required>
        The OIDC JWT from the identity provider.
      </ParamField>
      <ParamField query="auth-method" type="string" required>
        The authentication method to use. Must be `oidc-auth` when using OIDC Auth.
      </ParamField>
  </Expandable>
</ParamField>

```bash
  infisical relay start --auth-method=oidc-auth --machine-identity-id=<machine-identity-id> --jwt=<oidc-jwt> --host=<host> --name=<name>
```
</Accordion> <Accordion title="JWT Auth"> The JWT Auth method is used to authenticate with Infisical via a JWT token. 
<ParamField query="Flags">
  <Expandable title="properties">
      <ParamField query="jwt" type="string" required>
        The JWT token to use for authentication.
      </ParamField>
      <ParamField query="machine-identity-id" type="string" required>
        Your machine identity ID.
      </ParamField>
      <ParamField query="auth-method" type="string" required>
        The authentication method to use. Must be `jwt-auth` when using JWT Auth.
      </ParamField>
  </Expandable>
</ParamField>


```bash
  infisical relay start --auth-method=jwt-auth --jwt=<jwt> --machine-identity-id=<machine-identity-id> --host=<host> --name=<name>
```
</Accordion> <Accordion title="Token Auth"> You can use the `INFISICAL_TOKEN` environment variable to authenticate with Infisical with a raw machine identity access token. 
<ParamField query="Flags">
  <Expandable title="properties">
      <ParamField query="token" type="string" required>
        The machine identity access token to use for authentication.
      </ParamField>
  </Expandable>
</ParamField>

```bash
  infisical relay start --token=<token> --host=<host> --name=<name>
```
</Accordion> </AccordionGroup> </Accordion> <Accordion title="infisical relay systemd" defaultOpen="false"> Manage systemd service for Infisical 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
bash
infisical relay systemd <subcommand>

Subcommands

<AccordionGroup> <Accordion title="install"> Install and enable systemd service for the relay. Must be run with sudo on Linux systems.
bash
sudo infisical relay systemd install --host=<host> --name=<name> --token=<token> [flags]

Flags

<AccordionGroup> <Accordion title="--host"> 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.
bash
# Example with IP address
sudo infisical relay systemd install --host=203.0.113.100 --name=my-relay --token=<token>

# Example with hostname
sudo infisical relay systemd install --host=relay.example.com --name=my-relay --token=<token>
</Accordion> <Accordion title="--name"> The name of the relay.
bash
# Example
sudo infisical relay systemd install --name=my-relay --host=192.168.1.100 --token=<token>
</Accordion> <Accordion title="--token"> Connect with Infisical using machine identity access token.
bash
# Example
sudo infisical relay systemd install --token=<machine-identity-token> --host=<host> --name=<name>
</Accordion> <Accordion title="--domain"> Domain of your self-hosted Infisical instance. Optional flag for specifying a custom domain.
bash
# Example
sudo infisical relay systemd install --domain=http://localhost:8080 --token=<token> --host=<host> --name=<name>
</Accordion> </AccordionGroup>

Examples

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

# Install with custom domain
sudo infisical 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:

bash
sudo systemctl start infisical-relay

To check the service status:

bash
sudo systemctl status infisical-relay

To view service logs:

bash
sudo journalctl -u infisical-relay -f
</Accordion> <Accordion title="uninstall"> Uninstall and remove systemd service for the relay. Must be run with sudo on Linux systems.
bash
sudo infisical relay systemd uninstall

Examples

bash
# Uninstall the relay systemd service
sudo infisical relay systemd uninstall

What it does

  • Stops the infisical-relay systemd service if it's running
  • Disables the service from starting on boot
  • Removes the systemd service file
  • Cleans up the service configuration
</Accordion> </AccordionGroup> </Accordion> </AccordionGroup>