diff options
Diffstat (limited to 'docs/configuration')
21 files changed, 677 insertions, 135 deletions
diff --git a/docs/configuration/container/index.rst b/docs/configuration/container/index.rst index ed510477..044e31b8 100644 --- a/docs/configuration/container/index.rst +++ b/docs/configuration/container/index.rst @@ -1,34 +1,19 @@ -:lastproofread: 2021-06-30 - -.. include:: /_include/need_improvement.txt - -.. _container: +:lastproofread: 2022-06-10 ######### Container ######### +The VyOS container implementation is based on `Podman<https://podman.io/>` as +a deamonless container engine. + ************* Configuration ************* -.. cfgcmd:: set container <name> - - Set a named container. - -.. cfgcmd:: set container network <networkname> - - Creates a named container network - -.. cfgcmd:: set container registry <name> - - Adds registry to list of unqualified-search-registries. By default, for any - image that does not include the registry in the image name, Vyos will use - docker.io as the container registry. - -.. cfgcmd:: set container <name> image +.. cfgcmd:: set container name <name> image - Sets the image name in the hub registry + Sets the image name in the hub registry .. code-block:: none @@ -42,7 +27,7 @@ Configuration set container name mysql-server image quay.io/mysql:8.0 -.. cfgcmd:: set container <name> allow-host-networks +.. cfgcmd:: set container name <name> allow-host-networks Allow host networking in a container. The network stack of the container is not isolated from the host and will use the host IP. @@ -50,50 +35,52 @@ Configuration The following commands translate to "--net host" when the container is created - .. note:: **allow-host-networks** cannot be used with **network** + .. note:: **allow-host-networks** cannot be used with **network** -.. cfgcmd:: set container <name> description <text> +.. cfgcmd:: set container name <name> network <networkname> - Sets the container description + Attaches user-defined network to a container. + Only one network must be specified and must already exist. -.. cfgcmd:: set container <name> environment '<key>' value '<value>' +.. cfgcmd:: set container name <name> network <networkname> address <address> - Add custom environment variables. - Multiple environment variables are allowed. - The following commands translate to "-e key=value" when the container - is created. + Optionally set a specific static IPv4 or IPv6 address for the container. + This address must be within the named network prefix. - .. code-block:: none + .. note:: The first IP in the container network is reserved by the engine and cannot be used - set container name mysql-server environment 'MYSQL_DATABASE' value 'zabbix' - set container name mysql-server environment 'MYSQL_USER' value 'zabbix' - set container name mysql-server environment 'MYSQL_PASSWORD' value 'zabbix_pwd' - set container name mysql-server environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' +.. cfgcmd:: set container name <name> description <text> -.. cfgcmd:: set container <name> network <networkname> + Set a container description - Attaches user-defined network to a container. - Only one network must be specified and must already exist. +.. cfgcmd:: set container name <name> environment <key> value <value> - Optionally a specific static IPv4 or IPv6 address can be set for - the container. This address must be within the named network. + Add custom environment variables. + Multiple environment variables are allowed. + The following commands translate to "-e key=value" when the container + is created. .. code-block:: none - set container <name> network <networkname> address <address> + set container name mysql-server environment MYSQL_DATABASE value 'zabbix' + set container name mysql-server environment MYSQL_USER value 'zabbix' + set container name mysql-server environment MYSQL_PASSWORD value 'zabbix_pwd' + set container name mysql-server environment MYSQL_ROOT_PASSWORD value 'root_pwd' - .. note:: The first IP in the container network is reserved by the engine and cannot be used - -.. cfgcmd:: set container <name> port <portname> [source | destination ] <portnumber> +.. cfgcmd:: set container name <name> port <portname> source <portnumber> +.. cfgcmd:: set container name <name> port <portname> destination <portnumber> +.. cfgcmd:: set container name <name> port <portname> protocol <tcp | udp> - Publishes a port for the container + Publish a port for the container. .. code-block:: none set container name zabbix-web-nginx-mysql port http source 80 set container name zabbix-web-nginx-mysql port http destination 8080 + set container name zabbix-web-nginx-mysql port http protocol tcp -.. cfgcmd:: set container <name> volume <volumename> [source | destination ] <path> +.. cfgcmd:: set container name <name> volume <volumename> source <path> +.. cfgcmd:: set container name <name> volume <volumename> destination <path> Mount a volume into the container @@ -102,6 +89,85 @@ Configuration set container name coredns volume 'corefile' source /config/coredns/Corefile set container name coredns volume 'corefile' destination /etc/Corefile +.. cfgcmd:: set container name <name> restart [no | on-failure | always] + + Set the restart behavior of the container. + + - **no**: Do not restart containers on exit + - **on-failure**: Restart containers when they exit with a non-zero exit code, retrying indefinitely (default) + - **always**: Restart containers when they exit, regardless of status, retrying indefinitely + +.. cfgcmd:: set container name <name> memory <MB> + + Constrain the memory available to the container. + + Default is 512 MB. Use 0 MB for unlimited memory. + +.. cfgcmd:: set container name <name> device <devicename> source <path> +.. cfgcmd:: set container name <name> device <devicename> destination <path> + + Add a host device to the container. + +.. cfgcmd:: container name <name> cap-add <text> + + Set container capabilities or permissions. + + - **net-admin**: Network operations (interface, firewall, routing tables) + - **net-bind-service**: Bind a socket to privileged ports (port numbers less than 1024) + - **net-raw**: Permission to create raw network sockets + - **setpcap**: Capability sets (from bounded or inherited set) + - **sys-admin**: Administation operations (quotactl, mount, sethostname, setdomainame) + - **sys-time**: Permission to set system clock + +.. cfgcmd:: set container name <name> disable + + Disable a container. + +.. cfgcmd:: set container network <networkname> + + Creates a named container network + +.. cfgcmd:: set container registry <name> + + Adds registry to list of unqualified-search-registries. By default, for any + image that does not include the registry in the image name, Vyos will use + docker.io as the container registry. + + +****************** +Operation Commands +****************** + +.. opcmd:: add container image <containername> + + Pull a new image for container + +.. opcmd:: show container + + Show the list of all active containers. + +.. opcmd:: show container image + + Show the local container images. + +.. opcmd:: show container log <containername> + + Show logs from a given container + +.. opcmd:: show container network + + Show a list available container networks + +.. opcmd:: restart container <containername> + + Restart a given container + +.. opcmd:: update container image <containername> + + Update container image + + + ********************* Example Configuration ********************* diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst index 55881b1b..a36877b7 100644 --- a/docs/configuration/firewall/index.rst +++ b/docs/configuration/firewall/index.rst @@ -264,7 +264,7 @@ the action of the rule will be executed. .. cfgcmd:: set firewall name <name> rule <1-999999> action [drop | reject | accept] -.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> action [drop | +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> action [drop | reject | accept] This required setting defines the action of the current rule. @@ -275,11 +275,18 @@ the action of the rule will be executed. Provide a description for each rule. .. cfgcmd:: set firewall name <name> rule <1-999999> log [disable | enable] -.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> log [disable | +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> log [disable | enable] Enable or disable logging for the matched packet. +.. cfgcmd:: set firewall name <name> rule <1-999999> log-level [emerg | + alert | crit | err | warn | notice | info | debug] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> log-level [emerg | + alert | crit | err | warn | notice | info | debug] + + Define log-level. Only applicable if rule log is enable. + .. cfgcmd:: set firewall name <name> rule <1-999999> disable .. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> disable @@ -316,6 +323,32 @@ There are a lot of matching criteria against which the package can be tested. set firewall name WAN-IN-v4 rule 101 source address !203.0.113.0/24 set firewall ipv6-name WAN-IN-v6 rule 100 source address 2001:db8::202 +.. cfgcmd:: set firewall name <name> rule <1-999999> source geoip country-code + <country> +.. cfgcmd:: set firewall name <name> rule <1-999999> source geoip inverse-match +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source geoip + country-code <country> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source geoip + inverse-match +.. cfgcmd:: set firewall name <name> rule <1-999999> destination geoip + country-code <country> +.. cfgcmd:: set firewall name <name> rule <1-999999> destination geoip + inverse-match +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination geoip + country-code <country> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination geoip + inverse-match + +Match IP addresses based on its geolocation. +More info: `geoip matching +<https://wiki.nftables.org/wiki-nftables/index.php/GeoIP_matching>`_. + +Use inverse-match to match anything except the given country-codes. + +Data is provided by DB-IP.com under CC-BY-4.0 license. Attribution required, +permits redistribution so we can include a database in images(~3MB +compressed). Includes cron script (manually callable by op-mode update +geoip) to keep database and rules updated. .. cfgcmd:: set firewall name <name> rule <1-999999> source mac-address <mac-address> @@ -355,37 +388,40 @@ There are a lot of matching criteria against which the package can be tested. set firewall ipv6-name WAN-IN-v6 rule 10 source port '!22,https,3333-3338' .. cfgcmd:: set firewall name <name> rule <1-999999> source group - address-group <name> + address-group <name | !name> .. cfgcmd:: set firewall name <name> rule <1-999999> destination group - address-group <name> + address-group <name | !name> .. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source group - address-group <name> + address-group <name | !name> .. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination group - address-group <name> + address-group <name | !name> - Use a specific address-group + Use a specific address-group. Prepend character '!' for inverted matching + criteria. .. cfgcmd:: set firewall name <name> rule <1-999999> source group - network-group <name> + network-group <name | !name> .. cfgcmd:: set firewall name <name> rule <1-999999> destination group - network-group <name> + network-group <name | !name> .. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source group - network-group <name> + network-group <name | !name> .. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination group - network-group <name> + network-group <name | !name> - Use a specific network-group + Use a specific network-group. Prepend character '!' for inverted matching + criteria. .. cfgcmd:: set firewall name <name> rule <1-999999> source group - port-group <name> + port-group <name | !name> .. cfgcmd:: set firewall name <name> rule <1-999999> destination group - port-group <name> + port-group <name | !name> .. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source group - port-group <name> + port-group <name | !name> .. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination group - port-group <name> + port-group <name | !name> - Use a specific port-group + Use a specific port-group. Prepend character '!' for inverted matching + criteria. .. cfgcmd:: set firewall name <name> rule <1-999999> protocol [<text> | <0-255> | all | tcp_udp] @@ -423,6 +459,26 @@ There are a lot of matching criteria against which the package can be tested. Match against the state of a packet. +.. cfgcmd:: set firewall name <name> rule <1-999999> ttl <eq | gt | lt> <0-255> + + Match time to live parameter, where 'eq' stands for 'equal'; 'gt' stands for + 'greater than', and 'lt' stands for 'less than'. + +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> hop-limit <eq | gt | + lt> <0-255> + + Match hop-limit parameter, where 'eq' stands for 'equal'; 'gt' stands for + 'greater than', and 'lt' stands for 'less than'. + +.. cfgcmd:: set firewall name <name> rule <1-999999> recent count <1-255> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> recent count <1-255> +.. cfgcmd:: set firewall name <name> rule <1-999999> recent time <second | + minute | hour> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> recent time <second | + minute | hour> + + Match when 'count' amount of connections are seen within 'time'. These + matching criteria can be used to block brute-force attempts. *********************************** Applying a Rule-Set to an Interface @@ -495,10 +551,10 @@ Applying a Rule-Set to a Zone Before you are able to apply a rule-set to a zone you have to create the zones first. -It helps to think of the syntax as: (see below). The 'rule-set' should be +It helps to think of the syntax as: (see below). The 'rule-set' should be written from the perspective of: *Source Zone*-to->*Destination Zone* -.. cfgcmd:: set zone-policy zone <Destination Zone> from <Source Zone> +.. cfgcmd:: set zone-policy zone <Destination Zone> from <Source Zone> firewall name <rule-set> .. cfgcmd:: set zone-policy zone <name> from <name> firewall name @@ -786,3 +842,11 @@ Example Partial Config } } } + + +Update geoip database +===================== + +.. opcmd:: update geoip + + Command used to update GeoIP database and firewall sets. diff --git a/docs/configuration/interfaces/bridge.rst b/docs/configuration/interfaces/bridge.rst index ebb2232a..ddc293cc 100644 --- a/docs/configuration/interfaces/bridge.rst +++ b/docs/configuration/interfaces/bridge.rst @@ -78,7 +78,11 @@ Bridge Options .. cfgcmd:: set interfaces bridge <interface> igmp querier - Enable IGMP querier + Enable IGMP and MLD querier. + +.. cfgcmd:: set interfaces bridge <interface> igmp snooping + + Enable IGMP and MLD snooping. .. _stp: diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst index 3fe6b1d4..ff32d869 100644 --- a/docs/configuration/interfaces/openvpn.rst +++ b/docs/configuration/interfaces/openvpn.rst @@ -332,7 +332,7 @@ before using under the openvpn interface configuration. Now we need to specify the server network settings. In all cases we need to specify the subnet for client tunnel endpoints. Since we want clients to access -a specific network behind out router, we will use a push-route option for +a specific network behind our router, we will use a push-route option for installing that route on clients. .. code-block:: none diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst index b775011f..231652a0 100644 --- a/docs/configuration/interfaces/wireless.rst +++ b/docs/configuration/interfaces/wireless.rst @@ -590,3 +590,24 @@ To get it to work as an access point with this configuration you will need to set up a DHCP server to work with that network. You can - of course - also bridge the Wireless interface with any configured bridge (:ref:`bridge-interface`) on the system. + +.. _wireless-interface-intel-ax200: + +Intel AX200 +=========== + +The Intel AX200 card does not work out of the box in AP mode, see +https://unix.stackexchange.com/questions/598275/intel-ax200-ap-mode. You can +still put this card into AP mode using the following configuration: + +.. stop_vyoslinter +.. code-block:: none + + set interfaces wireless wlan0 channel '1' + set interfaces wireless wlan0 country-code 'us' + set interfaces wireless wlan0 mode 'n' + set interfaces wireless wlan0 physical-device 'phy0' + set interfaces wireless wlan0 ssid 'VyOS' + set interfaces wireless wlan0 type 'access-point' + +.. start_vyoslinter diff --git a/docs/configuration/policy/route-map.rst b/docs/configuration/policy/route-map.rst index 470c798e..97fa1102 100644 --- a/docs/configuration/policy/route-map.rst +++ b/docs/configuration/policy/route-map.rst @@ -82,10 +82,25 @@ Route Map IP next-hop of route to match, based on access-list. .. cfgcmd:: set policy route-map <text> rule <1-65535> match ip nexthop + address <x.x.x.x> + + IP next-hop of route to match, based on ip address. + +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip nexthop + prefix-len <0-32> + + IP next-hop of route to match, based on prefix length. + +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip nexthop prefix-list <text> IP next-hop of route to match, based on prefix-list. +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip nexthop + type <blackhole> + + IP next-hop of route to match, based on type. + .. cfgcmd:: set policy route-map <text> rule <1-65535> match ip route-source access-list <1-2699> diff --git a/docs/configuration/protocols/bgp.rst b/docs/configuration/protocols/bgp.rst index 24d81cef..fb9b9d6e 100644 --- a/docs/configuration/protocols/bgp.rst +++ b/docs/configuration/protocols/bgp.rst @@ -177,7 +177,7 @@ process. The BGP process starts when the first neighbor is configured. .. cfgcmd:: set protocols bgp local-as <asn> Set local autonomous system number that this router represents. This is a - a mandatory option! + mandatory option! Peers Configuration ------------------- @@ -431,7 +431,7 @@ Peer Parameters This command enforces Generalized TTL Security Mechanism (GTSM), as specified in :rfc:`5082`. With this command, only neighbors - that are the specified number of hops away will be allowed to + that are specified number of hops away will be allowed to become neighbors. The number of hops range is 1 to 254. This command is mutually exclusive with :cfgcmd:`ebgp-multihop`. @@ -563,11 +563,6 @@ Common parameters Path (both AS number and AS path length), Origin code, MED, IGP metric. Also, the next hop address for each path must be different. -.. cfgcmd:: set protocols bgp parameters default no-ipv4-unicast - - This command allows the user to specify that IPv4 peering is turned off by - default. - .. cfgcmd:: set protocols bgp parameters log-neighbor-changes This command enable logging neighbor up/down changes and reset reason. @@ -984,7 +979,7 @@ Show .. opcmd:: show ip bgp filter-list <name> - This command displays BGP routes allowed by by the specified AS Path + This command displays BGP routes allowed by the specified AS Path access list. .. opcmd:: show <ip|ipv6> bgp neighbors <address> advertised-routes diff --git a/docs/configuration/service/broadcast-relay.rst b/docs/configuration/service/broadcast-relay.rst index df48bfd6..b6e2bed7 100644 --- a/docs/configuration/service/broadcast-relay.rst +++ b/docs/configuration/service/broadcast-relay.rst @@ -28,6 +28,11 @@ Configuration want to receive/relay packets on both `eth1` and `eth2` both interfaces need to be added. +.. cfgcmd:: set service broadcast-relay id <n> address <ipv4-address> + + Set the source IP of forwarded packets, otherwise original senders address + is used. + .. cfgcmd:: set service broadcast-relay id <n> port <port> The UDP port number used by your apllication. It is mandatory for this kind diff --git a/docs/configuration/service/conntrack-sync.rst b/docs/configuration/service/conntrack-sync.rst index a7cd7060..1b72f8eb 100644 --- a/docs/configuration/service/conntrack-sync.rst +++ b/docs/configuration/service/conntrack-sync.rst @@ -114,11 +114,11 @@ Operation conntrack is not enabled. To enable conntrack, just create a NAT or a firewall rule. :cfgcmd:`set firewall state-policy established action accept` -.. opcmd:: show conntrack-sync external-cache +.. opcmd:: show conntrack-sync cache external Show connection syncing external cache entries -.. opcmd:: show conntrack-sync internal-cache +.. opcmd:: show conntrack-sync cache internal Show connection syncing internal cache entries diff --git a/docs/configuration/service/eventhandler.rst b/docs/configuration/service/eventhandler.rst new file mode 100644 index 00000000..15f08239 --- /dev/null +++ b/docs/configuration/service/eventhandler.rst @@ -0,0 +1,127 @@ +.. _event-handler: + +############# +Event Handler +############# + +********************************* +Event Handler Technology Overview +********************************* + +Event handler allows you to execute scripts when a string that matches a regex or a regex with +a service name appears in journald logs. You can pass variables, arguments, and a full matching string to the script. + + +****************************** +How to configure Event Handler +****************************** + + `1. Create an event handler`_ + + `2. Add regex to the script`_ + + `3. Add a full path to the script`_ + + `4. Add optional parameters`_ + +********************************* +Event Handler Configuration Steps +********************************* + +1. Create an event handler +========================== + + .. cfgcmd:: set service event-handler event <event-handler name> + + This is an optional command because the event handler will be automatically created after any of the next commands. + + +2. Add regex to the script +=========================================== + + .. cfgcmd:: set service event-handler event <event-handler name> filter pattern <regex> + + This is a mandatory command. Sets regular expression to match against log string message. + + .. note:: The regular expression matches if and only if the entire string matches the pattern. + + + +3. Add a full path to the script +================================ + + .. cfgcmd:: set service event-handler event <event-handler name> script path <path to script> + + This is a mandatory command. Sets the full path to the script. The script file must be executable. + + + +4. Add optional parameters +========================== + + .. cfgcmd:: set service event-handler event <event-handler name> filter syslog-identifier <sylogid name> + + This is an optional command. Filters log messages by syslog-identifier. + + .. cfgcmd:: set service event-handler event <event-handler name> script environment <env name> value <env value> + + This is an optional command. Adds environment and its value to the script. Use separate commands for each environment. + + One implicit environment exists. + + * ``message``: Full message that has triggered the script. + + .. cfgcmd:: set service event-handler event <event-handler name> script arguments <arguments> + + This is an optional command. Adds arguments to the script. Arguments must be separated by spaces. + + .. note:: We don't recomend to use arguments. Using environments is more preffereble. + + +******* +Example +******* + + Event handler that monitors the state of interface eth0. + + .. code-block:: none + + set service event-handler event INTERFACE_STATE_DOWN filter pattern '.*eth0.*,RUNNING,.*->.*' + set service event-handler event INTERFACE_STATE_DOWN filter syslog-identifier 'netplugd' + set service event-handler event INTERFACE_STATE_DOWN script environment interface_action value 'down' + set service event-handler event INTERFACE_STATE_DOWN script environment interface_name value 'eth2' + set service event-handler event INTERFACE_STATE_DOWN script path '/config/scripts/eventhandler.py' + + Event handler script + + .. code-block:: none + + #!/usr/bin/env python3 + # + # VyOS event-handler script example + from os import environ + import subprocess + from sys import exit + + # Perform actions according to requirements + def process_event() -> None: + # Get variables + message_text = environ.get('message') + interface_name = environ.get('interface_name') + interface_action = environ.get('interface_action') + # Print the message that triggered this script + print(f'Logged message: {message_text}') + # Prepare a command to run + command = f'sudo ip link set {interface_name} {interface_action}'.split() + # Execute a command + subprocess.run(command) + + if __name__ == '__main__': + try: + # Run script actions and exit + process_event() + exit(0) + except Exception as err: + # Exit properly in case if something in the script goes wrong + print(f'Error running script: {err}') + exit(1) diff --git a/docs/configuration/service/https.rst b/docs/configuration/service/https.rst index 22533db5..08b16575 100644 --- a/docs/configuration/service/https.rst +++ b/docs/configuration/service/https.rst @@ -28,6 +28,10 @@ Configuration Set the listen port of the local API, this has no effect on the webserver. The default is port 8080 +.. cfgcmd:: set service https api socket + + Use local socket for API + .. cfgcmd:: set service https api strict Enforce strict path checking @@ -89,4 +93,4 @@ To use this full configuration we asume a public accessible hostname. set service https virtual-host rtr01 listen-address 198.51.100.2 set service https virtual-host rtr01 listen-port 11443 set service https virtual-host rtr01 server-name rtr01.example.com - set service https api-restrict virtual-host rtr01.example.com + set service https api-restrict virtual-host rtr01 diff --git a/docs/configuration/service/index.rst b/docs/configuration/service/index.rst index 11a1a118..8607490d 100644 --- a/docs/configuration/service/index.rst +++ b/docs/configuration/service/index.rst @@ -25,3 +25,4 @@ Service ssh tftp-server webproxy + eventhandler diff --git a/docs/configuration/service/monitoring.rst b/docs/configuration/service/monitoring.rst index 7396f142..755669e1 100644 --- a/docs/configuration/service/monitoring.rst +++ b/docs/configuration/service/monitoring.rst @@ -1,10 +1,111 @@ Monitoring ---------- -Monitoring functionality with ``telegraf`` and ``InfluxDB 2`` is provided. +Azure-data-explorer +=================== +Telegraf output plugin azure-data-explorer_ + +.. cfgcmd:: set service monitoring telegraf azure-data-explorer authentication client-id <client-id> + + Authentication application client-id. + +.. cfgcmd:: set service monitoring telegraf azure-data-explorer authentication client-secret <client-secret> + + Authentication application client-secret. + +.. cfgcmd:: set service monitoring telegraf azure-data-explorer authentication tenant-id <tenant-id> + + Authentication application tenant-id + +.. cfgcmd:: set service monitoring telegraf azure-data-explorer database <name> + + Remote databe name. + +.. cfgcmd:: set service monitoring telegraf azure-data-explorer group-metrics <single-table | table-per-metric> + + Type of metrics grouping when push to Azure Data Explorer. The default is + ``table-per-metric``. + +.. cfgcmd:: set service monitoring telegraf azure-data-explorer table <name> + + Name of the single table Only if set group-metrics single-table. + +.. cfgcmd:: set service monitoring telegraf azure-data-explorer url <url> + + Remote URL. + +Prometheus-client +================= +Telegraf output plugin prometheus-client_ + +.. cfgcmd:: set service monitoring telegraf prometheus-client + + Output plugin Prometheus client + +.. cfgcmd:: set service monitoring telegraf prometheus-client allow-from <prefix> + + Networks allowed to query this server + +.. cfgcmd:: set service monitoring telegraf prometheus-client authentication username <username> + + HTTP basic authentication username + +.. cfgcmd:: set service monitoring telegraf prometheus-client authentication password <password> + + HTTP basic authentication username + +.. cfgcmd:: set service monitoring telegraf prometheus-client listen-address <address> + + Local IP addresses to listen on + +.. cfgcmd:: set service monitoring telegraf prometheus-client metric-version <1 | 2> + + Metris version, the default is ``2`` + +.. cfgcmd:: set service monitoring telegraf prometheus-client port <port> + + Port number used by connection, default is ``9273`` + +Example: + +.. code-block:: none + + set service monitoring telegraf prometheus-client + +.. code-block:: none + + vyos@r14:~$ curl --silent localhost:9273/metrics | egrep -v "#" | grep cpu_usage_system + cpu_usage_system{cpu="cpu-total",host="r14"} 0.20040080160320556 + cpu_usage_system{cpu="cpu0",host="r14"} 0.17182130584191915 + cpu_usage_system{cpu="cpu1",host="r14"} 0.22896393817971655 + +Splunk +====== +Telegraf output plugin splunk_. HTTP Event Collector. + +.. cfgcmd:: set service monitoring telegraf splunk authentication insecure + + Use TLS but skip host validation + +.. cfgcmd:: set service monitoring telegraf splunk authentication token <token> + + Authorization token + +.. cfgcmd:: set service monitoring telegraf splunk authentication url <url> + + Remote URL to Splunk collector + +Example: + +.. code-block:: none + + set service monitoring telegraf splunk authentication insecure + set service monitoring telegraf splunk authentication token 'xxxxf5b8-xxxx-452a-xxxx-43828911xxxx' + set service monitoring telegraf splunk url 'https://192.0.2.10:8088/services/collector' Telegraf ======== +Monitoring functionality with ``telegraf`` and ``InfluxDB 2`` is provided. Telegraf is the open source server agent to help you collect metrics, events and logs from your routers. @@ -43,3 +144,7 @@ An example of a configuration that sends ``telegraf`` metrics to remote set service monitoring telegraf port '8086' set service monitoring telegraf source 'all' set service monitoring telegraf url 'http://r1.influxdb2.local' + +.. _azure-data-explorer: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/azure_data_explorer +.. _prometheus-client: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/prometheus_client +.. _splunk: https://www.splunk.com/en_us/blog/it/splunk-metrics-via-telegraf.html
\ No newline at end of file diff --git a/docs/configuration/service/ssh.rst b/docs/configuration/service/ssh.rst index ad410a3c..baf17035 100644 --- a/docs/configuration/service/ssh.rst +++ b/docs/configuration/service/ssh.rst @@ -109,6 +109,36 @@ Configuration Specify name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. +Dynamic-protection +================== +Protects host from brute-force attacks against +SSH. Log messages are parsed, line-by-line, for recognized patterns. If an +attack, such as several login failures within a few seconds, is detected, the +offending IP is blocked. Offenders are unblocked after a set interval. + +.. cfgcmd:: set service ssh dynamic-protection + + Allow ``ssh`` dynamic-protection. + +.. cfgcmd:: set service ssh dynamic-protection allow-from <address | prefix> + + Whitelist of addresses and networks. Always allow inbound connections from + these systems. + +.. cfgcmd:: set service ssh dynamic-protection block-time <sec> + + Block source IP in seconds. Subsequent blocks increase by a factor of 1.5 + The default is 120. + +.. cfgcmd:: set service ssh dynamic-protection detect-time <sec> + + Remember source IP in seconds before reset their score. The default is 1800. + +.. cfgcmd:: set service ssh dynamic-protection threshold <sec> + + Block source IP when their cumulative attack score exceeds threshold. The + default is 30. + Operation ========= diff --git a/docs/configuration/system/acceleration.rst b/docs/configuration/system/acceleration.rst new file mode 100644 index 00000000..4c595022 --- /dev/null +++ b/docs/configuration/system/acceleration.rst @@ -0,0 +1,146 @@ +.. _acceleration: + +############ +Acceleration +############ + +In this command tree, all hardware acceleration options will be handled. +At the moment only `Intel® QAT`_ is supported + +********** +Intel® QAT +********** + +.. opcmd:: show system acceleration qat + + use this command to check if there is an Intel® QAT supported Processor in + your system. + + .. code-block:: + + vyos@vyos:~$ show system acceleration qat + 01:00.0 Co-processor [0b40]: Intel Corporation Atom Processor C3000 Series QuickAssist Technology [8086:19e2] (rev 11) + + if there is non device the command will show ```No QAT device found``` + +.. cfgcmd:: set system acceleration qat + + if there is a supported device, enable Intel® QAT + +.. opcmd:: show system acceleration qat status + + Check if the Intel® QAT device is up and ready to do the job. + + .. code-block:: + + vyos@vyos:~$ show system acceleration qat status + Checking status of all devices. + There is 1 QAT acceleration device(s) in the system: + qat_dev0 - type: c3xxx, inst_id: 0, node_id: 0, bsf: 0000:01:00.0, #accel: 3 #engines: 6 state: up + +Operation Mode +============== + +.. opcmd:: show system acceleration qat device <device> config + + Show the full config uploaded to the QAT device. + +.. opcmd:: show system acceleration qat device <device> flows + + Get an overview over the encryption counters. + +.. opcmd:: show system acceleration qat interrupts + + Show binded qat device interrupts to certain core. + + +Example +======= + +Let's build a simple VPN between 2 Intel® QAT ready devices. + +Side A: + +.. code-block:: + + set interfaces vti vti1 address '192.168.1.2/24' + set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256' + set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256' + set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14' + set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256' + set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256' + set vpn ipsec ipsec-interfaces interface 'eth0' + set vpn ipsec site-to-site peer 10.10.10.1 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 10.10.10.1 authentication pre-shared-secret 'Qwerty123' + set vpn ipsec site-to-site peer 10.10.10.1 connection-type 'initiate' + set vpn ipsec site-to-site peer 10.10.10.1 default-esp-group 'MyESPGroup' + set vpn ipsec site-to-site peer 10.10.10.1 ike-group 'MyIKEGroup' + set vpn ipsec site-to-site peer 10.10.10.1 local-address '10.10.10.2' + set vpn ipsec site-to-site peer 10.10.10.1 vti bind 'vti1' + +Side B: + +.. code-block:: + + set interfaces vti vti1 address '192.168.1.1/24' + set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256' + set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256' + set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14' + set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256' + set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256' + set vpn ipsec ipsec-interfaces interface 'eth0' + set vpn ipsec site-to-site peer 10.10.10.2 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 10.10.10.2 authentication pre-shared-secret 'Qwerty123' + set vpn ipsec site-to-site peer 10.10.10.2 connection-type 'initiate' + set vpn ipsec site-to-site peer 10.10.10.2 default-esp-group 'MyESPGroup' + set vpn ipsec site-to-site peer 10.10.10.2 ike-group 'MyIKEGroup' + set vpn ipsec site-to-site peer 10.10.10.2 local-address '10.10.10.1' + set vpn ipsec site-to-site peer 10.10.10.2 vti bind 'vti1' + +a bandwidth test over the VPN got these results: + +.. code-block:: + + Connecting to host 192.168.1.2, port 5201 + [ 9] local 192.168.1.1 port 51344 connected to 192.168.1.2 port 5201 + [ ID] Interval Transfer Bitrate Retr Cwnd + [ 9] 0.00-1.01 sec 32.3 MBytes 268 Mbits/sec 0 196 KBytes + [ 9] 1.01-2.03 sec 32.5 MBytes 268 Mbits/sec 0 208 KBytes + [ 9] 2.03-3.03 sec 32.5 MBytes 271 Mbits/sec 0 208 KBytes + [ 9] 3.03-4.04 sec 32.5 MBytes 272 Mbits/sec 0 208 KBytes + [ 9] 4.04-5.00 sec 31.2 MBytes 272 Mbits/sec 0 208 KBytes + [ 9] 5.00-6.01 sec 32.5 MBytes 272 Mbits/sec 0 234 KBytes + [ 9] 6.01-7.04 sec 32.5 MBytes 265 Mbits/sec 0 234 KBytes + [ 9] 7.04-8.04 sec 32.5 MBytes 272 Mbits/sec 0 234 KBytes + [ 9] 8.04-9.04 sec 32.5 MBytes 273 Mbits/sec 0 336 KBytes + [ 9] 9.04-10.00 sec 31.2 MBytes 272 Mbits/sec 0 336 KBytes + - - - - - - - - - - - - - - - - - - - - - - - - - + [ ID] Interval Transfer Bitrate Retr + [ 9] 0.00-10.00 sec 322 MBytes 270 Mbits/sec 0 sender + [ 9] 0.00-10.00 sec 322 MBytes 270 Mbits/sec receiver + +with :cfgcmd:`set system acceleration qat` on both systems the bandwidth +increases. + +.. code-block:: + + Connecting to host 192.168.1.2, port 5201 + [ 9] local 192.168.1.1 port 51340 connected to 192.168.1.2 port 5201 + [ ID] Interval Transfer Bitrate Retr Cwnd + [ 9] 0.00-1.00 sec 97.3 MBytes 817 Mbits/sec 0 1000 KBytes + [ 9] 1.00-2.00 sec 92.5 MBytes 776 Mbits/sec 0 1.07 MBytes + [ 9] 2.00-3.00 sec 92.5 MBytes 776 Mbits/sec 0 820 KBytes + [ 9] 3.00-4.00 sec 92.5 MBytes 776 Mbits/sec 0 899 KBytes + [ 9] 4.00-5.00 sec 91.2 MBytes 765 Mbits/sec 0 972 KBytes + [ 9] 5.00-6.00 sec 92.5 MBytes 776 Mbits/sec 0 1.02 MBytes + [ 9] 6.00-7.00 sec 92.5 MBytes 776 Mbits/sec 0 1.08 MBytes + [ 9] 7.00-8.00 sec 92.5 MBytes 776 Mbits/sec 0 1.14 MBytes + [ 9] 8.00-9.00 sec 91.2 MBytes 765 Mbits/sec 0 915 KBytes + [ 9] 9.00-10.00 sec 92.5 MBytes 776 Mbits/sec 0 1000 KBytes + - - - - - - - - - - - - - - - - - - - - - - - - - + [ ID] Interval Transfer Bitrate Retr + [ 9] 0.00-10.00 sec 927 MBytes 778 Mbits/sec 0 sender + [ 9] 0.00-10.01 sec 925 MBytes 775 Mbits/sec receiver + + +.. _`Intel® QAT`: https://www.intel.com/content/www/us/en/architecture-and-technology/intel-quick-assist-technology-overview.html
\ No newline at end of file diff --git a/docs/configuration/system/eventhandler.rst b/docs/configuration/system/eventhandler.rst deleted file mode 100644 index 3eab4e2c..00000000 --- a/docs/configuration/system/eventhandler.rst +++ /dev/null @@ -1,51 +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 <name> - description <feed description> - policy <policy name> - source - preset - syslog # Use the syslog logs for feed - custom - command <command to execute> # E.g. "tail -f /var/log/somelogfile" - named-pipe <path to a names pipe> - policy <policy name> - description <policy description> - event <event name> - description <event description> - pattern <regex> - run <command to run> - -In this small example a script runs every time a login failed and an interface -goes down - -.. code-block:: none - - vyos@vyos# show system event-handler - feed Syslog { - policy MyPolicy - source { - preset syslog - } - } - policy MyPolicy { - description "Test policy" - event BadThingsHappened { - pattern "authentication failure" - pattern "interface \.* index \d+ .* DOWN.*" - run /config/scripts/email-to-admin - } - }
\ No newline at end of file diff --git a/docs/configuration/system/index.rst b/docs/configuration/system/index.rst index 9b4bf2e3..5bf781af 100644 --- a/docs/configuration/system/index.rst +++ b/docs/configuration/system/index.rst @@ -7,6 +7,7 @@ System :maxdepth: 1 :includehidden: + acceleration conntrack console flow-accounting @@ -29,4 +30,3 @@ System :includehidden: default-route - eventhandler diff --git a/docs/configuration/system/ip.rst b/docs/configuration/system/ip.rst index 78aeef4e..29f46ae9 100644 --- a/docs/configuration/system/ip.rst +++ b/docs/configuration/system/ip.rst @@ -9,6 +9,15 @@ System configuration commands Use this command to disable IPv4 forwarding on all interfaces. +.. cfgcmd:: set system ip disable-directed-broadcast + + Use this command to disable IPv4 directed broadcast forwarding on all + interfaces. + + If set, IPv4 directed broadcast forwarding will be completely disabled + regardless of whether per-interface directed broadcast forwarding is + enabled or not. + .. cfgcmd:: set system ip arp table-size <number> Use this command to define the maximum number of entries to keep in @@ -67,4 +76,4 @@ And the different IPv4 **reset** commands available: bgp Clear Border Gateway Protocol (BGP) statistics or status igmp IGMP clear commands multicast IP multicast routing table - route Reset IP route
\ No newline at end of file + route Reset IP route diff --git a/docs/configuration/system/ipv6.rst b/docs/configuration/system/ipv6.rst index 19016e7b..0b9f9cc8 100644 --- a/docs/configuration/system/ipv6.rst +++ b/docs/configuration/system/ipv6.rst @@ -160,7 +160,7 @@ Show commands Reset commands ^^^^^^^^^^^^^^ -.. opcmd:: reset ipv6 bgp <address> +.. opcmd:: reset bgp ipv6 <address> Use this command to clear Border Gateway Protocol statistics or status. diff --git a/docs/configuration/vpn/dmvpn.rst b/docs/configuration/vpn/dmvpn.rst index f2c7b162..50563e8b 100644 --- a/docs/configuration/vpn/dmvpn.rst +++ b/docs/configuration/vpn/dmvpn.rst @@ -278,6 +278,7 @@ spoke01-spoke04 ip nhrp registration timeout 75 tunnel source FastEthernet0/0 tunnel mode gre multipoint + tunnel protection ipsec profile DMVPN tunnel key 1 ! interface FastEthernet0/0 diff --git a/docs/configuration/vrf/index.rst b/docs/configuration/vrf/index.rst index 90d99c56..e58005e7 100644 --- a/docs/configuration/vrf/index.rst +++ b/docs/configuration/vrf/index.rst @@ -197,7 +197,7 @@ Example VRF route leaking ----------------- -The following example topology was build using EVE-NG. +The following example topology was built using EVE-NG. .. figure:: /_static/images/vrf-example-topology-01.png :alt: VRF topology example @@ -338,7 +338,7 @@ VRF Route Leaking BGP routes may be leaked (i.e. copied) between a unicast VRF RIB and the VPN SAFI RIB of the default VRF for use in MPLS-based L3VPNs. Unicast routes may also be leaked between any VRFs (including the unicast RIB of the default BGP -instanced). A shortcut syntax is also available for specifying leaking from +instance). A shortcut syntax is also available for specifying leaking from one VRF to another VRF using the default instance’s VPN RIB as the intemediary . A common application of the VRF-VRF feature is to connect a customer’s private routing domain to a provider’s VPN service. Leaking is configured from |