homeassistant-syslog-receiver

KO | EN

gitlite — search

#python #ai #typescript #golang #docker #macos #nodejs #windows #awesome #kubernetes #vue #security #ios #open-source

homeassistant-syslog-receiver

(★ 18)

A Home Assistant integration that receives and filters syslog messages (UDP/TCP/TLS), fires events for automations, and can expose optional sensor entities.

homeassistant-syslog-receiver Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![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)
[![downloads](https://img.shields.io/github/downloads/zollak/homeassistant-syslog-receiver/total?color=brightgreen)](https://github.com/zollak/homeassistant-syslog-receiver/releases)
[![stars](https://img.shields.io/github/stars/zollak/homeassistant-syslog-receiver)](https://github.com/zollak/homeassistant-syslog-receiver/stargazers)
[![issues](https://img.shields.io/github/issues/zollak/homeassistant-syslog-receiver)](https://github.com/zollak/homeassistant-syslog-receiver/issues)
[![HACS](https://img.shields.io/badge/HACS-Custom-orange.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=zollak&repository=homeassistant-syslog-receiver&category=Integration)
[![Community Forum](https://img.shields.io/static/v1.svg?label=Community&message=Forum&color=41bdf5&logo=HomeAssistant&logoColor=white)](https://community.home-assistant.io/t/introducing-syslog-receiver-a-new-hacs-integration-for-ingesting-syslog-into-home-assistant)

# Syslog Receiver integration for Home Assisstant

[![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&repository=homeassistant-syslog-receiver&category=Integration)

This 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.

## Features

- Receive syslog messages over UDP, TCP, or encrypted TCP (TLS)
- Filter incoming syslog messages based on the source IP address.
- Filter syslog messages by severity.
- Fire events on the Home Assistant event bus for automations
- Optional sensor entity to expose last received message
- UI-based setup and options flows (no YAML configuration)
- Comprehensive logging and debugging support

## Installation via HACS

1. Install the [HACS](https://hacs.xyz/) integration if you haven't already.
2. 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`.
3. Download, then **Restart Home Assistant**.

## Configuration

1. Navigate to **Settings > Devices & Services > Integrations**.
2. Click **Add Integration**, search for **Syslog Receiver**.
3. Enter the following fields:
   - **Instance Name**: A friendly name for this listener (entity name)
   - **Host**: IP address to bind (e.g., `0.0.0.0`, which means it binds on all interfaces on Home Assisstant server)
     - Use `::` to bind to all IPv6 interfaces
     - Avoid using `fe80::...` (link-local) unless you add a scope like `%eth0` For example: `fe80::abcd:1234:5678:9abc%eth0` (with interface name)
   - **Port**: Port number (e.g., `514`)
   - **Protocol**: `UDP`, `TCP`, or `TCP+TLS`
   - **Use TLS**: Enable encrypted connections
   - **Certfile**: Path to your server certificate (PEM file)
   - **Keyfile**: Path to your private key (PEM file)
   - **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`)
   - **Minimum Severity**: Syslog priority threshold
   - **Enable Sensors**: Create a sensor entity for last message
4. Save to start the syslog listener.

## 🔤 Configurable Encoding Support

Some devices send syslog messages using encodings other than the default UTF-8. To ensure compatibility, this integration allows you to choose from a list of common encodings, or specify a custom one.

### Available Options

When configuring a syslog receiver instance (either during initial setup or later via the "Reconfigure" option), you can select from:

* `utf-8` (default)
* `latin1`
* `windows-1252`
* `ascii`
* `utf-16`
* `gbk`
* `big5`
* `Other…` – for entering a custom encoding manually (e.g. `cp1251`, `shift_jis`, etc.)

> 💡 If a custom encoding is set via the `"Other..."` option, it will be remembered and automatically added to the list the next time you open the configuration UI.

### How It Works

* Messages are decoded using the selected encoding.
* If decoding fails or the encoding is unknown, the system will **fall back to UTF-8** or system default using `errors="replace"` to avoid crashes.

### Example Use Case

If you're receiving garbled (like this `�` character) or unreadable messages in Home Assistant, try switching to a more appropriate encoding like `windows-1252` or `latin-1`. Many legacy networking devices (including some switches, routers, or printers) default to non-UTF encodings.

## 🐳 Installation in Docker without HACS

If you are using Home Assistant Core in a **Docker container without Supervisor**, HACS is not available by default.

To install this integration manually:

1. Clone this repository or download the latest release ZIP.

2. Copy the folder `custom_components/syslog_receiver` into:

```
   /config/custom_components/syslog_receiver
   ```

*(Ensure this path is in your Docker volume mapped to `/config`)*

3. Restart Home Assistant Core.

4. The integration will now be available to add via the UI (Config Flow).

Optional: You can install [HACS manually](https://hacs.xyz/docs/installation/manual/) in Docker-based setups to manage custom integrations through the UI.

### ℹ️ Notes for Docker & Container Users

If you run Home Assistant in Docker or similar containerized environments, especially with **MacVLAN**, there are a few important considerations:

- 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.
- If the syslog receiver does not appear to start or bind (nothing shows on `netstat -anu`), try:
  1. Setting the **container's actual IP address** in the Host field (e.g., `10.0.0.7`).
  2. Verifying that the port (e.g., `5514`) is **not used by another container** or service.
  3. Enabling **debug logging** for the integration to check bind failures.

```yaml
logger:
  logs:
    custom_components.syslog_receiver: debug
````

* You can find the container’s IP address using:

```bash
  docker exec -it homeassistant ip a
  ```
* Binding to `::` (for IPv6) may also work if your container is dual-stack enabled.

If the integration log shows:

```text
Could not bind UDP ('0.0.0.0', 5514): [Errno 99] Cannot assign requested address
```

…it means the bind failed. Use a valid, reachable IP instead.

## Example Use Cases of Configuration

### IPv4 Support

- **UDP Plain Listener**
  - Host: `0.0.0.0`
  - Port: `514`
  - Protocol: `UDP`
  - Use TLS: `False`

- **TCP Plain Listener**
  - Host: `0.0.0.0`
  - Port: `514`
  - Protocol: `TCP`
  - Use TLS: `False`

- **TCP Encrypted (TLS) Listener**
  - Host: `0.0.0.0`
  - Port: `6514` (commonly used for TLS syslog)
  - Protocol: `TCP`
  - Use TLS: `True`
  - Certfile/Keyfile: Your TLS certificate and private key paths

- **Multiple Hosts/Subnets**
  - In **Allowed IPs**, list all source IPs or hosts on your subnet separated by commas:
    ```text
    10.10.10.2, 10.10.10.3, 10.10.10.4
    ```
  - Currently, subnet masks are not supported; enumerate each IP.

### IPv6 Support

This integration now supports binding on IPv6 interfaces in addition to IPv4. You can:

* **Bind to all IPv6 interfaces** using `::` as the Host.
* **Bind to a specific IPv6 address**, like `2001:db8::1234` or `fe80::abcd:1234%eth0`.
* ❗ 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.
* If you’re unsure, use `::` to bind all IPv6 interfaces safely on most systems.

* 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).
* Add **IPv6 source addresses** to the Allowed IPs field (e.g., `fe80::1, 2001:db8::42`).

Make sure your Home Assistant system supports IPv6 binding and the ports used are open in the host firewall.

## TLS Setup

- **Server**: Provide a valid `certfile` and `keyfile` in the integration options. Home Assistant will load them on startup and bind an encrypted listener.
- **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).

If the cert/key are invalid or missing, the integration will log an error and fail to start.

### DTLS (UDP + TLS) Support

- **Not supported**: Native DTLS over UDP is not available in Python’s standard library. This integration can handle:
  1. **UDP** (plaintext)
  2. **TCP** (plaintext)
  3. **TCP + TLS** (encrypted)
- 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.

### 🔐 TLS Certificate Setup

To 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.

#### 1. Generate a Self-Signed TLS Certificate (for testing/demo)

Use `openssl` to generate a private key and self-signed certificate valid for 365 days:

```bash
openssl req -x509 -newkey rsa:2048 -keyout tls_key.pem -out tls_cert.pem -days 365 -nodes -subj "/CN=syslog.local"
```

This creates two files:

* `tls_key.pem` – your **private key**
* `tls_cert.pem` – your **self-signed certificate**

You can rename these if desired.

> 🧪 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.

---

#### 2. Store the Cert & Key in Home Assistant

* **Recommended Location:** Place the `.pem` files in your Home Assistant configuration directory (e.g., `/config/ssl/`).

Example:

```bash
  mkdir -p /config/ssl/syslog
  mv tls_cert.pem tls_key.pem /config/ssl/syslog/
  ```

* In the integration configuration:

* **Certfile:** `/config/ssl/syslog/tls_cert.pem`
  * **Keyfile:** `/config/ssl/syslog/tls_key.pem`

> 💡 Home Assistant maps `/config` to the internal config folder even in Docker or supervised installs.

---

#### 3. Configure the Syslog Client (Your Device)

On the sending device (NAS, router, Linux server, etc.), configure it to:

* Use **TCP or TLS** protocol.
* Point to the **IP address of your Home Assistant server**.
* Use the **same port number** configured in the Syslog Receiver integration (e.g., 6514).
* **Trust the certificate** (if possible) or disable verification.

**Example (Linux with rsyslog):**
Edit `/etc/rsyslog.conf` or a custom file under `/etc/rsyslog.d/`:

```bash
# Forward all logs to HA via TLS
*.* @@(o)192.168.1.100:6514
```

* `@@` = means TCP.
* `(o)` = means TLS with **optional** certificate validation
* Replace `192.168.1.100` with your Home Assistant IP address.
* Replace `6514` with your configured port.

For stricter verification:

```bash
*.* @@(o):192.168.1.100:6514;RSYSLOG_SyslogProtocol23Format
```

---

#### 4. Troubleshooting TLS

* If the certificate or key is missing or invalid, Home Assistant will log:

```
  Failed to load TLS cert/key: ...
  ```
* If clients cannot connect:

* Confirm port is open and reachable.
  * Check firewall and container networking.
  * Verify matching protocol and IP versions (IPv4 vs IPv6).

---

#### 🔁 Using Let's Encrypt (optional)

If you already use Let's Encrypt or another ACME client:

* Reuse the cert/key from `/ssl/fullchain.pem` and `/ssl/privkey.pem`.
* Set those paths in the Syslog Receiver integration settings.

> ⚠️ Be sure those files are readable by Home Assistant and have a valid domain (CN) matching what your client expects.

---

## Usage

Once configured, you can listen for `syslog_receiver_message` events:

- Listen for events `syslog_receiver_message` in automations:

```yaml
  trigger:
    platform: event
    event_type: syslog_receiver_message
  action:
    # use event.data.message, event.data.source_ip, event.data.severity
  ```

---

### ✅ 1. Automation example: notify on critical syslog errors

```yaml
trigger:
  platform: event
  event_type: syslog_receiver_message
condition:
  condition: template
  value_template: "{{ trigger.event.data.severity <= 2 }}"
action:
  service: notify.mobile_app
  data:
    title: "[SYSLOG ERROR] {{ trigger.event.data.source_ip }}"
    message: "{{ trigger.event.data.message }}"
```
---

### ✅ 2. Log all messages from a specific device to file

```yaml
alias: "Log NAS syslog to file"
trigger:
  platform: event
  event_type: syslog_receiver_message
condition:
  condition: template
  value_template: "{{ trigger.event.data.source_ip == '10.10.10.50' }}"
action:
  - service: system_log.write
    data:
      level: info
      message: "NAS syslog: {{ trigger.event.data.message }}"
```

---

### ✅ 3. Send a persistent notification for login attempts

```yaml
alias: "Notify on SSH login attempt"
trigger:
  platform: event
  event_type: syslog_receiver_message
condition:
  - condition: template
    value_template: >-
      "sshd" in trigger.event.data.message and (
      "Accepted password" in trigger.event.data.message or
      "Accepted publickey" in trigger.event.data.message)
action:
  - service: persistent_notification.create
    data:
      title: "SSH Login Detected"
      message: >-
        From {{ trigger.event.data.source_ip }}:
        {{ trigger.event.data.message }}
```

---

### ✅ 4. Create a scene trigger for router firewall rule changes

```yaml
alias: "Firewall Rule Changed"
trigger:
  platform: event
  event_type: syslog_receiver_message
condition:
  condition: template
  value_template: >
    "filter rule changed" in trigger.event.data.message
action:
  - service: script.turn_on
    target:
      entity_id: script.notify_admin_change
```

---

### ✅ 5. Turn on a light if a physical door sensor logs a state

```yaml
alias: "Trigger light on syslog motion"
trigger:
  platform: event
  event_type: syslog_receiver_message
condition:
  condition: template
  value_template: >
    "Motion detected" in trigger.event.data.message
    and trigger.event.data.source_ip == "192.168.1.99"
action:
  - service: light.turn_on
    target:
      entity_id: light.garden_spotlight
```

---

### ✅ 6. Exclude debug messages from database (via sensor)

If you're using the optional sensor, you may want to exclude low-severity updates in `recorder:` config:

```yaml
recorder:
  exclude:
    entity_globs:
      - sensor.syslog_receiver_*
  # or keep it but purge quickly:
  purge_keep_days: 3
```

---

### ✅ 7. Enable the sensor in the integration options to add `sensor.syslog_receiver_<entry_id>`.

---

## Logging

Set Home Assistant logger level for `custom_components.syslog_receiver` to `debug` for detailed logs.

## Storage Considerations

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

- **High-frequency logs** (e.g., dozens per second) will rapidly fill the recorder database with state changes.
- **Retention**: Adjust `recorder:` settings in `configuration.yaml` to limit history retention (e.g., `purge_keep_days`) or exclude the sensor entity entirely.
- **Alternatives**: If you only need event-based actions, consider leaving sensors disabled and using automations triggered on `syslog_receiver_message` events instead.

## License

This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for more details.

homeassistant-syslog-receiver

homeassistant-syslog-receiver Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

homeassistant-syslog-receiver

homeassistant-syslog-receiver Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README