User Tools

Site Tools


docs:guide-user:base-system:log.essentials

Runtime Logging in OpenWrt

The openwrt system logging facility is an important debugging/monitoring capability. This document describes common support for the LEDE 17 implementations. It appears there have been some changes in (recently) released Openwrt 18 branch.

Introduction

The standard logging facility is implemented using logd, the ubox log daemon. This is implemented as an in-core ring buffer with fixed sized records. The ring-buffer records can be read using readlog on the router, streamed to a file or sent to a remote system through a TCP/UDP socket.

Messages format

The message format differs based on the destination (local logread, local file, remote socket). Roughly it can be viewed as:

<time stamp> <router name> <subsystem name/pid> <log_prefix>: <message body>

The logging message facility and priority are roughly equivalent to syslog implementations (see linux /usr/include/sys/syslog.h). The local 'logread' executable puts the facility.priority after the time stamp. Logging to a remote socket puts a numeric value before the time stamp.

For some common OpenWrt messages see log.messages. FIXME - the log.messages reference is way out of date but a useful placeholder …

logd

logd is configured in /etc/config/system. After changing the file, run

/etc/init.d/log restart
/etc/init.d/system restart

to read in the new configuration and restart the service.

There are three basic destinations for log messages: the RAM ring-buffer (the default), a local persistent file, a remote destination listening for messages on a TCP or UDP port.

The full set of log_* options for /etc/config/system are defined in System Configuration

logread

This is the default interface and the simplest. It is a local executable that will read the ring-buffer records and display them chronologically.

Local File Logging

In order to log to a local file on the router, one needs to set the following options:

config system 
...
   option log_file '/var/log/mylog'
   option log_remote '0'

Network Logging

In order to log remotely one needs to set the following options in /etc/config/system

config system
...
   option log_ip <destination IP>
   option log_port <something not needing root, e.g. 5555>
   option log_proto <tcp or udp>

Additionally, the firewall3 default is to ACCEPT all LAN traffic. If the router blocks LAN-side access, add the following firewall3 rule to /etc/config/firewall to ACCEPT tcp/udp traffic from the router to the LAN-side.

config rule
      option target 'ACCEPT'
      option dest 'lan'
      option proto 'tcp udp'
      option dest_port '5555'
      option name 'ACCEPT-LOG-DEVICE-LAN'

and then reload the rules using /etc/init.d/firewall restart.

For the LAN-side station/client, there are a large number of mechanisms to listen for log messages. One of the simplest is ncat:

  • ncat -4 -l 5555 (TCP)
  • ncat -u -4 -l 5555 (UDP)

The advantage to using TCP is reliability - it logs every event. The disadvantage is it can cause some performance degradation on the router if the logging level is high. There is a section on iptable event logging which can cause a noticable latency in traffic throughput using TCP socket logging.

Test Runtime Logging Support

If you want to test the logging out, just run a command like

logger testLog “Blah1”

and it should be written to the configured destination. If an event is not logged, check:

* /sbin/logd is running; it should have an argument of -S <log_size> indicating the size of the ring-buffer, * logd is configured correctly in /etc/config/system, * restart it using /etc/init.d/log restart and check for warnings/errors

Alternative implementations

The logging mechanism discussed here uses logd. There are other packages that provide the same functionality.

See syslog-ng (log.syslog-ng3). FIXME - the syslog-ng page appears very out-of-date.

docs/guide-user/base-system/log.essentials.txt · Last modified: 2018/08/09 03:23 by dturvene