synology-operations

synology-operations

Operate against a Synology NAS over SSH (and optionally DSM HTTP API). All host- and credential-specific values come from the plugin's config — never hard-code them.

Pre-flight

Resolve the plugin data directory (${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/synology-mgmt/) and load config.json. If it doesn't exist or is incomplete, tell the user to run the onboard skill first and stop.

Available fields after load: host, ssh_user, ssh_port, ssh_key_path, dsm_web_url, volume_root, model, dsm_version, dsm_user_ref.

SSH access

SSH_OPTS=( -p "$SSH_PORT" )
[ -n "$SSH_KEY_PATH" ] && SSH_OPTS+=( -i "$SSH_KEY_PATH" )
ssh "${SSH_OPTS[@]}" "$SSH_USER@$HOST" "<command>"

Synology limits the default user shell. Prefix privileged commands with sudo (DSM will prompt or accept the user's password depending on config).

Typical tasks

File operations on shares

• List shares: ls -la "$VOLUME_ROOT" (each top-level dir is a share)
• Check a specific share: ls -la "$VOLUME_ROOT/<share>"
• Free space per volume: df -h | grep -E "^/dev|volume"

Storage health

# Volume + RAID status
sudo synostorage --info

# SMART status per disk (read-only)
sudo smartctl -a /dev/sata1
sudo smartctl -a /dev/sata2

# Btrfs scrub status (if applicable)
sudo btrfs scrub status "$VOLUME_ROOT"

Share / permissions

• List shared folders via DSM: sudo synoshare --enum ALL
• Inspect ACL on a folder: sudo synoacltool -get "$VOLUME_ROOT/<share>"

Snapshots (Btrfs / Snapshot Replication)

• List snapshots for a share: sudo synosnap --list "$VOLUME_ROOT/<share>"
• Read-only inspection only — never delete snapshots without explicit confirmation.

System

• DSM version and model: cat /etc.defaults/VERSION
• Uptime / load: uptime
• Running services: synoservicectl --list 2>/dev/null | head -50
• System log tail: sudo tail -100 /var/log/messages

DSM HTTP API (optional)

If the user has populated dsm_user_ref, you can authenticate to the DSM API at $DSM_WEB_URL/webapi/. Login flow:

curl "$DSM_WEB_URL/webapi/auth.cgi?api=SYNO.API.Auth&version=3&method=login&account=$USER&passwd=$PASS&session=FileStation&format=cookie"

Resolve the password from dsm_user_ref at runtime (1Password, env var, file). Don't log it.

Useful endpoints:

API	Purpose
SYNO.Core.System	System info
SYNO.Storage.CGI.Storage	Volume / RAID overview
SYNO.FileStation.List	List share contents
SYNO.Core.Share	Share management

Guidelines

• Confirm before any destructive operation on shared storage — delete, overwrite, snapshot removal, ACL change.
• Prefer read-only inspection first. Mutate only with explicit user confirmation.
• Don't run package installs / updates without confirmation — DSM updates can require reboot.
• Mind the volume path. The default in onboard is /volume1; multi-volume NASes have /volume2, /volume3, etc. Re-check volume_root and ask the user if a path doesn't exist.
• SSH session weight matters on small models. Don't open many parallel SSH sessions on entry-level units (DS220+, DS923+, etc.) — chain commands in a single session instead.