From e33e1268f944be445b5a771df0e97e913487512f Mon Sep 17 00:00:00 2001 From: rebortg Date: Mon, 30 Nov 2020 19:46:59 +0100 Subject: change include to absolute path --- docs/system/lcd.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/system') diff --git a/docs/system/lcd.rst b/docs/system/lcd.rst index 441becf5..2509946e 100644 --- a/docs/system/lcd.rst +++ b/docs/system/lcd.rst @@ -41,5 +41,5 @@ Configuration .. note:: We can't support all displays from the beginning. If your display type is missing, please create a feature request via Phabricator_. -.. include:: ../common-references.rst +.. include:: /common-references.rst -- cgit v1.2.3 From b1cb71c71935ad6b0a7d9effe8f4dc4467de2175 Mon Sep 17 00:00:00 2001 From: rebortg Date: Mon, 30 Nov 2020 21:15:16 +0100 Subject: arrange: system configration --- docs/automation/index.rst | 3 +- docs/configuration/system/acceleration.rst | 7 + docs/configuration/system/config-management.rst | 2 + docs/configuration/system/conntrack.rst | 2 + docs/configuration/system/console.rst | 43 ++++ docs/configuration/system/default-route.rst | 40 ++++ docs/configuration/system/domain-name.rst | 2 + docs/configuration/system/domain-search.rst | 2 + docs/configuration/system/eventhandler.rst | 48 +++++ docs/configuration/system/flow-accounting.rst | 203 ++++++++++++++++++ docs/configuration/system/host-name.rst | 63 ++++++ docs/configuration/system/index.rst | 32 +++ docs/configuration/system/ip.rst | 2 + docs/configuration/system/ipv6.rst | 2 + docs/configuration/system/lcd.rst | 45 ++++ docs/configuration/system/login.rst | 160 +++++++++++++++ docs/configuration/system/name-server.rst | 69 +++++++ docs/configuration/system/name-servers-dhcp.rst | 2 + docs/configuration/system/ntp.rst | 56 +++++ docs/configuration/system/option.rst | 94 +++++++++ docs/configuration/system/proxy.rst | 28 +++ docs/configuration/system/static-host-mapping.rst | 2 + docs/configuration/system/sysctl.rst | 2 + docs/configuration/system/syslog.rst | 226 +++++++++++++++++++++ docs/configuration/system/task-scheduler.rst | 40 ++++ docs/configuration/system/time-zone.rst | 18 ++ .../system/wifi-requlatory-domain.rst | 2 + docs/index.rst | 8 +- docs/information.rst | 97 --------- docs/operation/boot-options.rst | 57 ++++++ docs/operation/information.rst | 97 +++++++++ docs/system/advanced-index.rst | 19 -- docs/system/basic-index.rst | 14 -- docs/system/boot-options.rst | 57 ------ docs/system/default-route.rst | 40 ---- docs/system/eventhandler.rst | 48 ----- docs/system/flow-accounting.rst | 203 ------------------ docs/system/host-information.rst | 63 ------ docs/system/lcd.rst | 45 ---- docs/system/ntp.rst | 56 ----- docs/system/option.rst | 94 --------- docs/system/proxy.rst | 28 --- docs/system/serial-console.rst | 43 ---- docs/system/syslog.rst | 226 --------------------- docs/system/system-dns.rst | 69 ------- docs/system/task-scheduler.rst | 40 ---- docs/system/time-zone.rst | 18 -- docs/system/user-management.rst | 160 --------------- 48 files changed, 1352 insertions(+), 1325 deletions(-) create mode 100644 docs/configuration/system/acceleration.rst create mode 100644 docs/configuration/system/config-management.rst create mode 100644 docs/configuration/system/conntrack.rst create mode 100644 docs/configuration/system/console.rst create mode 100644 docs/configuration/system/default-route.rst create mode 100644 docs/configuration/system/domain-name.rst create mode 100644 docs/configuration/system/domain-search.rst create mode 100644 docs/configuration/system/eventhandler.rst create mode 100644 docs/configuration/system/flow-accounting.rst create mode 100644 docs/configuration/system/host-name.rst create mode 100644 docs/configuration/system/index.rst create mode 100644 docs/configuration/system/ip.rst create mode 100644 docs/configuration/system/ipv6.rst create mode 100644 docs/configuration/system/lcd.rst create mode 100644 docs/configuration/system/login.rst create mode 100644 docs/configuration/system/name-server.rst create mode 100644 docs/configuration/system/name-servers-dhcp.rst create mode 100644 docs/configuration/system/ntp.rst create mode 100644 docs/configuration/system/option.rst create mode 100644 docs/configuration/system/proxy.rst create mode 100644 docs/configuration/system/static-host-mapping.rst create mode 100644 docs/configuration/system/sysctl.rst create mode 100644 docs/configuration/system/syslog.rst create mode 100644 docs/configuration/system/task-scheduler.rst create mode 100644 docs/configuration/system/time-zone.rst create mode 100644 docs/configuration/system/wifi-requlatory-domain.rst delete mode 100644 docs/information.rst create mode 100644 docs/operation/boot-options.rst create mode 100644 docs/operation/information.rst delete mode 100644 docs/system/advanced-index.rst delete mode 100644 docs/system/basic-index.rst delete mode 100644 docs/system/boot-options.rst delete mode 100644 docs/system/default-route.rst delete mode 100644 docs/system/eventhandler.rst delete mode 100644 docs/system/flow-accounting.rst delete mode 100644 docs/system/host-information.rst delete mode 100644 docs/system/lcd.rst delete mode 100644 docs/system/ntp.rst delete mode 100644 docs/system/option.rst delete mode 100644 docs/system/proxy.rst delete mode 100644 docs/system/serial-console.rst delete mode 100644 docs/system/syslog.rst delete mode 100644 docs/system/system-dns.rst delete mode 100644 docs/system/task-scheduler.rst delete mode 100644 docs/system/time-zone.rst delete mode 100644 docs/system/user-management.rst (limited to 'docs/system') diff --git a/docs/automation/index.rst b/docs/automation/index.rst index 1f2b40b1..e07dfecc 100644 --- a/docs/automation/index.rst +++ b/docs/automation/index.rst @@ -12,5 +12,4 @@ VyOS Automation .. toctree:: :maxdepth: 1 - command-scripting - http-api \ No newline at end of file + command-scripting \ No newline at end of file diff --git a/docs/configuration/system/acceleration.rst b/docs/configuration/system/acceleration.rst new file mode 100644 index 00000000..b09da38b --- /dev/null +++ b/docs/configuration/system/acceleration.rst @@ -0,0 +1,7 @@ +.. _acceleration: + +############ +Acceleration +############ + + diff --git a/docs/configuration/system/config-management.rst b/docs/configuration/system/config-management.rst new file mode 100644 index 00000000..40973713 --- /dev/null +++ b/docs/configuration/system/config-management.rst @@ -0,0 +1,2 @@ +config-management +################# \ No newline at end of file diff --git a/docs/configuration/system/conntrack.rst b/docs/configuration/system/conntrack.rst new file mode 100644 index 00000000..7d5d4308 --- /dev/null +++ b/docs/configuration/system/conntrack.rst @@ -0,0 +1,2 @@ +conntrack +######### \ No newline at end of file diff --git a/docs/configuration/system/console.rst b/docs/configuration/system/console.rst new file mode 100644 index 00000000..4a750ada --- /dev/null +++ b/docs/configuration/system/console.rst @@ -0,0 +1,43 @@ +.. _serial-console: + +############## +Serial Console +############## + +For the average user a serial console has no advantage over a console offered +by a directly attached keyboard and screen. Serial consoles are much slower, +taking up to a second to fill a 80 column by 24 line screen. Serial consoles +generally only support non-proportional ASCII text, with limited support for +languages other than English. + +There are some scenarios where serial consoles are useful. System administration +of remote computers is usually done using :ref:`ssh`, but there are times when +access to the console is the only way to diagnose and correct software failures. +Major upgrades to the installed distribution may also require console access. + + +.. cfgcmd:: set system console device + + Defines the specified device as a system console. Available console devices + can be (see completion helper): + + * ``ttySN`` - Serial device name + * ``ttyUSBX`` - USB Serial device name + * ``hvc0`` - Xen console + +.. cfgcmd:: set system console device speed + + The speed (baudrate) of the console device. Supported values are: + + * ``1200`` - 1200 bps + * ``2400`` - 2400 bps + * ``4800`` - 4800 bps + * ``9600`` - 9600 bps + * ``19200`` - 19,200 bps + * ``38400`` - 38,400 bps (default for Xen console) + * ``57600`` - 57,600 bps + * ``115200`` - 115,200 bps (default for serial console) + + .. note:: If you use a USB to serial converter please note that most of them + use software emulation without flow control, thus you should start with a + common baud rate of 9600 as otherwise you could get diff --git a/docs/configuration/system/default-route.rst b/docs/configuration/system/default-route.rst new file mode 100644 index 00000000..27c74188 --- /dev/null +++ b/docs/configuration/system/default-route.rst @@ -0,0 +1,40 @@ +.. _default_gateway: + +##################### +Default Gateway/Route +##################### + +In the past (VyOS 1.1) used a gateway-address configured under the system tree +(:cfgcmd:`set system gateway-address
`), this is no longer supported +and existing configurations are migrated to the new CLI command. + +Configuration +============= + +.. cfgcmd:: set protocols static route 0.0.0.0/0 next-hop
+ + Specify static route into the routing table sending all non local traffic + to the nexthop address `
`. + + +.. cfgcmd:: delete protocols static route 0.0.0.0/0 + + Delete default route from the system. + +Operation +========= + +.. opcmd:: show ip route 0.0.0.0 + + Show routing table entry for the 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 10, metric 0, best + Last update 09:46:30 ago + * 172.18.201.254, via eth0.201 + +.. seealso:: Configuration of :ref:`static-routing` + diff --git a/docs/configuration/system/domain-name.rst b/docs/configuration/system/domain-name.rst new file mode 100644 index 00000000..9028b65b --- /dev/null +++ b/docs/configuration/system/domain-name.rst @@ -0,0 +1,2 @@ +domain-name +########### \ No newline at end of file diff --git a/docs/configuration/system/domain-search.rst b/docs/configuration/system/domain-search.rst new file mode 100644 index 00000000..f4aef62e --- /dev/null +++ b/docs/configuration/system/domain-search.rst @@ -0,0 +1,2 @@ +domain-search +############# \ 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..a68b3924 --- /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 + description + policy + source + preset + syslog # Use the syslog logs for feed + custom + command # E.g. "tail -f /var/log/somelogfile" + named-pipe + policy + description + event + description + pattern + 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..f09c1c9a --- /dev/null +++ b/docs/configuration/system/flow-accounting.rst @@ -0,0 +1,203 @@ +.. _flow-accounting: + +############### +Flow Accounting +############### + +VyOS supports flow-accounting for both IPv4 and IPv6 traffic. The system acts +as a flow exporter, and you are free to use it with any compatible collector. + +Flows can be exported via two different protocols: NetFlow (versions 5, 9 and +10/IPFIX) and sFlow. Additionally, you may save flows to an in-memory table +internally in a router. + +.. warning:: You need to disable the in-memory table in production environments! + Using :abbr:`IMT (In-Memory Table)` may lead to heavy CPU overloading and + unstable flow-accounting behavior. + + +NetFlow / IPFIX +=============== +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: + +* **exporter**: aggregates packets into flows and exports flow records towards + one or more flow collectors +* **collector**: responsible for reception, storage and pre-processing of flow + data received from a flow exporter +* **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. + +Configuration +============= + +In order for flow accounting information to be collected and displayed for an +interface, the interface must be configured for flow accounting. + +.. cfgcmd:: set system flow-accounting interface + + Configure and enable collection of flow information for the interface + identified by ``. + + You can configure multiple interfaces which whould participate in flow + accounting. + +.. note:: Will be recorded only packets/flows on **incoming** direction in + configured interfaces. + + +By default, recorded flows will be saved internally and can be listed with the +CLI command. You may disable using the local in-memory table with the command: + +.. cfgcmd:: set system flow-accounting disable-imt + + Internally, in flow-accounting processes exist a buffer for data exchanging + between core process and plugins (each export target is a separated plugin). + If you have high traffic levels or noted some problems with missed records + or stopping exporting, you may try to increase a default buffer size (10 + MiB) with the next command: + +.. cfgcmd:: set system flow-accounting buffer-size + + In case, if you need to catch some logs from flow-accounting daemon, you may + configure logging facility: + +.. cfgcmd:: set system flow-accounting syslog-facility + + TBD + +Flow Export +----------- + +In addition to displaying flow accounting information locally, one can also +exported them to a collection server. + +NetFlow +^^^^^^^ + +.. cfgcmd:: set system flow-accounting netflow version + + There are multiple versions available for the NetFlow data. The `` + used in the exported flow data can be configured here. The following + versions are supported: + + * **5** - Most common version, but restricted to IPv4 flows only + * **9** - NetFlow version 9 (default) + * **10** - :abbr:`IPFIX (IP Flow Information Export)` as per :rfc:`3917` + +.. cfgcmd:: set system flow-accounting netflow server
+ + Configure address of NetFlow collector. NetFlow server at `
` can + be both listening on an IPv4 or IPv6 address. + +.. cfgcmd:: set system flow-accounting netflow source-ip
+ + IPv4 or IPv6 source address of NetFlow packets + +.. cfgcmd:: set system flow-accounting netflow engine-id + + NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255. + +.. cfgcmd:: set system flow-accounting netflow sampling-rate + + Use this command to configure the sampling rate for flow accounting. The + system samples one in every `` packets, where `` is the value + configured for the sampling-rate option. The advantage of sampling every n + packets, where n > 1, allows you to decrease the amount of processing + resources required for flow accounting. The disadvantage of not sampling + every packet is that the statistics produced are estimates of actual data + flows. + + Per default every packet is sampled (that is, the sampling rate is 1). + +.. cfgcmd:: set system flow-accounting netflow timeout expiry-interval + + Specifies the interval at which Netflow data will be sent to a collector. As + per default, Netflow data will be sent every 60 seconds. + + You may also additionally configure timeouts for different types of + connections. + +.. cfgcmd:: set system flow-accounting netflow max-flows + + If you want to change the maximum number of flows, which are tracking + simultaneously, you may do this with this command (default 8192). + +sFlow +^^^^^ + +.. cfgcmd:: set system flow-accounting sflow server
+ + Configure address of sFlow collector. sFlow server at `
` can + be an IPv4 or IPv6 address. But you cannot export to both IPv4 and + IPv6 collectors at the same time! + +.. cfgcmd:: set system flow-accounting sflow sampling-rate + + Enable sampling of packets, which will be transmitted to sFlow collectors. + +.. cfgcmd:: set system flow-accounting sflow agent-address
+ + Configure a sFlow agent address. It can be IPv4 or IPv6 address, but you + must set the same protocol, which is used for sFlow collector addresses. By + default, using router-id from BGP or OSPF protocol, or the primary IP + address from the first interface. + +Example: +-------- + +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 + +Operation +========= + +Once flow accounting is configured on an interfaces it provides the ability to +display captured network traffic information for all configured interfaces. + +.. opcmd:: show flow-accounting interface + + Show flow accounting information for given ``. + + .. code-block:: none + + vyos@vyos:~$ show flow-accounting interface eth0 + IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES + ---------- ----------------- ----------------- ------------------------ --------------- ---------- ---------- ---------- ----- --------- ------- ------- + eth0 00:53:01:a8:28:ac ff:ff:ff:ff:ff:ff 192.0.2.2 255.255.255.255 5678 5678 udp 0 1 1 178 + eth0 00:53:01:b2:2f:34 33:33:ff:00:00:00 fe80::253:01ff:feb2:2f34 ff02::1:ff00:0 0 0 ipv6-icmp 0 2 1 144 + eth0 00:53:01:1a:b4:53 33:33:ff:00:00:00 fe80::253:01ff:fe1a:b453 ff02::1:ff00:0 0 0 ipv6-icmp 0 1 1 72 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 39 1 2064 + eth0 00:53:01:c8:33:af ff:ff:ff:ff:ff:ff 192.0.2.3 255.255.255.255 5678 5678 udp 0 1 1 154 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 146 1 9444 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 27 1 4455 + +.. opcmd:: show flow-accounting interface host
+ + Show flow accounting information for given `` for a specific host + only. + + .. code-block:: none + + vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.14 + IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES + ---------- ----------------- ----------------- ----------- ---------- ---------- ---------- ---------- ----- --------- ------- ------- + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 197 2 12940 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 94 1 4924 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 36 1 5877 diff --git a/docs/configuration/system/host-name.rst b/docs/configuration/system/host-name.rst new file mode 100644 index 00000000..30efe01e --- /dev/null +++ b/docs/configuration/system/host-name.rst @@ -0,0 +1,63 @@ +.. _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 +* Aliases + +Hostname +======== + +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. On the other hand this will be the name which appears on +the command line prompt. + +.. cfgcmd:: set system host-name + + Set system hostname. The hostname can be up to 63 characters. A hostname + must start and end with a letter or digit, and have as interior characters + only letters, digits, or a hyphen. + + The default hostname used is `vyos`. + +Domain Name +=========== + +A domain name is the label (name) assigned to a computer network and is thus +unique. VyOS appends the domain name as a suffix to any unqualified name. For +example, if you set the domain name `example.com`, and you would ping the +unqualified name of `crux`, then VyOS qualifies the name to `crux.example.com`. + +.. cfgcmd:: set system domain-name + + Configure system domain name. A domain name must start and end with a letter + or digit, and have as interior characters only letters, digits, or a hyphen. + +Static Hostname Mapping +======================= + +How an IP address is assigned to an interface in :ref:`ethernet-interface`. +This section shows how to statically map an IP address to a hostname for local +(meaning on this VyOS instance) name resolution. + +.. cfgcmd:: set system static-host-mapping host-name inet
+ + Create a static hostname mapping which will always resolve the name + `` to IP address `
`. + + +.. cfgcmd:: set system static-host-mapping host-name alias + + Create named `` for the configured static mapping for ``. + Thus the address configured as :cfgcmd:`set system static-host-mapping + host-name inet
` can be reached via multiple names. + + Multiple aliases can pe specified per host-name. diff --git a/docs/configuration/system/index.rst b/docs/configuration/system/index.rst new file mode 100644 index 00000000..ecf09a64 --- /dev/null +++ b/docs/configuration/system/index.rst @@ -0,0 +1,32 @@ +###### +System +###### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + acceleration + config-management + conntrack + console + domain-name + domain-search + flow-accounting + host-name + ip + ipv6 + lcd + login + name-server + name-servers-dhcp + ntp + options + proxy + static-host-mapping + sysctl + syslog + task-scheduler + time-zone + wifi-requlatory-domain diff --git a/docs/configuration/system/ip.rst b/docs/configuration/system/ip.rst new file mode 100644 index 00000000..74116eb0 --- /dev/null +++ b/docs/configuration/system/ip.rst @@ -0,0 +1,2 @@ +ip +## \ No newline at end of file diff --git a/docs/configuration/system/ipv6.rst b/docs/configuration/system/ipv6.rst new file mode 100644 index 00000000..19ed6d62 --- /dev/null +++ b/docs/configuration/system/ipv6.rst @@ -0,0 +1,2 @@ +ipv6 +#### \ No newline at end of file diff --git a/docs/configuration/system/lcd.rst b/docs/configuration/system/lcd.rst new file mode 100644 index 00000000..2509946e --- /dev/null +++ b/docs/configuration/system/lcd.rst @@ -0,0 +1,45 @@ +.. _system-display: + +******************** +System Display (LCD) +******************** + +The system LCD :abbr:`LCD (Liquid-crystal display)` option is for users running +VyOS on hardware that features an LCD display. This is typically a small display +built in an 19 inch rack-mountable appliance. Those displays are used to show +runtime data. + +To configure your LCD display you must first identify the used hardware, and +connectivity of the display to your system. This can be any serial port +(`ttySxx`) or serial via USB or even old parallel port interfaces. + +Configuration +============= + +.. cfgcmd:: set system lcd device + + This is the name of the physical interface used to connect to your LCD + display. Tab completion is supported and it will list you all available + serial interface. + + For serial via USB port information please refor to: :ref:`hardware_usb`. + +.. cfgcmd:: set system lcd model + + This is the LCD model used in your system. + + At the time of this writing the following displays are supported: + + * Crystalfontz CFA-533 + + * Crystalfontz CFA-631 + + * Crystalfontz CFA-633 + + * Crystalfontz CFA-635 + + .. note:: We can't support all displays from the beginning. If your display + type is missing, please create a feature request via Phabricator_. + +.. include:: /common-references.rst + diff --git a/docs/configuration/system/login.rst b/docs/configuration/system/login.rst new file mode 100644 index 00000000..6d89735f --- /dev/null +++ b/docs/configuration/system/login.rst @@ -0,0 +1,160 @@ +.. _user_management: + +############### +User Management +############### + +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. + +Both local administered and remote administered :abbr:`RADIUS (Remote +Authentication Dial-In User Service)` accounts are supported. + +Local +===== + +.. cfgcmd:: set system login user full-name "" + + Create new system user with username `` and real-name specified by + ``. + +.. cfgcmd:: set system login user authentication plaintext-password + + Specify the plaintext password user by user `` on this system. The + plaintext password will be automatically transferred into a secure hashed + password and not saved anywhere in plaintext. + +.. cfgcmd:: set system login user authentication encrypted-password + + Setup encrypted password for given username. This is useful for + transferring a hashed password from system to system. + +.. _ssh_key_based_authentication: + +Key Based Authentication +------------------------ + +It is highly recommended to use SSH key authentication. By default there is +only one user (``vyos``), and you can assign any number of keys to that user. +You can generate a ssh key with the ``ssh-keygen`` command on your local +machine, which will (by default) save it as ``~/.ssh/id_rsa.pub``. + +Every SSH key comes in three parts: + +``ssh-rsa AAAAB3NzaC1yc2EAAAABAA...VBD5lKwEWB username@host.example.com`` + +Only the type (``ssh-rsa``) and the key (``AAAB3N...``) are used. Note that the +key will usually be several hundred characters long, and you will need to copy +and paste it. Some terminal emulators may accidentally split this over several +lines. Be attentive when you paste it that it only pastes as a single line. +The third part is simply an identifier, and is for your own reference. + +.. cfgcmd:: set system login user authentication public-keys key + + Assign the SSH public key portion `` identified by per-key + `` to the local user ``. + +.. cfgcmd:: set system login user authentication public-keys type + + Every SSH public key portion referenced by `` requires the + configuration of the `` of public-key used. This type can be any of: + + * ``ecdsa-sha2-nistp256`` + * ``ecdsa-sha2-nistp384`` + * ``ecdsa-sha2-nistp521`` + * ``ssh-dss`` + * ``ssh-ed25519`` + * ``ssh-rsa`` + + .. note:: You can assign multiple keys to the same user by using a unique + identifier per SSH key. + +.. cfgcmd:: loadkey + + SSH keys can not only be specified on the command-line but also loaded for + a given user with `` from a file pointed to by `.` Keys + can be either loaded from local filesystem or any given remote location + using one of the following :abbr:`URIs (Uniform Resource Identifier)`: + + * ```` - Load from file on local filesystem path + * ``scp://@:/`` - Load via SCP from remote machine + * ``sftp://@/`` - Load via SFTP from remote machine + * ``ftp://@/`` - Load via FTP from remote machine + * ``http:///`` - Load via HTTP from remote machine + * ``tftp:///`` - Load via TFTP from remote machine + +Example +------- + +In the following example, both `User1` and `User2` will be able to SSH into +VyOS as user ``vyos`` using their very own keys. + +.. code-block:: none + + set system login user vyos authentication public-keys 'User1' key "AAAAB3Nz...KwEW" + set system login user vyos authentication public-keys 'User1' type ssh-rsa + set system login user vyos authentication public-keys 'User2' key "AAAAQ39x...fbV3" + set system login user vyos authentication public-keys 'User2' type ssh-rsa + + +RADIUS +====== + +In large deployments it is not reasonable to configure each user individually +on every system. VyOS supports using :abbr:`RADIUS (Remote Authentication +Dial-In User Service)` servers as backend for user authentication. + +Configuration +------------- + +.. cfgcmd:: set system login radius server
secret + + Specify the `
` of the RADIUS server user with the pre-shared-secret + given in ``. Multiple servers can be specified. + +.. cfgcmd:: set system login radius server
port + + Configure the discrete port under which the RADIUS server can be reached. + This defaults to 1812. + +.. cfgcmd:: set system login radius server
timeout + + Setup the `` in seconds when querying the RADIUS server. + +.. cfgcmd:: set system login radius server
disable + + Temporary disable this RADIUS server. It won't be queried. + +.. cfgcmd:: set system login radius 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 server - making + it error prone on e.g. OSPF networks when a link fails and a backup route is + taken. + +.. hint:: If you want 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. + + + +Login Banner +============ + +You are able to set post-login or pre-login banner messages to display certain +information for this system. + +.. cfgcmd:: set system login banner pre-login + + Configure `` which is shown during SSH connect and before a user is + logged in. + +.. cfgcmd:: set system login banner post-login + + Configure `` which is shown after user has logged in to the system. + +.. note:: To create a new line in your login message you need to escape the new + line character by using ``\\n``. diff --git a/docs/configuration/system/name-server.rst b/docs/configuration/system/name-server.rst new file mode 100644 index 00000000..59cfdb5d --- /dev/null +++ b/docs/configuration/system/name-server.rst @@ -0,0 +1,69 @@ +.. _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
+ + 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 + + 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/name-servers-dhcp.rst b/docs/configuration/system/name-servers-dhcp.rst new file mode 100644 index 00000000..6719fef9 --- /dev/null +++ b/docs/configuration/system/name-servers-dhcp.rst @@ -0,0 +1,2 @@ +name-servers-dhcp +################# \ No newline at end of file diff --git a/docs/configuration/system/ntp.rst b/docs/configuration/system/ntp.rst new file mode 100644 index 00000000..5fd1837f --- /dev/null +++ b/docs/configuration/system/ntp.rst @@ -0,0 +1,56 @@ +.. _ntp: + +### +NTP +### + +:abbr:`NTP (Network Time Protocol`) is a networking protocol for clock +synchronization between computer systems over packet-switched, variable-latency +data networks. In operation since before 1985, NTP is one of the oldest Internet +protocols in current use. + +NTP is intended to synchronize all participating computers to within a few +milliseconds of :abbr:`UTC (Coordinated Universal Time)`. It uses the +intersection algorithm, a modified version of Marzullo's algorithm, to select +accurate time servers and is designed to mitigate the effects of variable +network latency. NTP can usually maintain time to within tens of milliseconds +over the public Internet, and can achieve better than one millisecond accuracy +in local area networks under ideal conditions. Asymmetric routes and network +congestion can cause errors of 100 ms or more. + +The protocol is usually described in terms of a client-server model, but can as +easily be used in peer-to-peer relationships where both peers consider the other +to be a potential time source. Implementations send and receive timestamps using +:abbr:`UDP (User Datagram Protocol)` on port number 123. + +NTP supplies a warning of any impending leap second adjustment, but no +information about local time zones or daylight saving time is transmitted. + +The current protocol is version 4 (NTPv4), which is a proposed standard as +documented in :rfc:`5905`. It is backward compatible with version 3, specified +in :rfc:`1305`. + +Configuration +============= + +.. cfgcmd:: set system ntp server
+ + Configure one or more servers for synchronisation. Server name can be either + an IP address or :abbr:`FQDN (Fully Qualified Domain Name)`. + + There are 3 default NTP server set. You are able to change them. + + * 0.pool.ntp.org + * 1.pool.ntp.org + * 2.pool.ntp.org + +.. cfgcmd:: set system ntp listen-address
+ + Setup VyOS as an NTP responder, you must specify the `
` and + optionally the permitted clients. Multiple listen addresses can be + configured. + +.. cfgcmd:: set system ntp allow-clients address
+ + List of networks or client addresses permitted to contact this NTP server. + Multiple networks can be configured. diff --git a/docs/configuration/system/option.rst b/docs/configuration/system/option.rst new file mode 100644 index 00000000..e7661492 --- /dev/null +++ b/docs/configuration/system/option.rst @@ -0,0 +1,94 @@ +.. _system_option: + +####### +Options +####### + +This chapter describe the possibilities of advanced system behavior. + +******* +General +******* + +.. cfgcmd:: set system option ctrl-alt-delete + + Action which will be run once the ctrl-alt-del keystroke is received. + +.. cfgcmd:: set system option reboot-on-panic + + Automatically reboot system on kernel panic after 60 seconds. + +.. cfgcmd:: set system option startup-beep + + Play an audible beep to the system speaker when system is ready. + +*********** +HTTP client +*********** + +.. cfgcmd:: set system option http-client source-address
+ + Several commands utilize curl to initiate transfers. Configure the local + source IPv4/IPv6 address used for all CURL operations. + +.. cfgcmd:: set system option http-client source-interface + + Several commands utilize curl to initiate transfers. Configure the local + source interface used for all CURL operations. + +.. note:: `source-address` and `source-interface` can not be used at the same time. + +*************** +Keyboard Layout +*************** + +When starting a VyOS live system (the installation CD) the configured keyboard +layout defaults to US. As this might not suite everyones use case you can adjust +the used keyboard layout on the system console. + +.. cfgcmd:: set system option keyboard-layout + + Change system keyboard layout to given language. + + Defaults to ``us``. + + .. note:: Changing the keymap only has an effect on the system console, using + SSH oder Serial remote access to the device is not affected as the keyboard + layout here corresponds to your access system. + +.. _system_options_performance: + +*********** +Performance +*********** + +As more and more routers run on Hypervisors, expecially with a :abbr:`NOS +(Network Operating System)` as VyOS, it makes fewer and fewer sense to use +static resource bindings like ``smp-affinity`` as present in VyOS 1.2 and +earlier to pin certain interrupt handlers to specific CPUs. + +We now utilize `tuned` for dynamic resource balancing based on profiles. + + .. seealso:: https://access.redhat.com/sites/default/files/attachments/201501-perf-brief-low-latency-tuning-rhel7-v2.1.pdf + +.. cfgcmd:: set system option performance < throughput | latency > + + Configure one of the predefined system performance profiles. + + * ``throughput``: A server profile focused on improving network throughput. + This profile favors performance over power savings by setting ``intel_pstate`` + and ``max_perf_pct=100`` and increasing kernel network buffer sizes. + + It enables transparent huge pages, and uses cpupower to set the performance + cpufreq governor. It also sets ``kernel.sched_min_granularity_ns`` to 10 us, + ``kernel.sched_wakeup_granularity_ns`` to 15 uss, and ``vm.dirty_ratio`` to + 40%. + + * ``latency``: A server profile focused on lowering network latency. + This profile favors performance over power savings by setting ``intel_pstate`` + and ``min_perf_pct=100``. + + It disables transparent huge pages, and automatic NUMA balancing. It also + uses cpupower to set the performance cpufreq governor, and requests a + cpu_dma_latency value of 1. It also sets busy_read and busy_poll times to + 50 us, and tcp_fastopen to 3. diff --git a/docs/configuration/system/proxy.rst b/docs/configuration/system/proxy.rst new file mode 100644 index 00000000..8e0339a7 --- /dev/null +++ b/docs/configuration/system/proxy.rst @@ -0,0 +1,28 @@ +.. _system_proxy: + +############ +System Proxy +############ + +Some IT environments require the use of a proxy to connect to the Internet. +Without this configuration VyOS updates could not be installed directly by +using the :opcmd:`add system image` command (:ref:`update_vyos`). + +.. cfgcmd:: set system proxy url + + Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and + FTP (anonymous ftp). + +.. cfgcmd:: set system proxy port + + Configure proxy port if it does not listen to the default port 80. + +.. cfgcmd:: set system proxy username + + Some proxys require/support the "basic" HTTP authentication scheme as per + :rfc:`7617`, thus a username can be configured. + +.. cfgcmd:: set system proxy password + + Some proxys require/support the "basic" HTTP authentication scheme as per + :rfc:`7617`, thus a password can be configured. diff --git a/docs/configuration/system/static-host-mapping.rst b/docs/configuration/system/static-host-mapping.rst new file mode 100644 index 00000000..97d9a443 --- /dev/null +++ b/docs/configuration/system/static-host-mapping.rst @@ -0,0 +1,2 @@ +static-host-mapping +################### \ No newline at end of file diff --git a/docs/configuration/system/sysctl.rst b/docs/configuration/system/sysctl.rst new file mode 100644 index 00000000..82ffd159 --- /dev/null +++ b/docs/configuration/system/sysctl.rst @@ -0,0 +1,2 @@ +sysctl +###### \ No newline at end of file diff --git a/docs/configuration/system/syslog.rst b/docs/configuration/system/syslog.rst new file mode 100644 index 00000000..3449c15b --- /dev/null +++ b/docs/configuration/system/syslog.rst @@ -0,0 +1,226 @@ +.. _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 level + +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 facility level + +Log syslog messages to file specified via ``, for en explanation on +:ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords see +tables below. + +.. cfgcmd:: set system syslog file archive size + +Syslog will write `` kilobytes into the file specified by ``. +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 archive file + +Syslog uses logrotate to rotate logiles after a number of gives bytes. We keep +as many as `` 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
facility level + +Log syslog messages to remote host specified by `
`. 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
facility protocol + +Configure protocol used for communication to remote syslog host. This can be +either UDP or TCP. + + +Local User Account +------------------ + +.. cfgcmd:: set system syslog user facility level + +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 [all | authorization | directory | file | tail ] + +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 + - 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 + * - + - Number of lines to be displayed, default 10 + +When no options/parameters are used, the contents of the main syslog file are +displayed. + +.. hint:: Use ``show log | strip-private`` if you want to hide private data when sharing your logs. diff --git a/docs/configuration/system/task-scheduler.rst b/docs/configuration/system/task-scheduler.rst new file mode 100644 index 00000000..382da39f --- /dev/null +++ b/docs/configuration/system/task-scheduler.rst @@ -0,0 +1,40 @@ +.. _task-scheduler: + +############## +Task Scheduler +############## + +The task scheduler allows you to execute tasks on a given schedule. It makes +use of UNIX cron_. + +.. note:: All scripts excecuted this way are executed as root user - this may + be dangerous. Together with :ref:`command-scripting` this can be used for + automating (re-)configuration. + +.. cfgcmd:: set system task-scheduler task interval + + Specify the time interval when `` should be executed. The interval + is specified as number with one of the following suffixes: + + * ``none`` - Execution interval in minutes + * ``m`` - Execution interval in minutes + * ``h`` - Execution interval in hours + * ``d`` - Execution interval in days + + .. note:: If suffix is omitted, minutes are implied. + +.. cfgcmd:: set system task-scheduler task crontab-spec + + Set execution time in common cron_ time format. A cron `` of + ``30 */6 * * *`` would execute the `` at minute 30 past every 6th hour. + +.. cfgcmd:: set system task-scheduler task executable path + + Specify absolute `` to script which will be run when `` is + executed. + +.. cfgcmd:: set system task-scheduler task executable arguments + + Arguments which will be passed to the executable. + +.. _cron: https://en.wikipedia.org/wiki/Cron diff --git a/docs/configuration/system/time-zone.rst b/docs/configuration/system/time-zone.rst new file mode 100644 index 00000000..025c4376 --- /dev/null +++ b/docs/configuration/system/time-zone.rst @@ -0,0 +1,18 @@ +.. _timezone: + +######### +Time Zone +######### + +Time Zone setting is very important as e.g all your logfile entries will be +based on the configured zone. Without proper time zone configuration it will +be very difficult to compare logfiles from different systems. + +.. cfgcmd:: set system time-zone + + Specify the systems `` as the Region/Location that best defines + your location. For example, specifying US/Pacific sets the time zone to US + Pacific time. + + Command completion can be used to list available time zones. The adjustment + for daylight time will take place automatically based on the time of year. \ No newline at end of file diff --git a/docs/configuration/system/wifi-requlatory-domain.rst b/docs/configuration/system/wifi-requlatory-domain.rst new file mode 100644 index 00000000..2b6ce7d4 --- /dev/null +++ b/docs/configuration/system/wifi-requlatory-domain.rst @@ -0,0 +1,2 @@ +wifi-requlatory-domain +###################### \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 4612d5f8..96272fff 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,16 +4,17 @@ VyOS User Guide ############### - .. toctree:: :maxdepth: 2 :hidden: + :caption: FIND CAPTION NAME introducing/about introducing/history introducing/releases changelog/index + .. toctree:: :maxdepth: 2 :hidden: @@ -21,9 +22,8 @@ VyOS User Guide :caption: first steps installation/index - quick-start + quickstart/index cli - .. toctree:: :maxdepth: 2 @@ -31,6 +31,7 @@ VyOS User Guide :includehidden: :caption: Adminguide + configuration/index operation/index automation/index @@ -44,5 +45,6 @@ VyOS User Guide :includehidden: :caption: Contributing + contributing/index copyright diff --git a/docs/information.rst b/docs/information.rst deleted file mode 100644 index 02d6f1ec..00000000 --- a/docs/information.rst +++ /dev/null @@ -1,97 +0,0 @@ -.. _information: - -*********** -Information -*********** - -VyOS features a rich set of operational level commands to retrieve arbitrary -information about your running system. - -######## -Hardware -######## - -.. _hardware_usb: - -USB -=== - -In the past serial interface have been defined as ttySx and ttyUSBx where x was -an instance number of the serial interface. It was discovered that from system -boot to system boot the mapping of USB based serial interfaces will differ, -depending which driver was loaded first by the operating system. This will become -rather painful if you not only have serial interfaces for a console server -connected but in addition also a serial backed :ref:`wwan-interface`. - -To overcome this issue and the fact that in almost 50% of all cheap USB to serial -converters there is no serial number programmed, the USB to serial interface is -now directly identified by the USB root bridge and bus it connects to. This -somehow mimics the new network interface definitions we see in recend Linux -distributions. - -For additional details you can refer to https://phabricator.vyos.net/T2490. - -.. opcmd:: show hardware usb - - Retrieve a tree like representation of all connected USB devices. - - .. note:: If a device is unplugged and re-plugged it will receive a new - Port, Dev, If identification. - - .. code-block:: none - - vyos@vyos:~$ show hardware usb - /: Bus 03.Port 1: Dev 1, Class=root_hub, Driver=ehci-pci/2p, 480M - |__ Port 1: Dev 2, If 0, Class=Hub, Driver=hub/4p, 480M - |__ Port 3: Dev 4, If 0, Class=Vendor Specific Class, Driver=qcserial, 480M - |__ Port 3: Dev 4, If 2, Class=Vendor Specific Class, Driver=qcserial, 480M - |__ Port 3: Dev 4, If 3, Class=Vendor Specific Class, Driver=qcserial, 480M - |__ Port 3: Dev 4, If 8, Class=Vendor Specific Class, Driver=qmi_wwan, 480M - /: Bus 02.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 5000M - /: Bus 01.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 480M - |__ Port 1: Dev 2, If 0, Class=Vendor Specific Class, Driver=pl2303, 12M - |__ Port 2: Dev 3, If 0, Class=Hub, Driver=hub/4p, 480M - |__ Port 4: Dev 5, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 5, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 5, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 5, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 3: Dev 4, If 0, Class=Hub, Driver=hub/4p, 480M - |__ Port 3: Dev 6, If 0, Class=Hub, Driver=hub/4p, 480M - |__ Port 4: Dev 8, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 8, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 8, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 8, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 7, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 7, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 7, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 7, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - - -.. opcmd:: show hardware usb serial - - Retrieve a list and description of all connected USB serial devices. The device name - displayed, e.g. `usb0b2.4p1.0` can be directly used when accessing the serial console - as console-server device. - - .. code-block:: none - - vyos@vyos$ show hardware usb serial - Device Model Vendor - ------ ------ ------ - usb0b1.3p1.0 MC7710 Sierra Wireless, Inc. - usb0b1.3p1.2 MC7710 Sierra Wireless, Inc. - usb0b1.3p1.3 MC7710 Sierra Wireless, Inc. - usb0b1p1.0 USB-Serial_Controller_D Prolific Technology, Inc. - usb0b2.3.3.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.3.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.3.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.3.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd - diff --git a/docs/operation/boot-options.rst b/docs/operation/boot-options.rst new file mode 100644 index 00000000..d054748f --- /dev/null +++ b/docs/operation/boot-options.rst @@ -0,0 +1,57 @@ +.. _boot-options: + + +############ +Boot Options +############ + +.. warning:: This function may be highly disruptive. + It may cause major service interruption, so make sure you really + need it and verify your input carefully. + + + +VyOS has several kernel command line options to modify the normal boot +process. +To add an option, select the desired image in GRUB menu at load +time, press **e**, edit the first line, and press **Ctrl-x** to boot when +ready. + +.. image:: /_static/images/boot-options.png + :width: 80% + :align: center + + +Specify custom config file +========================== + +Tells the system to use specified file instead of ``/config/config.boot``. +If specified file does not exist or is not readable, fall back to +default config. No additional verification is performed, so make sure +you specify a valid config file. + +.. code-block:: none + + vyos-config=/path/to/file + +To load the *factory default* config, use: + +.. code-block:: none + + vyos-config=/opt/vyatta/etc/config.boot.default + + +Disable specific boot process steps +=================================== + +These options disable some boot steps. Make sure you understand the +:ref:`boot process ` well before using them! + +.. glossary:: + + no-vyos-migrate + Do not perform config migration. + + no-vyos-firewall + Do not initialize default firewall chains, renders any firewall configuration unusable. + diff --git a/docs/operation/information.rst b/docs/operation/information.rst new file mode 100644 index 00000000..02d6f1ec --- /dev/null +++ b/docs/operation/information.rst @@ -0,0 +1,97 @@ +.. _information: + +*********** +Information +*********** + +VyOS features a rich set of operational level commands to retrieve arbitrary +information about your running system. + +######## +Hardware +######## + +.. _hardware_usb: + +USB +=== + +In the past serial interface have been defined as ttySx and ttyUSBx where x was +an instance number of the serial interface. It was discovered that from system +boot to system boot the mapping of USB based serial interfaces will differ, +depending which driver was loaded first by the operating system. This will become +rather painful if you not only have serial interfaces for a console server +connected but in addition also a serial backed :ref:`wwan-interface`. + +To overcome this issue and the fact that in almost 50% of all cheap USB to serial +converters there is no serial number programmed, the USB to serial interface is +now directly identified by the USB root bridge and bus it connects to. This +somehow mimics the new network interface definitions we see in recend Linux +distributions. + +For additional details you can refer to https://phabricator.vyos.net/T2490. + +.. opcmd:: show hardware usb + + Retrieve a tree like representation of all connected USB devices. + + .. note:: If a device is unplugged and re-plugged it will receive a new + Port, Dev, If identification. + + .. code-block:: none + + vyos@vyos:~$ show hardware usb + /: Bus 03.Port 1: Dev 1, Class=root_hub, Driver=ehci-pci/2p, 480M + |__ Port 1: Dev 2, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 3: Dev 4, If 0, Class=Vendor Specific Class, Driver=qcserial, 480M + |__ Port 3: Dev 4, If 2, Class=Vendor Specific Class, Driver=qcserial, 480M + |__ Port 3: Dev 4, If 3, Class=Vendor Specific Class, Driver=qcserial, 480M + |__ Port 3: Dev 4, If 8, Class=Vendor Specific Class, Driver=qmi_wwan, 480M + /: Bus 02.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 5000M + /: Bus 01.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 480M + |__ Port 1: Dev 2, If 0, Class=Vendor Specific Class, Driver=pl2303, 12M + |__ Port 2: Dev 3, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 4: Dev 5, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 5, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 5, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 5, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 3: Dev 4, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 3: Dev 6, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 4: Dev 8, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 8, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 8, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 8, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + + +.. opcmd:: show hardware usb serial + + Retrieve a list and description of all connected USB serial devices. The device name + displayed, e.g. `usb0b2.4p1.0` can be directly used when accessing the serial console + as console-server device. + + .. code-block:: none + + vyos@vyos$ show hardware usb serial + Device Model Vendor + ------ ------ ------ + usb0b1.3p1.0 MC7710 Sierra Wireless, Inc. + usb0b1.3p1.2 MC7710 Sierra Wireless, Inc. + usb0b1.3p1.3 MC7710 Sierra Wireless, Inc. + usb0b1p1.0 USB-Serial_Controller_D Prolific Technology, Inc. + usb0b2.3.3.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.3.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.3.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.3.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd + diff --git a/docs/system/advanced-index.rst b/docs/system/advanced-index.rst deleted file mode 100644 index 8e855789..00000000 --- a/docs/system/advanced-index.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _advanced_system_tweaks: - -###### -System -###### - -.. toctree:: - :maxdepth: 2 - - boot-options - eventhandler - flow-accounting - lcd - ntp - option - proxy - serial-console - syslog - task-scheduler diff --git a/docs/system/basic-index.rst b/docs/system/basic-index.rst deleted file mode 100644 index b7bbf1c5..00000000 --- a/docs/system/basic-index.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _basic_system_tweaks: - -################### -Basic System Tweaks -################### - -.. toctree:: - :maxdepth: 2 - - user-management - host-information - default-route - time-zone - system-dns diff --git a/docs/system/boot-options.rst b/docs/system/boot-options.rst deleted file mode 100644 index d054748f..00000000 --- a/docs/system/boot-options.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. _boot-options: - - -############ -Boot Options -############ - -.. warning:: This function may be highly disruptive. - It may cause major service interruption, so make sure you really - need it and verify your input carefully. - - - -VyOS has several kernel command line options to modify the normal boot -process. -To add an option, select the desired image in GRUB menu at load -time, press **e**, edit the first line, and press **Ctrl-x** to boot when -ready. - -.. image:: /_static/images/boot-options.png - :width: 80% - :align: center - - -Specify custom config file -========================== - -Tells the system to use specified file instead of ``/config/config.boot``. -If specified file does not exist or is not readable, fall back to -default config. No additional verification is performed, so make sure -you specify a valid config file. - -.. code-block:: none - - vyos-config=/path/to/file - -To load the *factory default* config, use: - -.. code-block:: none - - vyos-config=/opt/vyatta/etc/config.boot.default - - -Disable specific boot process steps -=================================== - -These options disable some boot steps. Make sure you understand the -:ref:`boot process ` well before using them! - -.. glossary:: - - no-vyos-migrate - Do not perform config migration. - - no-vyos-firewall - Do not initialize default firewall chains, renders any firewall configuration unusable. - diff --git a/docs/system/default-route.rst b/docs/system/default-route.rst deleted file mode 100644 index 27c74188..00000000 --- a/docs/system/default-route.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. _default_gateway: - -##################### -Default Gateway/Route -##################### - -In the past (VyOS 1.1) used a gateway-address configured under the system tree -(:cfgcmd:`set system gateway-address
`), this is no longer supported -and existing configurations are migrated to the new CLI command. - -Configuration -============= - -.. cfgcmd:: set protocols static route 0.0.0.0/0 next-hop
- - Specify static route into the routing table sending all non local traffic - to the nexthop address `
`. - - -.. cfgcmd:: delete protocols static route 0.0.0.0/0 - - Delete default route from the system. - -Operation -========= - -.. opcmd:: show ip route 0.0.0.0 - - Show routing table entry for the 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 10, metric 0, best - Last update 09:46:30 ago - * 172.18.201.254, via eth0.201 - -.. seealso:: Configuration of :ref:`static-routing` - diff --git a/docs/system/eventhandler.rst b/docs/system/eventhandler.rst deleted file mode 100644 index a68b3924..00000000 --- a/docs/system/eventhandler.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. _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 - description - policy - source - preset - syslog # Use the syslog logs for feed - custom - command # E.g. "tail -f /var/log/somelogfile" - named-pipe - policy - description - event - description - pattern - 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/system/flow-accounting.rst b/docs/system/flow-accounting.rst deleted file mode 100644 index f09c1c9a..00000000 --- a/docs/system/flow-accounting.rst +++ /dev/null @@ -1,203 +0,0 @@ -.. _flow-accounting: - -############### -Flow Accounting -############### - -VyOS supports flow-accounting for both IPv4 and IPv6 traffic. The system acts -as a flow exporter, and you are free to use it with any compatible collector. - -Flows can be exported via two different protocols: NetFlow (versions 5, 9 and -10/IPFIX) and sFlow. Additionally, you may save flows to an in-memory table -internally in a router. - -.. warning:: You need to disable the in-memory table in production environments! - Using :abbr:`IMT (In-Memory Table)` may lead to heavy CPU overloading and - unstable flow-accounting behavior. - - -NetFlow / IPFIX -=============== -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: - -* **exporter**: aggregates packets into flows and exports flow records towards - one or more flow collectors -* **collector**: responsible for reception, storage and pre-processing of flow - data received from a flow exporter -* **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. - -Configuration -============= - -In order for flow accounting information to be collected and displayed for an -interface, the interface must be configured for flow accounting. - -.. cfgcmd:: set system flow-accounting interface - - Configure and enable collection of flow information for the interface - identified by ``. - - You can configure multiple interfaces which whould participate in flow - accounting. - -.. note:: Will be recorded only packets/flows on **incoming** direction in - configured interfaces. - - -By default, recorded flows will be saved internally and can be listed with the -CLI command. You may disable using the local in-memory table with the command: - -.. cfgcmd:: set system flow-accounting disable-imt - - Internally, in flow-accounting processes exist a buffer for data exchanging - between core process and plugins (each export target is a separated plugin). - If you have high traffic levels or noted some problems with missed records - or stopping exporting, you may try to increase a default buffer size (10 - MiB) with the next command: - -.. cfgcmd:: set system flow-accounting buffer-size - - In case, if you need to catch some logs from flow-accounting daemon, you may - configure logging facility: - -.. cfgcmd:: set system flow-accounting syslog-facility - - TBD - -Flow Export ------------ - -In addition to displaying flow accounting information locally, one can also -exported them to a collection server. - -NetFlow -^^^^^^^ - -.. cfgcmd:: set system flow-accounting netflow version - - There are multiple versions available for the NetFlow data. The `` - used in the exported flow data can be configured here. The following - versions are supported: - - * **5** - Most common version, but restricted to IPv4 flows only - * **9** - NetFlow version 9 (default) - * **10** - :abbr:`IPFIX (IP Flow Information Export)` as per :rfc:`3917` - -.. cfgcmd:: set system flow-accounting netflow server
- - Configure address of NetFlow collector. NetFlow server at `
` can - be both listening on an IPv4 or IPv6 address. - -.. cfgcmd:: set system flow-accounting netflow source-ip
- - IPv4 or IPv6 source address of NetFlow packets - -.. cfgcmd:: set system flow-accounting netflow engine-id - - NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255. - -.. cfgcmd:: set system flow-accounting netflow sampling-rate - - Use this command to configure the sampling rate for flow accounting. The - system samples one in every `` packets, where `` is the value - configured for the sampling-rate option. The advantage of sampling every n - packets, where n > 1, allows you to decrease the amount of processing - resources required for flow accounting. The disadvantage of not sampling - every packet is that the statistics produced are estimates of actual data - flows. - - Per default every packet is sampled (that is, the sampling rate is 1). - -.. cfgcmd:: set system flow-accounting netflow timeout expiry-interval - - Specifies the interval at which Netflow data will be sent to a collector. As - per default, Netflow data will be sent every 60 seconds. - - You may also additionally configure timeouts for different types of - connections. - -.. cfgcmd:: set system flow-accounting netflow max-flows - - If you want to change the maximum number of flows, which are tracking - simultaneously, you may do this with this command (default 8192). - -sFlow -^^^^^ - -.. cfgcmd:: set system flow-accounting sflow server
- - Configure address of sFlow collector. sFlow server at `
` can - be an IPv4 or IPv6 address. But you cannot export to both IPv4 and - IPv6 collectors at the same time! - -.. cfgcmd:: set system flow-accounting sflow sampling-rate - - Enable sampling of packets, which will be transmitted to sFlow collectors. - -.. cfgcmd:: set system flow-accounting sflow agent-address
- - Configure a sFlow agent address. It can be IPv4 or IPv6 address, but you - must set the same protocol, which is used for sFlow collector addresses. By - default, using router-id from BGP or OSPF protocol, or the primary IP - address from the first interface. - -Example: --------- - -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 - -Operation -========= - -Once flow accounting is configured on an interfaces it provides the ability to -display captured network traffic information for all configured interfaces. - -.. opcmd:: show flow-accounting interface - - Show flow accounting information for given ``. - - .. code-block:: none - - vyos@vyos:~$ show flow-accounting interface eth0 - IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES - ---------- ----------------- ----------------- ------------------------ --------------- ---------- ---------- ---------- ----- --------- ------- ------- - eth0 00:53:01:a8:28:ac ff:ff:ff:ff:ff:ff 192.0.2.2 255.255.255.255 5678 5678 udp 0 1 1 178 - eth0 00:53:01:b2:2f:34 33:33:ff:00:00:00 fe80::253:01ff:feb2:2f34 ff02::1:ff00:0 0 0 ipv6-icmp 0 2 1 144 - eth0 00:53:01:1a:b4:53 33:33:ff:00:00:00 fe80::253:01ff:fe1a:b453 ff02::1:ff00:0 0 0 ipv6-icmp 0 1 1 72 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 39 1 2064 - eth0 00:53:01:c8:33:af ff:ff:ff:ff:ff:ff 192.0.2.3 255.255.255.255 5678 5678 udp 0 1 1 154 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 146 1 9444 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 27 1 4455 - -.. opcmd:: show flow-accounting interface host
- - Show flow accounting information for given `` for a specific host - only. - - .. code-block:: none - - vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.14 - IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES - ---------- ----------------- ----------------- ----------- ---------- ---------- ---------- ---------- ----- --------- ------- ------- - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 197 2 12940 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 94 1 4924 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 36 1 5877 diff --git a/docs/system/host-information.rst b/docs/system/host-information.rst deleted file mode 100644 index 30efe01e..00000000 --- a/docs/system/host-information.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. _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 -* Aliases - -Hostname -======== - -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. On the other hand this will be the name which appears on -the command line prompt. - -.. cfgcmd:: set system host-name - - Set system hostname. The hostname can be up to 63 characters. A hostname - must start and end with a letter or digit, and have as interior characters - only letters, digits, or a hyphen. - - The default hostname used is `vyos`. - -Domain Name -=========== - -A domain name is the label (name) assigned to a computer network and is thus -unique. VyOS appends the domain name as a suffix to any unqualified name. For -example, if you set the domain name `example.com`, and you would ping the -unqualified name of `crux`, then VyOS qualifies the name to `crux.example.com`. - -.. cfgcmd:: set system domain-name - - Configure system domain name. A domain name must start and end with a letter - or digit, and have as interior characters only letters, digits, or a hyphen. - -Static Hostname Mapping -======================= - -How an IP address is assigned to an interface in :ref:`ethernet-interface`. -This section shows how to statically map an IP address to a hostname for local -(meaning on this VyOS instance) name resolution. - -.. cfgcmd:: set system static-host-mapping host-name inet
- - Create a static hostname mapping which will always resolve the name - `` to IP address `
`. - - -.. cfgcmd:: set system static-host-mapping host-name alias - - Create named `` for the configured static mapping for ``. - Thus the address configured as :cfgcmd:`set system static-host-mapping - host-name inet
` can be reached via multiple names. - - Multiple aliases can pe specified per host-name. diff --git a/docs/system/lcd.rst b/docs/system/lcd.rst deleted file mode 100644 index 2509946e..00000000 --- a/docs/system/lcd.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. _system-display: - -******************** -System Display (LCD) -******************** - -The system LCD :abbr:`LCD (Liquid-crystal display)` option is for users running -VyOS on hardware that features an LCD display. This is typically a small display -built in an 19 inch rack-mountable appliance. Those displays are used to show -runtime data. - -To configure your LCD display you must first identify the used hardware, and -connectivity of the display to your system. This can be any serial port -(`ttySxx`) or serial via USB or even old parallel port interfaces. - -Configuration -============= - -.. cfgcmd:: set system lcd device - - This is the name of the physical interface used to connect to your LCD - display. Tab completion is supported and it will list you all available - serial interface. - - For serial via USB port information please refor to: :ref:`hardware_usb`. - -.. cfgcmd:: set system lcd model - - This is the LCD model used in your system. - - At the time of this writing the following displays are supported: - - * Crystalfontz CFA-533 - - * Crystalfontz CFA-631 - - * Crystalfontz CFA-633 - - * Crystalfontz CFA-635 - - .. note:: We can't support all displays from the beginning. If your display - type is missing, please create a feature request via Phabricator_. - -.. include:: /common-references.rst - diff --git a/docs/system/ntp.rst b/docs/system/ntp.rst deleted file mode 100644 index 5fd1837f..00000000 --- a/docs/system/ntp.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. _ntp: - -### -NTP -### - -:abbr:`NTP (Network Time Protocol`) is a networking protocol for clock -synchronization between computer systems over packet-switched, variable-latency -data networks. In operation since before 1985, NTP is one of the oldest Internet -protocols in current use. - -NTP is intended to synchronize all participating computers to within a few -milliseconds of :abbr:`UTC (Coordinated Universal Time)`. It uses the -intersection algorithm, a modified version of Marzullo's algorithm, to select -accurate time servers and is designed to mitigate the effects of variable -network latency. NTP can usually maintain time to within tens of milliseconds -over the public Internet, and can achieve better than one millisecond accuracy -in local area networks under ideal conditions. Asymmetric routes and network -congestion can cause errors of 100 ms or more. - -The protocol is usually described in terms of a client-server model, but can as -easily be used in peer-to-peer relationships where both peers consider the other -to be a potential time source. Implementations send and receive timestamps using -:abbr:`UDP (User Datagram Protocol)` on port number 123. - -NTP supplies a warning of any impending leap second adjustment, but no -information about local time zones or daylight saving time is transmitted. - -The current protocol is version 4 (NTPv4), which is a proposed standard as -documented in :rfc:`5905`. It is backward compatible with version 3, specified -in :rfc:`1305`. - -Configuration -============= - -.. cfgcmd:: set system ntp server
- - Configure one or more servers for synchronisation. Server name can be either - an IP address or :abbr:`FQDN (Fully Qualified Domain Name)`. - - There are 3 default NTP server set. You are able to change them. - - * 0.pool.ntp.org - * 1.pool.ntp.org - * 2.pool.ntp.org - -.. cfgcmd:: set system ntp listen-address
- - Setup VyOS as an NTP responder, you must specify the `
` and - optionally the permitted clients. Multiple listen addresses can be - configured. - -.. cfgcmd:: set system ntp allow-clients address
- - List of networks or client addresses permitted to contact this NTP server. - Multiple networks can be configured. diff --git a/docs/system/option.rst b/docs/system/option.rst deleted file mode 100644 index e7661492..00000000 --- a/docs/system/option.rst +++ /dev/null @@ -1,94 +0,0 @@ -.. _system_option: - -####### -Options -####### - -This chapter describe the possibilities of advanced system behavior. - -******* -General -******* - -.. cfgcmd:: set system option ctrl-alt-delete - - Action which will be run once the ctrl-alt-del keystroke is received. - -.. cfgcmd:: set system option reboot-on-panic - - Automatically reboot system on kernel panic after 60 seconds. - -.. cfgcmd:: set system option startup-beep - - Play an audible beep to the system speaker when system is ready. - -*********** -HTTP client -*********** - -.. cfgcmd:: set system option http-client source-address
- - Several commands utilize curl to initiate transfers. Configure the local - source IPv4/IPv6 address used for all CURL operations. - -.. cfgcmd:: set system option http-client source-interface - - Several commands utilize curl to initiate transfers. Configure the local - source interface used for all CURL operations. - -.. note:: `source-address` and `source-interface` can not be used at the same time. - -*************** -Keyboard Layout -*************** - -When starting a VyOS live system (the installation CD) the configured keyboard -layout defaults to US. As this might not suite everyones use case you can adjust -the used keyboard layout on the system console. - -.. cfgcmd:: set system option keyboard-layout - - Change system keyboard layout to given language. - - Defaults to ``us``. - - .. note:: Changing the keymap only has an effect on the system console, using - SSH oder Serial remote access to the device is not affected as the keyboard - layout here corresponds to your access system. - -.. _system_options_performance: - -*********** -Performance -*********** - -As more and more routers run on Hypervisors, expecially with a :abbr:`NOS -(Network Operating System)` as VyOS, it makes fewer and fewer sense to use -static resource bindings like ``smp-affinity`` as present in VyOS 1.2 and -earlier to pin certain interrupt handlers to specific CPUs. - -We now utilize `tuned` for dynamic resource balancing based on profiles. - - .. seealso:: https://access.redhat.com/sites/default/files/attachments/201501-perf-brief-low-latency-tuning-rhel7-v2.1.pdf - -.. cfgcmd:: set system option performance < throughput | latency > - - Configure one of the predefined system performance profiles. - - * ``throughput``: A server profile focused on improving network throughput. - This profile favors performance over power savings by setting ``intel_pstate`` - and ``max_perf_pct=100`` and increasing kernel network buffer sizes. - - It enables transparent huge pages, and uses cpupower to set the performance - cpufreq governor. It also sets ``kernel.sched_min_granularity_ns`` to 10 us, - ``kernel.sched_wakeup_granularity_ns`` to 15 uss, and ``vm.dirty_ratio`` to - 40%. - - * ``latency``: A server profile focused on lowering network latency. - This profile favors performance over power savings by setting ``intel_pstate`` - and ``min_perf_pct=100``. - - It disables transparent huge pages, and automatic NUMA balancing. It also - uses cpupower to set the performance cpufreq governor, and requests a - cpu_dma_latency value of 1. It also sets busy_read and busy_poll times to - 50 us, and tcp_fastopen to 3. diff --git a/docs/system/proxy.rst b/docs/system/proxy.rst deleted file mode 100644 index 8e0339a7..00000000 --- a/docs/system/proxy.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. _system_proxy: - -############ -System Proxy -############ - -Some IT environments require the use of a proxy to connect to the Internet. -Without this configuration VyOS updates could not be installed directly by -using the :opcmd:`add system image` command (:ref:`update_vyos`). - -.. cfgcmd:: set system proxy url - - Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and - FTP (anonymous ftp). - -.. cfgcmd:: set system proxy port - - Configure proxy port if it does not listen to the default port 80. - -.. cfgcmd:: set system proxy username - - Some proxys require/support the "basic" HTTP authentication scheme as per - :rfc:`7617`, thus a username can be configured. - -.. cfgcmd:: set system proxy password - - Some proxys require/support the "basic" HTTP authentication scheme as per - :rfc:`7617`, thus a password can be configured. diff --git a/docs/system/serial-console.rst b/docs/system/serial-console.rst deleted file mode 100644 index 4a750ada..00000000 --- a/docs/system/serial-console.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. _serial-console: - -############## -Serial Console -############## - -For the average user a serial console has no advantage over a console offered -by a directly attached keyboard and screen. Serial consoles are much slower, -taking up to a second to fill a 80 column by 24 line screen. Serial consoles -generally only support non-proportional ASCII text, with limited support for -languages other than English. - -There are some scenarios where serial consoles are useful. System administration -of remote computers is usually done using :ref:`ssh`, but there are times when -access to the console is the only way to diagnose and correct software failures. -Major upgrades to the installed distribution may also require console access. - - -.. cfgcmd:: set system console device - - Defines the specified device as a system console. Available console devices - can be (see completion helper): - - * ``ttySN`` - Serial device name - * ``ttyUSBX`` - USB Serial device name - * ``hvc0`` - Xen console - -.. cfgcmd:: set system console device speed - - The speed (baudrate) of the console device. Supported values are: - - * ``1200`` - 1200 bps - * ``2400`` - 2400 bps - * ``4800`` - 4800 bps - * ``9600`` - 9600 bps - * ``19200`` - 19,200 bps - * ``38400`` - 38,400 bps (default for Xen console) - * ``57600`` - 57,600 bps - * ``115200`` - 115,200 bps (default for serial console) - - .. note:: If you use a USB to serial converter please note that most of them - use software emulation without flow control, thus you should start with a - common baud rate of 9600 as otherwise you could get diff --git a/docs/system/syslog.rst b/docs/system/syslog.rst deleted file mode 100644 index 3449c15b..00000000 --- a/docs/system/syslog.rst +++ /dev/null @@ -1,226 +0,0 @@ -.. _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 level - -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 facility level - -Log syslog messages to file specified via ``, for en explanation on -:ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords see -tables below. - -.. cfgcmd:: set system syslog file archive size - -Syslog will write `` kilobytes into the file specified by ``. -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 archive file - -Syslog uses logrotate to rotate logiles after a number of gives bytes. We keep -as many as `` 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
facility level - -Log syslog messages to remote host specified by `
`. 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
facility protocol - -Configure protocol used for communication to remote syslog host. This can be -either UDP or TCP. - - -Local User Account ------------------- - -.. cfgcmd:: set system syslog user facility level - -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 [all | authorization | directory | file | tail ] - -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 - - 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 - * - - - Number of lines to be displayed, default 10 - -When no options/parameters are used, the contents of the main syslog file are -displayed. - -.. hint:: Use ``show log | strip-private`` if you want to hide private data when sharing your logs. diff --git a/docs/system/system-dns.rst b/docs/system/system-dns.rst deleted file mode 100644 index 59cfdb5d..00000000 --- a/docs/system/system-dns.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. _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
- - 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 - - 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/system/task-scheduler.rst b/docs/system/task-scheduler.rst deleted file mode 100644 index 382da39f..00000000 --- a/docs/system/task-scheduler.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. _task-scheduler: - -############## -Task Scheduler -############## - -The task scheduler allows you to execute tasks on a given schedule. It makes -use of UNIX cron_. - -.. note:: All scripts excecuted this way are executed as root user - this may - be dangerous. Together with :ref:`command-scripting` this can be used for - automating (re-)configuration. - -.. cfgcmd:: set system task-scheduler task interval - - Specify the time interval when `` should be executed. The interval - is specified as number with one of the following suffixes: - - * ``none`` - Execution interval in minutes - * ``m`` - Execution interval in minutes - * ``h`` - Execution interval in hours - * ``d`` - Execution interval in days - - .. note:: If suffix is omitted, minutes are implied. - -.. cfgcmd:: set system task-scheduler task crontab-spec - - Set execution time in common cron_ time format. A cron `` of - ``30 */6 * * *`` would execute the `` at minute 30 past every 6th hour. - -.. cfgcmd:: set system task-scheduler task executable path - - Specify absolute `` to script which will be run when `` is - executed. - -.. cfgcmd:: set system task-scheduler task executable arguments - - Arguments which will be passed to the executable. - -.. _cron: https://en.wikipedia.org/wiki/Cron diff --git a/docs/system/time-zone.rst b/docs/system/time-zone.rst deleted file mode 100644 index 025c4376..00000000 --- a/docs/system/time-zone.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. _timezone: - -######### -Time Zone -######### - -Time Zone setting is very important as e.g all your logfile entries will be -based on the configured zone. Without proper time zone configuration it will -be very difficult to compare logfiles from different systems. - -.. cfgcmd:: set system time-zone - - Specify the systems `` as the Region/Location that best defines - your location. For example, specifying US/Pacific sets the time zone to US - Pacific time. - - Command completion can be used to list available time zones. The adjustment - for daylight time will take place automatically based on the time of year. \ No newline at end of file diff --git a/docs/system/user-management.rst b/docs/system/user-management.rst deleted file mode 100644 index 6d89735f..00000000 --- a/docs/system/user-management.rst +++ /dev/null @@ -1,160 +0,0 @@ -.. _user_management: - -############### -User Management -############### - -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. - -Both local administered and remote administered :abbr:`RADIUS (Remote -Authentication Dial-In User Service)` accounts are supported. - -Local -===== - -.. cfgcmd:: set system login user full-name "" - - Create new system user with username `` and real-name specified by - ``. - -.. cfgcmd:: set system login user authentication plaintext-password - - Specify the plaintext password user by user `` on this system. The - plaintext password will be automatically transferred into a secure hashed - password and not saved anywhere in plaintext. - -.. cfgcmd:: set system login user authentication encrypted-password - - Setup encrypted password for given username. This is useful for - transferring a hashed password from system to system. - -.. _ssh_key_based_authentication: - -Key Based Authentication ------------------------- - -It is highly recommended to use SSH key authentication. By default there is -only one user (``vyos``), and you can assign any number of keys to that user. -You can generate a ssh key with the ``ssh-keygen`` command on your local -machine, which will (by default) save it as ``~/.ssh/id_rsa.pub``. - -Every SSH key comes in three parts: - -``ssh-rsa AAAAB3NzaC1yc2EAAAABAA...VBD5lKwEWB username@host.example.com`` - -Only the type (``ssh-rsa``) and the key (``AAAB3N...``) are used. Note that the -key will usually be several hundred characters long, and you will need to copy -and paste it. Some terminal emulators may accidentally split this over several -lines. Be attentive when you paste it that it only pastes as a single line. -The third part is simply an identifier, and is for your own reference. - -.. cfgcmd:: set system login user authentication public-keys key - - Assign the SSH public key portion `` identified by per-key - `` to the local user ``. - -.. cfgcmd:: set system login user authentication public-keys type - - Every SSH public key portion referenced by `` requires the - configuration of the `` of public-key used. This type can be any of: - - * ``ecdsa-sha2-nistp256`` - * ``ecdsa-sha2-nistp384`` - * ``ecdsa-sha2-nistp521`` - * ``ssh-dss`` - * ``ssh-ed25519`` - * ``ssh-rsa`` - - .. note:: You can assign multiple keys to the same user by using a unique - identifier per SSH key. - -.. cfgcmd:: loadkey - - SSH keys can not only be specified on the command-line but also loaded for - a given user with `` from a file pointed to by `.` Keys - can be either loaded from local filesystem or any given remote location - using one of the following :abbr:`URIs (Uniform Resource Identifier)`: - - * ```` - Load from file on local filesystem path - * ``scp://@:/`` - Load via SCP from remote machine - * ``sftp://@/`` - Load via SFTP from remote machine - * ``ftp://@/`` - Load via FTP from remote machine - * ``http:///`` - Load via HTTP from remote machine - * ``tftp:///`` - Load via TFTP from remote machine - -Example -------- - -In the following example, both `User1` and `User2` will be able to SSH into -VyOS as user ``vyos`` using their very own keys. - -.. code-block:: none - - set system login user vyos authentication public-keys 'User1' key "AAAAB3Nz...KwEW" - set system login user vyos authentication public-keys 'User1' type ssh-rsa - set system login user vyos authentication public-keys 'User2' key "AAAAQ39x...fbV3" - set system login user vyos authentication public-keys 'User2' type ssh-rsa - - -RADIUS -====== - -In large deployments it is not reasonable to configure each user individually -on every system. VyOS supports using :abbr:`RADIUS (Remote Authentication -Dial-In User Service)` servers as backend for user authentication. - -Configuration -------------- - -.. cfgcmd:: set system login radius server
secret - - Specify the `
` of the RADIUS server user with the pre-shared-secret - given in ``. Multiple servers can be specified. - -.. cfgcmd:: set system login radius server
port - - Configure the discrete port under which the RADIUS server can be reached. - This defaults to 1812. - -.. cfgcmd:: set system login radius server
timeout - - Setup the `` in seconds when querying the RADIUS server. - -.. cfgcmd:: set system login radius server
disable - - Temporary disable this RADIUS server. It won't be queried. - -.. cfgcmd:: set system login radius 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 server - making - it error prone on e.g. OSPF networks when a link fails and a backup route is - taken. - -.. hint:: If you want 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. - - - -Login Banner -============ - -You are able to set post-login or pre-login banner messages to display certain -information for this system. - -.. cfgcmd:: set system login banner pre-login - - Configure `` which is shown during SSH connect and before a user is - logged in. - -.. cfgcmd:: set system login banner post-login - - Configure `` which is shown after user has logged in to the system. - -.. note:: To create a new line in your login message you need to escape the new - line character by using ``\\n``. -- cgit v1.2.3