Synology Commands

Overview

The netapi synology command group provides CLI access to Synology NAS devices via DSM API.

Prerequisites

Load secrets before using Synology commands:

dsource d000 dev/network

Required environment variables:

Variable Description

SYNOLOGY_IP

Synology NAS IP

SYNOLOGY_USER

DSM username

SYNOLOGY_PASS

DSM password

Global Options

Option Short Description

--host

-H

Override NAS IP (overrides env)

Example:

# Target specific NAS
netapi synology -H 10.50.1.50 info

System Information

info

Show Synology system information:

netapi synology info

Returns:

  • Model name

  • DSM version

  • Serial number

  • Uptime

volumes

List storage volumes:

netapi synology volumes

Returns:

  • Volume ID

  • Status

  • Size / Used space

  • File system type

disks

List physical disks:

netapi synology disks

Returns:

  • Disk name (e.g., disk1, disk2)

  • Model

  • Serial number

  • Status

  • Temperature

shares

List shared folders:

netapi synology shares

Returns:

  • Share name

  • Path

  • Description

Certificate Operations

The cert subcommand manages SSL/TLS certificates on the Synology NAS.

cert list

List installed certificates:

netapi synology cert list

Returns:

  • Certificate ID

  • Description

  • Subject/CN

  • Expiration date

  • Is default

cert import

Import certificate from local files:

# Import cert and key
netapi synology cert import -c /path/to/cert.pem -k /path/to/key.pem

# With chain and description
netapi synology cert import \
    -c /path/to/cert.pem \
    -k /path/to/key.pem \
    --chain /path/to/chain.pem \
    -d "LetsEncrypt Wildcard"

# Set as default certificate
netapi synology cert import -c cert.pem -k key.pem --default

Options:

Option Required Description

-c, --cert

Yes

Path to certificate PEM file

-k, --key

Yes

Path to private key PEM file

--chain

No

Path to intermediate/chain PEM

-d, --descr

No

Certificate description

--default

No

Set as default certificate

cert import-from-certmgr

Import certificate from certmgr-01 to Synology via direct file copy:

# Import default domain certificate
netapi synology cert import-from-certmgr

# Import specific domain
netapi synology cert import-from-certmgr -D guest.domusdigitalis.dev

# Dry run to see commands
netapi synology cert import-from-certmgr --dry-run

# Specify cert ID (auto-detected if not set)
netapi synology cert import-from-certmgr --cert-id abc123

This command bypasses the buggy DSM API (which fails with ECDSA certs) by:

  1. Copying PEM files to NAS /tmp

  2. Installing to /usr/syno/etc/certificate/_archive/<cert_id>/

  3. Running synow3tool --gen-all to propagate to all services

  4. Restarting nginx

Requires passwordless sudo configured on NAS for cert commands.

Options:

Option Required Description

-c, --certmgr

No

certmgr host (default: 10.50.1.60)

--certmgr-user

No

certmgr SSH user (default: ansible)

-D, --domain

No

Certificate domain (default: guest.domusdigitalis.dev)

--cert-id

No

DSM cert ID (auto-detect if not set)

--dry-run

No

Show commands without executing

Backup Validation

Monitor and validate infrastructure backups stored on the NAS.

backup-status

Dashboard view of all backup folders with age, size, and file count:

netapi synology backup-status
Sample Output
                                    Backup Status
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━┳━━━━━━━━┳━━━━━━━━━┓
┃ System   ┃ Folder            ┃ Files ┃ Devices ┃     Size   ┃ Age ┃ Status ┃ Latest  ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━╇━━━━━━━━╇━━━━━━━━━┩
│ ISE      │ /ise_backups      │     7 │       1 │    3.4 GB  │ 54m │  ✓ OK  │ 01-24   │
│ WLC      │ /wlc_backups      │     4 │       1 │   59.5 KB  │ 42m │  ✓ OK  │ 01-24   │
│ pfSense  │ /firewall_backups │     3 │       1 │  110.4 KB  │ 42m │  ✓ OK  │ 01-24   │
│ Switches │ /switch_backups   │     3 │       2 │   23.4 KB  │ 24m │  ✓ OK  │ 01-24   │
│ KVM VMs  │ /kvm_backups      │    16 │       8 │  113.3 KB  │  0m │  ✓ OK  │ 01-24   │
│ Keycloak │ /Backups/keycloak │     2 │       2 │    9.7 KB  │ 24m │  ✓ OK  │ 01-24   │
└──────────┴───────────────────┴───────┴─────────┴────────────┴─────┴────────┴─────────┘

✓ All 6 backup sets current

Detailed Device View

Show individual devices with their backup ages:

netapi synology backup-status --detailed
Sample Output (Detailed)
                                    Backup Status
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━┳━━━━━━━━┳━━━━━━━━━┓
┃ System   ┃ Folder            ┃ Files ┃ Devices ┃     Size   ┃ Age ┃ Status ┃ Latest  ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━╇━━━━━━━━╇━━━━━━━━━┩
│ KVM VMs  │ /kvm_backups      │    16 │       8 │  113.3 KB  │  0m │  ✓ OK  │ 01-24   │
│          │   9800-CL-WLC     │       │         │            │  0m │        │         │
│          │   certmgr-01      │       │         │            │  0m │        │         │
│          │   home-dc01       │       │         │            │  0m │        │         │
│          │   ipsk-manager    │       │         │            │  0m │        │         │
│          │   ise-01          │       │         │            │  0m │        │         │
│          │   keycloak-01     │       │         │            │  0m │        │         │
│          │   P50             │       │         │            │  0m │        │         │
│          │   pfsense-01      │       │         │            │  0m │        │         │
└──────────┴───────────────────┴───────┴─────────┴────────────┴─────┴────────┴─────────┘

Device ages are color-coded:

  • Green: < 24 hours old

  • Yellow: > 7 days old

  • Red: Missing or very stale

Options:

Option Short Description

--format

-f

Output format: table or json

--detailed

-d

Show individual device names with ages

JSON output for scripting:

netapi synology backup-status -f json

backup-check

Check backup freshness and alert if stale. Returns exit code 1 on failure - useful for cron/monitoring:

# Default 7-day (168h) threshold
netapi synology backup-check

# Custom threshold (24 hours)
netapi synology backup-check --max-age 24

# Quiet mode - only output on failure
netapi synology backup-check --max-age 24 --quiet
Sample Output (Success)
✓ BACKUP CHECK PASSED
  All 6 backup sets within 168h threshold
Sample Output (Failure)
BACKUP CHECK FAILED
  4 OK, 2 ISSUES

  ✗ ISE: 180.5h old (max: 168h)
  ✗ Keycloak: NO BACKUPS in /Backups/keycloak

Options:

Option Short Description

--max-age

-m

Max age in hours before alert (default: 168)

--quiet

-q

Only output on failure

backup-list

List recent backups for a specific system:

netapi synology backup-list kvm
netapi synology backup-list ise --limit 5
Sample Output
           Recent KVM Backups (/kvm_backups)
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ Filename                         ┃   Size ┃             Date ┃    Age ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
│ 9800-CL-WLC-20260124-191735.xml  │ 4.0 KB │ 2026-01-24 19:18 │ 1m ago │
│ certmgr-01-20260124-191736.xml   │ 8.1 KB │ 2026-01-24 19:18 │ 1m ago │
│ home-dc01-20260124-191736.xml    │ 8.0 KB │ 2026-01-24 19:18 │ 1m ago │
│ ipsk-manager-20260124-191735.xml │ 8.7 KB │ 2026-01-24 19:18 │ 1m ago │
│ ise-01-20260124-191736.xml       │ 6.8 KB │ 2026-01-24 19:18 │ 1m ago │
└──────────────────────────────────┴────────┴──────────────────┴────────┘

Showing 5 of 16 total backups

Valid system names: ise, wlc, pfsense, switch, kvm, keycloak

Options:

Option Short Description

--limit

-n

Number of recent backups to show (default: 10)

Monitoring Integration

Cron Job for Daily Check

# /etc/cron.d/backup-check
0 8 * * * user eval "$(dsec source d000 dev/storage)" && \
    netapi synology backup-check --max-age 24 --quiet || \
    mail -s "Backup Alert" admin@example.com

Prometheus/Alertmanager

Export JSON for Prometheus node_exporter textfile collector:

#!/bin/bash
# /opt/scripts/backup-metrics.sh
eval "$(dsec source d000 dev/storage)"
netapi synology backup-status -f json | python3 -c "
import sys, json
data = json.load(sys.stdin)
for r in data:
    label = r['label'].lower().replace(' ', '_')
    age = r['age_hours'] or 999
    print(f'backup_age_hours{{system=\"{label}\"}} {age}')
    print(f'backup_file_count{{system=\"{label}\"}} {r[\"count\"]}')
" > /var/lib/node_exporter/textfile/backups.prom

File Operations

list-files

List files in a folder:

netapi synology list-files /firewall_backups

upload

Upload a file to NAS:

netapi synology upload /tmp/backup.xml /firewall_backups

Integration with certmgr

Both pfSense and Synology certificate commands integrate with the centralized certificate manager (certmgr-01).

Typical workflow:

# 1. Certbot renews certificates on certmgr-01
# 2. Deploy to pfSense
netapi pfsense cert import-from-certmgr -D guest.domusdigitalis.dev

# 3. Deploy to Synology
netapi synology cert import-from-certmgr -D guest.domusdigitalis.dev