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/configuration/system/login.rst | 160 ++++++++++++++++++++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 docs/configuration/system/login.rst (limited to 'docs/configuration/system/login.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``. -- cgit v1.2.3 From 4f5320bd55e6659be51a2d15b6df348b5d112937 Mon Sep 17 00:00:00 2001 From: rebortg Date: Fri, 11 Dec 2020 15:08:50 +0100 Subject: system: fix lint errors --- docs/configuration/system/eventhandler.rst | 9 ++- docs/configuration/system/flow-accounting.rst | 3 +- docs/configuration/system/login.rst | 12 ++- docs/configuration/system/name-server.rst | 2 + docs/configuration/system/option.rst | 24 +++--- docs/configuration/system/syslog.rst | 103 ++++++++++++++------------ 6 files changed, 87 insertions(+), 66 deletions(-) (limited to 'docs/configuration/system/login.rst') diff --git a/docs/configuration/system/eventhandler.rst b/docs/configuration/system/eventhandler.rst index a68b3924..3eab4e2c 100644 --- a/docs/configuration/system/eventhandler.rst +++ b/docs/configuration/system/eventhandler.rst @@ -3,9 +3,11 @@ 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). +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. +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 @@ -27,7 +29,8 @@ It uses "feeds" (output of commands, or a named pipes) and "policies" that defin pattern run -In this small example a script runs every time a login failed and an interface goes down +In this small example a script runs every time a login failed and an interface +goes down .. code-block:: none diff --git a/docs/configuration/system/flow-accounting.rst b/docs/configuration/system/flow-accounting.rst index f09c1c9a..5bc737d6 100644 --- a/docs/configuration/system/flow-accounting.rst +++ b/docs/configuration/system/flow-accounting.rst @@ -121,7 +121,8 @@ NetFlow Per default every packet is sampled (that is, the sampling rate is 1). -.. cfgcmd:: set system flow-accounting netflow timeout expiry-interval +.. 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. diff --git a/docs/configuration/system/login.rst b/docs/configuration/system/login.rst index 6d89735f..0492f4d1 100644 --- a/docs/configuration/system/login.rst +++ b/docs/configuration/system/login.rst @@ -19,13 +19,15 @@ Local Create new system user with username `` and real-name specified by ``. -.. cfgcmd:: set system login user authentication plaintext-password +.. 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 +.. 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. @@ -50,12 +52,14 @@ 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 +.. 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 +.. 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: diff --git a/docs/configuration/system/name-server.rst b/docs/configuration/system/name-server.rst index 59cfdb5d..1896eeda 100644 --- a/docs/configuration/system/name-server.rst +++ b/docs/configuration/system/name-server.rst @@ -28,6 +28,7 @@ Example In this example, some *OpenNIC* servers are used, two IPv4 addresses and two IPv6 addresses: +.. stop_vyoslinter .. code-block:: none @@ -36,6 +37,7 @@ and two IPv6 addresses: set system name-server 2a01:4f8:161:3441::1 set system name-server 2a00:f826:8:2::195 +.. start_vyoslinter Domain search order =================== diff --git a/docs/configuration/system/option.rst b/docs/configuration/system/option.rst index e7661492..e029ec96 100644 --- a/docs/configuration/system/option.rst +++ b/docs/configuration/system/option.rst @@ -1,8 +1,8 @@ .. _system_option: -####### -Options -####### +###### +Option +###### This chapter describe the possibilities of advanced system behavior. @@ -36,7 +36,8 @@ HTTP client 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. +.. note:: `source-address` and `source-interface` can not be used at the same + time. *************** Keyboard Layout @@ -69,15 +70,20 @@ 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 +.. stop_vyoslinter + +.. seealso:: https://access.redhat.com/sites/default/files/attachments/201501-perf-brief-low-latency-tuning-rhel7-v2.1.pdf + +.. start_vyoslinter .. 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. + 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, @@ -85,8 +91,8 @@ We now utilize `tuned` for dynamic resource balancing based on profiles. 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``. + 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 diff --git a/docs/configuration/system/syslog.rst b/docs/configuration/system/syslog.rst index 3449c15b..a4d641b5 100644 --- a/docs/configuration/system/syslog.rst +++ b/docs/configuration/system/syslog.rst @@ -22,9 +22,9 @@ 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. + 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 @@ -32,20 +32,21 @@ 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. + 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. + 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. + 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 @@ -59,16 +60,17 @@ 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. + 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 +.. cfgcmd:: set system syslog host
facility protocol + -Configure protocol used for communication to remote syslog host. This can be -either UDP or TCP. + Configure protocol used for communication to remote syslog host. This can be + either UDP or TCP. Local User Account @@ -76,11 +78,11 @@ 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. + 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: @@ -191,36 +193,39 @@ 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 + 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 +.. 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. +.. hint:: Use ``show log | strip-private`` if you want to hide private data + when sharing your logs. -- cgit v1.2.3