🍳 synology-api-recipes

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

Powered by synology-api — 50+ DSM API endpoints, one pip install.

---

📦 The Full Menu

🩺 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:

1. Fork → Create recipe in the right recipes/category/ folder
2. Use common.py for NAS connection — don't reinvent the auth wheel
3. Add --dry-run support, because trust is earned
4. 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

GPL-3.0-or-later — Copyright © 2025 Renato Visaggio.

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}