🍳 synology-api-recipes

May 30, 2026 · View on GitHub

Production-ready Python recipes for Synology NAS automation — disk health, Docker, media, security. Powered by synology-api.

Your NAS runs 24/7. Might as well make it do something useful besides eating electricity.

Stop copy-pasting scripts from socials and forums threads from 2019. synology-api-recipes is the cookbook for Synology NAS automation — ready-to-run Python scripts that solve actual problems. Each recipe is tested against real API methods, won't crash on import, and doesn't require a PhD in DSM internals.

😫 The Problem

Your Synology NAS is the most reliable device in your house. It has never crashed. It has never complained. It just... sits there. Meanwhile:

Disks accumulate SMART errors in total silence until one day — click click click — and your Plex library is gone
Docker containers run images from 2022 because "if it ain't broke" (it's broke, you just don't know it yet)
Someone in Belarus is trying admin/admin 300 times a day and DSM is like "this is fine"
SSL certificates expire and suddenly your entire family group chat is asking why Nextcloud is down
That 4TB "Misc" shared folder has permissions set to "Everyone: Read/Write" because you were tired that one Tuesday in 2023

You don't need to become a sysadmin. You just need a few good scripts.

🍕 The Solution

26 recipes. 9 categories. One .env file. Zero excuses.

Each recipe is:

Actually tested — every method call verified against the real synology-api
Plug & play — one config file, one command, go touch grass
Telegram-native — alerts land in your pocket, not in a log file you'll never read
Cron-friendly — built for crontab -e, not for interactive tinkering

🩺 Monitoring (4 recipes)

Recipe	Pitch
`disk_health_alert.py`	SMART, temperature, bad sectors. Alerts BEFORE the click of death.
`storage_usage_alert.py`	Volume usage alerts. "95% full" is not a good surprise at 2 AM.
`container_monitor.py`	Watches Docker containers, restarts crash victims, judges your uptime.
`package_update_checker.py`	Lists pending DSM package updates you've been ignoring since 2023.

🐳 Docker (2 recipes)

Recipe	Pitch
`auto_update_containers.py`	Checks registry for newer images, restarts containers. Manual pull still required — DSM Docker, am I right?
`container_updater.py`	Exports container configs, checks resource usage, generates update reports.

📁 Storage (3 recipes)

Recipe	Pitch
`disk_health_monitor.py`	Tracks every disk, alerts on warning signs. Your data deserves better than hope.
`smart_recycle_bin.py`	Per-folder retention. Downloads: 7 days. Documents: forever (you hoarder).
`orphaned_files_finder.py`	Finds files belonging to deleted users, in folders that shouldn't exist. Digital archaeology.

🎬 Media (3 recipes)

Recipe	Pitch
`media_library_sync.py`	Detects Movies vs TV, creates Plex folder structure, moves files. Stop manually renaming `Show.Name.S01E05.1080p.AMZN.WEB-DL.DDP5.1.H264-NTb.mkv`.
`download_organizer.py`	Watches completed downloads, renames, sorts. Your Downloads folder will finally know peace.
`photo_organizer.py`	Sorts photos by date into folders. Your 4,712 cat photos will be beautifully organized.

🔐 Security (4 recipes)

Recipe	Pitch
`login_monitor.py`	Failed login monitoring with GeoIP. Knows when Belarus is knocking.
`security_audit_report.py`	Weekly security report. Because audits sound professional and make you feel important.
`shared_folder_audit.py`	Finds folders open to "Everyone". Spots the Tuesday 2023 mistakes.
`user_inactivity_report.py`	Finds accounts that haven't logged in since the Before Times. Time for a cleanup.

📸 Surveillance (2 recipes)

Recipe	Pitch
`camera_health_check.py`	Checks all cameras are connected and recording. Because the one day you skip is the day something happens.
`camera_snapshot_backup.py`	Takes snapshots from all cameras. Prove to your neighbor their cat IS on your roof.

🔒 Certificate (1 recipe)

Recipe	Pitch
`certificate_monitor.py`	Warns 30/14/7 days before SSL certs expire. Avoids the 3 AM panic.

☁️ Cloud & Drive (2 recipes)

Recipe	Pitch
`cloud_sync_monitor.py`	Checks Cloud Sync connections. Because "it's syncing" is tech's greatest lie.
`drive_admin_report.py`	Synology Drive usage stats. See who actually uses it (spoiler: one person).

🖥️ Virtualization & VPN (2 recipes)

Recipe	Pitch
`vm_status_monitor.py`	Checks VMM guests. VMs crash at 3 AM Saturday — at least now you'll know.
`vpn_client_monitor.py`	Lists VPN connections. Find out who gave cousin Mario access.

🎵 Audio & More (3 recipes)

Recipe	Pitch
`audio_playlist_backup.py`	Lists Audio Station playlists. One day you WILL click Delete on the wrong one.
`photo_album_stats.py`	Synology Photos stats. Exactly 4,712 cat photos. You're welcome.
`auto_usb_backup.py`	Detects USB drives, creates backup folders. Because you WILL forget to copy those photos from your camera.

📥 Downloads (2 recipes)

Recipe	Pitch
`download_notifier.py`	Alerts when downloads complete. So you can watch that Linux ISO immediately.
`cleanup_old_downloads.py`	Removes old completed downloads. Your NAS has feelings too.

⚡ 60-Second Quick Start

# 1. Clone
git clone https://github.com/N4S4/synology-api-recipes.git
cd synology-api-recipes

# 2. Install
pip install -r requirements.txt

# 3. Configure (set your NAS password + optional Telegram)
cp .env.example .env
nano .env

# 4. Run your first recipe (dry run — totally safe)
python recipes/monitoring/disk_health_alert.py --dry-run

# 5. Add to cron
crontab -e
# Every morning at 8:
0 8 * * * cd /opt/synology-api-recipes && python recipes/monitoring/disk_health_alert.py

⚙️ Configuration

One file. Five minutes. Done forever.

# Required — your NAS
NAS_IP=192.168.1.2
NAS_PORT=5001
NAS_USERNAME=your_admin_user
NAS_PASSWORD=your_actual_password_no_really

# Optional — Telegram alerts (create a bot with @BotFather in 2 min)
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghikl
TELEGRAM_CHAT_ID=159718277

# Optional — Recipe customization
RECYCLE_POLICY=downloads:7,documents:30,media:14
DOCKER_SKIP_CONTAINERS=portainer,watchtower

Security note: Your .env file is gitignored. Don't commit it. Don't share it. Don't screenshot it. We've all been there.

📁 Project Layout

synology-api-recipes/
├── recipes/
│   ├── common.py                 # NAS connection, Telegram, utilities
│   ├── monitoring/               # 4 recipes
│   │   ├── disk_health_alert.py
│   │   ├── storage_usage_alert.py
│   │   ├── container_monitor.py
│   │   └── package_update_checker.py
│   ├── docker/                   # 2 recipes
│   │   ├── auto_update_containers.py
│   │   └── container_updater.py
│   ├── storage/                  # 3 recipes
│   │   ├── disk_health_monitor.py
│   │   ├── recycle_bin_cleaner.py
│   │   └── storage_usage_alert.py
│   ├── media/                    # 3 recipes
│   │   ├── download_organizer.py
│   │   ├── media_library_sync.py
│   │   ├── photo_organizer.py
│   │   └── photo_album_stats.py
│   ├── security/                 # 4 recipes
│   │   ├── login_monitor.py
│   │   ├── security_audit_report.py
│   │   ├── shared_folder_audit.py
│   │   └── user_inactivity_report.py
│   ├── surveillance/             # 2 recipes
│   │   ├── camera_health_check.py
│   │   └── camera_snapshot_backup.py
│   ├── certificate/              # 1 recipe
│   │   └── certificate_monitor.py
│   ├── downloads/                # 2 recipes
│   │   ├── download_notifier.py
│   │   └── cleanup_old_downloads.py
│   ├── backup/                   # 2 recipes
│   │   ├── auto_usb_backup.py
│   │   └── snapshot_scheduler.py
│   ├── cloud/                    # 1 recipe
│   │   └── cloud_sync_monitor.py
│   ├── drive/                    # 1 recipe
│   │   └── drive_admin_report.py
│   ├── virtualization/           # 1 recipe
│   │   └── vm_status_monitor.py
│   ├── vpn/                      # 1 recipe
│   │   └── vpn_client_monitor.py
│   ├── audio/                    # 1 recipe
│   │   └── audio_playlist_backup.py
│   └── orphaned/                 # 1 recipe
│       └── orphaned_files_finder.py
├── .env.example
├── requirements.txt
├── LICENSE
├── CONTRIBUTING.md
└── README.md                     # You are here. Hi.

🤝 Contributing

Got a script that saved your weekend? Share it. This cookbook runs on community contributions and mild procrastination.

The short version:

Fork → Create recipe in the right recipes/category/ folder
Use common.py for NAS connection — don't reinvent the auth wheel
Add --dry-run support, because trust is earned
Open a PR → We'll review, maybe laugh at your variable names, merge

See CONTRIBUTING.md for the full guide. Yes, there's a guide. We're that kind of project.

🧱 Built On

synology-api — 50+ DSM API modules, one wrapper
python-dotenv — .env files for people who don't want to hardcode passwords
requests — HTTP for humans, also used by the Telegram webhook fallback

⚠️ Known Limitations (a.k.a. "It's not a bug, it's DSM")

Some recipes require specific DSM packages installed on your NAS. If a recipe fails:

Docker recipes → Docker package must be installed
Surveillance recipes → Surveillance Station package required
Cloud Sync / Drive → Cloud Sync or Synology Drive package required
Security Advisor / Log Center → Those packages must be active
Some System APIs → Require admin-level privileges (not all work with limited accounts)

The scripts handle missing packages gracefully — they'll tell you what's missing instead of crashing. Mostly.

📄 License

Free as in freedom. Use it, modify it, share it. Just keep it open.

Built with ☕ and mild sleep deprivation
_{by @N4S4 and contributors who also have NAS devices they probably should check on more often}