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/08/03 20:01] – dturvene | docs:guide-user:base-system:log.essentials [2024/06/02 06:30] – [logread] stokito | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== | + | ====== Logging |
| - | The openwrt system logging facility is an important debugging/ | + | {{section> |
| ===== Introduction ===== | ===== Introduction ===== | ||
| - | The standard logging facility is implemented using '' | + | The OpenWrt system logging facility is an important debugging/ |
| - | The ring-buffer records can be read using '' | + | 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 | ||
| + | |||
| + | # Write a message with a tag to syslog | ||
| + | logger -t TAG MESSAGE | ||
| + | |||
| + | # List syslog filtered by tag | ||
| + | logread -e TAG | ||
| + | </ | ||
| + | |||
| + | < | ||
| + | Usage: logger [OPTIONS] [MESSAGE] | ||
| + | |||
| + | Write MESSAGE (or stdin) to syslog | ||
| + | |||
| + | -s Log to stderr as well as the system log | ||
| + | -t TAG Log using the specified tag (defaults to user name) | ||
| + | -p PRIO Priority (numeric or facility.level pair) | ||
| + | </ | ||
| + | |||
| + | 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 ===== | ||
| - | The message format differs based on the destination (local logread, local file, remote socket). | + | The message format differs based on the destination (local logread, local file, remote socket). |
| + | Roughly it can be viewed as: | ||
| - | '' | + | < |
| - | + | <time stamp> <router name> < | |
| - | The logging message facility and priority are roughly equivalent to syslog implementations (see linux | + | </code> |
| - | '' | + | |
| - | FIXME - the log messages example is way out of date but a useful placeholder | + | The logging message facility and priority are roughly equivalent to syslog implementations (see linux ''/ |
| + | 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. | ||
| - | ===== Alternative implementations | + | ===== logd ===== |
| - | The logging mechanism discussed here uses '' | + | '' |
| - | provide the same functionality. | + | It also listens for ''/ |
| + | It's configured in ''/ | ||
| - | See '' | + | <code bash> |
| - | FIXME - the page says to not use this... | + | service |
| + | service system restart | ||
| + | </ | ||
| + | to read in the new configuration and restart the service. | ||
| - | ==== Output ==== | + | There are three basic destinations for log messages: the RAM ring buffer |
| - | Syslogd writes the log messages | + | |
| + | The full set of '' | ||
| + | [[docs: | ||
| - | ====== logd and logread ====== | + | ==== logread ==== |
| + | This is the default interface to read log messages. It's provided by the [[https:// | ||
| - | In Chaos Calmer 15.01, '' | + | It is a local executable in '' |
| + | To show all log messages that contains a specific text (like a daemon name) and follow (like in '' | ||
| + | <code bash> | ||
| + | logread -fe firewall | ||
| + | </ | ||
| + | |||
| + | Options: | ||
| + | < | ||
| + | -s < | ||
| + | -l < | ||
| + | -e < | ||
| + | -r < | ||
| + | -F < | ||
| + | -S < | ||
| + | -p < | ||
| + | -h < | ||
| + | -P < | ||
| + | -z < | ||
| + | -Z < | ||
| + | -f Follow log messages | ||
| + | -u Use UDP as the protocol | ||
| + | -t Add an extra timestamp | ||
| + | -0 Use \0 instead of \n as trailer when using TCP | ||
| + | </ | ||
| + | |||
| + | Please note that if you install the [[: | ||
| + | |||
| + | |||
| + | |||
| + | ==== Local file logging ==== | ||
| + | In order to log to a local file on the router, one needs to set the following options: | ||
| + | |||
| + | <code bash> | ||
| + | config system | ||
| + | ... | ||
| + | | ||
| + | | ||
| + | </ | ||
| + | |||
| + | ==== Network logging ==== | ||
| + | In order to log remotely one needs to set the following options in ''/ | ||
| + | |||
| + | <code bash> | ||
| + | config system | ||
| + | ... | ||
| + | | ||
| + | | ||
| + | | ||
| + | </ | ||
| + | |||
| + | 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). | ||
| + | |||
| + | Additionally, | ||
| + | |||
| + | <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:// | ||
| + | |||
| + | 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 log files by host name of sending device | + | < |
| - | # src http:// | + | $template |
| - | | + | *.* -?DynamicFile |
| - | *.* -?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 by adding a few lines to your '' | ||
| - | ==== RAM Logging ==== | + | Replace '' |
| - | TODO | + | And will appear in help manuals when you're logged in, reference the guide [[https:// |
| + | < | ||
| + | $template logzFormatFileTagName," | ||
| + | *.* @@listener.logz.io: | ||
| + | </ | ||
| + | |||
| + | Confirm you have the right config with: | ||
| + | |||
| + | <code bash> | ||
| + | rsyslogd -N1 | ||
| + | </ | ||
| + | |||
| + | ===== Archive ===== | ||
| + | The logging mechanism discussed here uses '' | ||
| + | provide the same functionality. | ||
| + | |||
| + | See '' | ||
| + | FIXME - the '' | ||