From 8943fc9f877cbee3301a8261ddd27b4b1f15f174 Mon Sep 17 00:00:00 2001 From: rebortg Date: Mon, 30 Nov 2020 20:53:36 +0100 Subject: arrange services and protocols --- docs/configuration/service/broadcast-relay.rst | 61 ++ docs/configuration/service/conntrack-sync.rst | 200 +++++++ docs/configuration/service/console-server.rst | 107 ++++ docs/configuration/service/dhcp-relay.rst | 2 + docs/configuration/service/dhcp-server.rst | 776 +++++++++++++++++++++++++ docs/configuration/service/dhcpv6-relay.rst | 2 + docs/configuration/service/dhcpv6-server.rst | 2 + docs/configuration/service/dns.rst | 313 ++++++++++ docs/configuration/service/https.rst | 166 ++++++ docs/configuration/service/index.rst | 29 + docs/configuration/service/ipoe-server.rst | 149 +++++ docs/configuration/service/lldp.rst | 141 +++++ docs/configuration/service/mdns.rst | 44 ++ docs/configuration/service/pppoe-advert.rst | 2 + docs/configuration/service/pppoe-server.rst | 397 +++++++++++++ docs/configuration/service/router-advert.rst | 89 +++ docs/configuration/service/salt-minion.rst | 2 + docs/configuration/service/snmp.rst | 266 +++++++++ docs/configuration/service/ssh.rst | 106 ++++ docs/configuration/service/tftp-server.rst | 54 ++ docs/configuration/service/webproxy.rst | 153 +++++ 21 files changed, 3061 insertions(+) create mode 100644 docs/configuration/service/broadcast-relay.rst create mode 100644 docs/configuration/service/conntrack-sync.rst create mode 100644 docs/configuration/service/console-server.rst create mode 100644 docs/configuration/service/dhcp-relay.rst create mode 100644 docs/configuration/service/dhcp-server.rst create mode 100644 docs/configuration/service/dhcpv6-relay.rst create mode 100644 docs/configuration/service/dhcpv6-server.rst create mode 100644 docs/configuration/service/dns.rst create mode 100644 docs/configuration/service/https.rst create mode 100644 docs/configuration/service/index.rst create mode 100644 docs/configuration/service/ipoe-server.rst create mode 100644 docs/configuration/service/lldp.rst create mode 100644 docs/configuration/service/mdns.rst create mode 100644 docs/configuration/service/pppoe-advert.rst create mode 100644 docs/configuration/service/pppoe-server.rst create mode 100644 docs/configuration/service/router-advert.rst create mode 100644 docs/configuration/service/salt-minion.rst create mode 100644 docs/configuration/service/snmp.rst create mode 100644 docs/configuration/service/ssh.rst create mode 100644 docs/configuration/service/tftp-server.rst create mode 100644 docs/configuration/service/webproxy.rst (limited to 'docs/configuration/service') diff --git a/docs/configuration/service/broadcast-relay.rst b/docs/configuration/service/broadcast-relay.rst new file mode 100644 index 00000000..df48bfd6 --- /dev/null +++ b/docs/configuration/service/broadcast-relay.rst @@ -0,0 +1,61 @@ +.. _udp_broadcast_relay: + +################### +UDP Broadcast Relay +################### + +Certain vendors use broadcasts to identify their equipment within one ethernet +segment. Unfortunately if you split your network with multiple VLANs you loose +the ability of identifying your equipment. + +This is where "UDP broadcast relay" comes into play! It will forward received +broadcasts to other configured networks. + +Every UDP port which will be forward requires one unique ID. Currently we +support 99 IDs! + +Configuration +------------- + +.. cfgcmd:: set service broadcast-relay id description + + A description can be added for each and every unique relay ID. This is + useful to distinguish between multiple different ports/appliactions. + +.. cfgcmd:: set service broadcast-relay id interface + + The interface used to receive and relay individual broadcast packets. If you + want to receive/relay packets on both `eth1` and `eth2` both interfaces need + to be added. + +.. cfgcmd:: set service broadcast-relay id port + + The UDP port number used by your apllication. It is mandatory for this kind + of operation. + +.. cfgcmd:: set service broadcast-relay id disable + + Each broadcast relay instance can be individually disabled without deleting + the configured node by using the following command: + +.. cfgcmd:: set service broadcast-relay disable + + In addition you can also disable the whole service without the need to remove + it from the current configuration. + +.. note:: You can run the UDP broadcast relay service on multiple routers + connected to a subnet. There is **NO** UDP broadcast relay packet storm! + +Example +------- + +To forward all broadcast packets received on `UDP port 1900` on `eth3`, `eth4` +or `eth5` to all other interfaces in this configuration. + +.. code-block:: none + + set service broadcast-relay id 1 description 'SONOS' + set service broadcast-relay id 1 interface 'eth3' + set service broadcast-relay id 1 interface 'eth4' + set service broadcast-relay id 1 interface 'eth5' + set service broadcast-relay id 1 port '1900' diff --git a/docs/configuration/service/conntrack-sync.rst b/docs/configuration/service/conntrack-sync.rst new file mode 100644 index 00000000..55cd088e --- /dev/null +++ b/docs/configuration/service/conntrack-sync.rst @@ -0,0 +1,200 @@ +.. include:: /_include/need_improvement.txt + +Conntrack +--------- + +One of the important features built on top of the Netfilter framework is +connection tracking. Connection tracking allows the kernel to keep track of all +logical network connections or sessions, and thereby relate all of the packets +which may make up that connection. NAT relies on this information to translate +all related packets in the same way, and iptables can use this information to +act as a stateful firewall. + +The connection state however is completely independent of any upper-level +state, such as TCP's or SCTP's state. Part of the reason for this is that when +merely forwarding packets, i.e. no local delivery, the TCP engine may not +necessarily be invoked at all. Even connectionless-mode transmissions such as +UDP, IPsec (AH/ESP), GRE and other tunneling protocols have, at least, a pseudo +connection state. The heuristic for such protocols is often based upon a preset +timeout value for inactivity, after whose expiration a Netfilter connection is +dropped. + +Each Netfilter connection is uniquely identified by a (layer-3 protocol, source +address, destination address, layer-4 protocol, layer-4 key) tuple. The layer-4 +key depends on the transport protocol; for TCP/UDP it is the port numbers, for +tunnels it can be their tunnel ID, but otherwise is just zero, as if it were +not part of the tuple. To be able to inspect the TCP port in all cases, packets +will be mandatorily defragmented. + +It is possible to use either Multicast or Unicast to sync conntrack traffic. +Most examples below show Multicast, but unicast can be specified by using the +"peer" keywork after the specificed interface, as in the following example: + +set service conntrack-sync interface eth0 peer 192.168.0.250 + +Configuration +^^^^^^^^^^^^^ + +.. code-block:: none + + # Protocols only for which local conntrack entries will be synced (tcp, udp, icmp, sctp) + set service conntrack-sync accept-protocol + + # Queue size for listening to local conntrack events (in MB) + set service conntrack-sync event-listen-queue-size + + # Protocol for which expect entries need to be synchronized. (all, ftp, h323, nfs, sip, sqlnet) + set service conntrack-sync expect-sync + + # Failover mechanism to use for conntrack-sync [REQUIRED] + set service conntrack-sync failover-mechanism + + set service conntrack-sync cluster group + set service conntrack-sync vrrp sync-group <1-255> + + # IP addresses for which local conntrack entries will not be synced + set service conntrack-sync ignore-address ipv4 + + # Interface to use for syncing conntrack entries [REQUIRED] + set service conntrack-sync interface + + # Multicast group to use for syncing conntrack entries + set service conntrack-sync mcast-group + + # Peer to send Unicast UDP conntrack sync entires to, if not using Multicast above + set service conntrack-sync interface peer + + # Queue size for syncing conntrack entries (in MB) + set service conntrack-sync sync-queue-size + +Example +^^^^^^^ +The next example is a simple configuration of conntrack-sync. + + +.. figure:: /_static/images/service_conntrack_sync-schema.png + :scale: 60 % + :alt: Conntrack Sync Example + + Conntrack Sync Example + +First of all, make sure conntrack is enabled by running + +.. code-block:: none + + show conntrack table ipv4 + +If the table is empty and you have a warning message, it means conntrack is not +enabled. To enable conntrack, just create a NAT or a firewall rule. + +.. code-block:: none + + set firewall state-policy established action accept + +You now should have a conntrack table + +.. code-block:: none + + $ show conntrack table ipv4 + TCP state codes: SS - SYN SENT, SR - SYN RECEIVED, ES - ESTABLISHED, + FW - FIN WAIT, CW - CLOSE WAIT, LA - LAST ACK, + TW - TIME WAIT, CL - CLOSE, LI - LISTEN + + CONN ID Source Destination Protocol TIMEOUT + 1015736576 10.35.100.87:58172 172.31.20.12:22 tcp [6] ES 430279 + 1006235648 10.35.101.221:57483 172.31.120.21:22 tcp [6] ES 413310 + 1006237088 10.100.68.100 172.31.120.21 icmp [1] 29 + 1015734848 10.35.100.87:56282 172.31.20.12:22 tcp [6] ES 300 + 1015734272 172.31.20.12:60286 239.10.10.14:694 udp [17] 29 + 1006239392 10.35.101.221 172.31.120.21 icmp [1] 29 + +Now configure conntrack-sync service on ``router1`` **and** ``router2`` + +.. code-block:: none + + set service conntrack-sync accept-protocol 'tcp,udp,icmp' + set service conntrack-sync event-listen-queue-size '8' + set service conntrack-sync failover-mechanism cluster group 'GROUP' + set service conntrack-sync interface 'eth0' + set service conntrack-sync mcast-group '225.0.0.50' + set service conntrack-sync sync-queue-size '8' + +If you are using VRRP, you need to define a VRRP sync-group, and use ``vrrp sync-group`` instead of ``cluster group``. + +.. code-block:: none + + set high-availablilty vrrp group internal virtual-address ... etc ... + set high-availability vrrp sync-group syncgrp member 'internal' + set service conntrack-sync failover-mechanism vrrp sync-group 'syncgrp' + + +On the active router, you should have information in the internal-cache of +conntrack-sync. The same current active connections number should be shown in +the external-cache of the standby router + +On active router run: + +.. code-block:: none + + $ show conntrack-sync statistics + + Main Table Statistics: + + cache internal: + current active connections: 10 + connections created: 8517 failed: 0 + connections updated: 127 failed: 0 + connections destroyed: 8507 failed: 0 + + cache external: + current active connections: 0 + connections created: 0 failed: 0 + connections updated: 0 failed: 0 + connections destroyed: 0 failed: 0 + + traffic processed: + 0 Bytes 0 Pckts + + multicast traffic (active device=eth0): + 868780 Bytes sent 224136 Bytes recv + 20595 Pckts sent 14034 Pckts recv + 0 Error send 0 Error recv + + message tracking: + 0 Malformed msgs 0 Lost msgs + + + +On standby router run: + + +.. code-block:: none + + + $ show conntrack-sync statistics + + Main Table Statistics: + + cache internal: + current active connections: 0 + connections created: 0 failed: 0 + connections updated: 0 failed: 0 + connections destroyed: 0 failed: 0 + + cache external: + current active connections: 10 + connections created: 888 failed: 0 + connections updated: 134 failed: 0 + connections destroyed: 878 failed: 0 + + traffic processed: + 0 Bytes 0 Pckts + + multicast traffic (active device=eth0): + 234184 Bytes sent 907504 Bytes recv + 14663 Pckts sent 21495 Pckts recv + 0 Error send 0 Error recv + + message tracking: + 0 Malformed msgs 0 Lost msgs + diff --git a/docs/configuration/service/console-server.rst b/docs/configuration/service/console-server.rst new file mode 100644 index 00000000..cf222544 --- /dev/null +++ b/docs/configuration/service/console-server.rst @@ -0,0 +1,107 @@ +.. _console_server: + +############## +Console Server +############## + +Starting of with VyOS 1.3 (equuleus) we added support for running VyOS as an +Out-of-Band Management device which provides remote access by means of SSH to +directly attached serial interfaces. + +Serial interfaces can be any interface which is directly connected to the CPU +or chipset (mostly known as a ttyS interface in Linux) or any other USB to +serial converter (Prolific PL2303 or FTDI FT232/FT4232 based chips). + +If you happened to use a Cisco NM-16A - Sixteen Port Async Network Module or +NM-32A - Thirty-two Port Async Network Module - this is your VyOS replacement. + +For USB port information please refor to: :ref:`hardware_usb`. + +Configuration +============= + +Between computers, the most common configuration used was "8N1": eight bit +characters, with one start bit, one stop bit, and no parity bit. Thus 10 Baud +times are used to send a single character, and so dividing the signalling +bit-rate by ten results in the overall transmission speed in characters per +second. This is also the default setting if none of those options are defined. + +.. cfgcmd:: set service console-server data-bits [7 | 8] + + Configure either seven or eight data bits. This defaults to eight data + bits if left unconfigured. + +.. cfgcmd:: set service console-server description + + A user friendly description identifying the connected peripheral. + +.. cfgcmd:: set service console-server parity [even | odd | none] + + Set the parity option for the console. If unset this will default to none. + +.. cfgcmd:: set service console-server stop-bits [1 | 2] + + Configure either one or two stop bits. This defaults to one stop bits if + left unconfigured. + +.. cfgcmd:: set service console-server speed [ 300 | 1200 | 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200 ] + + .. note:: USB to serial converters will handle most of their work in software + so you should be carefull with the selected baudrate as some times they + can't cope with the expected speed. + +Remote Access +------------- + +Each individual configured console-server device can be directly exposed to +the outside world. A user can directly connect via SSH to the configured +port. + +.. cfgcmd:: set service console-server ssh port + + Accept SSH connections for the given `` on TCP port ``. + After successfull authentication the user will be directly dropped to + the connected serial device. + + .. hint:: Multiple users can connect to the same serial device but only + one is allowed to write to the console port. + +Operation +========= + +.. opcmd:: show console-server ports + + Show configured serial ports and their respective interface configuration. + + .. code-block:: none + + vyos@vyos:~$ show console-server ports + usb0b2.4p1.0 on /dev/serial/by-bus/usb0b2.4p1.0@ at 9600n + +.. opcmd:: show console-server user + + Show currently connected users. + + .. code-block:: none + + vyos@vyos:~$ show console-server user + usb0b2.4p1.0 up vyos@localhost + + +.. opcmd:: connect console-server + + Locally connect to serial port identified by ``. + + .. code-block:: none + + vyos@vyos-r1:~$ connect console-server usb0b2.4p1.0 + [Enter `^Ec?' for help] + [-- MOTD -- VyOS Console Server] + + vyos-r2 login: + + .. hint:: Multiple users can connect to the same serial device but only + one is allowed to write to the console port. + + .. hint:: The sequence ``^Ec?`` translates to: ``Ctrl+E c ?``. To quit + the session use: ``Ctrl+E c .`` diff --git a/docs/configuration/service/dhcp-relay.rst b/docs/configuration/service/dhcp-relay.rst new file mode 100644 index 00000000..445519b3 --- /dev/null +++ b/docs/configuration/service/dhcp-relay.rst @@ -0,0 +1,2 @@ +dhcp-relay +########## \ No newline at end of file diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst new file mode 100644 index 00000000..56316793 --- /dev/null +++ b/docs/configuration/service/dhcp-server.rst @@ -0,0 +1,776 @@ +.. _dhcp: + +############# +DHCP / DHCPv6 +############# + +VyOS uses ISC DHCPd for both IPv4 and IPv6 address assignment. + +.. _dhcp-server: + +DHCP Server +=========== + +The network topology is declared by shared-network-name and the subnet +declarations. The DHCP service can serve multiple shared networks, with each +shared network having 1 or more subnets. Each subnet must be present on an +interface. A range can be declared inside a subnet to define a pool of dynamic +addresses. Multiple ranges can be defined and can contain holes. Static +mappings can be set to assign "static" addresses to clients based on their MAC +address. + +Configuration +------------- + +.. cfgcmd:: set service dhcp-server shared-network-name authoritative + + This says that this device is the only DHCP server for this network. If other + devices are trying to offer DHCP leases, this machine will send 'DHCPNAK' to + any device trying to request an IP address that is not valid for this + network. + +.. cfgcmd:: set service dhcp-server shared-network-name subnet default-router
+ + This is a configuration parameter for the ``, saying that as part of + the response, tell the client that the default gateway can be reached at + `
`. + +.. cfgcmd:: set service dhcp-server shared-network-name subnet dns-server
+ + This is a configuration parameter for the subnet, saying that as part of the + response, tell the client that the DNS server can be found at `
`. + + Multiple DNS servers can be defined. + +.. cfgcmd:: set service dhcp-server shared-network-name subnet lease