Skip to main content

Custom Commands and Multiple Targets

Custom shell scripts​

argv is an argument array. It does not automatically interpret pipes, redirects, wildcards, or &&. Explicitly invoke a shell when those features are needed:

reload:
  argv: [/bin/sh, /opt/certone/reload-site.sh]
  timeout: 30s
  dir: /opt/certone
  env:
    APP_ENV: production

A simple script:

#!/bin/sh
set -eu
/usr/sbin/nginx -s reload

Scripts should exit after the operation completes and return exit code 0 on success. Do not use a long-running foreground service directly as a reload command, or return success after an operation failed.

Working directories and environment variables in system services can differ from an interactive terminal. Use absolute paths and explicitly configure the required environment. Do not depend on an interactive sudo password prompt.

Windows custom file targets can also invoke PowerShell:

reload:
  argv:
    - 'C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe'
    - -NoProfile
    - -NonInteractive
    - -File
    - 'C:\ProgramData\CertOne\reload-app.ps1'
  timeout: 30s

Configure the local script execution policy and application permissions appropriately.

Multiple certificates and targets​

When one application reload can load several certificates, put them in the same target:

targets:
  - name: nginx-sites
    type: files
    certificates:
      - id: cert-SITE_A
        key_path: /etc/nginx/certs/site-a/key.pem
        fullchain_path: /etc/nginx/certs/site-a/fullchain.pem
      - id: cert-SITE_B
        key_path: /etc/nginx/certs/site-b/key.pem
        fullchain_path: /etc/nginx/certs/site-b/fullchain.pem
    check:
      argv: [/usr/sbin/nginx, -t]
    reload:
      argv: [/usr/sbin/nginx, -s, reload]

Use separate targets for different applications, each with its own validation and reload commands. A certificate ID can appear in multiple targets, but every output path must be unique.

File rollback is per target; all targets do not form a single transaction. Other targets may already have succeeded when one fails. Inspect results by target name.