Skip to content

Instantly share code, notes, and snippets.

@sliekens

sliekens/synology-nut.md

Created January 11, 2026 00:17
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save sliekens/ab47c015145a85fbf829c3ba26960aa3 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save sliekens/ab47c015145a85fbf829c3ba26960aa3 to your computer and use it in GitHub Desktop.
Download ZIP
Synology DSM7 UPS/NUT Documentation
Raw
synology-nut.md

Synology DSM7 UPS/NUT Documentation

Overview

Synology DSM7 uses NUT (Network UPS Tools) to manage UPS devices. The system integrates with systemd for service management.

Systemd Service

Service File Location

  • Symlink: /etc/systemd/system/syno-bootup-done.target.wants/ups-net.service
  • Script: /usr/syno/lib/systemd/scripts/ups-net.sh

Service Definition

[Unit]
Description=UPS-Network Daemon
After=syno-bootup-done.target
DefaultDependencies=yes
IgnoreOnIsolate=yes

[Install]
WantedBy=syno-bootup-done.target

[Service]
Type=forking
ExecStart=/usr/syno/lib/systemd/scripts/ups-net.sh start
ExecStop=/usr/syno/lib/systemd/scripts/ups-net.sh stop
ExecReload=/usr/syno/lib/systemd/scripts/ups-net.sh reload

[X-Synology]
NameI18n=helptoc:power_ups
InfoCenterDisplay=yes
FirewallSections=ups_server

Service Commands

systemctl start ups-net.service
systemctl stop ups-net.service
systemctl reload ups-net.service
systemctl restart ups-net.service

ups-net.sh Script

Location: /usr/syno/lib/systemd/scripts/ups-net.sh

This script handles UPS network daemon startup for both master (SNMP) and slave modes. It sources /usr/syno/bin/synoupscommon for shared variables and functions.

Key Variables (from synoupscommon)

Variable Value / Path Description
UpsMode usb | snmp Connection mode (from ups_mode in config, defaults to usb)
SlaveEnabled 0 | 1 Set to 1 if upsslave_enabled=yes
MasterEnabled 0 | 1 Set to 1 if ups_enabled=yes
SYNOUPS_CONF /usr/syno/etc/ups/synoups.conf Main Synology UPS configuration
UPS_CONF /etc/ups/ups.conf NUT driver configuration
UPS_CONF_BACKUP /etc.defaults/ups/ups.conf Default/backup ups.conf
UPSSCHED_CONF /etc/ups/upssched.conf NUT event scheduler config
UPSMON_CONF /etc/ups/upsmon.conf NUT monitor configuration
UPS_STATE /run/ups_state Runtime state directory
UPS_LOCK /tmp/ups/ups.lock Lock file for exclusive access

Modes of Operation

1. USB Mode

If UpsMode is usb, the script exits immediately (handled elsewhere).

2. Slave Mode (SlaveEnabled=1)

  • Connects to a remote UPS server (master)
  • Reads upsslave_server from config
  • Supports IPv6 addresses (wrapped in brackets)
  • Configures upsmon to monitor remote server
  • Sets up ONBATT event handlers with optional wait timer

3. Master Mode with SNMP (MasterEnabled=1 + UpsMode=snmp)

  • Communicates with UPS via SNMP protocol
  • Configures the snmp-ups driver in ups.conf
  • Supports SNMP v2c and v3
  • SNMP v3 security levels:
    • noAuthNoPriv - No authentication, no privacy
    • authNoPriv - Authentication only
    • authPriv - Authentication + privacy/encryption
  • Starts the SNMP UPS driver with retry logic (up to 15 attempts)
  • Starts both NUT server and client

SNMP Configuration Options

Config Key Description
ups_snmp_ip UPS SNMP IP address
ups_snmp_community SNMP community string
ups_snmp_version SNMP version (default: v2c)
ups_snmp_mib MIB to use (default: auto)
ups_snmp_user SNMPv3 username
ups_snmp_auth Enable authentication (yes/no)
ups_snmp_auth_type Auth protocol (e.g., MD5, SHA)
ups_snmp_auth_key Auth password
ups_snmp_privacy Enable privacy (yes/no)
ups_snmp_privacy_type Privacy protocol (e.g., DES, AES)
ups_snmp_privacy_key Privacy password

Event Handling

The script configures upssched for power events:

AT ONBATT * EXECUTE onbatt
AT ONBATT * START-TIMER waittimeup <ups_wait_time>
  • ups_wait_time - Seconds to wait on battery before triggering shutdown

Script Flow

start
  └─► USB mode? → exit
  └─► Slave mode?
  │     └─► Configure upsmon for remote server
  │     └─► StartClient()
  └─► Master SNMP mode?
        └─► Configure snmp-ups driver
        └─► StartSnmpUpsDriver() (with retries)
        └─► StartServer()
        └─► StartClient()

stop
  └─► StopUps()

reload
  └─► Slave: StartClient()
  └─► Master: RestartServer() + StartClient()

restart
  └─► StopUps() → WaitStop() → StartUps()

Locking

Uses file locking (flock) on $UPS_LOCK to prevent concurrent execution.

synoupscommon Library

Location: /usr/syno/bin/synoupscommon

This is a shared shell library sourced by UPS scripts. It defines paths, variables, and common functions.

Directory & File Paths

Variable Path Description
UPS_STATE /run/ups_state Runtime state directory
UPS_ROOT /tmp/ups Temporary UPS directory
UPS_LOCK /tmp/ups/ups.lock Lock file for flock
UPS_UDEVLOCK /tmp/upsudevlock udev lock file
SYNOUPS_CONF /usr/syno/etc/ups/synoups.conf Main Synology UPS config
UPSSCHED_CONF /etc/ups/upssched.conf NUT upssched config
UPSMON_CONF /etc/ups/upsmon.conf NUT upsmon config
UPSMON_CONF_BACKUP /etc.defaults/ups/upsmon.conf Backup upsmon config
UPS_CONF /etc/ups/ups.conf NUT ups.conf
UPS_CONF_BACKUP /etc.defaults/ups/ups.conf Backup ups.conf
NUTSCAN_USB_H /etc/ups/nutscan-usb.h USB device header
UPS_TABLE /lib/udev/devicetable/usb.nut-hid USB HID device table

Binary Paths

Variable Path
BIN_UPSMON /usr/sbin/upsmon
BIN_UPSD /usr/sbin/upsd
BIN_UPSC /usr/bin/upsc
BIN_SYNONOTIFY /usr/syno/bin/synonotify

PID Files

Variable Path
UPSMON_PID /run/upsmon.pid
UPSD_PID /run/ups_state/upsd.pid

Debug Logging

Debug output can be enabled via synoups.conf:

Config Key Description
upslog General UPS log file path
upsmon_dbg upsmon debug output file
upsd_dbg upsd debug output file
upsdrv_dbg UPS driver debug output file

When debug keys are set, daemons run with -DDD flag for verbose output.

Mode Detection

The library reads synoups.conf to determine operation mode:

# Check if UPS is supported on this device
SupportUPS = /etc.defaults/synoinfo.conf → supportups

# Master mode enabled?
ups_enabled=yes → MasterEnabled=1

# Slave mode enabled?
upsslave_enabled=yes → SlaveEnabled=1

# Connection mode (defaults to "usb" if empty)
ups_mode=usb|snmp → UpsMode

Key Functions

StartServer()

Starts the NUT data server (upsd):

  1. Updates /etc/ups/upsd.conf with LISTEN 0.0.0.0
  2. Stops any existing upsd instance
  3. Starts upsd (with debug if upsd_dbg is set)

RestartServer()

Restarts upsd if currently running.

StartClient()

Starts the UPS monitor client (upsmon):

  1. Stops any existing upsmon
  2. Starts upsmon (with debug if upsmon_dbg is set)

StopUps()

Graceful shutdown of all UPS daemons:

killall upsmon
killall upssched
killall upsd
upsdrvctl stop

ForceStopUps()

Force kills all UPS processes with killall -9 after timeout.

WaitStop()

Waits up to 9 seconds (3 attempts × 3 seconds) for processes to stop, then calls ForceStopUps().

CheckUpsmonConf(mode, [server_ip])

Configures upsmon.conf for local or remote monitoring:

Mode MONITOR Line
local MONITOR ups@localhost 1 monuser secret master
remote MONITOR ups@<server_ip> 1 monuser secret slave

CheckUPSSupport(vendorID, productID)

Checks if a USB device is a supported UPS by looking it up in the device table.

isInBlackList(device)

Checks if a device is blacklisted (e.g., Belkin_F5U002 printer adapter).

ShowLog(message)

Logs to stdout and syslog (user.err facility, tag upsmsg).

USB Device Blacklist

Some USB devices are explicitly blocked from being recognized as UPS devices:

Device USB ID Reason
Belkin F5U002 050d/0002 Printer adapter

Quick Reference: File Paths

Configuration Files

Path Description
/usr/syno/etc/ups/synoups.conf Main Synology UPS config - master/slave mode, SNMP settings, wait time
/etc/ups/ups.conf NUT driver configuration (device, port, driver type)
/etc/ups/upsd.conf NUT server configuration (listen address)
/etc/ups/upsmon.conf NUT monitor configuration (MONITOR directive)
/etc/ups/upssched.conf NUT event scheduler (ONBATT timers, actions)
/etc.defaults/synoinfo.conf System info - contains supportups flag

Backup/Default Configs

Path Description
/etc.defaults/ups/ups.conf Default ups.conf (restored on start)
/etc.defaults/ups/upsmon.conf Default upsmon.conf (restored if empty)

Scripts & Binaries

Path Description
/usr/syno/lib/systemd/scripts/ups-net.sh Systemd service script
/usr/syno/bin/synoupscommon Shared library (sourced by scripts)
/usr/sbin/upsmon NUT monitor daemon
/usr/sbin/upsd NUT data server daemon
/usr/bin/upsc NUT client (query UPS status)
/usr/bin/upsdrvctl NUT driver control utility
/usr/bin/snmp-ups SNMP UPS driver
/usr/syno/bin/synonotify Synology notification utility

Runtime Files

Path Description
/run/ups_state/ Runtime state directory
/run/ups_state/upsd.pid upsd PID file
/run/upsmon.pid upsmon PID file
/tmp/ups/ Temporary UPS directory
/tmp/ups/ups.lock Lock file for exclusive access
/tmp/upsudevlock udev lock file

USB Device Tables

Path Description
/lib/udev/devicetable/usb.nut-hid USB HID device table for UPS detection
/etc/ups/nutscan-usb.h USB device header for scanning

Quick Reference: synoups.conf Keys

General Settings

Key Values Description
ups_enabled yes / no Enable master mode
upsslave_enabled yes / no Enable slave mode
ups_mode usb / snmp Connection type (default: usb)
upsslave_server IP address Master server IP (slave mode)
ups_wait_time seconds Time on battery before shutdown

SNMP Settings (Master Mode)

Key Values Description
ups_snmp_ip IP address SNMP UPS IP address
ups_snmp_community string SNMP community string
ups_snmp_version v2c / v3 SNMP version (default: v2c)
ups_snmp_mib string MIB to use (default: auto)
ups_snmp_user string SNMPv3 username
ups_snmp_auth yes / no Enable SNMPv3 authentication
ups_snmp_auth_type MD5 / SHA Auth protocol
ups_snmp_auth_key string Auth password
ups_snmp_privacy yes / no Enable SNMPv3 encryption
ups_snmp_privacy_type DES / AES Privacy protocol
ups_snmp_privacy_key string Privacy password

Debug Settings

Key Value Description
upslog file path General log file
upsmon_dbg file path upsmon debug output
upsd_dbg file path upsd debug output
upsdrv_dbg file path Driver debug output
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment