syslog: restructure chapter and tables to the new cfgcmd/opcmd style

(cherry picked from commit 5e5d68f889e971560abb695fa3ad7ba84890e82d)

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.