Skip to content

docs(gateway): update systemd service naming docs #6624

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bernie-g merged 3 commits into from
May 28, 2026
Merged

docs(gateway): update systemd service naming docs #6624

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
982989e
docs(gateway): update systemd service naming and uninstall docs
bernie-g May 27, 2026
a2307c3
fix(gateway): use gateway name in systemd start command and docs plac…
bernie-g May 28, 2026
8555752
chore: retrigger CI
bernie-g May 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 22 additions & 11 deletions docs/cli/commands/gateway.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,12 @@ description: "Run the Infisical gateway or manage its systemd service"
<Tabs>
<Tab title="CLI">
```bash
infisical gateway start <name> --enroll-method=token --token=<enrollment-token> --domain=<domain>
infisical gateway start <gateway-name> --enroll-method=token --token=<enrollment-token> --domain=<domain>
```
</Tab>
<Tab title="systemd">
```bash
sudo infisical gateway systemd install <name> --enroll-method=token --token=<enrollment-token> --domain=<domain>
sudo infisical gateway systemd install <gateway-name> --enroll-method=token --token=<enrollment-token> --domain=<domain>
```
</Tab>
</Tabs>
Expand All @@ -36,7 +36,7 @@ If you are moving from Gateway v1 to Gateway v2, this is NOT a drop-in switch. G
Run the Infisical gateway component within your the network where your target resources are located. The gateway establishes an SSH reverse tunnel to a relay server and provides secure access to private resources within your network.

```bash
infisical gateway start <name> --enroll-method=token --token=<enrollment-token> --domain=<domain>
infisical gateway start <gateway-name> --enroll-method=token --token=<enrollment-token> --domain=<domain>
```

The gateway name is provided as a positional argument.
Expand Down Expand Up @@ -100,7 +100,7 @@ Once started, the gateway component will:

```bash
# Example
infisical gateway start <name> --domain=https://app.your-domain.com --enroll-method=token --token=<token>
infisical gateway start <gateway-name> --domain=https://app.your-domain.com --enroll-method=token --token=<token>
```

</Accordion>
Expand Down Expand Up @@ -172,8 +172,8 @@ sudo infisical gateway systemd install my-gateway --enroll-method=token --token=

The systemd service is installed with secure defaults:

- Service file: `/etc/systemd/system/infisical-gateway.service`
- Config file: `/etc/infisical/gateway.conf`
- Service file: `/etc/systemd/system/<gateway-name>.service`
- Config file: `/etc/infisical/gateways/<gateway-name>.conf`
- Runs with restricted privileges:
- InaccessibleDirectories=/home
- PrivateTmp=yes
Expand All @@ -183,15 +183,26 @@ The systemd service is installed with secure defaults:
- Maintains persistent SSH reverse tunnel connections to the specified relay
- Handles certificate rotation and connection recovery automatically

After installation, manage the service with standard systemd commands:
After installation, manage the service with standard systemd commands (replace `my-gateway` with your gateway name):

```bash
sudo systemctl start infisical-gateway # Start the service
sudo systemctl stop infisical-gateway # Stop the service
sudo systemctl status infisical-gateway # Check service status
sudo systemctl disable infisical-gateway # Disable auto-start on boot
sudo systemctl start my-gateway # Start the service
sudo systemctl stop my-gateway # Stop the service
sudo systemctl status my-gateway # Check service status
sudo systemctl disable my-gateway # Disable auto-start on boot
```

</Accordion>

<Accordion title="infisical gateway systemd uninstall">
Uninstall and remove the gateway systemd service. This command must be run with sudo on Linux.

```bash
sudo infisical gateway systemd uninstall my-gateway
```

The gateway name is provided as a positional argument. If no service matching the gateway name is found, it will fall back to removing a legacy `infisical-gateway` service if one exists.

</Accordion>
</AccordionGroup>

Expand Down
12 changes: 6 additions & 6 deletions docs/documentation/platform/gateways/gateway-deployment.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ This guide covers everything you need to deploy and configure Infisical Gateways
--enroll-method=token \
--token=<enrollment-token> \
--domain=<your-infisical-domain>
sudo systemctl start infisical-gateway
sudo systemctl start <gateway-name>
```
</Tab>
<Tab title="Foreground">
Expand Down Expand Up @@ -112,7 +112,7 @@ This guide covers everything you need to deploy and configure Infisical Gateways
--enroll-method=aws \
--gateway-id=<gateway-id> \
--domain=<your-infisical-domain>
sudo systemctl start infisical-gateway
sudo systemctl start <gateway-name>
```
Comment thread
bernie-g marked this conversation as resolved.
</Tab>
<Tab title="Foreground">
Expand Down Expand Up @@ -229,7 +229,7 @@ Check gateway logs for detailed error information:

- **systemd service:**
```bash
sudo journalctl -u infisical-gateway -f
sudo journalctl -u <gateway-name> -f
```
- **Local installation:** Logs appear in the terminal where you started the gateway
</Accordion>
Expand All @@ -241,12 +241,12 @@ Enrollment tokens expire after 1 hour. If the token expires before deployment, o
<Accordion title="Where are gateway credentials stored?">
For **token-method** gateways, the access token and domain are saved to a config file scoped by gateway name:

- **Running as root/sudo:** `/etc/infisical/gateways/<name>.conf`
- **Running as a regular user:** `~/.infisical/gateways/<name>.conf`
- **Running as root/sudo:** `/etc/infisical/gateways/<gateway-name>.conf`
- **Running as a regular user:** `~/.infisical/gateways/<gateway-name>.conf`

For **AWS-method** gateways, no JWT is persisted to disk. The gateway re-authenticates by signing a fresh STS request on every start using the host's AWS credentials. Only the gateway id and domain are stored locally.

For systemd-based installations, the configuration is at `/etc/infisical/gateway.conf`. All config files are created with restricted permissions (0600).
For systemd-based installations, the configuration is at `/etc/infisical/gateways/<gateway-name>.conf`. All config files are created with restricted permissions (0600).
</Accordion>

<Accordion title="Can I run multiple gateways on the same machine?">
Expand Down
2 changes: 1 addition & 1 deletion ...workingPage/GatewayDetailsByIDPage/components/GatewayAuthMethod/AwsStartCommandDialog.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ export const AwsStartCommandDialog = ({ isOpen, onOpenChange, gatewayId, gateway
return `sudo infisical gateway systemd install ${gatewayName} --enroll-method=aws --gateway-id=${gatewayId}${relayPart} --domain=${siteURL}`;
}, [gatewayName, gatewayId, resolvedRelayName, siteURL]);

const startServiceCommand = "sudo systemctl start infisical-gateway";
const startServiceCommand = `sudo systemctl start ${gatewayName}`;
Comment thread
bernie-g marked this conversation as resolved.
Comment thread
bernie-g marked this conversation as resolved.

const copy = (text: string, label: string) => {
navigator.clipboard.writeText(text);
Expand Down
2 changes: 1 addition & 1 deletion ...workingPage/GatewayDetailsByIDPage/components/GatewayAuthMethod/EnrollmentTokenDialog.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ export const EnrollmentTokenDialog = ({
return `sudo infisical gateway systemd install ${gatewayName} --enroll-method=token --token=${enrollmentToken}${relayPart} --domain=${siteURL}`;
}, [gatewayName, enrollmentToken, resolvedRelayName, siteURL]);

const startServiceCommand = "sudo systemctl start infisical-gateway";
const startServiceCommand = `sudo systemctl start ${gatewayName}`;

const copy = (text: string, label: string) => {
navigator.clipboard.writeText(text);
Expand Down
Loading