Configuration Reference

Configuration files and paths

Configuration uses YAML with a single document and space-based indentation. Unknown fields are rejected, so misspelled settings are not silently ignored.

The default path is ~/.certone/config.yaml on Linux/macOS and %USERPROFILE%\.certone\config.yaml on Windows. For another location, explicitly pass --config to each command.

Use absolute file and directory paths. YAML values containing ~, $HOME, or %ProgramData% are not automatically expanded. Single-quote Windows paths in YAML, for example:

state_dir: 'C:\ProgramData\CertOne\state'

Configuration is loaded at process startup. Restart a persistent process after editing it. Temporary terminal environment variables and command-line overrides are not automatically saved to configuration or made persistent service settings. Put long-term values in the configuration file or explicitly in the service's runtime environment.

Global settings

Field	Required / default	Description
server.allow_http	Default false	Enable only for an explicitly chosen HTTP environment; use HTTPS in production
node.id	Required	Platform node ID
node.token	Required	Node Token, entered directly in the configuration
state_dir	Required	Absolute, writable, persistent state directory
sync_interval	Default 1h	Periodic reconciliation interval, minimum 1m; does not affect real-time push
logging.level	Default info	debug, info, warn, or error
logging.format	Default text	text or json
logging.file	No separate file by default	Optional absolute log path; logs still go to standard error
targets	Required	At least one deployment target

Log files rotate automatically at approximately 10 MiB, retaining five historical files plus the current file. Containers can omit logging.file, use container logs, and configure Docker log rotation.

Node association changes take effect on the next synchronization without a restart. Changes to deployment rules in the configuration file still require a restart. Unbinding a certificate stops its synchronization but retains deployed files and DSM entries, avoiding disruption to services still using them.

Minimal automatic-discovery configuration

This configuration writes all associated certificates to ~/.certone/certificates/<certificate-id>/ for the runtime user. Replace the node ID, Token, and state directory:

node:
  id: node-REPLACE
  token: REPLACE_WITH_NODE_TOKEN
state_dir: /home/deploy/.certone/state
targets:
  - name: certificates
    type: files

An advanced certificates[].id mapping controls how a target deploys a certificate, not which certificates the node can download. Even with explicit mappings, the agent caches all valid certificates associated with the node.

Target and certificate fields

Field	Description
targets[].name	Unique local target name used in logs and status
targets[].type	files, synology, or iis
targets[].certificates	Optional deployment rules; when omitted, associated certificates are discovered automatically and file targets use separate default directories
certificates[].id	Normally omitted for automatic discovery; specify only for an advanced mapping to one certificate
certificates[].domains	Optional domain coverage checks
certificates[].key_path	PEM private key output path; must be configured together with fullchain_path
certificates[].fullchain_path	PEM certificate and chain output path
certificates[].pfx_path	Optional PFX/P12 output path
certificates[].jks_path	Optional JKS output path
certificates[].password	Required export password for PFX/JKS
certificates[].alias	Required JKS key-entry name

Target names and certificate IDs may contain letters, digits, hyphens, and underscores, up to 160 characters. Target names must be unique. Certificate IDs must not repeat within a target.

File targets need at least one output format. Output paths must be absolute and unique, must not overwrite the configuration file, and must not be inside state_dir.

A files target writes associated certificates into separate directories and runs validation and reload once for the target. Automatic discovery requires {id} in every output path. Synology templates use description: CertOne-{id} to create a separate entry per certificate. Each IIS target corresponds to an existing HTTPS binding and selects a unique certificate using iis.host. Add separate targets for multiple sites; you do not need to repeat certificate IDs. Without a hostname, exactly one certificate must be associated. Zero or multiple matches produce an error.

Local validation, reload, and rollback

These fields apply only to files targets:

check:
  argv: [/usr/sbin/nginx, -t]
  timeout: 15s
reload:
  argv: [/usr/sbin/nginx, -s, reload]
  timeout: 15s
rollback:
  argv: [/usr/sbin/nginx, -s, reload]
  timeout: 15s

Execution order: validate certificate → back up old files → write new files → check → reload → verify (if configured) → record success.

Field	Meaning
argv	Argument array: the executable's absolute path first, followed by one argument per entry
timeout	Maximum command duration; default 30s
dir	Optional working directory; use an absolute path
env	Optional environment-variable mapping for the command

A failed check prevents reloading the new configuration. For failures requiring service recovery, the agent restores the old files and invokes rollback, falling back to reload if no rollback command is configured.

These commands are preconfigured locally by an administrator. Platform push notifications do not directly supply arbitrary shell commands.

Verify the application certificate

verify:
  address: 127.0.0.1:443
  server_name: example.com
  # certificate_id: cert-REPLACE  # Set only when an explicit selection is needed
  # Add a private CA if needed:
  # ca_file: /home/deploy/.certone/site-ca.pem

• address is the actual address and port to connect to.
• server_name is the TLS hostname used for trust verification and SNI site selection.
• certificate_id is normally omitted so a unique certificate is selected by server_name. An explicit ID must belong to the current target. Zero or multiple matches produce an error.
• ca_file adds a trusted private CA; it does not disable certificate validation.

The program allows approximately 15 seconds for asynchronous reloads, then checks that the service presents the expected certificate. Verification failure invokes the file target's recovery workflow.

An address behind a CDN, load balancer, or TLS proxy may return that layer's certificate. For local deployment verification, choose an address that reaches the application directly.

Each target's verify checks one endpoint and one certificate. It does not establish that every domain and replica has been verified.

Configuration overrides

Precedence: command-line options > environment variables > YAML.

YAML field	Environment variable	Command-line option
node.id	CERTONE_NODE_ID	--node-id
state_dir	CERTONE_STATE_DIR	None; use YAML or an environment variable

Put the Token in YAML under node.token; leading and trailing whitespace is trimmed. There is no Token command-line option. CERTONE_TOKEN is only for environment-variable mode. Put passwords in the corresponding password field; their contents are used literally. Quote passwords containing YAML special characters.