diff options
Diffstat (limited to 'docs/configuration/system')
| -rw-r--r-- | docs/configuration/system/console.rst | 17 | ||||
| -rw-r--r-- | docs/configuration/system/eventhandler.rst | 48 | ||||
| -rw-r--r-- | docs/configuration/system/flow-accounting.rst | 81 | ||||
| -rw-r--r-- | docs/configuration/system/host-information.rst | 175 | ||||
| -rw-r--r-- | docs/configuration/system/index.rst | 24 | ||||
| -rw-r--r-- | docs/configuration/system/ip.rst | 75 | ||||
| -rw-r--r-- | docs/configuration/system/ipv6.rst | 202 | ||||
| -rw-r--r-- | docs/configuration/system/login.rst | 129 | ||||
| -rw-r--r-- | docs/configuration/system/name-server.rst | 68 | ||||
| -rw-r--r-- | docs/configuration/system/ntp.rst | 19 | ||||
| -rw-r--r-- | docs/configuration/system/syslog.rst | 224 | ||||
| -rw-r--r-- | docs/configuration/system/task-scheduler.rst | 60 | ||||
| -rw-r--r-- | docs/configuration/system/time-zone.rst | 11 |
13 files changed, 1133 insertions, 0 deletions
diff --git a/docs/configuration/system/console.rst b/docs/configuration/system/console.rst new file mode 100644 index 00000000..730c9da1 --- /dev/null +++ b/docs/configuration/system/console.rst @@ -0,0 +1,17 @@ +.. _serial-console: + +Serial console +============== + + + +Configuring Console +------------------- + +.. code-block:: none + + vyos@vyos# set system console + Possible completions: + +> device Serial console device name + +> network Network based console logging + powersave Enable screen blank powersaving on VGA console
\ No newline at end of file diff --git a/docs/configuration/system/eventhandler.rst b/docs/configuration/system/eventhandler.rst new file mode 100644 index 00000000..4421e79c --- /dev/null +++ b/docs/configuration/system/eventhandler.rst @@ -0,0 +1,48 @@ +.. _event-handler: + +Event Handler +------------- + +Event handler allows you to execute scripts when a string that matches a regex appears in a text stream (e.g. log file). + +It uses "feeds" (output of commands, or a named pipes) and "policies" that define what to execute if a regex is matched. + +.. code-block:: none + + system + event-handler + feed <name> + description <feed description> + policy <policy name> + source + preset + syslog # Use the syslog logs for feed + custom + command <command to execute> # E.g. "tail -f /var/log/somelogfile" + named-pipe <path to a names pipe> + policy <policy name> + description <policy description> + event <event name> + description <event description> + pattern <regex> + run <command to run> + +In this small example a script runs every time a login failed and an interface goes down + +.. code-block:: none + + vyos@vyos# show system event-handler + feed Syslog { + policy MyPolicy + source { + preset syslog + } + } + policy MyPolicy { + description "Test policy" + event BadThingsHappened { + pattern "authentication failure" + pattern "interface \.* index \d+ .* DOWN.*" + run /config/scripts/email-to-admin + } + }
\ No newline at end of file diff --git a/docs/configuration/system/flow-accounting.rst b/docs/configuration/system/flow-accounting.rst new file mode 100644 index 00000000..9c876001 --- /dev/null +++ b/docs/configuration/system/flow-accounting.rst @@ -0,0 +1,81 @@ +.. _flow-accounting: + +NetFlow is a feature that was introduced on Cisco routers around 1996 that +provides the ability to collect IP network traffic as it enters or exits an +interface. By analyzing the data provided by NetFlow, a network administrator +can determine things such as the source and destination of traffic, class of +service, and the causes of congestion. A typical flow monitoring setup (using +NetFlow) consists of three main components: + +* Flow exporter: aggregates packets into flows and exports flow records towards + one or more flow collectors +* Flow collector: responsible for reception, storage and pre-processing of flow + data received from a flow exporter +* Analysis application: analyzes received flow data in the context of intrusion + detection or traffic profiling, for example + +For connectionless protocols as like ICMP and UDP, a flow is considered complete +once no more packets for this flow appear after configurable timeout. + +NetFlow is usually enabled on a per-interface basis to limit load on the router +components involved in NetFlow, or to limit the amount of NetFlow records +exported. + +VyOS supports flow accounting through NetFlow (version 5, 9 and 10) or sFlow. + +Flow Accounting +--------------- + +In order for flow accounting information to be collected and displayed for an +interface, the interface must be configured for flow accounting. The following +example shows how to configure ``eth0`` and ``bond3`` for flow accounting. + +.. code-block:: none + + set system flow-accounting interface eth0 + set system flow-accounting interface bond3 + + +NetFlow is a protocol originating from Cisco Systems. It works on level3. +VyOS supports version 5, 9 and 10 (IPFIX - IP Flow Information Export) + +NetFlow v5 example: + +.. code-block:: none + + set system flow-accounting netflow engine-id 100 + set system flow-accounting netflow version 5 + set system flow-accounting netflow server 192.168.2.10 port 2055 + +Displaying Flow Accounting Information +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Once flow accounting is configured on an interfaces it provides the ability to +display captured network traffic information for all configured interfaces. + +The following op-mode command shows flow accounting for eth0. + +.. code-block:: none + + vyos@vyos:~$ show flow-accounting interface eth0 + flow-accounting for [eth0] + Src Addr Dst Addr Sport Dport Proto Packets Bytes Flows + 0.0.0.0 192.0.2.50 811 811 udp 7733 591576 0 + 0.0.0.0 192.0.2.50 811 811 udp 7669 586558 1 + 192.0.2.200 192.0.2.51 56188 22 tcp 586 36504 1 + 192.0.2.99 192.0.2.51 61636 161 udp 46 6313 4 + 192.0.2.99 192.0.2.51 61638 161 udp 42 5364 9 + 192.0.2.99 192.0.2.51 61640 161 udp 42 5111 3 + 192.0.2.200 192.0.2.51 54702 22 tcp 86 4432 1 + 192.0.2.99 192.0.2.51 62509 161 udp 24 3540 1 + 192.0.2.99 192.0.2.51 0 0 icmp 49 2989 8 + 192.0.2.99 192.0.2.51 54667 161 udp 18 2658 1 + 192.0.2.99 192.0.2.51 54996 161 udp 18 2622 1 + 192.0.2.99 192.0.2.51 63708 161 udp 18 2622 1 + 192.0.2.99 192.0.2.51 62111 161 udp 18 2622 1 + 192.0.2.99 192.0.2.51 61646 161 udp 16 1977 4 + 192.0.2.99 192.0.2.51 56038 161 udp 10 1256 1 + 192.0.2.99 192.0.2.51 55570 161 udp 6 1146 1 + 192.0.2.99 192.0.2.51 54599 161 udp 6 1134 1 + 192.0.2.99 192.0.2.51 56304 161 udp 8 1029 1 + diff --git a/docs/configuration/system/host-information.rst b/docs/configuration/system/host-information.rst new file mode 100644 index 00000000..71209412 --- /dev/null +++ b/docs/configuration/system/host-information.rst @@ -0,0 +1,175 @@ +.. _host-information: + +Host Information +---------------- + +This section describes the system's host information and how to configure them, +it covers the following topics: + +* Host name +* Domain +* IP address +* Default gateway +* Aliases + +Host Name +^^^^^^^^^ + +A hostname is the label (name) assigned to a network device (a host) on a +network and is used to distinguish one device from another on specific networks +or over the internet. + +Set a system host name: + +.. code-block:: none + + set system host-name <hostname> + +.. note:: Only letters, numbers and hyphens are allowed. + +Show host name: + +.. code-block:: none + + show system host-name + +Delete host name: + +.. code-block:: none + + delete system host-name <hostname> + +Example: Set system hostname to 'RT01': + +.. code-block:: none + + set system host-name RT01 + commit + show system host-name + host-name RT01 + +Domain Name +^^^^^^^^^^^ + +A domain name is the label (name) assigned to a computer network and is thus +unique. + +Set the system's domain: + +.. code-block:: none + + set system domain-name <domain> + +.. note:: Only letters, numbers, hyphens and periods are allowed. + +Show domain: + +.. code-block:: none + + show system domain-name + +Remove domain name: + +.. code-block:: none + + set system delete domain-name <domain> + +Example: Set system domain to example.com: + +.. code-block:: none + + set system domain-name example.com + commit + show system domain-name + domain-name example.com + +Static host mappings +^^^^^^^^^^^^^^^^^^^^ + +How to assign IPs to interfaces is described in chapter +:ref:`interfaces-addresses`. This section shows how to statically map a system +IP to its host name for local (meaning on this VyOS instance) DNS resolution: + +.. code-block:: none + + set system static-host-mapping host-name <hostname> inet <IP address> + +Show static mapping: + +.. code-block:: none + + show system static-host-mapping + +Example: Create a static mapping between the system's hostname `RT01` and +IP address `10.20.30.41`: + +.. code-block:: none + + set system static-host-mapping host-name RT01 inet 10.20.30.41 + commit + show system static-host-mapping + host-name RT01 { + inet 10.20.30.41 + } + +Aliases +******* + +One or more system aliases (static mappings) can be defined: + +.. code-block:: none + + set system static-host-mapping host-name <hostname> alias <alias> + +Show aliases: + +.. code-block:: none + + show system static-mapping + +Delete alias: + +.. code-block:: none + + delete system static-host-mapping host-name <hostname> alias <alias> + +Example: Set alias `router1` for system with hostname `RT01`: + +.. code-block:: none + + set system static-host-mapping host-name RT01 alias router1 + commit + show system static-host-mapping + host-name RT01 { + alias router1 + inet 10.20.30.41 + } + +Default Gateway/Route +^^^^^^^^^^^^^^^^^^^^^ + +In the past (VyOS 1.1.8) used a gateway-address configured in the system tree +(`set system gateway-address <IP address>`) this is no longer supported and +existing configurations are migrated to the new CLI commands. + +It is replaced by inserting a static route into the routing table using: + +.. code-block:: none + + set protocols static route 0.0.0.0/0 next-hop <gateway ip> + +Delete the default route from the system + +.. code-block:: none + + delete protocols static route 0.0.0.0/0 + +Show default route: + +.. code-block:: none + + vyos@vyos$ show ip route 0.0.0.0 + Routing entry for 0.0.0.0/0 + Known via "static", distance 1, metric 0, best + Last update 3d00h23m ago + * 172.16.34.6, via eth1 diff --git a/docs/configuration/system/index.rst b/docs/configuration/system/index.rst new file mode 100644 index 00000000..07ba2ff5 --- /dev/null +++ b/docs/configuration/system/index.rst @@ -0,0 +1,24 @@ +.. _system: + +System +====== + +After a basic system setup by setting up :ref:`interfaces-addresses`, VyOS +should be ready for further configuration which is described in this chapter. + + +.. toctree:: + :maxdepth: 2 + + host-information + console + eventhandler + flow-accounting + login + ip + ipv6 + name-server + ntp + syslog + task-scheduler + time-zone
\ No newline at end of file diff --git a/docs/configuration/system/ip.rst b/docs/configuration/system/ip.rst new file mode 100644 index 00000000..6c158de9 --- /dev/null +++ b/docs/configuration/system/ip.rst @@ -0,0 +1,75 @@ +.. _ip: + +IPv4 +==== + +System configuration commands +----------------------------- + + +.. cfgcmd:: set system ip disable-forwarding + + Use this command to disable IPv4 forwarding on all interfaces. + + +.. cfgcmd:: set system ip arp table-size <number> + + Use this command to define the maximum number of entries to keep in + the ARP cache (1024, 2048, 4096, 8192, 16384, 32768). + + +.. cfgcmd:: set system ip multipath layer4-hashing + + Use this command to use Layer 4 information for IPv4 ECMP hashing. + + +Operational commands +-------------------- + + +show commands +^^^^^^^^^^^^^ + +See below the different parameters available for the IPv4 **show** command: + +.. code-block:: + + vyos@vyos:~$ show ip + Possible completions: + access-list Show all IP access-lists + as-path-access-list + Show all as-path-access-lists + bgp Show Border Gateway Protocol (BGP) information + community-list + Show IP community-lists + extcommunity-list + Show extended IP community-lists + forwarding Show IP forwarding status + groups Show IP multicast group membership + igmp Show IGMP (Internet Group Management Protocol) information + large-community-list + Show IP large-community-lists + multicast Show IP multicast + ospf Show IPv4 Open Shortest Path First (OSPF) routing information + pim Show PIM (Protocol Independent Multicast) information + ports Show IP ports in use by various system services + prefix-list Show all IP prefix-lists + protocol Show IP route-maps per protocol + rip Show Routing Information Protocol (RIP) information + route Show IP routes + + +reset commands +^^^^^^^^^^^^^^ + +And the different IPv4 **reset** commands available: + +.. code-block:: + + vyos@vyos:~$ reset ip + Possible completions: + arp Reset Address Resolution Protocol (ARP) cache + bgp Clear Border Gateway Protocol (BGP) statistics or status + igmp IGMP clear commands + multicast IP multicast routing table + route Reset IP route diff --git a/docs/configuration/system/ipv6.rst b/docs/configuration/system/ipv6.rst new file mode 100644 index 00000000..8b00ccf8 --- /dev/null +++ b/docs/configuration/system/ipv6.rst @@ -0,0 +1,202 @@ +.. _ipv6: + + +IPv6 +==== + +System configuration commands +----------------------------- + +.. cfgcmd:: set system ipv6 disable + + Use this command to disable assignment of IPv6 addresses on all + interfaces. + + +.. cfgcmd:: set system ipv6 disable-forwarding + + Use this command to disable IPv6 forwarding on all interfaces. + + +.. cfgcmd:: set system ipv6 neighbor table-size <number> + + Use this command to define the maximum number of entries to keep in + the Neighbor cache (1024, 2048, 4096, 8192, 16384, 32768). + + +.. cfgcmd:: set system ipv6 strict-dad + + Use this command to disable IPv6 operation on interface when + Duplicate Address Detection fails on Link-Local address. + + +.. cfgcmd:: set system ipv6 multipath layer4-hashing + + Use this command to user Layer 4 information for ECMP hashing. + +.. cfgcmd:: set system ipv6 blacklist + + Use this command to prevent the IPv6 kernel module from being loaded. + + + +Operational commands +-------------------- + +Show commands +^^^^^^^^^^^^^ + + +.. opcmd:: show ipv6 neighbors + + Use this command to show IPv6 Neighbor Discovery Protocol information. + + +.. opcmd:: show ipv6 groups + + Use this command to show IPv6 multicast group membership. + + +.. opcmd:: show ipv6 forwarding + + Use this command to show IPv6 forwarding status. + +.. opcmd:: show ipv6 route + + Use this command to show IPv6 routes. + + + Check the many parameters available for the `show ipv6 route` command: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 route + Possible completions: + <Enter> Execute the current command + <X:X::X:X> Show IPv6 routes of given address or prefix + <X:X::X:X/M> + bgp Show IPv6 BGP routes + cache Show kernel IPv6 route cache + connected Show IPv6 connected routes + forward Show kernel IPv6 route table + isis Show IPv6 ISIS routes + kernel Show IPv6 kernel routes + ospfv3 Show IPv6 OSPF6 routes + ripng Show IPv6 RIPNG routes + static Show IPv6 static routes + summary Show IPv6 routes summary + table Show IP routes in policy table + + +.. opcmd:: show ipv6 prefix-list + + Use this command to show all IPv6 prefix lists + + There are different parameters for getting prefix-list information: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 prefix-list + Possible completions: + <Enter> Execute the current command + <WORD> Show specified IPv6 prefix-list + detail Show detail of IPv6 prefix-lists + summary Show summary of IPv6 prefix-lists + +.. opcmd:: show ipv6 access-list + + Use this command to show all IPv6 access lists + + You can also specify which IPv6 access-list should be shown: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 access-list + Possible completions: + <Enter> Execute the current command + <text> Show specified IPv6 access-list + + + +.. opcmd:: show ipv6 bgp + + Use this command to show IPv6 Border Gateway Protocol information. + + + In addition, you can specify many other parameters to get BGP + information: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 bgp + Possible completions: + <Enter> Execute the current command + <X:X::X:X> Show BGP information for given address or prefix + <X:X::X:X/M> + community Show routes matching the communities + community-list + Show routes matching the community-list + filter-list Show routes conforming to the filter-list + large-community + Show routes matching the large-community-list + large-community-list + neighbors Show detailed information on TCP and BGP neighbor connections + prefix-list Show routes matching the prefix-list + regexp Show routes matching the AS path regular expression + summary Show summary of BGP neighbor status + + + +.. opcmd:: show ipv6 ospfv3 + + Use this command to get information about OSPFv3. + + You can get more specific OSPFv3 information by using the parameters + shown below: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 ospfv3 + Possible completions: + <Enter> Execute the current command + area Show OSPFv3 spf-tree information + border-routers + Show OSPFv3 border-router (ABR and ASBR) information + database Show OSPFv3 Link state database information + interface Show OSPFv3 interface information + linkstate Show OSPFv3 linkstate routing information + neighbor Show OSPFv3 neighbor information + redistribute Show OSPFv3 redistribute External information + route Show OSPFv3 routing table information + +.. opcmd:: show ipv6 ripng + + Use this command to get information about the RIPNG protocol + +.. opcmd:: show ipv6 ripng status + + Use this command to show the status of the RIPNG protocol + + + +Reset commands +^^^^^^^^^^^^^^ + +.. opcmd:: reset ipv6 bgp <address> + + Use this command to clear Border Gateway Protocol statistics or + status. + + +.. opcmd:: reset ipv6 neighbors <address | interface> + + Use this command to reset IPv6 Neighbor Discovery Protocol cache for + an address or interface. + +.. opcmd:: reset ipv6 route cache + + Use this command to flush the kernel IPv6 route cache. + An address can be added to flush it only for that route. + + + diff --git a/docs/configuration/system/login.rst b/docs/configuration/system/login.rst new file mode 100644 index 00000000..c34e41a0 --- /dev/null +++ b/docs/configuration/system/login.rst @@ -0,0 +1,129 @@ +.. _systemusers: + +Login +----- + +The default VyOS user account (`vyos`), as well as newly created user accounts, +have all capabilities to configure the system. All accounts have sudo capabilities +and therefore can operate as root on the system. Setting the level to admin is +optional, all accounts on the system will have admin privileges. + +Both local administered and remote administered RADIUS (Remote Authentication +Dial-In User Service) accounts are supported. + +Local +^^^^^ + +Create user account `jsmith` and the password `mypassword`. + +.. code-block:: none + + set system login user jsmith full-name "Johan Smith" + set system login user jsmith authentication plaintext-password mypassword + +The command: + +.. code-block:: none + + show system login + +will show the contents of :code:`system login` configuration node: + +.. code-block:: none + + user jsmith { + authentication { + encrypted-password $6$0OQHjuQ8M$AYXVn7jufdfqPrSk4/XXsDBw99JBtNsETkQKDgVLptXogHA2bU9BWlvViOFPBoFxIi.iqjqrvsQdQ./cfiiPT. + plaintext-password "" + } + full-name "Johan Smith" + level admin + } + +SSH with Public Keys +******************** + +The following command will load the public key `dev.pub` for user `jsmith` + +.. code-block:: none + + loadkey jsmith dev.pub + +.. note:: This requires uploading the `dev.pub` public key to the VyOS router + first. As an alternative you can also load the SSH public key directly + from a remote system: + +.. code-block:: none + + loadkey jsmith scp://devuser@dev001.vyos.net/home/devuser/.ssh/dev.pub + +In addition SSH public keys can be fully added using the CLI. Each key can be +given a unique identifier, `calypso` is used oin the example below to id an SSH +key. + +.. code-block:: none + + set system login user jsmith authentication public-keys callisto key 'AAAAB3Hso...Q==' + set system login user jsmith authentication public-keys callisto type 'ssh-rsa' + +RADIUS +^^^^^^ + +VyOS supports using one or more RADIUS servers as backend for user authentication. + +The following command sets up two servers for RADIUS authentication, one with a +discrete timeout of `5` seconds and a discrete port of `1812` and the other using +a default timeout and port. + +.. code-block:: none + + set system login radius-server 192.168.1.2 secret 's3cr3t0815' + set system login radius-server 192.168.1.2 timeout '5' + set system login radius-server 192.168.1.2 port '1812' + set system login radius-server 192.168.1.3 secret 's3cr3t0816' + +This configuration results in: + +.. code-block:: none + + show system login + radius-server 192.168.1.2 { + secret s3cr3t0815 + timeout 5 + port 1812 + } + radius-server 192.168.1.3 { + secret s3cr3t0816 + } + +.. note:: If you wan't to have admin users to authenticate via RADIUS it is + essential to sent the ``Cisco-AV-Pair shell:priv-lvl=15`` attribute. Without + the attribute you will only get regular, non privilegued, system users. + +Source Address +************** + +RADIUS servers could be hardened by only allowing certain IP addresses to connect. +As of this the source address of each RADIUS query can be configured. If this is +not set incoming connections to the RADIUS server will use the nearest interface +address pointing towards the RADIUS server - making it error prone on e.g. OSPF +networks when a link fails. + +.. code-block:: none + + set system login radius-source-address 192.168.1.254 + +Login Banner +^^^^^^^^^^^^ + +You are able to set post-login or pre-login messages with the following lines: + +.. code-block:: none + + set system login banner pre-login "UNAUTHORIZED USE OF THIS SYSTEM IS PROHIBITED\n" + set system login banner post-login "Welcome to VyOS" + +the **\\n** create a newline. + + + diff --git a/docs/configuration/system/name-server.rst b/docs/configuration/system/name-server.rst new file mode 100644 index 00000000..70848f6d --- /dev/null +++ b/docs/configuration/system/name-server.rst @@ -0,0 +1,68 @@ +.. _system-dns: + +########## +System DNS +########## + + +This section describes configuring DNS on the system, namely: + + * DNS name servers + * Domain search order + + +DNS name servers +================ + +.. cfgcmd:: set system name-server <address> + + Use this command to specify a DNS server for the system to be used + for DNS lookups. More than one DNS server can be added, configuring + one at a time. Both IPv4 and IPv6 addresses are supported. + + + +Example +------- + +In this example, some *OpenNIC* servers are used, two IPv4 addresses +and two IPv6 addresses: + + +.. code-block:: none + + set system name-server 176.9.37.132 + set system name-server 195.10.195.195 + set system name-server 2a01:4f8:161:3441::1 + set system name-server 2a00:f826:8:2::195 + + +Domain search order +=================== + +In order for the system to use and complete unqualified host names, a +list can be defined which will be used for domain searches. + + +.. cfgcmd:: set system domain-search domain <domain> + + Use this command to define domains, one at a time, so that the system + uses them to complete unqualified host names. Maximum: 6 entries. + + +.. note:: Domain names can include letters, numbers, hyphens and periods + with a maximum length of 253 characters. + + +Example +------- + +The system is configured to attempt domain completion in the following +order: vyos.io (first), vyos.net (second) and vyos.network (last): + + +.. code-block:: none + + set system domain-search domain vyos.io + set system domain-search domain vyos.net + set system domain-search domain vyos.network diff --git a/docs/configuration/system/ntp.rst b/docs/configuration/system/ntp.rst new file mode 100644 index 00000000..95ff0692 --- /dev/null +++ b/docs/configuration/system/ntp.rst @@ -0,0 +1,19 @@ +.. _ntp: + +NTP +=== + +there are 3 default NTP server set. You are able to change them. + +.. code-block:: none + + set system ntp server 0.pool.ntp.org + set system ntp server 1.pool.ntp.org + set system ntp server 2.pool.ntp.org + +To set up VyOS as an NTP responder, you must specify the listen address and optionally the permitted clients. + +.. code-block:: none + + set system ntp listen-address 192.168.199.1 + set system ntp allow-clients address 192.168.199.0/24 diff --git a/docs/configuration/system/syslog.rst b/docs/configuration/system/syslog.rst new file mode 100644 index 00000000..9f3e1a28 --- /dev/null +++ b/docs/configuration/system/syslog.rst @@ -0,0 +1,224 @@ +.. _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 +`local7` error messages, emergency messages will be sent to the console, too. + +To configure syslog, you need to switch into configuration mode. + +Logging +======= + +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. + +Console +------- + +.. cfgcmd:: set system syslog console facility <keyword> level <keyword> + +Log syslog messages to ``/dev/console``, for an explanation on +:ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords +see tables below. + + +Custom File +----------- + +.. cfgcmd:: set system syslog file <filename> facility <keyword> level <keyword> + +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. + +.. cfgcmd:: set system syslog file <filename> archive size <size> + +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> + +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. + + +Remote Host +----------- + +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. + + +.. cfgcmd:: set system syslog host <address> facility <keyword> level <keyword> + +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. + + +.. cfgcmd:: set system syslog host <address> facility <keyword> protocol <udp|tcp> + +Configure protocol used for communication to remote syslog host. This can be +either UDP or TCP. + + +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 + :header-rows: 0 + + * - all + - Display contents of all master log files of the specified image + * - authorization + - Display all authorization attempts of the specified image + * - directory + - Display list of all user-defined log files of the specified image + * - file <file name> + - Display contents of a specified user-defined log file of the specified image + * - tail + - Display last lines of the system log of the specified image + * - <lines> + - Number of lines to be displayed, default 10 + +When no options/parameters are used, the contents of the main syslog file are +displayed. diff --git a/docs/configuration/system/task-scheduler.rst b/docs/configuration/system/task-scheduler.rst new file mode 100644 index 00000000..7fe49988 --- /dev/null +++ b/docs/configuration/system/task-scheduler.rst @@ -0,0 +1,60 @@ +.. _task-scheduler: + + +Task scheduler +-------------- + +| Task scheduler — allows scheduled task execution. Note that scripts excecuted this way are executed as root user - this may be dangerous. +| Together with :ref:`commandscripting` this can be used for automating configuration. + +.. code-block:: none + + system + task-scheduler + task <name> + cron-spec <UNIX cron time spec> + executable + arguments <arguments string> + path <path to executable> + interval + <int32>[mhd] + +Interval +******** + +You are able to set the time as an time interval. + +.. code-block:: none + + set system task-scheduler task <name> interval <value><suffix> + +Sets the task to execute every N minutes, hours, or days. Suffixes: + + * m — minutes + * h — hours + * d — days + +If suffix is omitted, minutes are implied. + +Or set the execution time in common cron time. + +.. code-block:: none + + set system task-scheduler task TEST crontab-spec "* * * 1 *" + +Example +******* + +.. code-block:: none + + system + task-scheduler + task mytask + interval 2h + executable + path /config/scripts/mytask + arguments "arg1 arg2 arg3" + task anothertask + cron-spec "* * * 1 *" + executable + path /config/scripts/anothertask
\ No newline at end of file diff --git a/docs/configuration/system/time-zone.rst b/docs/configuration/system/time-zone.rst new file mode 100644 index 00000000..9e1690e8 --- /dev/null +++ b/docs/configuration/system/time-zone.rst @@ -0,0 +1,11 @@ +.. _timezone: + +Time Zone +========= + +To set the system time zone type: + +.. code-block:: none + + [edit] + vyos@vyos# set system time-zone [time-zone]
\ No newline at end of file |