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
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 post-sync command, because the Gateway is what executes it

Create a Linux Server Sync

Infisical UI
API

In your Application, go to the Certificate Syncs tab and click Create Sync.
Select the Linux Server option.
Configure the Destination:
- SSH Connection: The SSH Connection used to reach the server.
- Destination Directory: The absolute path to the directory where certificate files are written, for example /etc/ssl/certs.
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 Post-Sync Command, or leave it empty:
- 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. Post-Sync Commands covers the available placeholders and what happens when the command fails.
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.

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}}",
        "postSyncCommand": "sudo systemctl reload nginx"
    },
    "destinationConfig": {
        "destinationPath": "/etc/ssl/certs"
    }
}'

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.

Post-Sync Commands

Delivering a certificate file does not 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. Set one command on the sync. It runs on the target server, in that server’s own shell, once per sync run that delivers at least one file. Leaving the field empty means nothing runs, so there is no separate toggle. If a sync run does not 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 field accepts 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 the command, never Infisical. The sync’s SSH Connection must therefore use a gateway, otherwise the command is rejected when you save the sync.

The command runs on the target server, not on Infisical, and only after the whole delivery has finished:

Setting a Command

Open the sync's Post-Sync Command step

Edit the sync and select Post-Sync Command.

Write the command

Use a placeholder wherever you need a value from the run:

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.

Available Placeholders

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

Placeholder	Value
`{{certificatePath}}`	Full path of the certificate file delivered this run. Single-certificate syncs only
`{{certificateDirectory}}`	The destination directory
`{{certificateFiles}}`	Every path written this run, 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

Each value is inserted already quoted for the target’s shell, so write {{certificatePath}} rather than "{{certificatePath}}". A placeholder 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 placeholder 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 placeholders to a sync that already has several. To act on every certificate in the run, use {{certificateFiles}}, which lists one path per line:

echo {{certificateFiles}} | while read -r file; do echo "delivered $file"; done

Length Limit

A command is limited to 2048 characters, counted after the placeholders are substituted. For anything longer, put the logic in a script on the server and call that script.

Post-Sync Command FAQ

When exactly does the command run?

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 if the command fails?

The sync is marked failed and the reason appears as the sync’s last error. The delivered files stay in place, because they were written before the command ran. A command that fails is reported, not repeated.

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

Yes. 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 sync still reports success. 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

Can the command run twice for the same certificate?

Yes, in some cases. If a sync run does not complete, Infisical may attempt it again, and the command runs as part of that attempt. Prefer a command that is safe to run more than once. A service reload or restart is.

Is there a time limit?

Yes, 30 seconds, enforced by the gateway. A command that needs longer should start the work in the background or live in a script on the server.

Least Privilege

The command runs as the account the SSH Connection authenticates with, so constraining that account bounds what any command can do. A service reload does not need root. Grant the connection user a sudoers rule for that one command instead:

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

Anyone who can edit the sync can change the command, so treat edit access to these syncs 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.

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 does not 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

Export Formats

How It Works

Post-Sync Commands

Setting a Command

Available Placeholders

Length Limit

Post-Sync Command FAQ

Least Privilege

Removing Certificates

FAQ

What’s Next?

Windows Server

Auto-Renewal

Other Sync Destinations

​Prerequisites

​Create a Linux Server Sync

​Sample request

​Export Formats

​How It Works

​Post-Sync Commands

​Setting a Command

​Available Placeholders

​Length Limit

​Post-Sync Command FAQ

​Least Privilege

​Removing Certificates

​FAQ

​What’s Next?

Windows Server

Auto-Renewal

Other Sync Destinations

Prerequisites

Create a Linux Server Sync

Sample request

Export Formats

How It Works

Post-Sync Commands

Setting a Command

Available Placeholders

Length Limit

Post-Sync Command FAQ

Least Privilege

Removing Certificates

FAQ

What’s Next?