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/07 21:14] – 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 | + | 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 | + | FIXME - the log.messages reference is way out of date but a useful placeholder. |
| ===== logd ===== | ===== logd ===== | ||
| - | '' | + | '' |
| + | It also listens for ''/ | ||
| + | It' | ||
| - | ''/ | + | <code bash> |
| + | service | ||
| + | service system restart | ||
| + | </ | ||
| to read in the new configuration and restart the service. | 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. | + | 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 '' | The full set of '' | ||
| - | https:// | + | [[docs:guide-user:base-system:system_configuration|System Configuration]] |
| ==== logread ==== | ==== logread ==== | ||
| - | This is the default interface | + | This is the default interface |
| - | ==== Local File Logging | + | 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: | In order to log to a local file on the router, one needs to set the following options: | ||
| - | | + | <code bash> |
| - | (...) | + | config system |
| - | option log_file '/ | + | ... |
| - | option log_remote ' | + | |
| + | | ||
| + | </ | ||
| - | ==== Network | + | ==== Network |
| - | In order to log remotely one needs to set the following options in '/ | + | In order to log remotely one needs to set the following options in ''/ |
| - | | + | <code bash> |
| - | (...) | + | config system |
| - | option log_ip < | + | ... |
| - | option log_port <something not needing root, e.g. 5555> | + | |
| - | option log_proto <tcp or udp> | + | |
| - | + | | |
| - | There are a large number of mechanisms to listen for log messages on the remote server. One of the simplest is ncat: | + | </ |
| - | * '' | + | 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 advantage to using TCP is reliability - it logs every event. The disadvantage is it can cause some performance degradation on the router | + | Additionally, |
| - | ====== Test Runtime Logging Support ===== | + | <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 be written to the configured destination. If an event is not logged, check: | + | and it should be written to the configured destination. |
| + | If an event is not logged, check: | ||
| - | * ''/ | + | * ''/ |
| * '' | * '' | ||
| - | * restart it using '' | + | * restart it using '' |
| + | |||
| + | ===== 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. | ||
| + | |||
| + | <code bash> | ||
| + | # Install packages | ||
| + | opkg update | ||
| + | opkg install logrotate | ||
| + | |||
| + | # Configure logging | ||
| + | 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 | ||
| + | |||
| + | # Configure cron | ||
| + | cat << " | ||
| + | 58 23 * * * logrotate / | ||
| + | EOF | ||
| + | service cron restart | ||
| + | |||
| + | # Debugging | ||
| + | logrotate --verbose --debug / | ||
| + | </ | ||
| ===== Alternative implementations ===== | ===== Alternative implementations ===== | ||
| + | See **rsyslog** - to e.g. route all or specific logs to a (central) rsyslog receiver | ||
| + | |||
| + | <code bash> | ||
| + | opkg install rsyslog | ||
| + | </ | ||
| + | |||
| + | With the config file: / | ||
| + | |||
| + | < | ||
| + | *.info; | ||
| + | .. | ||
| + | kern.* | ||
| + | </ | ||
| + | |||
| + | If you add to the rsyslog receiver' | ||
| + | |||
| + | < | ||
| + | $template DynamicFile,"/ | ||
| + | *.* -? | ||
| + | </ | ||
| + | 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 '' | ||
| + | |||
| + | Replace '' | ||
| + | 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 '' | The logging mechanism discussed here uses '' | ||
| provide the same functionality. | provide the same functionality. | ||
| Line 73: | Line 262: | ||
| See '' | See '' | ||
| FIXME - the '' | FIXME - the '' | ||
| - | |||