Skip to content
dkwolf1 edited this page Nov 11, 2026 · 1 revision

Syslog Forwarding

Available in v3.15.0 and newer. The integration periodically downloads the Deco system log and forwards new lines to a receiver as RFC 5424 messages. This is polling, not a direct real-time log stream from the router.

Forwarding is off by default and configured independently for each Deco integration entry. No extra sensor needs to be enabled.

Before enabling

  • Use a receiver reachable from Home Assistant on a trusted local network.
  • UDP and TCP are supported; TLS syslog is not implemented.
  • Raw router logs are not automatically redacted. They can contain names, addresses and authentication-related protocol data.
  • Downloads use the shared Deco API session and can delay normal client/status polling.
  • Legacy encrypted local-web firmware, including the documented S7 firmware, cannot download or forward logs. One warning is logged and forwarding stops until reload.

Configure the entry

Open Settings > Devices & services > TP-Link Deco, then the entry's options.

Setting Example or default
Forward the Deco system log to a syslog server Enable
Syslog server host Receiver's LAN IP or hostname, without a URL scheme
Syslog server port 514 by default; use the receiver's actual port
Syslog protocol UDP by default, or TCP
Minimum system log level to forward ALL by default
Syslog forwarding interval in seconds 300 by default; minimum 60

The host is the receiver, not the Deco or HA address. In a test where HA is 192.168.1.119 and the Windows receiver is 192.168.1.122, set the host to 192.168.1.122.

Supported levels are ALERT, CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUG and ALL. Levels include more severe messages. HA integration debug logging is independent of this router-side filter.

Start with the default interval. Prefer a more selective level such as WARNING for routine operation when detailed router output is unnecessary. Do not shorten the interval on a slow or unstable mesh simply to avoid reaching the line limit.

What gets forwarded

  • The first successful non-empty download establishes a starting position without forwarding old history.
  • Changing the minimum log level also establishes a new position.
  • Restarting HA resumes from the per-entry saved position when it still exists in the retained router log.
  • Empty downloads are ignored. The first non-overlapping download is skipped; another non-empty download with no overlap is treated as new log content.
  • Each poll sends at most the newest 1,000 new lines. Older excess lines are discarded, not queued.
  • A reported send failure retains the position for a later poll to retry.
  • UDP has no delivery acknowledgement. TCP can duplicate a partially delivered batch when a retry is necessary.
  • The entry's polling switch pauses forwarding. An already-running download or send may finish.
  • Disabling forwarding removes its saved position when the entry reloads. Re-enabling starts fresh and skips the existing history.

This feature is not a guaranteed or lossless log archive. A manual download can capture the full log currently retained by the Deco.

Interpreting the cap warning

For example:

Forwarding only the newest 1000 of 3322 Deco system log lines

This means 1,000 lines were selected and 2,322 older excess lines were skipped. It is not a crash, but the missing lines will not be forwarded later. The warning can repeat on verbose firmware.

Temporary Windows receiver test

These examples use port 5514, not the default 514. Match that port in the integration. Start the receiver before enabling forwarding. A loopback probe verifies only the Windows receiver; verify messages actually arrive from HA as well.

Use an isolated, trusted test setup. The examples display only counts and source addresses, not raw message content. They are basic test receivers, not production syslog servers.

Find the receiver's LAN address

Run in ordinary PowerShell:

Get-NetIPAddress -AddressFamily IPv4 |
    Where-Object {
        $_.AddressState -eq "Preferred" -and
        $_.IPAddress -notlike "127.*" -and
        $_.IPAddress -notlike "169.254.*"
    } |
    Select-Object InterfaceAlias, IPAddress

Choose the active physical LAN/WiFi address, not a VPN, virtual adapter or loopback address.

Temporary firewall exceptions

Only on a trusted Windows Private network, run the rule for the protocol being tested in administrator PowerShell. These rules allow inbound traffic from the local subnet only. Do not disable the entire firewall.

New-NetFirewallRule -Name "DecoSyslogTest" -DisplayName "Temporary Deco syslog test" -Direction Inbound -Action Allow -Protocol UDP -LocalPort 5514 -RemoteAddress LocalSubnet -Profile Private
New-NetFirewallRule -Name "DecoSyslogTestTCP" -DisplayName "Temporary Deco TCP syslog test" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 5514 -RemoteAddress LocalSubnet -Profile Private

Check for an existing rule with the same name before repeating. Public profiles and routed/VLAN sources may not match these examples; ask your network administrator for an appropriately scoped rule.

UDP receiver

Run this complete block in an ordinary PowerShell window. After pasting, press Enter on an empty line after the final brace if PowerShell still shows its >> continuation prompt.

$udp = [Net.Sockets.UdpClient]::new(5514)
$udp.Client.ReceiveTimeout = 1000
$sender = [Net.IPEndPoint]::new([Net.IPAddress]::Any, 0)
$count = 0
Write-Host "UDP receiver active on port 5514. Stop with Ctrl+C."
try {
    while ($true) {
        try {
            $bytes = $udp.Receive([ref]$sender)
            $count++
            if ($count -eq 1 -or $count % 100 -eq 0) {
                Write-Host "$(Get-Date -Format HH:mm:ss): UDP received $count messages; last source $sender"
            }
        }
        catch [Net.Sockets.SocketException] {
            if ($_.Exception.SocketErrorCode -ne [Net.Sockets.SocketError]::TimedOut) {
                throw
            }
        }
    }
}
finally {
    $udp.Dispose()
}

Set the entry's syslog host to this PC's LAN address, port to 5514 and protocol to UDP. Allow the first download and at least one later interval with new log events. The default interval is five minutes. A successful HA send is not proof that Windows received it.

TCP receiver

Open a separate ordinary PowerShell window and run:

$listener = [Net.Sockets.TcpListener]::new([Net.IPAddress]::Any, 5514)
$listener.Start()
Write-Host "TCP receiver active on port 5514. Stop with Ctrl+C."
try {
    while ($true) {
        if (-not $listener.Pending()) {
            Start-Sleep -Milliseconds 200
            continue
        }
        $client = $listener.AcceptTcpClient()
        $reader = [IO.StreamReader]::new($client.GetStream())
        $count = 0
        try {
            while ($null -ne ($line = $reader.ReadLine())) {
                $count++
            }
            Write-Host "$(Get-Date -Format HH:mm:ss): TCP received $count lines from $($client.Client.RemoteEndPoint)"
        }
        finally {
            $reader.Dispose()
            $client.Dispose()
        }
    }
}
finally {
    $listener.Stop()
}

Set the integration protocol to TCP, keeping the same host and port. The sender opens and closes a connection for each batch; the count appears after the connection closes. UDP and TCP can use the same numerical port simultaneously, but require separate listeners and firewall rules.

Validation checklist

  1. Confirm real receiver output from HA, not only a locally generated test.
  2. Confirm normal client and node updates continue and no new errors appear.
  3. Test both UDP and TCP if both are needed.
  4. Restart HA with forwarding enabled and confirm reception resumes.
  5. Turn forwarding off and wait longer than one interval, allowing an in-flight request to finish. Reception should stop while normal polling continues.
  6. Disable temporary HA debug logging and save the collected log if needed.

Passing on one mesh does not guarantee every firmware behaves the same way.

Cleanup

Disable forwarding in the integration before stopping temporary receivers. Stop each receiver with Ctrl+C.

Remove only the test rules created above, using administrator PowerShell:

Remove-NetFirewallRule -Name "DecoSyslogTest" -ErrorAction SilentlyContinue
Remove-NetFirewallRule -Name "DecoSyslogTestTCP" -ErrorAction SilentlyContinue
Get-NetFirewallRule -Name "DecoSyslogTest","DecoSyslogTestTCP" -ErrorAction SilentlyContinue

No output from the final command means those named rules are absent. Existing unrelated firewall rules are not changed.

Troubleshooting

  • No output: check the saved host, exact port, protocol, receiver process, Windows profile, inbound rules, VPN restrictions and network isolation.
  • Only the test banner appears: it is printed before the receive loop starts; ensure the pasted block was submitted, especially when >> remains visible.
  • Local probe works but HA does not: the probe does not test the inbound network path from HA.
  • One warning then no more polls: check whether the firmware uses the unsupported legacy encrypted transport.
  • Older warning remains after disabling: inspect its timestamp and occurrence count; an old HA log entry does not mean forwarding is still active.
  • Repeated cap warnings: reduce log verbosity if appropriate; understand that excess lines are being discarded.

For a report, follow Diagnostics-and-Bug-Reports and include sanitized HA forwarding messages, receiver results, protocol, interval, model and exact firmware. Do not publish raw router authentication material.