{"id":29512969,"url":"https://github.com/zollak/homeassistant-syslog-receiver","last_synced_at":"2025-07-16T12:11:21.334Z","repository":{"id":293252370,"uuid":"983414241","full_name":"zollak/homeassistant-syslog-receiver","owner":"zollak","description":"A Home Assistant integration that receives and filters syslog messages (UDP/TCP/TLS), fires events for automations, and can expose optional sensor entities.","archived":false,"fork":false,"pushed_at":"2025-07-09T10:15:44.000Z","size":37,"stargazers_count":4,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-09T11:26:20.572Z","etag":null,"topics":["event-bus","homeassistant","homeassistant-custom-component","homeassistant-integration","logging","network","syslog","tcp","tls","udp"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zollak.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-14T10:51:51.000Z","updated_at":"2025-07-09T10:15:10.000Z","dependencies_parsed_at":"2025-07-01T16:35:30.186Z","dependency_job_id":"002e3131-c1e0-44a1-8473-f7cc7688e844","html_url":"https://github.com/zollak/homeassistant-syslog-receiver","commit_stats":null,"previous_names":["zollak/homeassistant-syslog-receiver"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/zollak/homeassistant-syslog-receiver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zollak%2Fhomeassistant-syslog-receiver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zollak%2Fhomeassistant-syslog-receiver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zollak%2Fhomeassistant-syslog-receiver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zollak%2Fhomeassistant-syslog-receiver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zollak","download_url":"https://codeload.github.com/zollak/homeassistant-syslog-receiver/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zollak%2Fhomeassistant-syslog-receiver/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265508515,"owners_count":23779166,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["event-bus","homeassistant","homeassistant-custom-component","homeassistant-integration","logging","network","syslog","tcp","tls","udp"],"created_at":"2025-07-16T12:11:17.179Z","updated_at":"2025-07-16T12:11:21.256Z","avatar_url":"https://github.com/zollak.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![version](https://img.shields.io/github/manifest-json/v/zollak/homeassistant-syslog-receiver?filename=custom_components%2Fsyslog_receiver%2Fmanifest.json)](https://github.com/zollak/homeassistant-syslog-receiver/releases/latest)\n[![downloads](https://img.shields.io/github/downloads/zollak/homeassistant-syslog-receiver/total?color=brightgreen)](https://github.com/zollak/homeassistant-syslog-receiver/releases)\n[![stars](https://img.shields.io/github/stars/zollak/homeassistant-syslog-receiver)](https://github.com/zollak/homeassistant-syslog-receiver/stargazers)\n[![issues](https://img.shields.io/github/issues/zollak/homeassistant-syslog-receiver)](https://github.com/zollak/homeassistant-syslog-receiver/issues)\n[![HACS](https://img.shields.io/badge/HACS-Custom-blue.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=zollak\u0026repository=homeassistant-syslog-receiver\u0026category=Integration)\n\n# Syslog Receiver integration for Home Assisstant\n\n[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=zollak\u0026repository=homeassistant-syslog-receiver\u0026category=Integration)\n\nThis is a custom integration for Home Assistant which listens for incoming syslog messages over UDP, TCP, or TLS and can trigger automations via events or expose the messages via sensors.\n\n## Features\n\n- Receive syslog messages over UDP, TCP, or encrypted TCP (TLS)\n- Filter incoming syslog messages based on the source IP address.\n- Filter syslog messages by severity.\n- Fire events on the Home Assistant event bus for automations\n- Optional sensor entity to expose last received message\n- UI-based setup and options flows (no YAML configuration)\n- Comprehensive logging and debugging support\n\n## Installation via HACS\n\n1. Install the [HACS](https://hacs.xyz/) integration if you haven't already.\n2. Go to the HACS store, search for **Syslog Receiver**, or click on the \"Add Repository\" button and add repository URL `https://github.com/zollak/homeassistant-syslog-receiver`.\n3. Download, then **Restart Home Assistant**.\n\n## Configuration\n\n1. Navigate to **Settings \u003e Devices \u0026 Services \u003e Integrations**.\n2. Click **Add Integration**, search for **Syslog Receiver**.\n3. Enter the following fields:\n   - **Instance Name**: A friendly name for this listener (entity name)\n   - **Host**: IP address to bind (e.g., `0.0.0.0`, which means it binds on all interfaces on Home Assisstant server)\n     - Use `::` to bind to all IPv6 interfaces\n     - Avoid using `fe80::...` (link-local) unless you add a scope like `%eth0` For example: `fe80::abcd:1234:5678:9abc%eth0` (with interface name)\n   - **Port**: Port number (e.g., `514`)\n   - **Protocol**: `UDP`, `TCP`, or `TCP+TLS`\n   - **Use TLS**: Enable encrypted connections\n   - **Certfile**: Path to your server certificate (PEM file)\n   - **Keyfile**: Path to your private key (PEM file)\n   - **Allowed IPs**: Comma-separated list of source IPs to accept (e.g., IPv4: `10.10.10.2,10.10.10.3,10.10.10.10`, IPv6: `fe80::1, 2001:db8::42`)\n   - **Minimum Severity**: Syslog priority threshold\n   - **Enable Sensors**: Create a sensor entity for last message\n4. Save to start the syslog listener.\n\n## 🐳 Installation in Docker without HACS\n\nIf you are using Home Assistant Core in a **Docker container without Supervisor**, HACS is not available by default.\n\nTo install this integration manually:\n\n1. Clone this repository or download the latest release ZIP.\n\n2. Copy the folder `custom_components/syslog_receiver` into:\n\n   ```\n   /config/custom_components/syslog_receiver\n   ```\n\n   *(Ensure this path is in your Docker volume mapped to `/config`)*\n\n3. Restart Home Assistant Core.\n\n4. The integration will now be available to add via the UI (Config Flow).\n\nOptional: You can install [HACS manually](https://hacs.xyz/docs/installation/manual/) in Docker-based setups to manage custom integrations through the UI.\n\n### ℹ️ Notes for Docker \u0026 Container Users\n\nIf you run Home Assistant in Docker or similar containerized environments, especially with **MacVLAN**, there are a few important considerations:\n\n- Setting **`Host` to `0.0.0.0`** means \"bind on all available interfaces\". On most systems this works, but in **MacVLAN or strict Docker networks**, `0.0.0.0` may **not resolve to usable interfaces** inside the container.\n- If the syslog receiver does not appear to start or bind (nothing shows on `netstat -anu`), try:\n  1. Setting the **container's actual IP address** in the Host field (e.g., `10.0.0.7`).\n  2. Verifying that the port (e.g., `5514`) is **not used by another container** or service.\n  3. Enabling **debug logging** for the integration to check bind failures.\n\n```yaml\nlogger:\n  logs:\n    custom_components.syslog_receiver: debug\n````\n\n* You can find the container’s IP address using:\n\n  ```bash\n  docker exec -it homeassistant ip a\n  ```\n* Binding to `::` (for IPv6) may also work if your container is dual-stack enabled.\n\nIf the integration log shows:\n\n```text\nCould not bind UDP ('0.0.0.0', 5514): [Errno 99] Cannot assign requested address\n```\n\n…it means the bind failed. Use a valid, reachable IP instead.\n\n## Example Use Cases of Configuration\n\n### IPv4 Support\n\n- **UDP Plain Listener**\n  - Host: `0.0.0.0`\n  - Port: `514`\n  - Protocol: `UDP`\n  - Use TLS: `False`\n\n- **TCP Plain Listener**\n  - Host: `0.0.0.0`\n  - Port: `514`\n  - Protocol: `TCP`\n  - Use TLS: `False`\n\n- **TCP Encrypted (TLS) Listener**\n  - Host: `0.0.0.0`\n  - Port: `6514` (commonly used for TLS syslog)\n  - Protocol: `TCP`\n  - Use TLS: `True`\n  - Certfile/Keyfile: Your TLS certificate and private key paths\n\n- **Multiple Hosts/Subnets**\n  - In **Allowed IPs**, list all source IPs or hosts on your subnet separated by commas:\n    ```text\n    10.10.10.2, 10.10.10.3, 10.10.10.4\n    ```\n  - Currently, subnet masks are not supported; enumerate each IP.\n\n### IPv6 Support\n\nThis integration now supports binding on IPv6 interfaces in addition to IPv4. You can:\n\n* **Bind to all IPv6 interfaces** using `::` as the Host.\n* **Bind to a specific IPv6 address**, like `2001:db8::1234` or `fe80::abcd:1234%eth0`.\n* ❗ If you're using a **link-local IPv6 address** (`fe80::/10`), you **must include a scope** (e.g., `%eth0`) or the integration will fail to bind.\n* If you’re unsure, use `::` to bind all IPv6 interfaces safely on most systems.\n\n* Use both IPv4 and IPv6 simultaneously by using `::` on systems where dual-stack is enabled (i.e., it also accepts IPv4 on the same port).\n* Add **IPv6 source addresses** to the Allowed IPs field (e.g., `fe80::1, 2001:db8::42`).\n\nMake sure your Home Assistant system supports IPv6 binding and the ports used are open in the host firewall.\n\n## TLS Setup\n\n- **Server**: Provide a valid `certfile` and `keyfile` in the integration options. Home Assistant will load them on startup and bind an encrypted listener.\n- **Client**: Configure your device to send syslog over TLS to the Home Assistant host and port. Ensure the client trusts the server certificate (install CA or disable validation).\n\nIf the cert/key are invalid or missing, the integration will log an error and fail to start.\n\n### DTLS (UDP + TLS) Support\n\n- **Not supported**: Native DTLS over UDP is not available in Python’s standard library. This integration can handle:\n  1. **UDP** (plaintext)\n  2. **TCP** (plaintext)\n  3. **TCP + TLS** (encrypted)\n- For **UDP + TLS** (DTLS), a third-party DTLS stack or custom implementation would be required, as the built-in `ssl` module does not provide DTLS.\n\n### 🔐 TLS Certificate Setup\n\nTo securely receive syslog messages using **TCP + TLS**, you must provide a certificate and private key to the Syslog Receiver integration. This allows the server to authenticate itself to clients (your syslog sources) and encrypt the connection.\n\n#### 1. Generate a Self-Signed TLS Certificate (for testing/demo)\n\nUse `openssl` to generate a private key and self-signed certificate valid for 365 days:\n\n```bash\nopenssl req -x509 -newkey rsa:2048 -keyout tls_key.pem -out tls_cert.pem -days 365 -nodes -subj \"/CN=syslog.local\"\n```\n\nThis creates two files:\n\n* `tls_key.pem` – your **private key**\n* `tls_cert.pem` – your **self-signed certificate**\n\nYou can rename these if desired.\n\n\u003e 🧪 Note: Self-signed certificates are sufficient for local testing but may cause trust issues on syslog clients unless you disable certificate verification or import the CA.\n\n---\n\n#### 2. Store the Cert \u0026 Key in Home Assistant\n\n* **Recommended Location:** Place the `.pem` files in your Home Assistant configuration directory (e.g., `/config/ssl/`).\n\n  Example:\n\n  ```bash\n  mkdir -p /config/ssl/syslog\n  mv tls_cert.pem tls_key.pem /config/ssl/syslog/\n  ```\n\n* In the integration configuration:\n\n  * **Certfile:** `/config/ssl/syslog/tls_cert.pem`\n  * **Keyfile:** `/config/ssl/syslog/tls_key.pem`\n\n\u003e 💡 Home Assistant maps `/config` to the internal config folder even in Docker or supervised installs.\n\n---\n\n#### 3. Configure the Syslog Client (Your Device)\n\nOn the sending device (NAS, router, Linux server, etc.), configure it to:\n\n* Use **TCP or TLS** protocol.\n* Point to the **IP address of your Home Assistant server**.\n* Use the **same port number** configured in the Syslog Receiver integration (e.g., 6514).\n* **Trust the certificate** (if possible) or disable verification.\n\n**Example (Linux with rsyslog):**\nEdit `/etc/rsyslog.conf` or a custom file under `/etc/rsyslog.d/`:\n\n```bash\n# Forward all logs to HA via TLS\n*.* @@(o)192.168.1.100:6514\n```\n\n* `@@` = means TCP.\n* `(o)` = means TLS with **optional** certificate validation\n* Replace `192.168.1.100` with your Home Assistant IP address.\n* Replace `6514` with your configured port.\n\nFor stricter verification:\n\n```bash\n*.* @@(o):192.168.1.100:6514;RSYSLOG_SyslogProtocol23Format\n```\n\n---\n\n#### 4. Troubleshooting TLS\n\n* If the certificate or key is missing or invalid, Home Assistant will log:\n\n  ```\n  Failed to load TLS cert/key: ...\n  ```\n* If clients cannot connect:\n\n  * Confirm port is open and reachable.\n  * Check firewall and container networking.\n  * Verify matching protocol and IP versions (IPv4 vs IPv6).\n\n---\n\n#### 🔁 Using Let's Encrypt (optional)\n\nIf you already use Let's Encrypt or another ACME client:\n\n* Reuse the cert/key from `/ssl/fullchain.pem` and `/ssl/privkey.pem`.\n* Set those paths in the Syslog Receiver integration settings.\n\n\u003e ⚠️ Be sure those files are readable by Home Assistant and have a valid domain (CN) matching what your client expects.\n\n---\n\n## Usage\n\nOnce configured, you can listen for `syslog_received` events:\n\n- Listen for events `syslog_receiver_message` in automations:\n\n  ```yaml\n  trigger:\n    platform: event\n    event_type: syslog_receiver_message\n  action:\n    # use event.data.message, event.data.source_ip, event.data.severity\n  ```\n\n---\n\n### ✅ 1. Automation example: notify on critical syslog errors\n\n```yaml\ntrigger:\n  platform: event\n  event_type: syslog_receiver_message\ncondition:\n  condition: template\n  value_template: \"{{ trigger.event.data.severity \u003c= 2 }}\"\naction:\n  service: notify.mobile_app\n  data:\n    title: \"[SYSLOG ERROR] {{ trigger.event.data.source_ip }}\"\n    message: \"{{ trigger.event.data.message }}\"\n```\n---\n\n### ✅ 2. Log all messages from a specific device to file\n\n```yaml\nalias: \"Log NAS syslog to file\"\ntrigger:\n  platform: event\n  event_type: syslog_receiver_message\ncondition:\n  condition: template\n  value_template: \"{{ trigger.event.data.source_ip == '10.10.10.50' }}\"\naction:\n  - service: system_log.write\n    data:\n      level: info\n      message: \"NAS syslog: {{ trigger.event.data.message }}\"\n```\n\n---\n\n### ✅ 3. Send a persistent notification for login attempts\n\n```yaml\nalias: \"Notify on SSH login attempt\"\ntrigger:\n  platform: event\n  event_type: syslog_receiver_message\ncondition:\n  - condition: template\n    value_template: \u003e-\n      \"sshd\" in trigger.event.data.message and (\n      \"Accepted password\" in trigger.event.data.message or\n      \"Accepted publickey\" in trigger.event.data.message)\naction:\n  - service: persistent_notification.create\n    data:\n      title: \"SSH Login Detected\"\n      message: \u003e-\n        From {{ trigger.event.data.source_ip }}:\n        {{ trigger.event.data.message }}\n```\n\n---\n\n### ✅ 4. Create a scene trigger for router firewall rule changes\n\n```yaml\nalias: \"Firewall Rule Changed\"\ntrigger:\n  platform: event\n  event_type: syslog_receiver_message\ncondition:\n  condition: template\n  value_template: \u003e\n    \"filter rule changed\" in trigger.event.data.message\naction:\n  - service: script.turn_on\n    target:\n      entity_id: script.notify_admin_change\n```\n\n---\n\n### ✅ 5. Turn on a light if a physical door sensor logs a state\n\n```yaml\nalias: \"Trigger light on syslog motion\"\ntrigger:\n  platform: event\n  event_type: syslog_receiver_message\ncondition:\n  condition: template\n  value_template: \u003e\n    \"Motion detected\" in trigger.event.data.message\n    and trigger.event.data.source_ip == \"192.168.1.99\"\naction:\n  - service: light.turn_on\n    target:\n      entity_id: light.garden_spotlight\n```\n\n---\n\n### ✅ 6. Exclude debug messages from database (via sensor)\n\nIf you're using the optional sensor, you may want to exclude low-severity updates in `recorder:` config:\n\n```yaml\nrecorder:\n  exclude:\n    entity_globs:\n      - sensor.syslog_receiver_*\n  # or keep it but purge quickly:\n  purge_keep_days: 3\n```\n\n---\n\n### ✅ 7. Enable the sensor in the integration options to add `sensor.syslog_receiver_\u003centry_id\u003e`.\n\n---\n\n## Logging\n\nSet Home Assistant logger level for `custom_components.syslog_receiver` to `debug` for detailed logs.\n\n## Storage Considerations\n\nEnabling the sensor for each syslog receiver instance creates a Home Assistant sensor entity that updates its state with every received message. Depending on volume, this can generate large amounts of state history and impact your database size and performance:\n\n- **High-frequency logs** (e.g., dozens per second) will rapidly fill the recorder database with state changes.\n- **Retention**: Adjust `recorder:` settings in `configuration.yaml` to limit history retention (e.g., `purge_keep_days`) or exclude the sensor entity entirely.\n- **Alternatives**: If you only need event-based actions, consider leaving sensors disabled and using automations triggered on `syslog_receiver_message` events instead.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for more details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzollak%2Fhomeassistant-syslog-receiver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzollak%2Fhomeassistant-syslog-receiver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzollak%2Fhomeassistant-syslog-receiver/lists"}