mirror of
https://github.com/kernelkit/infix.git
synced 2026-08-06 07:33:01 +02:00
doc: new Syslog Support document
Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
This commit is contained in:
Joachim Wiberg
@@ -18,6 +18,7 @@ the `help` command.
|
||||
- [Introduction](introduction.md)
|
||||
- [System Configuration](system.md)
|
||||
- [Network Configuration](networking.md)
|
||||
- [Syslog Support](syslog.md)
|
||||
- **Infix In-Depth**
|
||||
- [Boot Procedure](boot.md)
|
||||
- [Branding & Releases](branding.md)
|
||||
|
||||
+207
@@ -0,0 +1,207 @@
|
||||
## Syslog Support
|
||||
|
||||
The system comes with native logging to internal storage, `/var/log/`,
|
||||
or `/log` for a shortcut. Depending on the device, this may be a RAM
|
||||
disk, meaning logs are not retained across reboots. This document
|
||||
details how to log to external media or remote syslog servers.
|
||||
|
||||
It is also possible to set up the device to act as a syslog server (log
|
||||
sink), this is covered briefly at the very end of this document.
|
||||
|
||||
> **Note:** the native logging cannot be modified, only the log file
|
||||
> rotation can be changed. Please see the `dir` admin-exec command for
|
||||
> a listing of existing native log files.
|
||||
|
||||
|
||||
### Log to File
|
||||
|
||||
Logging to a local file is useful when combined with an external media.
|
||||
E.g., a USB stick with a log partition (named/labeled: "log"). Below is
|
||||
an example.
|
||||
|
||||
For a list of available log facilities, see the table in a later section.
|
||||
|
||||
```bash
|
||||
admin@example:/> configure
|
||||
admin@example:/config/> edit syslog
|
||||
admin@example:/config/syslog/> edit actions log-file file:/media/log/mylog
|
||||
admin@example:/config/syslog/actions/log-file/file:/media/log/mylog/> set facility-list
|
||||
all audit auth authpriv console cron cron2 daemon ftp kern
|
||||
local0 local1 local2 local3 local4 local5 local6 local7 lpr mail
|
||||
news ntp syslog user uucp
|
||||
admin@example:/config/syslog/actions/log-file/file:hej/> set facility-list all severity
|
||||
alert all critical debug emergency error info none notice warning
|
||||
admin@example:/config/syslog/actions/log-file/file:/media/log/mylog/> set facility-list all severity critical
|
||||
admin@example:/config/syslog/actions/log-file/file:/media/log/mylog/> set facility-list mail severity warning
|
||||
admin@example:/config/syslog/actions/log-file/file:/media/log/mylog/> leave
|
||||
admin@example:/>
|
||||
```
|
||||
|
||||
> **Note:** the `log-file` syntax requires the leading prefix `file:`.
|
||||
> If the path is not absolute, e.g., `file:mylog`, the file is saved to
|
||||
> the system default path, i.e., `/log/mylog`. In this case, verify
|
||||
> that the filename is not already in use.
|
||||
|
||||
|
||||
### Log Rotation
|
||||
|
||||
By default log files are allowed to grow to a size of 1 MiB after which
|
||||
they are "rotated". The whole reason for this is to not fill up the
|
||||
disk with outdated logs. A rotated file is saved in stages and older
|
||||
ones are also compressed (using `gzip`). Use the `show log` command in
|
||||
admin-exec context to start the log file viewer:
|
||||
|
||||
admin@example:/config/syslog/> do show log
|
||||
log log.0 log.1.gz log.2.gz log.3.gz log.4.gz log.5.gz
|
||||
admin@example:/config/syslog/> do show log log.1.gz
|
||||
|
||||
> **Tip:** use the Tab key on your keyboard list available log files.
|
||||
> The `do` prefix is also very useful in configure context to access
|
||||
> commands from admin-exec context.
|
||||
|
||||
By default 10 compressed older files are saved. Here the oldest is
|
||||
`log.5.gz` and the most recently rotated one is `log.0`.
|
||||
|
||||
Log file rotation can be configured both globally and per log file.
|
||||
Here we show the global settings, the set up is the same for per log
|
||||
file, which if unset inherit the global settings:
|
||||
|
||||
```bash
|
||||
admin@example:/> configure
|
||||
admin@example:/config/> edit syslog file-rotation
|
||||
admin@example:/config/syslog/file-rotation/> show
|
||||
admin@example:/config/syslog/file-rotation/>
|
||||
```
|
||||
|
||||
The defaults are not shown. We can inspect them by asking the YANG
|
||||
model for the help texts:
|
||||
|
||||
```bash
|
||||
admin@example:/config/syslog/file-rotation/> help
|
||||
max-file-size number-of-files
|
||||
admin@example:/config/syslog/file-rotation/> help max-file-size
|
||||
NAME
|
||||
max-file-size kilobytes
|
||||
|
||||
DESCRIPTION
|
||||
Maximum log file size (kiB), before rotation.
|
||||
|
||||
DEFAULT
|
||||
1024
|
||||
admin@example:/config/syslog/file-rotation/> help number-of-files
|
||||
NAME
|
||||
number-of-files [0..4294967295]
|
||||
|
||||
DESCRIPTION
|
||||
Maximum number of log files retained.
|
||||
|
||||
DEFAULT
|
||||
10
|
||||
```
|
||||
|
||||
To change the defaults to something smaller, 512 kiB and 20 (remember
|
||||
everything after .0 is compressed, and text compresses well):
|
||||
|
||||
```bash
|
||||
admin@example:/config/syslog/file-rotation/> set max-file-size 512
|
||||
admin@example:/config/syslog/file-rotation/> set number-of-files 20
|
||||
admin@example:/config/syslog/file-rotation/> show
|
||||
number-of-files 20;
|
||||
max-file-size 512;
|
||||
admin@example:/config/syslog/file-rotation/> leave
|
||||
admin@example:/>
|
||||
```
|
||||
|
||||
|
||||
### Log Format
|
||||
|
||||
There are three major syslog log formats, the default is [RFC3164][] for
|
||||
log files and BSD for remote logging. Depending on time synchronization
|
||||
and remote log server capabilities, or policies, the [RFC5424][] format
|
||||
is often preferred since it not only has better time resolution but also
|
||||
supports structured logging:
|
||||
|
||||
BSD : myproc[8710]: Kilroy was here.
|
||||
RFC3164 : Aug 24 05:14:15 192.0.2.1 myproc[8710]: Kilroy was here.
|
||||
RFC5424 : 2003-08-24T05:14:15.000003-07:00 192.0.2.1 myproc 8710 - - Kilroy was here.
|
||||
|
||||
The BSD format is only applicable to remote logging. It remains the
|
||||
default for compatibility reasons, and is recommended since the device
|
||||
may not have proper time, making it better for the remote log server to
|
||||
perform time stamping at the time of arrival.
|
||||
|
||||
Configuring the log format is the same for log files and remotes:
|
||||
|
||||
```bash
|
||||
admin@example:/config/> edit syslog actions log-file file:foobar
|
||||
admin@example:/config/syslog/actions/log-file/file:foobar/> set log-format
|
||||
bsd rfc3164 rfc5424
|
||||
admin@example:/config/syslog/actions/log-file/file:foobar/> set log-format rfc5424
|
||||
admin@example:/config/syslog/actions/log-file/file:foobar/> leave
|
||||
admin@example:/>
|
||||
```
|
||||
|
||||
[RFC3164]: https://datatracker.ietf.org/doc/html/rfc3164
|
||||
[RFC5424]: https://datatracker.ietf.org/doc/html/rfc5424
|
||||
|
||||
### Log to Remote Server
|
||||
|
||||
Logging to a remote syslog server is the recommended way of supervising
|
||||
the system. This way all login attempts (console, SSH, or web) and any
|
||||
configuration changes can be traced, even in cases of a remote attacker
|
||||
tries to cover their traces by deleting logs.
|
||||
|
||||
The recommended setup involves using a fixed IP address, default BSD log
|
||||
format, and the default Internet port (514). This is the most reliable,
|
||||
because your device may not have DNS set up or even available, and some
|
||||
remote syslog servers do not support receiving time stamped log messages
|
||||
-- this is of course entirely dependent on how the remote server is set
|
||||
up, as well as local policy.
|
||||
|
||||
```bash
|
||||
admin@example:/config/> edit syslog
|
||||
actions file-rotation server
|
||||
admin@example:/config/> edit syslog actions destination moon
|
||||
admin@example:/config/syslog/actions/destination/moon/> set
|
||||
facility-list log-format udp
|
||||
admin@example:/config/syslog/actions/destination/moon/> set udp
|
||||
address port
|
||||
admin@example:/config/syslog/actions/destination/moon/> set udp address 192.168.0.12
|
||||
admin@example:/config/syslog/actions/destination/moon/> set facility-list container severity all
|
||||
admin@example:/config/syslog/actions/destination/moon/> leave
|
||||
admin@example:/>
|
||||
```
|
||||
|
||||
> **Note:** the alternatives shown below each prompt in the example
|
||||
> above can be found by tapping the Tab key.
|
||||
|
||||
### Facilities
|
||||
|
||||
| **Code** | **Facility** | **Description** |
|
||||
|----------|--------------|-------------------------------------------|
|
||||
| 0 | kern | Kernel log messages |
|
||||
| 1 | user | User-level messages |
|
||||
| 2 | mail | Mail system |
|
||||
| 3 | daemon | General system daemons |
|
||||
| 4 | auth | Security/authorization messages |
|
||||
| 5 | syslog | Messages generated by syslogd |
|
||||
| 6 | lpr | Line printer subsystem |
|
||||
| 7 | news | Network news subsystem |
|
||||
| 8 | uucp | UNIX-to-UNIX copy |
|
||||
| 9 | cron | Clock/cron daemon (BSD, Linux) |
|
||||
| 10 | authpriv | Security/authorization messages (private) |
|
||||
| 11 | ftp | FTP daemon |
|
||||
| 12 | ntp | NTP subsystem |
|
||||
| 13 | audit | Log audit (security) |
|
||||
| 14 | console | Log alert |
|
||||
| 15 | cron2 | Clock/cron daemon (Solaris) |
|
||||
| 16 | rauc* | local0, reserved for RAUC |
|
||||
| 17 | container* | local1, reserved for containers |
|
||||
| 18 | local2 | Currently unused |
|
||||
| 19 | local3 | Currently unused |
|
||||
| 20 | local4 | Currently unused |
|
||||
| 21 | local5 | Currently unused |
|
||||
| 22 | reserved* | local6, reserved for industrial Ethernet |
|
||||
| 23 | web* | local7, reserved for nginx web server |
|
||||
|
||||
Facilities marked `*` are local augments to the model.
|
||||
Reference in New Issue
Block a user