Synology Configuration and API Deployment

Before deployment

CertOne imports certificates through the local DSM API. It does not need to modify internal DSM certificate files, mount the Docker socket, or run a privileged container.

Confirm that:

1. The NAS can run a Linux binary or dedicated container matching its architecture.
2. The agent environment can reach the DSM management address.
3. The DSM account has certificate-management permissions.
4. You know how services will be assigned certificates after the first import. To replace an existing entry, record its internal DSM ID or unique description and use an advanced mapping.
5. The account's MFA/OTP policy supports unattended deployment.

The platform Token and DSM password have different purposes. Put them in node.token and synology.password respectively, within the same config.yaml.

Configuration example

This configuration automatically handles all associated certificates, creating or updating DSM entries using CertOne-{id}. To update only a specific existing DSM entry, set both certificates[].id and DSM's certificate_id in an advanced mapping. These IDs belong to the platform and DSM respectively and are not interchangeable.

node:
  id: node-REPLACE
  token: REPLACE_WITH_NODE_TOKEN
state_dir: /root/.certone/state
sync_interval: 1h
logging:
  level: info
  format: text
targets:
  - name: dsm
    type: synology
    synology:
      url: https://nas.example.com:5001
      username: certone-user
      password: REPLACE_WITH_DSM_PASSWORD
      description: CertOne-{id}
      create: true
      as_default: false
      # ca_file: /root/.certone/dsm-ca.pem
      # otp: '123456'

Field	Usage
url	DSM address reachable from the agent
username / password	DSM login account and password
description	Certificate description to match; must be unique and use the actual full text
certificate_id	Known internal DSM certificate ID; when provided, ID-based selection takes precedence
create	Default false; explicitly set true to allow creation when no certificate matches the description
as_default	Whether to request making the certificate the default; set according to your requirements
ca_file	Optional certificate file for trusting a private DSM CA
otp	Optional currently valid one-time code

If an explicit certificate_id cannot be found, create: true does not create a different certificate ID instead.

Replacing a certificate reuses its DSM ID. After import, verify the certificate assignments for each service in DSM, especially for newly created entries. Do not assume a new certificate is automatically assigned to every NAS service.

Container deployment

For a first deployment, use the dedicated image and environment variables in the Synology NAS guide, or its Compose example. This section covers building your own image and using a configuration file.

Obtain the dedicated image for your NAS architecture from your administrator or image distribution channel. To build it yourself, use a directory containing a Linux certone binary:

FROM alpine:3.23
RUN apk add --no-cache ca-certificates
COPY --chmod=0755 certone /usr/local/bin/certone
ENTRYPOINT ["/usr/local/bin/certone"]
CMD ["run", "--config", "/root/.certone/config.yaml"]

docker build -t certone-synology:local .

Example directory layout:

certone-dsm/
├── compose.yaml
└── certone/
    ├── config.yaml
    └── state/                 # Created automatically on the first run

compose.yaml:

services:
  certone:
    image: certone-synology:local
    init: true
    restart: unless-stopped
    volumes:
      - ./certone:/root/.certone
    logging:
      driver: json-file
      options:
        max-size: 10m
        max-file: '5'

Replace image if using another image name. Create the project in the NAS container-management interface or run the following where Compose is available:

docker compose up -d
docker compose logs --tail 100 certone

Synology notes

• On a bridged network, 127.0.0.1 refers to the container itself, usually not DSM. Use the NAS LAN address or a resolvable hostname.
• The HTTPS hostname must match the certificate DSM currently serves. ca_file addresses CA trust only; it does not fix hostname mismatches or expired certificates.
• Replacing DSM's certificate may affect trust on the next API connection. If you trusted a particular self-signed leaf certificate, recheck trust after replacement.
• HTTP can be used in an explicitly chosen local environment, but sends credentials in plaintext. Prefer correctly configured HTTPS trust.
• otp uses the configured code; it does not generate TOTP codes. A fixed code cannot support long-term unattended login.
• doctor --network checks the platform connection. DSM login, permissions, and imports must be verified through a real deployment.
• DSM_API_ERROR means DSM rejected an operation. Investigate its return code, account permissions, and DSM version requirements rather than assuming a platform Token problem.