Background Services and Status
Configure continuous operation after a successful initial deployment and verification of the application's certificate. The system service manages the agent process; the agent handles connection retries, version checks, and certificate deployment.
Choose a runtime mode
| Mode | Use case | Lifetime |
|---|---|---|
certone sync --once | Initial deployment or manual verification | Exits after one synchronization cycle |
certone run | Local foreground operation or an existing process manager | Runs continuously |
| System service | Continuous local operation and startup at boot | Managed by the operating system |
certone exec -- application-command | Start a Docker application after preparing certificates | Runs alongside the application |
Only one persistent instance may use a state directory at a time. Stop the foreground process with Ctrl+C before installing a background service.
Choose the account and permissions
A regular user can initialize configuration, connect to the platform, and deploy to applications that the user has permission to manage. The following operations require additional permissions:
| Operation | Required permission |
|---|---|
| Write to a protected certificate directory | Write access to the destination directory |
| Reload an application managed by root | Permission to manage its processes |
| Import IIS certificates and update bindings | Local machine certificate store and IIS management permissions |
| Register or control a system service | System service management permissions |
The default system service runs as root on Linux/macOS and as a system account on Windows. Local commands in the configuration inherit those permissions. Use trusted configuration and scripts, and restrict who can modify them.
When elevating privileges, explicitly specify the original configuration path. For example, run this from the terminal of the user who created the configuration:
sudo "$(command -v certone)" sync --once --config "$HOME/.certone/config.yaml"
Here, sudo grants access to protected directories or application management operations. The configuration path is expanded before elevation, avoiding a switch to a different root-owned configuration. Running as an administrator may make state and logs administrator-owned; use the same runtime account and configuration path for subsequent maintenance.
Install a system service
First complete check, doctor --network, and a one-time deployment successfully. Put the executable and configuration file in their permanent locations.
- Linux / macOS
- Windows
Run these commands from the terminal of the user who created the configuration. sudo is required to register, start, and control the system service:
sudo "$(command -v certone)" service install --config "$HOME/.certone/config.yaml"
sudo "$(command -v certone)" service start --config "$HOME/.certone/config.yaml"
sudo "$(command -v certone)" service status --config "$HOME/.certone/config.yaml"
Restart after changing configuration:
sudo "$(command -v certone)" service restart --config "$HOME/.certone/config.yaml"
You can omit sudo in a root terminal, but still supply the actual configuration file's absolute path. Linux uses systemd, and macOS uses launchd or another supported system service manager.
Use an administrator PowerShell session. Administrator privileges are needed to register and control the Windows service; IIS deployment also requires certificate store and website binding management permissions:
certone service install --config "$env:USERPROFILE\.certone\config.yaml"
certone service start --config "$env:USERPROFILE\.certone\config.yaml"
Get-Service certone
Restart after changing configuration:
certone service restart --config "$env:USERPROFILE\.certone\config.yaml"
If another account created the configuration, or it is in a directory such as ProgramData, replace the example path with its absolute path and grant the service account read access.
Service registration records the absolute paths of both the executable and configuration. The built-in service name is certone. To run multiple independent services, arrange distinct service names and separate state directories yourself. Without system service installation permissions, use an existing process manager to run certone run.
Run in the background with Docker
Use --restart unless-stopped or restart: unless-stopped as shown in Docker Deployment or Synology NAS Deployment, and persist the agent directory. Do not register another system service inside the container.
Inspect status and logs
For a local installation using the default configuration:
certone status
The local wizard defaults to ~/.certone/logs/certone.log. For containers, use docker logs --tail 100 container-name. If an administrator runs the service, use that account to read protected configuration, state, and logs. See Troubleshooting for commands.
| Observation | Meaning |
|---|---|
| System service or container is running | The process exists; it may not be connected to the platform |
Saved connection state is online | The most recent saved connection was healthy; check its timestamp and current logs, since targets may still have deployment failures |
| Deployed version has changed | That target completed its deployment workflow |
verified: true | That target's verification check passed |
pending: true | The target needs another attempt; inspect its failure logs |
status reads saved records. Consider their updated timestamp together with the actual HTTPS certificate. Before the first run, status explains that no deployment has run yet instead of reporting a missing-file error. Use status --json for machine-readable output. A stopped state after sync --once completes is normal.
service status prints unknown, running, or stopped. You can also use systemctl status certone or Windows Get-Service certone.
Recover from an authentication failure
On AUTH_INVALID or NODE_DISABLED, the agent stops automatic authentication retries:
- Check the node ID, Token, and node status in the platform.
- Confirm that you are editing the configuration or container parameters the process actually reads.
- Restart the service, or recreate the container if its environment variables changed.
- Check the connection, instance status, and deployment results.
The process may remain running without retrying authentication, preventing restart policies from creating an authentication loop. An explicit authentication failure during exec initialization also prevents the application from starting.
Service start, stop, restart, status and uninstall do not require a valid deployment configuration. You can stop a service even when its YAML is broken, correct the file, run check, and restart. Installation still requires valid configuration.