Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revisionBoth sides next revision | ||
| docs:guide-user:base-system:log.essentials [2018/05/23 16:17] – Change some Germany text with English borisov87 | docs:guide-user:base-system:log.essentials [2024/06/02 06:30] – [logread] stokito | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== | + | ====== |
| + | {{section> | ||
| - | FIXME These instructions appear to be very dated; " | + | ===== Introduction ===== |
| + | The OpenWrt | ||
| + | The standard logging facility is implemented using '' | ||
| + | This is implemented as a [[wp> | ||
| + | The ring buffer records can be read using '' | ||
| + | <code bash> | ||
| + | # List syslog | ||
| + | logread | ||
| - | ===== Introduction ===== | + | # Write a message with a tag to syslog |
| - | In Unix it is common to use centralized logging systems using a deamon and ''/ | + | logger -t TAG MESSAGE |
| - | While many normal distributions use Syslog | + | # List syslog filtered by tag |
| + | logread -e TAG | ||
| + | </ | ||
| + | |||
| + | < | ||
| + | Usage: logger [OPTIONS] [MESSAGE] | ||
| + | |||
| + | Write MESSAGE | ||
| + | |||
| + | -s Log to stderr as well as the system log | ||
| + | -t TAG Log using the specified tag (defaults to user name) | ||
| + | -p PRIO Priority | ||
| + | </ | ||
| + | |||
| + | Examples of using priority and tag values: | ||
| + | <code bash> | ||
| + | logger " | ||
| + | logger -p notice -t example_tag " | ||
| + | logger -p err -t example_tag " | ||
| + | # Fri May 8 00:23:26 2020 user.notice root: example | ||
| + | # Fri May 8 00:23:31 2020 user.notice example_tag: | ||
| + | # Fri May 8 00:23:40 2020 user.err example_tag: | ||
| + | </ | ||
| ===== Messages format ===== | ===== Messages format ===== | ||
| - | An example | + | The message |
| + | Roughly it can be viewed as: | ||
| + | |||
| < | < | ||
| - | Feb 28 23: | + | <time stamp> <router |
| </ | </ | ||
| - | The format includes date, hostname, | + | |
| + | The logging message | ||
| + | The local ' | ||
| + | Logging to a remote socket puts a numeric value before the time stamp. | ||
| For some common OpenWrt messages see [[docs: | For some common OpenWrt messages see [[docs: | ||
| + | FIXME - the log.messages reference is way out of date but a useful placeholder. | ||
| - | ===== ubox ===== | + | ===== logd ===== |
| - | As said earlier, OpenWrt currently uses its own system log implementation which is implemented as part of '' | + | '' |
| - | - '' | + | It also listens for '' |
| - | | + | It's configured in '' |
| - | ===== BusyBox ===== | + | <code bash> |
| - | So far the vanilla firmwares offered on OpenWrt utilize the '' | + | service log restart |
| + | service system restart | ||
| + | </code> | ||
| - | ^ Name ^ | + | to read in the new configuration and restart the service. |
| - | | busybox klogd | 242620 | Kernel logger | + | |
| - | | busybox syslogd | + | |
| - | < | + | 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. |
| - | klogd | + | |
| - | klogd [-c n] [-n] | + | The full set of '' |
| + | [[docs:guide-user: | ||
| + | |||
| + | ==== logread ==== | ||
| + | This is the default interface to read log messages. It's provided by the [[https:// | ||
| - | | + | It is a local executable in ''/ |
| - | -c n Sets the default | + | To show all log messages |
| - | | + | <code bash> |
| + | logread | ||
| </ | </ | ||
| + | Options: | ||
| < | < | ||
| - | syslogd | + | -s < |
| - | | + | -l < |
| - | | + | -e < |
| - | | + | -r < |
| - | -n Run in foreground | + | -F < |
| - | -O FILE Log to given file (default:/ | + | -S < |
| - | -l n Set local log level | + | -p < |
| - | -S Smaller logging output | + | -h < |
| - | -s SIZE Max size (KB) before rotate (default: | + | -P < |
| - | -b NUM Number of rotated logs to keep (default:1, max=99, | + | -z < |
| - | -R HOST[: | + | -Z < |
| - | -L Log locally and via network (default is network only if -R) | + | -f Follow log messages |
| - | -D Drop duplicates | + | -u Use UDP as the protocol |
| - | -C[size(KiB)] | + | -t Add an extra timestamp |
| + | -0 Use \0 instead of \n as trailer when using TCP | ||
| </ | </ | ||
| - | The " | + | Please note that if you install the [[: |
| - | you probably have syslogd running '' | + | |
| - | '' | ||
| - | 16KB is a busybox default value. To change it, set '' | ||
| - | Who logs? The syslogd acts as the server and any program can act as the client and send log messages | + | ==== Local file logging ==== |
| + | In order to log to a local file on the router, one needs to set the following options: | ||
| - | Any program can act as the client and the syslogd acts as the server. Communication is prone to the //syslog communications protocol//. | + | <code bash> |
| + | config system | ||
| + | ... | ||
| + | | ||
| + | | ||
| + | </code> | ||
| + | ==== Network logging ==== | ||
| + | In order to log remotely one needs to set the following options in ''/ | ||
| - | ==== Output ==== | + | <code bash> |
| - | Syslogd writes the log messages it receives into a file or into the RAM ringbuffer (option '' | + | config system |
| + | ... | ||
| + | | ||
| + | | ||
| + | | ||
| + | </ | ||
| - | ==== Structure of syslog message | + | For the destination port, if you'll be manually reading the logs on the remote system as an unprivileged user (such as via the netcat command given below), then specify a high port (e.g. 5555). If you're sending to a syslog server, use whatever port the syslog server is listening on (typically 514). |
| - | === The Header | + | |
| - | The header contains | + | |
| - | The timestamp is set by the receiver of the log-message, the syslogd, not by the sender (for example | + | Additionally, |
| - | The hostname or the ip address belong | + | |
| - | ====== logd and logread ====== | + | <code bash> |
| + | config rule | ||
| + | option target ' | ||
| + | option dest ' | ||
| + | option proto 'tcp udp' | ||
| + | option dest_port ' | ||
| + | option name ' | ||
| + | </ | ||
| + | |||
| + | and then reload the rules using '' | ||
| + | |||
| + | For the LAN-side station/ | ||
| + | One of the simplest is ncat: | ||
| + | |||
| + | <code bash> | ||
| + | # TCP | ||
| + | ncat -4 -l 5555 | ||
| + | |||
| + | # Read UDP logs with ncat or python3 | ||
| + | ncat -u -4 -l 5555 | ||
| + | python3 -c " | ||
| + | s = socket.socket(socket.AF_INET, | ||
| + | s.bind((' | ||
| + | while True: | ||
| + | | ||
| + | </ | ||
| + | |||
| + | Log messages are in [[https:// | ||
| + | The above netcat method will therefore yield somewhat messy output. The python log reader above will most of the time get the line breaks into the right spots. A cleaner solution is to send messages to a remote machine' | ||
| + | See [[https:// | ||
| - | In Chaos Calmer 15.01, '' | + | 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 | If you want to test the logging out, just run a command like | ||
| - | '' | + | < |
| - | And it should | + | and it should |
| + | If an event is not logged, | ||
| - | Both of these (logd and logread) are started, stopped and restarted from /etc/init.d/log and are configured | + | * '' |
| + | * '' | ||
| + | * restart it using '' | ||
| - | ==== File Logging | + | ===== Logrotate |
| + | To automatically manage large collections of daily, weekly, or monthly logs, you may want to use [[packages: | ||
| + | Here's an example that rotates a persistent log on a USB storage each night keeping it for 1 week. | ||
| - | <WRAP center round important 60%> | + | <code bash> |
| - | This configuration of logging is not robust for logging systems errors. | + | # Install packages |
| + | opkg update | ||
| + | opkg install logrotate | ||
| - | Noted when trying to capture causes of the kernel oom-killer being called. | + | # Configure logging |
| - | </WRAP> | + | uci set system.@system[0].log_file=" |
| + | uci set system.@system[0].log_remote=" | ||
| + | uci commit system | ||
| + | service system restart | ||
| + | # Configure logrotate | ||
| + | cat << " | ||
| + | include / | ||
| + | / | ||
| + | daily | ||
| + | rotate 1 | ||
| + | missingok | ||
| + | notifempty | ||
| + | postrotate | ||
| + | service log restart | ||
| + | sleep 1 | ||
| + | logger -p warn -s "Log rotation complete" | ||
| + | endscript | ||
| + | } | ||
| + | EOF | ||
| - | Note that if you are file logging locally [[https://forum.openwrt.org/viewtopic.php? | + | # Configure cron |
| + | cat << " | ||
| + | 58 23 * * * logrotate / | ||
| + | EOF | ||
| + | service cron restart | ||
| - | config system | + | # Debugging |
| - | | + | logrotate --verbose --debug |
| - | option zonename ' | + | </code> |
| - | option timezone ' | + | |
| - | | + | |
| - | option cronloglevel ' | + | |
| - | option log_file '/mnt/ | + | |
| - | option log_type ' | + | |
| - | option log_size 100000 | + | |
| - | option log_buffer_size 2048 | + | |
| - | option log_remote ' | + | |
| - | ==== Network Logging | + | ===== Alternative implementations |
| + | See **rsyslog** - to e.g. route all or specific logs to a (central) rsyslog receiver | ||
| - | config system | + | <code bash> |
| - | (...) | + | opkg install rsyslog |
| - | | + | </code> |
| - | more log_* options https://openwrt.org/ | + | With the config file: /etc/rsyslog.conf |
| - | general guide http://bredsaal.dk/debian-rsyslog-server-with-openwrt-rsyslog-client | + | < |
| + | *.info; | ||
| + | .. | ||
| + | kern.* | ||
| + | </code> | ||
| - | note: I recommend adding these lines in / | + | If you add to the rsyslog receiver' |
| - | # separate | + | < |
| - | # src http://www.rsyslog.com/article60/ | + | $template DynamicFile,"/ |
| - | $template | + | *.* -? |
| - | *.* -?DynaFile | + | </ |
| + | you get the messages separated from every sender in a own folder. | ||
| + | ===== rsyslog and Logz.io ===== | ||
| + | You can support logging direct to a cloud ELK provider like Logz.io | ||
| + | |||
| + | Replace '' | ||
| + | And will appear in help manuals when you're logged in, reference the guide [[https://app.logz.io/#/dashboard/ | ||
| + | |||
| + | < | ||
| + | $template | ||
| + | *.* @@listener.logz.io: | ||
| + | </ | ||
| + | |||
| + | Confirm you have the right config with: | ||
| + | |||
| + | <code bash> | ||
| + | rsyslogd | ||
| + | </ | ||
| - | ==== RAM Logging | + | ===== Archive |
| - | TODO | + | The logging mechanism discussed here uses '' |
| + | provide the same functionality. | ||
| + | See '' | ||
| + | FIXME - the '' | ||