Linux Server

Deploy certificates from Infisical to a directory on a Linux server over SSH. Files are written atomically over SFTP so a reader never sees a partially written certificate or key.

Certificate Syncs are configured per Application. First select which certificates to sync, then configure the Linux Server destination.

Prerequisites

An SSH Connection with access to the target server, or an LDAP Connection to the domain the server is joined to. See using an LDAP connection for many servers.
For an LDAP Connection: the connection URL must use LDAPS on port 636, because a hardened domain controller rejects a plaintext simple bind on port 389 with strongerAuthRequired. The domain controller must be reachable as well as the target server, since every run reads the directory to derive the login.
The destination directory must already exist on the server and the connection user must be able to write to it
The server must be reachable from Infisical, either directly or through an Infisical Gateway
A Gateway is required to use a health check or a post-sync command, because the Gateway is what executes them. It must be running Infisical CLI v0.43.120 or later

Create a Linux Server sync

Infisical UI
API

In your Application, go to the Certificate Syncs tab and select Create Sync.
Select the Linux Server option.
Configure the Destination:
- Connection: The SSH Connection used to reach the server, or an LDAP Connection to the domain the server is joined to.
- Destination Directory: The absolute path to the directory where certificate files are written, for example /etc/ssl/certs.
Configure the Target Host. This step appears only when the connection is an LDAP Connection, because that connection reaches a whole domain rather than one machine:
- Target Host: The machine this sync delivers to. Servers found in the directory are offered as suggestions, and you can enter a host that isn’t listed. Enter a host name or an IPv4 address. Underscores, ports and IPv6 literals aren’t accepted.
- Port: Leave empty to use 22. Set a value only if the SSH listener is on a non-standard port.
- Trusted Host Keys: Optional. Paste the output of ssh-keyscan <host>. When set, the sync only connects if the host presents one of these keys.
Configure the Sync Options:
- Export Format: Choose PEM to write separate certificate, chain, and key files, or PKCS#12 to write a single password-protected .pfx bundle.
- Certificate File Extension: For PEM, choose .pem (default) or .crt for the certificate and chain files. Both hold the same PEM-encoded content, so pick the one the consuming service expects.
- Combine Certificate and Chain: For PEM, write the leaf certificate followed by the chain in a single file (a full-chain file, as nginx expects) and skip the separate chain file.
- File Permissions and Private Key Permissions: Octal modes for the delivered certificate and chain files (default 644) and for the private key file (default 600).
- Owner and Group: Optionally set the owner and group on the delivered files. Changing ownership requires the connection user to be root or to have passwordless sudo.
- PKCS#12 Password: Required when the export format is PKCS#12. It protects the delivered bundle.
- Include Private Key: For PEM, controls whether the private key is written alongside the certificate. The sync fails for a certificate whose key is not available, for example one issued from an external CSR.
- Include Root CA in Certificate Chain: Include the root CA in the delivered chain. Leave it off when the consuming service only needs the intermediates.
- Enable Removal of Certificates: Delete the delivered files from the server when a certificate is removed from the sync, revoked, or expired.
- Certificate Name Schema: The base file name, using placeholders such as {{commonName}}, {{certificateId}}, or {{shortCertificateId}}. The export format adds the extension. A schema with no placeholder can be linked to only one certificate.
- Auto-Sync Enabled: Automatically sync certificates when changes occur.
Configure the Commands, or leave them empty:
- Health check: A command run on the server before any certificate is written, to confirm the host is ready, for example test -w /etc/ssl/certs. A non-zero exit stops the sync, so nothing is delivered. See health check.
- Post-sync command: A command run on the server after the sync delivers a certificate, so the service that uses it picks up the new file, for example sudo systemctl reload nginx. See post-sync command.
Configure the Details:
- Name: The name of your sync.
- Description: Optional description.
Select which certificates should be synced.
Review and click Create Sync.

To create a Linux Server Certificate Sync, make an API request to the Create Linux Server PKI Sync endpoint.destinationConfig.host is required when connectionId refers to an LDAP Connection, and an optional port sits alongside it, defaulting to 22. Both are rejected when connectionId refers to an SSH Connection, because that connection carries its own host and port.

Sample request

Request

curl --request POST \
--url https://app.infisical.com/api/v1/cert-manager/syncs/linux-server \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "my-linux-cert-sync",
    "applicationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "connectionId": "550e8400-e29b-41d4-a716-446655440000",
    "isAutoSyncEnabled": true,
    "certificateIds": ["550e8400-e29b-41d4-a716-446655440000"],
    "syncOptions": {
        "exportFormat": "pem",
        "includePrivateKey": true,
        "canRemoveCertificates": true,
        "certificateNameSchema": "{{commonName}}",
        "healthCheckCommand": "test -w /etc/ssl/certs",
        "postSyncCommand": "sudo systemctl reload nginx"
    },
    "destinationConfig": {
        "destinationPath": "/etc/ssl/certs",
        "host": "server01.corp.example.com"
    }
}'

Using an LDAP connection for many servers

An SSH Connection stores the target machine’s address alongside its credential, so it reaches exactly one server. Pushing one certificate to fifty servers means fifty connections holding the same credential, and fifty objects to update when that credential is rotated. An LDAP Connection removes that duplication. It’s both the credential and the directory, so one connection serves as many syncs as you have servers. Each sync names its own Target Host, and every sync shares the one credential. When you rotate the service account’s password on the connection, every sync that uses it picks up the new password on its next run with no further action. This works because an Active Directory service account is a single identity. On a domain-joined Linux host, the same username and password that performs the LDAP bind performs the SSH logon, so no second credential is needed. The host must accept domain credentials over SSH, which is what a directory client such as SSSD provides. The Target Host field offers machines read from the directory. The list isn’t closed, because the name a domain controller advertises isn’t always the address you can reach, so you can enter a host that isn’t listed. The value must be a host name or an IPv4 address.

The sync authenticates to the Target Host with the connection’s credential. Application Admins can set it, so give the service account only the access it needs to deliver certificates.

Infisical logs in to the server as DOMAIN\user, for example CORP\svc-certs. Whether a Linux host accepts that form depends on how its directory client is configured. A host joined to the domain with realm join uses the SSSD ad provider, which understands DOMAIN\user out of the box. A host configured against the directory over LDAP instead uses the ldap provider, whose default name parsing only understands user@domain, so the login is rejected before the password is ever checked. Add the domain-qualified form to that host’s sssd.conf:

[domain/CORP]
re_expression = (((?P<domain>[^\\]+)\\(?P<name>.+$))|((?P<name>[^@]+)@(?P<domain>.+$))|(^(?P<name>[^@\\]+)$))
use_fully_qualified_names = False

Confirm it with getent passwd 'CORP\svc-certs' on the server before creating the sync. If that returns nothing, the sync will fail to authenticate no matter what the connection holds.

Export formats

The file extension is set by the export format, not by the name schema. The name schema only provides the base file name. PEM writes the certificate, chain, and private key (when included) as separate files. The certificate and chain files use the extension you select, either .pem (default) or .crt. PKCS#12 writes a single password-protected .pfx bundle that contains the certificate, chain, and private key. For a certificate whose common name is app.example.com, synced to /etc/ssl/certs with the default {{commonName}} name schema, the delivered files are:

PEM (.pem extension)
  /etc/ssl/certs/app.example.com.pem        certificate
  /etc/ssl/certs/app.example.com.chain.pem  chain
  /etc/ssl/certs/app.example.com.key        private key (when included)

PKCS#12
  /etc/ssl/certs/app.example.com.pfx

How it works

When syncing certificates, Infisical opens an SSH session to the server and, for each certificate, packages it in the chosen export format and writes the resulting files to the destination directory. Files are written atomically over SFTP so a reader never sees a partially written certificate or key.

Commands

A sync can run two optional commands on the target server, in that server’s own shell:

A health check runs before any certificate is written and gates the delivery, for example test -w /etc/ssl/certs.
A post-sync command runs after the delivery has finished, so the service that uses the certificate picks up the new file, for example sudo systemctl reload nginx.

Set each on the sync’s Commands step. Leaving a field empty means nothing runs, so neither has a separate toggle. Both accept a whole script, so several steps can run in one go: put each on its own line, or chain them with &&.

Your Infisical Gateway runs both commands, never Infisical. The sync’s App Connection must therefore use a gateway, otherwise the command is rejected when you save the sync.The Gateway must be running Infisical CLI v0.43.120 or later. Earlier Gateways either can’t run the command at all or can’t unlock an SSH Connection’s passphrase-protected private key, so the command fails. Run infisical --version on the Gateway host to check, and see Gateway deployment for how to upgrade.

Available variables

Write a variable where you want this run’s value. Infisical substitutes it before the command is sent to the server, so a command keeps working when the name schema or export format changes.

Variable	Value
`{{certificatePath}}`	Full path of the certificate file this run writes. Single-certificate syncs only
`{{certificateDirectory}}`	The destination directory
`{{certificateFiles}}`	Every path this run writes, one per line
`{{commonName}}`	The certificate’s common name. Single-certificate syncs only
`{{pkcs12Password}}`	The PKCS#12 export password, set only when the export format is PKCS#12

The paths are the same for both commands, but a health check runs before anything is written, so they describe the files the run is about to write rather than files already on the host. Each value is inserted already quoted for the target’s shell, so write {{certificatePath}} rather than "{{certificatePath}}". A variable that has no value for the run becomes an empty string. Only the names in this table are substituted. Anything else in double braces is left in the command exactly as you wrote it, so a command that calls a tool with its own braces (helm, jq, a Go template) keeps working, and a misspelled variable reaches the server as literal text rather than silently turning into nothing.

{{certificatePath}} and {{commonName}} name one specific certificate, so a command that uses either can only be saved on a sync with a single certificate linked. Linking a second certificate to such a sync is rejected, as is adding one of these variables to a sync that already has several. To act on every certificate in the run, use {{certificateFiles}}, which lists one path per line.

Length limit

Each command is limited to 8192 characters, counted as you write it, before variables are substituted. For anything longer, put the logic in a script on the server and have the command call that script.

Least privilege

Both commands run as the account the SSH Connection authenticates with, so constraining that account bounds what either can do. A service reload doesn’t need root. Grant the connection user a sudoers rule for that one command instead:

svc-infisical ALL=(root) NOPASSWD: /usr/bin/systemctl reload nginx

Only Application Admins can set either command, so treat that role as access to the target server.

The rendered command is visible in the target server’s process table while it runs. This only matters if you reference {{pkcs12Password}}, and only to accounts that already have a shell on the server the sync writes private keys to.

Health check

A sync can only tell you the host wasn’t ready once it has already tried. If the destination directory was renamed or the service that owns it is stopped, you find out from a failed sync, and on a renewal that is the day the certificate was going to expire anyway. A health check moves that discovery earlier. It runs on the target server before any certificate is written. If it exits non-zero, the sync stops there: no files are delivered, no removals happen, and no post-sync command runs. The same check also runs on its own once a day, so a host that stops being ready between syncs is reported when it happens rather than at the next renewal. Write a check that answers a question rather than one that changes something. test -w /etc/ssl/certs and systemctl is-active nginx are good checks. Creating the directory or starting the service is work for the post-sync command. The check runs on the target server, not on Infisical, and gates everything after it:

Open the sync's Commands step

Edit the sync and select Commands.

Write the check

Anything that exits non-zero when the host isn’t ready works. The variables resolve to the files this run is about to write, so a check can look at where a certificate is going:

set -e
test -w {{certificateDirectory}}
test ! -e {{certificatePath}} || test -w {{certificatePath}}
systemctl is-active --quiet nginx

To check every certificate the run would write instead of one, loop over {{certificateFiles}}:

echo {{certificateFiles}} | while read -r file; do test -w "$(dirname "$file")"; done

Test it, then save the sync

Test check runs the check against the host straight away, so you can see the result without waiting for a sync. It resolves variables against the certificates linked to the sync, so it works once at least one is selected and tells you if none is. {{pkcs12Password}} is the exception: the export password only exists once a saved sync delivers a certificate, so a test always rejects it.Save the sync once the check passes. On a real run, a failing check fails the sync without delivering anything, and the reason appears as the sync’s last error.

Post-sync command

Delivering a certificate file doesn’t make the service use it. NGINX keeps serving the old certificate until something reloads it. A post-sync command is that last step, run for you right after the files land. It runs once per sync run that delivers at least one file. If a sync run doesn’t complete, Infisical may attempt it again and the command runs with it, so prefer a command that is safe to run more than once. The command runs on the target server, not on Infisical, and only after the whole delivery has finished:

Open the sync's Commands step

Edit the sync and select Commands.

Write the command

Use a variable wherever you need a value from the run. Typing {{ in the command field lists the ones available for this sync, so you can pick one instead of remembering the name:

cp {{certificatePath}} /etc/nginx/ssl/live.pem && systemctl reload nginx

Save and trigger a sync

Save the sync, then trigger it. If the command fails, the reason appears as the sync’s last error.

Command FAQ

When exactly does each command run?

The health check runs before anything else in a sync run, including before Infisical opens the SFTP session it would write with. It also runs once a day on its own, whether or not a sync is due.The post-sync command runs after every file in the run has been delivered and after any removals, so the server is in its final state before the service reloads. A run that delivers nothing runs nothing. Renewals, adding a certificate, and a manual trigger all deliver files, so all three run the command. Removing a certificate from the sync does not.

What happens when a command fails?

Either way the sync is marked failed and the reason appears as the sync’s last error. A command that fails is reported, not repeated.What is left on the host differs. When the health check fails, every certificate in the run is reported as skipped with that same reason, so it is clear nothing reached the host, and files already on the server from an earlier run are left exactly as they are, because the sync never wrote or deleted anything. When the post-sync command fails, the delivered files stay in place, because they were written before the command ran.

Can I run several commands, and what happens if one of them fails?

Yes, in either field. Write one per line, or chain them with &&.By default the shell only reports the last line’s exit status, so an earlier line that fails is not noticed and the command counts as having succeeded. Start the script with set -e so the first failure stops it and fails the sync:

set -e
cp {{certificatePath}} /etc/nginx/ssl/live.pem
nginx -t
systemctl reload nginx

Is there a time limit?

Yes, and it differs by command: 15 seconds for the health check, 30 seconds for the post-sync command. Both are enforced by the Gateway, and running out of time counts as a failure.The check’s limit is deliberately much shorter, because the check gates delivery: a host that cannot answer a readiness question in fifteen seconds is itself the problem worth reporting. Keep the check to a question that is cheap to answer, and give a post-sync command that needs longer than thirty seconds a script on the server that starts the work in the background.

Can a command run twice for the same certificate?

Yes, in some cases. If a sync run doesn’t complete, Infisical may attempt it again, and both commands run as part of that attempt. Prefer commands that are safe to run more than once. A service reload or restart is.

Does a failed health check get retried?

Not within the run. A host that isn’t ready is usually not ready a few seconds later either, so retrying only delays the report. The next sync or the next daily check is the retry.

Where do I see the result of the daily health check?

A failing daily check records the failure and its reason against the sync’s health check, shown as Last Checked on the sync’s page, and notifies the application’s administrators. It doesn’t change the sync’s own status, which continues to report the last delivery. Either way the run is recorded in the sync’s logs with the command and the first part of its output.

Can I use the health check to prepare the host instead of just checking it?

You can, since it’s a free-text command, but prefer not to. A check that also does work runs before every sync and has fifteen seconds to finish, and if it fails halfway you have changed the host and delivered nothing. Keep preparation in the post-sync command, or in a script the check only verifies the result of.

Removing certificates

When certificate removal is enabled and a certificate is removed from the sync, revoked, or expired, Infisical deletes exactly the files it delivered for that certificate.

FAQ

Can I import certificates from a Linux server back into Infisical?

No. The Linux Server sync only delivers certificates to the server. It doesn’t read certificates back into Infisical.

What happens if the destination directory does not exist?

The sync fails with a clear error. Create the directory and grant the connection user write access, then run the sync again.

What’s next?

Windows Server

Deploy certificates to Windows servers over WinRM.

Auto-Renewal

Enable automatic certificate renewal and syncing.

Other Sync Destinations

View all supported sync destinations.

Certificate management

Product reference

Reference

Prerequisites

Create a Linux Server sync

Sample request

Using an LDAP connection for many servers

Export formats

How it works

Commands

Available variables

Length limit

Least privilege

Health check

Post-sync command

Command FAQ

Removing certificates

FAQ

What’s next?

Windows Server

Auto-Renewal

Other Sync Destinations

​Prerequisites

​Create a Linux Server sync

​Sample request

​Using an LDAP connection for many servers

​The host must accept the DOMAIN\user login form

​Export formats

​How it works

​Commands

​Available variables

​Length limit

​Least privilege

​Health check

​Post-sync command

​Command FAQ

​Removing certificates

​FAQ

​What’s next?

Windows Server

Auto-Renewal

Other Sync Destinations

Prerequisites

Create a Linux Server sync

Sample request

Using an LDAP connection for many servers

The host must accept the `DOMAIN\user` login form

Export formats

How it works

Commands

Available variables

Length limit

Least privilege

Health check

Post-sync command

Command FAQ

Removing certificates

FAQ

What’s next?