diff options
Diffstat (limited to 'docs/configuration/service')
| -rw-r--r-- | docs/configuration/service/dhcp-server.rst | 212 | ||||
| -rw-r--r-- | docs/configuration/service/ids.rst | 179 | ||||
| -rw-r--r-- | docs/configuration/service/index.rst | 1 | ||||
| -rw-r--r-- | docs/configuration/service/router-advert.rst | 5 |
4 files changed, 199 insertions, 198 deletions
diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst index eaa6a9f2..502d1e1b 100644 --- a/docs/configuration/service/dhcp-server.rst +++ b/docs/configuration/service/dhcp-server.rst @@ -49,15 +49,15 @@ Configuration Inform client that the DNS server can be found at `<address>`. This is the configuration parameter for the entire shared network definition. - All subnets will inherit this configuration item if not specified locally. + All subnets will inherit this configuration item if not specified locally. Multiple DNS servers can be defined. -.. cfgcmd:: set service dhcp-server shared-network-name <name> option +.. cfgcmd:: set service dhcp-server shared-network-name <name> option vendor-option <option-name> - This configuration parameter lets you specify a vendor-option for the - entire shared network definition. All subnets will inherit this - configuration item if not specified locally. An example for Ubiquiti is + This configuration parameter lets you specify a vendor-option for the + entire shared network definition. All subnets will inherit this + configuration item if not specified locally. An example for Ubiquiti is shown below: **Example:** @@ -66,14 +66,14 @@ Pass address of Unifi controller at ``172.16.100.1`` to all clients of ``NET1`` .. code-block:: none - set service dhcp-server shared-network-name 'NET1' option vendor-option + set service dhcp-server shared-network-name 'NET1' option vendor-option ubiquiti '172.16.100.1' .. cfgcmd:: set service dhcp-server listen-address <address> - This configuration parameter lets the DHCP server to listen for DHCP - requests sent to the specified address, it is only realistically useful for - a server whose only clients are reached via unicasts, such as via DHCP relay + This configuration parameter lets the DHCP server to listen for DHCP + requests sent to the specified address, it is only realistically useful for + a server whose only clients are reached via unicasts, such as via DHCP relay agents. Individual Client Subnet @@ -148,24 +148,205 @@ Individual Client Subnet request where no full FQDN is passed. This option can be given multiple times if you need multiple search domains (DHCP Option 119). -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> option vendor-option <option-name> This configuration parameter lets you specify a vendor-option for the - subnet specified within the shared network definition. An example for + subnet specified within the shared network definition. An example for Ubiquiti is shown below: **Example:** -Create ``172.18.201.0/24`` as a subnet within ``NET1`` and pass address of +Create ``172.18.201.0/24`` as a subnet within ``NET1`` and pass address of Unifi controller at ``172.16.100.1`` to clients of that subnet. .. code-block:: none - set service dhcp-server shared-network-name 'NET1' subnet + set service dhcp-server shared-network-name 'NET1' subnet '172.18.201.0/24' option vendor-option ubiquiti '172.16.100.1' +Dynamic DNS Update (RFC 2136) +----------------------------- + +VyOS DHCP service supports RFC-2136 DDNS protocol. Based on DHCP lease change +events, DHCP server generates DDNS update requests (defines as NameChangeRequests +or NCRs) and posts them to a compliant DNS server, that will update its name +database accordingly. + +VyOS built-in DNS Forwarder does not support DDNS, you will need an external DNS +server with RFC-2136 DDNS support. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update + + Enables DDNS globally. + +**Behavioral settings** + +These settings can be configured on the global level and overridden on the scope +level, i.e. for individual shared networks or subnets. See examples below. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update send-updates [ enable + | disable ] + + If set to ``enable`` on global level, updates for all scopes will be enabled, + except if explicitly set to ``disable`` on the scope level. If set to ``disable``, + updates will only be sent for scopes, where ``send-updates`` is explicity + set to ``enable``. + + This model is followed for a few behavioral settings below: if the option is + not set, the setting is inherited from the parent scope. You can override the + parent scope setting by setting the option explicitly. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update override-no-update [ enable + | disable ] + + VyOS will ignore client request not to update DNS records and send DDNS + update requests regardless. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update override-client-update [ enable + | disable ] + + VyOS will override client DDNS request settings and always update both + forward and reverse DNS records. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update update-on-renew [ enable + | disable ] + + Issue DDNS update requests on DHCP lease renew. In busy networks this may + generate a lot of traffic. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update conflict-resolution [ enable + | disable ] + + Use RFC-4703 conflict resolution. This algorithm helps in situation when + multiple clients reserve same IP addresses or advertise identical hostnames. + Should be used in most situations. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update replace-client-name [ never + | always | when-present | when-not-present ] + + * **never**: use the name sent by the client. If the client didn't provide any, + do not generate one. This is the default behavior + + * **always**: always generate a name for the client + + * **when-present**: replace the name the client sent with a generated one, if + the client didn't send any, do not generate one + + * **when-not-present**: use the name sent by the client. If the client didn't + send any, generate one for the client + + The names are generated using ``generated-prefix``, ``qualifying-suffix`` and the + client's IP address string. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update generated-prefix <prefix> + + Prefix used in client name generation. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update qualifying-suffix <suffix> + + DNS suffix used in client name generation. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update ttl-percent <0-100> + + TTL of the DNS record as a percentage of the DHCP lease time. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update hostname-char-set + <character string> + + Characters, that are considered invalid in the client name. They will be replaced + with ``hostname-char-replacement`` string. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update hostname-char-replacement + <character string> + + Replacement string for the invalid characters defined by ``hostname-char-set``. + +**TSIG keys definition** + +This is the global list of TSIG keys for DDNS updates. They need to be specified by +the name in the DNS domain definitions. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update tsig-key <key-name> + algorithm <algorithm> + + Sets the algorithm for the TSIG key. Supported algorithms are ``hmac-md5``, + ``hmac-sha1``, ``hmac-sha224``, ``hmac-sha256``, ``hmac-sha384``, ``hmac-sha512`` + +.. cfgcmd:: set service dhcp-server dynamic-dns-update tsig-key <key-name> + secret <key-secret> + + base64-encoded TSIG key secret value + +**DNS domains definition** + +This is global configuration of DNS servers for the updatable forward and reverse +DNS domains. For every domain multiple DNS servers can be specified. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-domain + <domain-name> key-name <tsig-key-name> + + TSIG key used for the domain. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-domain + <domain-name> dns-server <number> address <ip-address> + + IP address of the DNS server. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-domain + <domain-name> dns-server <number> port <port> + + UDP port of the DNS server. ``53`` is the default. + +**Example:** + +Global configuration you will most likely want: + +.. code-block:: none + + set service dhcp-server dynamic-dns-update send-updates enable + set service dhcp-server dynamic-dns-update conflict-resolution enable + +Override the above configuration for a shared network NET1: + +.. code-block:: none + + set service dhcp-server shared-network-name 'NET1' dynamic-dns-update replace-client-name when-not-present + set service dhcp-server shared-network-name 'NET1' dynamic-dns-update generated-prefix ip + set service dhcp-server shared-network-name 'NET1' dynamic-dns-update qualifying-suffix mybigdomain.net + +And in a subnet within the same shared network: + +.. code-block:: none + + set service dhcp-server shared-network-name 'NET1' subnet '172.18.201.0/24' dynamic-dns-update qualifying-suffix mydomain.net + +Configure TSIG keys: + +.. code-block:: none + + set service dhcp-server dynamic-dns-update tsig-key mydomain-net algorithm hmac-sha256 + set service dhcp-server dynamic-dns-update tsig-key mydomain-net secret eWF5YW15bGl0dGxla2V5IQ== + set service dhcp-server dynamic-dns-update tsig-key reverse-172-18-201 algorithm hmac-sha256 + set service dhcp-server dynamic-dns-update tsig-key reverse-172-18-201 secret eWF5YW15YW5vdGhlcmxpdHRsZWtleSE= + +Configure DDNS domains: + +.. code-block:: none + + set service dhcp-server dynamic-dns-update forward-domain mydomain.net key-name mydomain-net + set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 1 address '172.18.0.254' + set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 1 port 1053 + set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 2 address '192.168.124.254' + set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 2 port 53 + set service dhcp-server dynamic-dns-update forward-domain 201.18.172.in-addr.arpa key-name reverse-172-18-201 + set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 1 address '172.18.0.254' + set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 1 port 1053 + set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 2 address '192.168.124.254' + set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 2 port 53 + + High Availability ----------------- @@ -645,7 +826,7 @@ used: .. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet - <prefix> prefix-delegation prefix <pd-prefix> excluded-prefix-length <length> + <prefix> prefix-delegation prefix <pd-prefix> excluded-prefix-length <length> Define lenght of exclude prefix in `<pd-prefix>`. @@ -663,8 +844,7 @@ used: set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 range 1 stop 2001:db8::199 set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 prefix-delegation prefix 2001:db8:0:10:: delegated-length '64' set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 prefix-delegation prefix 2001:db8:0:10:: prefix-length '60' - - + set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 subnet-id 1 Address pools ------------- diff --git a/docs/configuration/service/ids.rst b/docs/configuration/service/ids.rst deleted file mode 100644 index 8a64467f..00000000 --- a/docs/configuration/service/ids.rst +++ /dev/null @@ -1,179 +0,0 @@ -.. _ids: - -############### -DDoS Protection -############### - -********** -FastNetMon -********** - -FastNetMon is a high-performance DDoS detector/sensor built on top of multiple -packet capture engines: NetFlow, IPFIX, sFlow, AF_PACKET (port mirror). It can -detect hosts in the deployed network sending or receiving large volumes of -traffic, packets/bytes/flows per second and perform a configurable action to -handle that event, such as calling a custom script. - -VyOS includes the FastNetMon Community Edition. - -Configuration -============= - -.. cfgcmd:: set service ids ddos-protection alert-script <text> - - Configure alert script that will be executed when an attack is detected. - -.. cfgcmd:: set service ids ddos-protection ban-time <1-4294967294> - - Configure how long an IP (attacker) should be kept in blocked state. - Default value is 1900. - -.. cfgcmd:: set service ids ddos-protection direction [in | out] - - Configure direction for processing traffic. - -.. cfgcmd:: set service ids ddos-protection exclude-network <x.x.x.x/x> -.. cfgcmd:: set service ids ddos-protection exclude-network <h:h:h:h:h:h:h:h/x> - - Specify IPv4 and/or IPv6 networks which are going to be excluded. - -.. cfgcmd:: set service ids ddos-protection listen-interface <text> - - Configure listen interface for mirroring traffic. - -.. cfgcmd:: set service ids ddos-protection mode [mirror | sflow] - - Configure traffic capture mode. - -.. cfgcmd:: set service ids ddos-protection network <x.x.x.x/x> -.. cfgcmd:: set service ids ddos-protection network <h:h:h:h:h:h:h:h/x> - - Specify IPv4 and/or IPv6 networks that should be protected/monitored. - -.. cfgcmd:: set service ids ddos-protection sflow listen-address <x.x.x.x> - - Configure local IPv4 address to listen for sflow. - -.. cfgcmd:: set service ids ddos-protection sflow port <1-65535> - - Configure port number to be used for sflow connection. Default port is 6343. - -.. cfgcmd:: set service ids ddos-protection threshold general - [fps | mbps | pps] <0-4294967294> - - Configure general threshold parameters. - -.. cfgcmd:: set service ids ddos-protection threshold icmp - [fps | mbps | pps] <0-4294967294> - - Configure ICMP threshold parameters. - -.. cfgcmd:: set service ids ddos-protection threshold tcp - [fps | mbps | pps] <0-4294967294> - - Configure TCP threshold parameters - -.. cfgcmd:: set service ids ddos-protection threshold udp - [fps | mbps | pps] <0-4294967294> - - Configure UDP threshold parameters - -Example -======= - -A configuration example can be found in this section. -In this simplified scenario, main things to be considered are: - - * Network to be protected: 192.0.2.0/24 (public IPs use by - customers) - - * **ban-time** and **threshold**: these values are kept very low in order - to easily identify and generate and attack. - - * Direction: **in** and **out**. Protect public network from external - attacks, and identify internal attacks towards internet. - - * Interface **eth0** used to connect to upstream. - -Since we are analyzing attacks to and from our internal network, two types -of attacks can be identified, and different actions are needed: - - * External attack: an attack from the internet towards an internal IP - is identify. In this case, all connections towards such IP will be - blocked - - * Internal attack: an attack from the internal network (generated by a - customer) towards the internet is identify. In this case, all connections - from this particular IP/Customer will be blocked. - - -So, firewall configuration needed for this setup: - -.. code-block:: none - - set firewall group address-group FNMS-DST-Block - set firewall group address-group FNMS-SRC-Block - - set firewall ipv4 forward filter rule 10 action 'drop' - set firewall ipv4 forward filter rule 10 description 'FNMS - block destination' - set firewall ipv4 forward filter rule 10 destination group address-group 'FNMS-DST-Block' - - set firewall ipv4 forward filter rule 20 action 'drop' - set firewall ipv4 forward filter rule 20 description 'FNMS - Block source' - set firewall ipv4 forward filter rule 20 source group address-group 'FNMS-SRC-Block' - -Then, FastNetMon configuration: - -.. code-block:: none - - set service ids ddos-protection alert-script '/config/scripts/fnm-alert.sh' - set service ids ddos-protection ban-time '10' - set service ids ddos-protection direction 'in' - set service ids ddos-protection direction 'out' - set service ids ddos-protection listen-interface 'eth0' - set service ids ddos-protection mode 'mirror' - set service ids ddos-protection network '192.0.2.0/24' - set service ids ddos-protection threshold general pps '100' - -And content of the script: - -.. code-block:: none - - #!/bin/bash - - # alert-script is called twice. - # When an attack occurs, the program calls a bash script twice: - # 1st time when threshold exceed - # 2nd when we collect 100 packets for detailed audit of what happened. - - # Do nothing if “attack_details” is passed as an argument - if [ "${4}" == "attack_details" ]; then - # Do nothing - exit - fi - # Arguments: - ip=$1 - direction=$2 - pps_rate=$3 - action=$4 - - logger -t FNMS "** Start - Running alert script **" - - if [ "${direction}" == "incoming" ] ; then - group="FNMS-DST-Block" - origin="external" - else - group="FNMS-SRC-Block" - origin="internal" - fi - - if [ "${action}" == "ban" ] ; then - logger -t FNMS "Attack detected for IP ${ip} and ${direction} direction from ${origin} network. Need to block IP address." - logger -t FNMS "Adding IP address ${ip} to firewall group ${group}." - sudo nft add element ip vyos_filter A_${group} { ${ip} } - else - logger -t FNMS "Timeout for IP ${ip}, removing it from group ${group}." - sudo nft delete element ip vyos_filter A_${group} { ${ip} } - fi - logger -t FNMS "** End - Running alert script **" - exit diff --git a/docs/configuration/service/index.rst b/docs/configuration/service/index.rst index f5c97d14..fb6f8413 100644 --- a/docs/configuration/service/index.rst +++ b/docs/configuration/service/index.rst @@ -16,7 +16,6 @@ Service dns eventhandler https - ids ipoe-server lldp mdns diff --git a/docs/configuration/service/router-advert.rst b/docs/configuration/service/router-advert.rst index 365017dd..cb9a6037 100644 --- a/docs/configuration/service/router-advert.rst +++ b/docs/configuration/service/router-advert.rst @@ -46,6 +46,7 @@ Configuration "Interval", "interval", "Min and max intervals between unsolicited multicast RAs" "DNSSL", "dnssl", "DNS search list to advertise" "Name Server", "name-server", "Advertise DNS server per https://tools.ietf.org/html/rfc6106" + "Auto Ignore Prefix", "auto-ignore", "Exclude a prefix from being advertised when the wildcard ::/64 prefix is used" .. start_vyoslinter @@ -56,8 +57,8 @@ Advertising a Prefix .. cfgcmd:: set service router-advert interface <interface> prefix <prefix/mask> .. note:: You can also opt for using `::/64` as prefix for your :abbr:`RAs (Router - Advertisements)`. This will take the IPv6 GUA prefix assigned to the interface, - which comes in handy when using DHCPv6-PD. + Advertisements)`. This is a special wildcard prefix that will emit :abbr:`RAs (Router Advertisements)` for every prefix assigned to the interface. + This comes in handy when using dynamically obtained prefixes from DHCPv6-PD. .. stop_vyoslinter |