diff options
| -rw-r--r-- | docs/system/syslog.rst | 303 |
1 files changed, 175 insertions, 128 deletions
diff --git a/docs/system/syslog.rst b/docs/system/syslog.rst index c9dc8a1c..4c50f6c9 100644 --- a/docs/system/syslog.rst +++ b/docs/system/syslog.rst @@ -1,9 +1,8 @@ .. _syslog: - - +###### Syslog ------- +###### Per default VyOSs has minimal syslog logging enabled which is stored and rotated locally. Errors will be always logged to a local file, which includes @@ -11,150 +10,198 @@ rotated locally. Errors will be always logged to a local file, which includes To configure syslog, you need to switch into configuration mode. -Logging to serial console -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The below would log all messages to :code:`/dev/console`. - -.. code-block:: none - - set system syslog console facility all level all - -Use the **[tab]** function to display all facilities and levels which can -be configured. - -.. code-block:: none - - vyos@vyos# set system syslog console facility <TAB> - Possible completions: - > all All facilities excluding "mark" - > auth Authentication and authorization - > authpriv Non-system authorization - > cron Cron daemon - > daemon System daemons - > kern Kernel - > lpr Line printer spooler - > mail Mail subsystem - > mark Timestamp - > news USENET subsystem - > protocols depricated will be set to local7 - > security depricated will be set to auth - > syslog Authentication and authorization - > user Application processes - > uucp UUCP subsystem - > local0 Local facility 0 - > local1 Local facility 1 - > local2 Local facility 2 - > local3 Local facility 3 - > local4 Local facility 4 - > local5 Local facility 5 - > local6 Local facility 6 - > local7 Local facility 7 - - vyos@vyos# set system syslog console facility all level <TAB> - Possible completions: - emerg Emergency messages - alert Urgent messages - crit Critical messages - err Error messages - warning Warning messages - notice Messages for further investigation - info Informational messages - debug Debug messages - all Log everything - - -Logging to a custom file -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Logging to a custom file, rotation size and the number of rotate files left -on the system can be configured. - -.. code-block:: none - - set system syslog file <FILENAME> facility <FACILITY> level <LEVEL> - set system syslog file <FILENAME> archive file <NUMBER OF FILES> - set system syslog file FILENAME archive size <FILESIZE> - -The very same setting can be applied to the global configuration, to modify -the defaults for the global logging. - -Logging to a remote host -^^^^^^^^^^^^^^^^^^^^^^^^ +Logging +======= -Logging to a remote host leaves the local logging configuration intact, it -can be configured in parallel. You can log ro multiple hosts at the same time, -using either TCP or UDP. The default is sending the messages via UDP. +Syslog supports logging to multiple targets, those targets could be a plain +file on your VyOS installation itself, a serial console or a remote syslog +server which is reached via :abbr:`IP (Internet Protocol)` UDP/TCP. -**UDP** +Console +------- -.. code-block:: none +.. cfgcmd:: set system syslog console facility <keyword> level <keyword> - set system syslog host 10.1.1.1 facility all level all - <optional> - set system syslog host 10.1.1.1 facility all protocol udp +Log syslog messages to ``/dev/console``, for en explanation on +:ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords +see tables below. -**TCP** +Custom File +----------- -.. code-block:: none +.. cfgcmd:: set system syslog file <filename> facility <keyword> level <keyword> - set system syslog host 10.1.1.2 facility all level all - set system syslog host 10.1.1.2 facility all protocol tcp +Log syslog messages to file specified via `<filename>`, for en explanation on +:ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords see +tables below. -Logging to a local user account -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. cfgcmd:: set system syslog file <filename> archive size <size> -If logging to a local useraccount is configured, all defined log messages are -display on the console if the local user is logged in, if the user is not -logged in, no messages are being displayed. +Syslog will write `<size>` kilobytes into the file specified by `<filename>`. +After this limit has been reached, the custom file is "rotated" by logrotate +and a new custom file is created. + +.. cfgcmd:: set system syslog file <filename> archive file <number> -.. code-block:: none +Syslog uses logrotate to rotate logiles after a number of gives bytes. We keep +as many as `<number>` rotated file before they are deleted on the system. - set system syslog user <LOCAL_USERNAME> facility <FACILITY> level <LEVEL> -Show logs -^^^^^^^^^ +Remote Host +----------- -Display log files on the console +Logging to a remote host leaves the local logging configuration intact, it +can be configured in parallel to a custom file or console logging. You can log +to multiple hosts at the same time, using either TCP or UDP. The default is +sending the messages via port 514/UDP. -.. code-block:: none - vyos@vyos:~$ show log - Possible completions: - <Enter> Execute the current command - all Show contents of all master log files - authorization Show listing of authorization attempts - cluster Show log for Cluster - conntrack-sync - Show log for Conntrack-sync - dhcp Show log for Dynamic Host Control Protocol (DHCP) - directory Show listing of user-defined log files - dns Show log for Domain Name Service (DNS) - file Show contents of user-defined log file - firewall Show log for Firewall - https Show log for Https - image Show logs from an image - lldp Show log for Lldp - nat Show log for Network Address Translation (NAT) - openvpn Show log for Openvpn - snmp Show log for Simple Network Monitoring Protocol (SNMP) - tail Monitor last lines of messages file - vpn Show log for Virtual Private Network (VPN) - vrrp Show log for Virtual Router Redundancy Protocol (VRRP) - webproxy Show log for Webproxy +.. cfgcmd:: set system syslog host <address> facility <keyword> level <keyword> -Show contents of a log file in an image -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Log syslog messages to remote host specified by `<address>`. The address can be +specified by either FQDN or IP address. For en explanation on +:ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords see +tables below. -Log messages from a specified image can be displayed on the console: -.. code-block:: none +.. cfgcmd:: set system syslog host <address> facility <keyword> protocol <udp|tcp> - $ show log image <image name> - $ show log image <image name> [all | authorization | directory | file <file name> | tail <lines>] +Configure protocol used for communication to remote syslog host. This can be +either UDP or TCP. -Details of allowed parameters: + +Local User Account +------------------ + +.. cfgcmd:: set system syslog user <username> facility <keyword> level <keyword> + +If logging to a local user account is configured, all defined log messages are +display on the console if the local user is logged in, if the user is not +logged in, no messages are being displayed. For en explanation on +:ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords see +tables below. + +.. _syslog_facilities: + +Facilities +========== + +List of facilities used by syslog. Most facilities names are self explanatory. +Facilities local0 - local7 common usage is f.e. as network logs facilities for +nodes and network equipment. Generally it depends on the situation how to +classify logs and put them to facilities. See facilities more as a tool rather +than a directive to follow. + +Facilities can be adjusted to meet the needs of the user: + ++----------+----------+----------------------------------------------------+ +| Facility | Keyword | Description | +| Code | | | ++==========+==========+====================================================+ +| | all | All facilities | ++----------+----------+----------------------------------------------------+ +| 0 | kern | Kernel messages | ++----------+----------+----------------------------------------------------+ +| 1 | user | User-level messages | ++----------+----------+----------------------------------------------------+ +| 2 | mail | Mail system | ++----------+----------+----------------------------------------------------+ +| 3 | daemon | System daemons | ++----------+----------+----------------------------------------------------+ +| 4 | auth | Security/authentication messages | ++----------+----------+----------------------------------------------------+ +| 5 | syslog | Messages generated internally by syslogd | ++----------+----------+----------------------------------------------------+ +| 6 | lpr | Line printer subsystem | ++----------+----------+----------------------------------------------------+ +| 7 | news | Network news subsystem | ++----------+----------+----------------------------------------------------+ +| 8 | uucp | UUCP subsystem | ++----------+----------+----------------------------------------------------+ +| 9 | cron | Clock daemon | ++----------+----------+----------------------------------------------------+ +| 10 | security | Security/authentication messages | ++----------+----------+----------------------------------------------------+ +| 11 | ftp | FTP daemon | ++----------+----------+----------------------------------------------------+ +| 12 | ntp | NTP subsystem | ++----------+----------+----------------------------------------------------+ +| 13 | logaudit | Log audit | ++----------+----------+----------------------------------------------------+ +| 14 | logalert | Log alert | ++----------+----------+----------------------------------------------------+ +| 15 | clock | clock daemon (note 2) | ++----------+----------+----------------------------------------------------+ +| 16 | local0 | local use 0 (local0) | ++----------+----------+----------------------------------------------------+ +| 17 | local1 | local use 1 (local1) | ++----------+----------+----------------------------------------------------+ +| 18 | local2 | local use 2 (local2) | ++----------+----------+----------------------------------------------------+ +| 19 | local3 | local use 3 (local3) | ++----------+----------+----------------------------------------------------+ +| 20 | local4 | local use 4 (local4) | ++----------+----------+----------------------------------------------------+ +| 21 | local5 | local use 5 (local5) | ++----------+----------+----------------------------------------------------+ +| 22 | local6 | use 6 (local6) | ++----------+----------+----------------------------------------------------+ +| 23 | local7 | local use 7 (local7) | ++----------+----------+----------------------------------------------------+ + +.. _syslog_severity_level: + +Severity Level +============== + ++-------+---------------+---------+-------------------------------------------+ +| Value | Severity | Keyword | Description | ++=======+===============+=========+===========================================+ +| | | all | Log everything | ++-------+---------------+---------+-------------------------------------------+ +| 0 | Emergency | emerg | System is unusable - a panic condition | ++-------+---------------+---------+-------------------------------------------+ +| 1 | Alert | alert | Action must be taken immediately - A | +| | | | condition that should be corrected | +| | | | immediately, such as a corrupted system | +| | | | database. | ++-------+---------------+---------+-------------------------------------------+ +| 2 | Critical | crit | Critical conditions - e.g. hard drive | +| | | | errors. | ++-------+---------------+---------+-------------------------------------------+ +| 3 | Error | err | Error conditions | ++-------+---------------+---------+-------------------------------------------+ +| 4 | Warning | warning | Warning conditions | ++-------+---------------+---------+-------------------------------------------+ +| 5 | Notice | notice | Normal but significant conditions - | +| | | | conditions that are not error conditions, | +| | | | but that may require special handling. | ++-------+---------------+---------+-------------------------------------------+ +| 6 | Informational | info | Informational messages | ++-------+---------------+---------+-------------------------------------------+ +| 7 | Debug | debug | Debug-level messages - Messages that | +| | | | contain information normally of use only | +| | | | when debugging a program. | ++-------+---------------+---------+-------------------------------------------+ + + +Display Logs +============ + +.. opcmd:: show log [all | authorization | cluster | conntrack-sync | ...] + +Display log files of given category on the console. Use tab completion to get +a list of available categories. Thos categories could be: all, authorization, +cluster, conntrack-sync, dhcp, directory, dns, file, firewall, https, image +lldp, nat, openvpn, snmp, tail, vpn, vrrp + +If no option is specified, this defaults to `all`. + +.. opcmd:: show log image <name> [all | authorization | directory | file <file name> | tail <lines>] + +Log messages from a specified image can be displayed on the console. Details of +allowed parameters: .. list-table:: :widths: 25 75 @@ -173,5 +220,5 @@ Details of allowed parameters: * - <lines> - Number of lines to be displayed, default 10 - -When no options/parameters are used, the contents of the main syslog file are displayed. +When no options/parameters are used, the contents of the main syslog file are +displayed. |