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
• 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, mesh point and standalone access point are all supported modes. If the router lacks a feature, the library says so 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).

pip install aiosynologysrm

import asyncio

import aiohttp

from aiosynologysrm import SrmClient


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with SrmClient(
            "192.0.2.1",
            "admin-user",
            "secret",
            session=session,
            ssl=False,  # SRM ships a self-signed certificate; better: pin it, see below
        ) as client:
            info = await client.get_system_info()
            print(info.model, info.firmware_version)

            devices = await client.get_network_devices()
            for device in devices.devices:
                if device.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.

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

FirewallRules and SecuritySettings have a fingerprint property: a hash without hit counters, so you can detect configuration changes without comparing field by field. For any other list, aiosynologysrm.fingerprint(item.raw for item in items) gives the same kind of hash.

See the changelog for what each release adds.

Errors

Every error derives from SrmError. The ones you will meet most:

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.