aiosynologysrm

PyPI	Python	Release Date	Downloads

CI	License	Typed	Issues	Discussions

A Python library that reads what your Synology router knows: its own state, the devices on your network, and over time DHCP, Wi-Fi, firewall and more. It talks to the router's Web API (Synology Router Manager, SRM) and never changes a setting.

It is built as a foundation for integrations such as Home Assistant, but works in any asyncio program.

Unofficial. Not affiliated with, endorsed by or supported by Synology Inc. "Synology" and "SRM" are trademarks of Synology Inc.

Table of contents

• Why this library?
• Which devices work?
• Quick start
• Certificate and two-factor authentication
• What it can read
• Diagnostics
• Errors
• Documentation
• Contributing
• License

Why this library?

synology-srm by aerialls pioneered Python access to SRM and is what Home Assistant's built-in integration uses. It is synchronous and has not changed since 2023. This library starts fresh for today's needs:

Which devices work?

Router and standalone access point are tested; mesh setups are in scope but not tested yet (help wanted). If the router lacks a feature, the library raises SrmUnsupportedError instead of guessing. Details and how to report your model: docs/compatibility.md.

Quick start

You need Python 3.12 or newer and an SRM administrator account (SRM's Web API only answers administrators; a dedicated account for your integration is a good idea).

The library only reads, but the account it uses can change everything on the router: keep the password safe, and prefer certificate pinning over ssl=False (see below). Each failed login counts towards SRM's auto block; after one, the client stops logging in by itself until you call login() again.

pip install aiosynologysrm

import asyncio

import aiohttp

from aiosynologysrm import SrmClient

# SRM ships a self-signed certificate: pin its fingerprint (see "Certificate" below for how to
# read it once and confirm it).
FINGERPRINT = "<the router's SHA-256 fingerprint, hex>"


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with SrmClient(
            "192.0.2.1",
            "admin-user",
            "secret",
            session=session,
            ssl=aiohttp.Fingerprint(bytes.fromhex(FINGERPRINT)),
        ) as client:
            info = await client.get_system_info()
            print(info.model, info.firmware_ver)

            devices = await client.get_network_devices()
            for device in devices.devices:
                if device.is_online:
                    print(device.mac, device.hostname, device.connection)


asyncio.run(main())

Certificate and two-factor authentication

SRM ships a self-signed certificate, so the default ssl=True rejects it. Instead of switching verification off, pin the certificate: fetch its fingerprint once, let the user confirm it, store it and pass it on every connection.

from aiosynologysrm import get_certificate_fingerprint

fingerprint = await get_certificate_fingerprint("192.0.2.1")  # SHA-256, lowercase hex
client = SrmClient(..., ssl=aiohttp.Fingerprint(bytes.fromhex(fingerprint)))

A renewed certificate then raises SrmCertificateError until the new fingerprint is confirmed. ssl also takes False or an ssl.SSLContext. ssl=True uses the aiohttp session's own setting, so with a session that does not verify certificates nothing is checked; pin a fingerprint or pass an SSLContext instead.

Two-factor authentication works for interactive use only: otp_code is sent with the first login and never again. When the session ends, the next login raises SrmTwoFactorRequiredError and needs a fresh code. For unattended use (Home Assistant, scripts), create a dedicated administrator account without two-factor authentication.

What it can read

Each getter sends one SRM call and returns its answer as a typed model. Field names are SRM's own keys in snake_case, including SRM's spelling (is_baned), so SRM's documentation and the web interface's requests map 1:1. Values keep SRM's units and formats; raw holds the complete object.

Anything derived is in aiosynologysrm.helpers, kept apart from the models on purpose: locate_clients() tells for each client which router or access point it is attached to, by Wi-Fi (which radio) or cable, from the lists of several devices; the classification of an address (address_scope: public, private, carrier-grade NAT), summed hit counters per rule (hits_by_rule), radio settings paired with their live state (pair_radios), durations and dates from SRM's text (up_time, lease_remaining, firmware_date), used space, and config_hash() to detect configuration changes from the models' raw.

See the changelog for what each release adds.

Diagnostics

aiosynologysrm-diagnostics <router> --user <admin> (or python -m aiosynologysrm.diagnostics) prints a JSON report to paste into an issue. It contains exactly this:

• library version, router model, SRM version, operating mode
• whether the WAN IPv4 address is public, private or cgnat (the category, not the address)
• the minimum and maximum version of each API the library uses
• for every getter: whether it works or which error code it returned, how many items it returned (leave this out with --no-counts), the type of every field (str, int, None, ...) and how many keys SRM sent that the library does not map yet (only the number, never the names)

It contains no addresses, host names, network names or other values. GitHub issues in a public repository are always public, so read the output before posting it. The password comes from SRM_PASSWORD or a prompt; an unknown certificate is shown for confirmation. Applications can call aiosynologysrm.diagnostics.collect_diagnostics(client).

When a value itself matters, for example a field the library parses wrongly, turn the raw answer into a fixture with scripts/anonymize.py (see CONTRIBUTING.md) and attach that.

Errors

Every error from talking to the router derives from SrmError; wrong arguments raise ValueError (an invalid host) or TypeError (supports() with something that is not a getter).

After a failed login (authentication, 2FA, blocked) the client sends no further logins until login() is called, so polling cannot run into SRM's auto block. Each request has its own timeout; one read can chain catalog, login and a retry, so wrap a whole update in asyncio.timeout() if it must finish in a fixed time.

Error messages never contain passwords or session data, so they are safe to log.

Documentation

• Compatibility: devices, firmware, modes, how support is decided
• Design: how the library stays read-only, sessions, versions, privacy

Contributing

Reports with your router model and SRM version help most. See CONTRIBUTING.md; for security issues SECURITY.md.

License

MIT. Provided "as is", without warranty of any kind. The icon and header images are CC BY 4.0; their source is in eizedev/brand.