diff options
| -rw-r--r-- | docs/about.rst | 21 | ||||
| -rw-r--r-- | docs/contributing/development.rst | 85 | ||||
| -rw-r--r-- | docs/index.rst | 23 | ||||
| -rw-r--r-- | docs/routing/bgp.rst | 204 | ||||
| -rw-r--r-- | docs/routing/index.rst | 1 | ||||
| -rw-r--r-- | docs/routing/rpki.rst | 46 | ||||
| -rw-r--r-- | docs/services/dhcp.rst | 304 | ||||
| -rw-r--r-- | docs/services/dns-forwarding.rst | 163 | ||||
| -rw-r--r-- | docs/services/dynamic-dns.rst | 196 | ||||
| -rw-r--r-- | docs/services/lldp.rst | 139 | ||||
| -rw-r--r-- | docs/services/references.rst | 3 | ||||
| -rw-r--r-- | docs/services/ssh.rst | 185 | ||||
| -rw-r--r-- | docs/services/tftp.rst | 58 | ||||
| -rw-r--r-- | docs/system/config-management.rst | 43 | ||||
| -rw-r--r-- | docs/system/syslog.rst | 303 |
15 files changed, 1206 insertions, 568 deletions
diff --git a/docs/about.rst b/docs/about.rst index 9a7a7aac..15a672a6 100644 --- a/docs/about.rst +++ b/docs/about.rst @@ -25,24 +25,3 @@ always refer to the documentation matching your current, running installation. If a change in the CLI is required, VyOS will ship a so called migration script which will take care of adjusting the synatax. No action needs to be taken by you. - - -**************** -Copyright Notice -**************** - -Copyright (C) 2018-2019 VyOS maintainers and contributors - -Permission is granted to make and distribute verbatim copies of this manual -provided the copyright notice and this permission notice are preserved on all -copies. - -Permission is granted to copy and distribute modified versions of this manual -under the conditions for verbatim copying, provided that the entire resulting -derived work is distributed under the terms of a permission notice identical -to this one. - -Permission is granted to copy and distribute translations of this manual into -another language, under the above conditions for modified versions, except that -this permission notice may be stated in a translation approved by the VyOS -maintainers.
\ No newline at end of file diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst index c699ad48..1c257772 100644 --- a/docs/contributing/development.rst +++ b/docs/contributing/development.rst @@ -41,14 +41,18 @@ impossible to keep track of all the changes and bugs/feature requests in one's head. We use a bugtracker known as Phabricator_ for it ("issue tracker" would be a better term, but this one stuck). -The information is used in two ways: +The information is used in three ways: * Keep track of the progress (what we've already done in this branch and what we still need to do). * Prepare release notes for upcoming releases -To make this approach work, every change must be associated with a bug number +* Help future maintainers of VyOS (it could be you!) to find out why certain + things have been changed in the codebase or why certain features have been + added + +To make this approach work, every change must be associated with a task number (prefixed with **T**) and a component. If there is no bug report/feature request for the changes you are going to make, you have to create a Phabricator_ task first. Once there is an entry in Phabricator_, you should reference its id in @@ -61,19 +65,21 @@ If there is no Phabricator_ reference in the commits of your pull request, we have to ask you to ammend the commit message. Otherwise we will have to reject it. -In general, use an editor to create your commit messages rather than passing -them on the command line. The format should be and is inspired by this blog -post: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html +Writing good commit messages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* A single, short, summary of the commit (recommended 50 characters or less, - not exceeding 80 characters) +The format should be and is inspired by: https://git-scm.com/book/ch5-2.html - * Add prefix of changed component to your commit headline, e.g. ``snmp: - T1111:`` or ``ethernet: T2222:``. If multiple components are touched by - this commit, you can use multiple prefixes, e.g.: ``snmp: ethernet:`` +* A single, short, summary of the commit (recommended 50 characters or less, + not exceeding 80 characters) containing a prefix of the changed component + and the corresponding Phabricator_ reference e.g. ``snmp: T1111:`` or + ``ethernet: T2222:`` - multiple components could be concatenated as in + ``snmp: ethernet: T3333`` -* Followed by a blank line (this line is mandatory - else Git will treat the - whole commit message as the headline only) +* In some contexts, the first line is treated as the subject of an email and + the rest of the text as the body. The blank line separating the summary from + the body is critical (unless you omit the body entirely); tools like rebase + can get confused if you run the two together. * Followed by a message which describes all the details like: @@ -108,6 +114,7 @@ Limits: Please submit your patches using the well-known GitHub pull-request against our repositories found in the VyOS GitHub organisation at https://github.com/vyos + Determinine source package -------------------------- @@ -125,6 +132,7 @@ This means the file in question (``/opt/vyatta/sbin/vyatta-update-webproxy.pl``) is located in the ``vyatta-webproxy`` package which can be found here: https://github.com/vyos/vyatta-webproxy + Fork Repository and submit Patch -------------------------------- @@ -161,6 +169,7 @@ record them in your created Git commit: * Submit the patch ``git push`` and create the GitHub pull-request. + Attach patch to Phabricator task -------------------------------- @@ -172,6 +181,7 @@ commits and send it to maintainers@vyos.net or attach it directly to the bug * Export last commit to patch file: ``git format-patch`` or export the last two commits into its appropriate patch files: ``git format-patch -2`` + Coding Guidelines ================= @@ -184,6 +194,7 @@ implied logic of any one source file.. Python 3 **shall** be used. How long can we keep Python 2 alive anyway? No considerations for Python 2 compatibility **should** be taken at any time. + Formatting ---------- @@ -195,6 +206,7 @@ Formatting ``au FileType xml setlocal equalprg=xmllint\ --format\ --recover\ -\ 2>/dev/null`` now you can call the linter using ``gg=G`` in command mode. + Text generation ^^^^^^^^^^^^^^^ @@ -205,6 +217,7 @@ used for structured, multi-line formats such as those used by ISC DHCPd. The default template processor for VyOS code is Jinja2_. + Summary ------- @@ -215,6 +228,7 @@ campaign: * No old style command definitions * No code incompatible with Python3 + Python ====== @@ -240,6 +254,7 @@ Please use the following template as good starting point when developing new modules or even rewrite a whole bunch of code in the new style XML/Pyhon interface. + Configuration Script Structure and Behaviour -------------------------------------------- @@ -361,6 +376,7 @@ For easy orientation we suggest you take a look on the ``ntp.py`` or ``interfaces-bonding.py`` (for tag nodes) implementation. Both files can be found in the vyos-1x_ repository. + XML (used for CLI definitions) ============================== @@ -466,6 +482,46 @@ Command definitions are purely declarative, and cannot contain any logic. All logic for generating config files for target applications, restarting services and so on is implemented in configuration scripts instead. +GNU Preprocessor +---------------- + +XML interface definition files use the `xml.in` file extension which was +implemented in T1843_. XML interface definitions tend to have a lot of +duplicated code in areas such as: + +* VIF (incl. VIF-S/VIF-C) +* Address +* Description +* Enabled/Disabled + +Instead of supplying all those XML nodes multiple times there are now include +files with predefined features. Brief overview: + +* `IPv4, IPv6 and DHCP(v6)`_ address assignment +* `IPv4, IPv6`_ address assignment +* `VLAN (VIF)`_ definition +* `MAC address`_ assignment + +All interface definition XML input files (.in suffix) will be sent to the GCC +preprocess and the output is stored in the `build/interface-definitions` +folder. The previously mentioned `scripts/build-command-templates` script +operates on the `build/interface-definitions` folder to generate all required +CLI nodes. + +.. code-block:: none + + $ make interface_definitions + install -d -m 0755 build/interface-definitions + install -d -m 0755 build/op-mode-definitions + Generating build/interface-definitions/intel_qat.xml from interface-definitions/intel_qat.xml.in + Generating build/interface-definitions/interfaces-bonding.xml from interface-definitions/interfaces-bonding.xml.in + Generating build/interface-definitions/cron.xml from interface-definitions/cron.xml.in + Generating build/interface-definitions/pppoe-server.xml from interface-definitions/pppoe-server.xml.in + Generating build/interface-definitions/mdns-repeater.xml from interface-definitions/mdns-repeater.xml.in + Generating build/interface-definitions/tftp-server.xml from interface-definitions/tftp-server.xml.in + [...] + + Guidelines ---------- @@ -642,3 +698,8 @@ http://dev.packages.vyos.net/repositories/. .. _Phabricator: https://phabricator.vyos.net/ .. _Jenkins: https://jenkins.io/ .. _Dockerhub: https://hub.docker.com/u/vyos/ +.. _T1843: https://phabricator.vyos.net/T1843 +.. _`IPv4, IPv6 and DHCP(v6)`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/address-ipv4-ipv6-dhcp.xml.i +.. _`IPv4, IPv6`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/address-ipv4-ipv6.xml.i +.. _`VLAN (VIF)`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/vif.xml.i +.. _`MAC address`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/interface-mac.xml.i diff --git a/docs/index.rst b/docs/index.rst index 48fce5b6..8305b344 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -67,4 +67,25 @@ VyOS User Guide contributing/build-vyos contributing/issues-features contributing/development - contributing/documentation
\ No newline at end of file + contributing/documentation + + +################ +Copyright Notice +################ + +Copyright (C) 2018-2019 VyOS maintainers and contributors + +Permission is granted to make and distribute verbatim copies of this manual +provided the copyright notice and this permission notice are preserved on all +copies. + +Permission is granted to copy and distribute modified versions of this manual +under the conditions for verbatim copying, provided that the entire resulting +derived work is distributed under the terms of a permission notice identical +to this one. + +Permission is granted to copy and distribute translations of this manual into +another language, under the above conditions for modified versions, except that +this permission notice may be stated in a translation approved by the VyOS +maintainers.
\ No newline at end of file diff --git a/docs/routing/bgp.rst b/docs/routing/bgp.rst index 1bb33aee..37cf3c92 100644 --- a/docs/routing/bgp.rst +++ b/docs/routing/bgp.rst @@ -1,13 +1,177 @@ .. _bgp: +### BGP ---- +### :abbr:`BGP (Border Gateway Protocol) is one of the Exterior Gateway Protocols and the de facto standard interdomain routing protocol. The latest BGP version is 4. BGP-4 is described in :rfc:`1771` and updated by :rfc:`4271`. :rfc:`2858` adds multiprotocol support to BGP. +VyOS makes use of :abbr:`FRR (Free Range Routing)` and we would like to thank +them for their effort! + +Basic Concepts +============== + +.. _bgp-autonomous-systems: + +Autonomous Systems +------------------ + +From :rfc:`1930`: + + An AS is a connected group of one or more IP prefixes run by one or more + network operators which has a SINGLE and CLEARLY DEFINED routing policy. + +Each AS has an identifying number associated with it called an :abbr:`ASN +(Autonomous System Number)`. This is a two octet value ranging in value from 1 +to 65535. The AS numbers 64512 through 65535 are defined as private AS numbers. +Private AS numbers must not be advertised on the global Internet. + +The :abbr:`ASN (Autonomous System Number)` is one of the essential elements of +BGP. BGP is a distance vector routing protocol, and the AS-Path framework +provides distance vector metric and loop detection to BGP. + +.. _bgp-address-families: + +Address Families +---------------- + +Multiprotocol extensions enable BGP to carry routing information for multiple +network layer protocols. BGP supports an Address Family Identifier (AFI) for +IPv4 and IPv6. + +.. _bgp-route-selection: + +Route Selection +--------------- + +The route selection process used by FRR's BGP implementation uses the following +decision criterion, starting at the top of the list and going towards the +bottom until one of the factors can be used. + +1. **Weight check** + + Prefer higher local weight routes to lower routes. + +2. **Local preference check** + + Prefer higher local preference routes to lower. + +3. **Local route check** + + Prefer local routes (statics, aggregates, redistributed) to received routes. + +4. **AS path length check** + + Prefer shortest hop-count AS_PATHs. + +5. **Origin check** + + Prefer the lowest origin type route. That is, prefer IGP origin routes to + EGP, to Incomplete routes. + +6. **MED check** + + Where routes with a MED were received from the same AS, prefer the route + with the lowest MED. :ref:`bgp-med`. + +7. **External check** + + Prefer the route received from an external, eBGP peer over routes received + from other types of peers. + +8. **IGP cost check** + + Prefer the route with the lower IGP cost. + +9. **Multi-path check** + + If multi-pathing is enabled, then check whether the routes not yet + distinguished in preference may be considered equal. If + :clicmd:`bgp bestpath as-path multipath-relax` is set, all such routes are + considered equal, otherwise routes received via iBGP with identical AS_PATHs + or routes received from eBGP neighbours in the same AS are considered equal. + +10. **Already-selected external check** + + Where both routes were received from eBGP peers, then prefer the route + which is already selected. Note that this check is not applied if + :clicmd:`bgp bestpath compare-routerid` is configured. This check can + prevent some cases of oscillation. + +11. **Router-ID check** + + Prefer the route with the lowest `router-ID`. If the route has an + `ORIGINATOR_ID` attribute, through iBGP reflection, then that router ID is + used, otherwise the `router-ID` of the peer the route was received from is + used. + +12. **Cluster-List length check** + + The route with the shortest cluster-list length is used. The cluster-list + reflects the iBGP reflection path the route has taken. + +13. **Peer address** + + Prefer the route received from the peer with the higher transport layer + address, as a last-resort tie-breaker. + +.. _bgp-capability-negotiation: + +Capability Negotiation +---------------------- + +When adding IPv6 routing information exchange feature to BGP. There were some +proposals. :abbr:`IETF (Internet Engineering Task Force)` +:abbr:`IDR (Inter Domain Routing)` adopted a proposal called Multiprotocol +Extension for BGP. The specification is described in :rfc:`2283`. The protocol +does not define new protocols. It defines new attributes to existing BGP. When +it is used exchanging IPv6 routing information it is called BGP-4+. When it is +used for exchanging multicast routing information it is called MBGP. + +*bgpd* supports Multiprotocol Extension for BGP. So if a remote peer supports +the protocol, *bgpd* can exchange IPv6 and/or multicast routing information. + +Traditional BGP did not have the feature to detect a remote peer's +capabilities, e.g. whether it can handle prefix types other than IPv4 unicast +routes. This was a big problem using Multiprotocol Extension for BGP in an +operational network. :rfc:`2842` adopted a feature called Capability +Negotiation. *bgpd* use this Capability Negotiation to detect the remote peer's +capabilities. If a peer is only configured as an IPv4 unicast neighbor, *bgpd* +does not send these Capability Negotiation packets (at least not unless other +optional BGP features require capability negotiation). + +By default, FRR will bring up peering with minimal common capability for the +both sides. For example, if the local router has unicast and multicast +capabilities and the remote router only has unicast capability the local router +will establish the connection with unicast only capability. When there are no +common capabilities, FRR sends Unsupported Capability error and then resets the +connection. + +.. _bgp-router-configuration: + +BGP Router Configuration +======================== + +ASN and Router ID +----------------- + +.. cfgcmd:: set protocols bgp '<ASN>' + +First of all you must configure BGP router with the :abbr:`ASN (Autonomous +System Number)`. The AS number is an identifier for the autonomous system. The +BGP protocol uses the AS number for detecting whether the BGP connection is +internal or external. + +.. cfgcmd:: set protocols bgp '<ASN>' parameters router-id + +This command specifies the router-ID. If router ID is not specified it will use +the highest interface IP address. + + IPv4 ^^^^ @@ -147,41 +311,3 @@ Route filter can be applied using a route-map: We could expand on this and also deny link local and multicast in the rule 20 action deny. - -RPKI -^^^^ - -:abbr:`RPKI (Resource Public Key Infrastructure)` is a framework :abbr:`PKI (Public Key Infastucrure)` -designed to secure the Internet routing insfratructure. -It associate a BGP route announcement with the correct originating :abbr:`ASN (Autonomus System Number)` and check it validation. -RPKI described in :rfc:`6480`. This is a separate server. You can find more details at RIPE-NNC_. - -Imported prefixes during the validation may have values: valid, invalid and notfound. - -* The valid state means that prefix and ASN that originated it match the :abbr:`ROA (Route Origination Authorizations)` base. -* Invalid means that prefix/prefix length and ASN that originated it doesn't match with ROA. -* Notfound means that prefix not found in ROA. - -We can build route-maps for import, based on these states. -Simple RPKI configuration, where 'routinator' - RPKI cache server with ip '10.11.11.1'. - -.. code-block:: none - - set protocols rpki cache routinator address '10.11.11.1' - set protocols rpki cache routinator port '3323' - -Example route-map for import. We can set local-preference logic based on states. -Also we may not import prefixes with the state 'invalid'. - -.. code-block:: none - - set policy route-map ROUTES-IN rule 10 action 'permit' - set policy route-map ROUTES-IN rule 10 match rpki 'valid' - set policy route-map ROUTES-IN rule 10 set local-preference '300' - set policy route-map ROUTES-IN rule 20 action 'permit' - set policy route-map ROUTES-IN rule 20 match rpki 'notfound' - set policy route-map ROUTES-IN rule 20 set local-preference '125' - set policy route-map ROUTES-IN rule 30 action 'deny' - set policy route-map ROUTES-IN rule 30 match rpki 'invalid' - -.. _RIPE-NNC: https://github.com/RIPE-NCC/rpki-validator-3/wiki diff --git a/docs/routing/index.rst b/docs/routing/index.rst index b49120f7..26342bf2 100644 --- a/docs/routing/index.rst +++ b/docs/routing/index.rst @@ -9,6 +9,7 @@ Routing arp bgp + rpki ospf pbr rip diff --git a/docs/routing/rpki.rst b/docs/routing/rpki.rst new file mode 100644 index 00000000..0c41c875 --- /dev/null +++ b/docs/routing/rpki.rst @@ -0,0 +1,46 @@ +.. _rpki: + +#### +RPKI +#### + +:abbr:`RPKI (Resource Public Key Infrastructure)` is a framework :abbr:`PKI +(Public Key Infastucrure)` designed to secure the Internet routing +infrastructure. It associate a BGP route announcement with the correct +originating :abbr:`ASN (Autonomus System Number)` and check its validity. + +RPKI is described in :rfc:`6480`. This is a separate server. You can find more +details at RIPE-NNC_. + +Imported prefixes during the validation may have values: valid, invalid and +not found. + +* The valid state means that prefix and ASN that originated it match the + :abbr:`ROA (Route Origination Authorizations)` base. +* Invalid means that prefix/prefix length and ASN that originated it doesn't + match with ROA. +* Notfound means that prefix not found in ROA. + +We can build route-maps for import, based on these states. Simple RPKI +configuration, where 'routinator' - RPKI cache server with ip '10.11.11.1'. + +.. code-block:: none + + set protocols rpki cache routinator address '10.11.11.1' + set protocols rpki cache routinator port '3323' + +Example route-map for import. We can set local-preference logic based on states. +Also we may not import prefixes with the state 'invalid'. + +.. code-block:: none + + set policy route-map ROUTES-IN rule 10 action 'permit' + set policy route-map ROUTES-IN rule 10 match rpki 'valid' + set policy route-map ROUTES-IN rule 10 set local-preference '300' + set policy route-map ROUTES-IN rule 20 action 'permit' + set policy route-map ROUTES-IN rule 20 match rpki 'notfound' + set policy route-map ROUTES-IN rule 20 set local-preference '125' + set policy route-map ROUTES-IN rule 30 action 'deny' + set policy route-map ROUTES-IN rule 30 match rpki 'invalid' + +.. _RIPE-NNC: https://github.com/RIPE-NCC/rpki-validator-3/wiki diff --git a/docs/services/dhcp.rst b/docs/services/dhcp.rst index f74195d8..1303395a 100644 --- a/docs/services/dhcp.rst +++ b/docs/services/dhcp.rst @@ -9,39 +9,33 @@ VyOS uses ISC DHCPd for both IPv4 and IPv6 address assignment. DHCP Server =========== -Multiple DHCP Servers can be run from a single machine. Each DHCP service is -identified by a ``shared-network-name``. +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. Basic Example ------------- -We are offering address space in the 192.0.2.0/24 network, which is -physically connected on eth1, and pppoe0 is our connection to the internet. -We are using the network name ``<name>``. - -Prerequisites: - -* Configuring PPPoE interface is assumed to be done already, and appears - on `pppoe0` -* Interface ``eth1`` is configured to be connected to our DHCP subnet - 192.0.2.0/24 by assigning e.g. address 192.0.2.1/24. - -Multiple DHCP ranges can be defined and may contain holes. +In this example, we are offering address space in the 192.0.2.0/24 network. +We are using the network name `dhcpexample`. .. code-block:: none - set service dhcp-server shared-network-name '<name>' authoritative - set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 default-router 192.0.2.1 - set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 dns-server 192.0.2.1 - set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 lease 86400 - set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 range 0 start 192.0.2.100 - set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 range 0 stop 192.0.2.199 + set service dhcp-server shared-network-name dhcpexample authoritative + set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 default-router 192.0.2.1 + set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 dns-server 192.0.2.1 + set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 lease 86400 + set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 range 0 start 192.0.2.100 + set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 range 0 stop 192.0.2.199 The generated config will look like: .. code-block:: none - vyos@vyos# show service dhcp-server shared-network-name '<name>' + vyos@vyos# show service dhcp-server shared-network-name dhcpexample authoritative subnet 192.0.2.0/24 { default-router 192.0.2.1 @@ -53,23 +47,22 @@ The generated config will look like: } } - Explanation ^^^^^^^^^^^ -.. cfgcmd:: set service dhcp-server shared-network-name '<name>' authoritative +.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample 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 '<name>' subnet 192.0.2.0/24 default-router 192.0.2.1 +.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 default-router 192.0.2.1 This is a configuration parameter for the subnet, saying that as part of the response, tell the client that I am the default router for this network -.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 dns-server 192.0.2.1 +.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 dns-server 192.0.2.1 This is a configuration parameter for the subnet, saying that as part of the response, tell the client that I am the DNS server for this network. If you @@ -77,20 +70,20 @@ do not want to run a DNS server, you could also provide one of the public DNS servers, such as google's. You can add multiple entries by repeating the line. -.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 lease 86400 +.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 lease 86400 Assign the IP address to this machine for 24 hours. It is unlikely you'd need to shorten this period, unless you are running a network with lots of devices appearing and disappearing. -.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 range 0 start 192.0.2.100 -Make a range of addresses available for clients starting from .100 [...] +.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 range 0 start 192.0.2.100 -.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 range 0 stop 192.0.2.199 +Make a range of addresses available for clients starting from .100 [...] -[...] and ending at .199 +.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 range 0 stop 192.0.2.199 +[...] and ending at .199. Failover -------- @@ -115,7 +108,7 @@ A generic name referencing this sync service. .. cfgcmd:: set service dhcp-server shared-network-name 'LAN' subnet '192.0.2.0/24' failover status '{primary|secondary}' The primary and secondary statements determines whether the server is primary -r secondary. +or secondary. .. note:: In order for the primary and the secondary DHCP server to keep their lease tables in sync, they must be able to reach each other on TCP @@ -134,16 +127,18 @@ Static mappings You can specify a static DHCP assignment on a per host basis. You will need the MAC address of the station and your desired IP address. The address must be -inside your subnet definition but can be outside of your range sttement. +inside the subnet definition but can be outside of the range statement. + +.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping static-mapping-01 mac-address ff:ff:ff:ff:ff:ff -.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 static-mapping <host> ip-address 192.0.2.10 +Each host is uniquely identified by its MAC address. -Configure desired IPv4 address for your host referenced to as `host`. +.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping static-mapping-01 ip-address 192.0.2.10 -.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 static-mapping <hodt> mac-address ff:ff:ff:ff:ff:ff +IP address to assign to this host. It must be inside the subnet in which it is defined but can be outside the dynamic range. +If ip-address is not specified, an IP from the dynamic pool (as specified by ``range``) is used. This is useful, for example, in combination with hostfile update. -Configure MAC address for your host referenced by as `host` used in this static -assignment. +.. hint:: This is the equivalent of the host block in dhcpd.conf of isc-dhcpd. DHCP Options ------------ @@ -170,6 +165,209 @@ The domain-name parameter should be the domain name used when completing DNS request where no full FQDN is passed. This option can be given multiple times if you need multiple search domains (DHCP Option 119). +.. list-table:: + :header-rows: 1 + :stub-columns: 0 + :widths: 12 7 23 40 20 + + * - Setting name + - Option number + - ISC-DHCP Option name + - Option description + - Multi + * - client-prefix-length + - 1 + - subnet-mask + - Specifies the clients subnet mask as per RFC 950. If unset, subnet declaration is used. + - N + * - time-offset + - 2 + - time-offset + - Offset of the client's subnet in seconds from Coordinated Universal Time (UTC) + - N + * - default-router + - 3 + - routers + - IPv4 address of router on the client's subnet + - N + * - time-server + - 4 + - time-servers + - RFC 868 time server IPv4 address + - Y + * - dns-server + - 6 + - domain-name-servers + - DNS server IPv4 address + - Y + * - domain-name + - 15 + - domain-name + - Client domain name + - Y + * - ip-forwarding + - 19 + - ip-forwarding + - Enable IP forwarding on client + - N + * - ntp-server + - 42 + - ntp-servers + - IP address of NTP server + - Y + * - wins-server + - 44 + - netbios-name-servers + - NetBIOS over TCP/IP name server + - Y + * - server-identifier + - 54 + - dhcp-server-identifier + - IP address for DHCP server identifier + - N + * - bootfile-server + - siaddr + - next-server + - IPv4 address of next bootstrap server + - N + * - tftp-server-name + - 66 + - tftp-server-name + - Name or IPv4 address of TFTP server + - N + * - bootfile-name + - 67 + - bootfile-name, filename + - Bootstrap file name + - N + * - smtp-server + - 69 + - smtp-server + - IP address of SMTP server + - Y + * - pop-server + - 70 + - pop-server + - IP address of POP3 server + - Y + * - domain-search + - 119 + - domain-search + - Client domain search + - Y + * - static-route + - 121, 249 + - rfc3442-static-route, windows-static-route + - Classless static route + - N + * - wpad-url + - 252 + - wpad-url, wpad-url code 252 = text + - Web Proxy Autodiscovery (WPAD) URL + - N + * - lease + - + - default-lease-time, max-lease-time + - Lease timeout in seconds (default: 86400) + - N + * - range + - + - range + - DHCP lease range + - Y + * - exclude + - + - + - IP address to exclude from DHCP lease range + - Y + * - failover + - + - + - DHCP failover parameters + - + * - static-mapping + - + - + - Name of static mapping + - Y + +Multi: can be specified multiple times. + +Raw parameters +-------------- + +Raw parameters can be passed to shared-network-name, subnet and static-mapping: + +.. code-block:: none + + set service dhcp-server shared-network-name dhcpexample shared-network-parameters + <text> Additional shared-network parameters for DHCP server. + set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 subnet-parameters + <text> Additional subnet parameters for DHCP server. + set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters + <text> Additional static-mapping parameters for DHCP server. + Will be placed inside the "host" block of the mapping. + +These parameters are passed as-is to isc-dhcp's dhcpd.conf under the configuration node they are defined in. +They are not validated so an error in the raw parameters won't be caught by vyos's scripts and will cause dhcpd to fail to start. +Always verify that the parameters are correct before commiting the configuration. +Refer to isc-dhcp's dhcpd.conf manual for more information: +https://kb.isc.org/docs/isc-dhcp-44-manual-pages-dhcpdconf + +Example +^^^^^^^ + +.. opcmd:: set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option domain-name-servers 192.0.2.11, 192.0.2.12;" + +Override the static-mapping's dns-server with a custom one that will be sent only to this host. + +Operation Mode +-------------- + +.. opcmd:: restart dhcp server + +Restart the DHCP server + +.. opcmd:: show dhcp server statistics + +Show the DHCP server statistics: + +.. code-block:: none + + vyos@vyos:~$ show dhcp server statistics + Pool Size Leases Available Usage + ----------- ------ -------- ----------- ------- + dhcpexample 99 2 97 2% + +.. opcmd:: show dhcp server statistics pool <pool> + +Show the DHCP server statistics for the specified pool. + +.. opcmd:: show dhcp server leases + +Show statuses of all active leases: + +.. code-block:: none + + vyos@vyos:~$ show dhcp server leases + IP address Hardware address State Lease start Lease expiration Remaining Pool Hostname + -------------- ------------------ ------- ------------------- ------------------- ---------- ----------- --------- + 192.0.2.104 aa:bb:cc:dd:ee:ff active 2019/12/05 14:24:23 2019/12/06 02:24:23 6:05:35 dhcpexample test1 + 192.0.2.115 ab:ac:ad:ae:af:bf active 2019/12/05 18:02:37 2019/12/06 06:02:37 9:43:49 dhcpexample test2 + +.. hint:: Static mappings aren't shown. To show all states, use ``show dhcp server leases state all``. + +.. opcmd:: show dhcp server leases pool <pool> + +Show only leases in the specified pool. + +.. opcmd:: show dhcp server leases sort <key> + +Sort the output by the specified key. Possible keys: ip, hardware_address, state, start, end, remaining, pool, hostname (default = ip) + +.. opcmd:: show dhcp server leases state <state> + +Show only leases with the specified state. Possible states: all, active, free, expired, released, abandoned, reset, backup (default = active) DHCPv6 Server ============= @@ -268,16 +466,16 @@ be created. The following example explains the process. **Example:** * IPv6 address ``2001:db8::101`` shall be statically mapped -* Device MAC address will be ``00:53:c5:b7:5e:23`` * Host specific mapping shall be named ``client1`` -.. hint:: The MAC address identifier is defined by the last 4 byte of the - MAC address. +.. hint:: The identifier is the device's DUID: colon-separated hex list (as used by isc-dhcp option dhcpv6.client-id). + If the device already has a dynamic lease from the DHCPv6 server, its DUID can be found with ``show service dhcpv6 server leases``. + The DUID begins at the 5th octet (after the 4th colon) of IAID_DUID. .. code-block:: none set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 ipv6-address 2001:db8::101 - set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 identifier c5b75e23 + set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 identifier 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff The configuration will look as follows: @@ -294,12 +492,11 @@ The configuration will look as follows: } static-mapping client1 { ipv6-address 2001:db8::101 - identifier c5b75e23 + identifier 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff } } } - Operation Mode -------------- @@ -315,6 +512,27 @@ To show the current status of the DHCPv6 server. Show statuses of all assigned leases: +.. code-block:: none + + vyos@vyos:~$ show dhcpv6 server leases + IPv6 address State Last communication Lease expiration Remaining Type Pool IAID_DUID + ------------- ------- -------------------- ------------------- ----------- ------------- ----- -------------------------------------------- + 2001:db8::101 active 2019/12/05 19:40:10 2019/12/06 07:40:10 11:45:21 non-temporary NET1 98:76:54:32:00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff + 2001:db8::102 active 2019/12/05 14:01:23 2019/12/06 02:01:23 6:06:34 non-temporary NET1 87:65:43:21:00:01:00:01:11:22:33:44:fa:fb:fc:fd:fe:ff + +.. hint:: Static mappings aren't shown. To show all states, use ``show dhcp server leases state all``. + +.. opcmd:: show dhcpv6 server leases pool <pool> + +Show only leases in the specified pool. + +.. opcmd:: show dhcpv6 server leases sort <key> + +Sort the output by the specified key. Possible keys: expires, iaid_duid, ip, last_comm, pool, remaining, state, type (default = ip) + +.. opcmd:: show dhcpv6 server leases state <state> + +Show only leases with the specified state. Possible states: abandoned, active, all, backup, expired, free, released, reset (default = active) DHCP Relay ========== diff --git a/docs/services/dns-forwarding.rst b/docs/services/dns-forwarding.rst index fbfac6c9..a4fbdd9f 100644 --- a/docs/services/dns-forwarding.rst +++ b/docs/services/dns-forwarding.rst @@ -1,72 +1,145 @@ +.. _dns-forwarding: + +############## DNS Forwarding --------------- +############## -Use DNS forwarding if you want your router to function as a DNS server for the -local network. There are several options, the easiest being 'forward all -traffic to the system DNS server(s)' (defined with set system name-server): +Configuration +============= -.. code-block:: none +VyOS provides DNS infrastructure for small networks. It is designed to be +lightweight and have a small footprint, suitable for resource constrained +routers and firewalls, for this we utilize PowerDNS recursor. - set service dns forwarding system +VyOS DNS forwarder does not require an upstream DNS server. It can serve as a +full recursive DNS server - but it can also forward queries to configurable +upstream DNS servers. By not configuring any upstream DNS servers you also +avoid to be tracked by the provider of your upstream DNS server. -Manually setting DNS servers for forwarding: +.. cfgcmd:: set service dns forwarding system -.. code-block:: none +Forward incoming DNS queries to the DNS servers configured under the ``system +name-server`` nodes. - set service dns forwarding name-server 8.8.8.8 - set service dns forwarding name-server 8.8.4.4 +.. cfgcmd:: set service dns forwarding name-server <address> -Manually setting DNS servers with IPv6 connectivity: +Send all DNS queries to the IPv4/IPv6 DNS server specified under `<address>`. +You can configure multiple nameservers here. -.. code-block:: none +.. cfgcmd:: set service dns forwarding domain <domain-name> server <address> - set service dns forwarding name-server 2001:4860:4860::8888 - set service dns forwarding name-server 2001:4860:4860::8844 +Forward received queries for a particular domain (specified via `domain-name`) +to a given name-server. Multiple nameservers can be specified. -Setting a forwarding DNS server for a specific domain: +.. note:: This also works for reverse-lookup zones e.g. ``18.172.in-addr.arpa``. -.. code-block:: none +.. cfgcmd:: set service dns forwarding allow-from <network> - set service dns forwarding domain example.com server 192.0.2.1 +Given the fact that open DNS recursors could be used on DDOS amplification +attacts, you must configure the networks which are allowed to use this recursor. +A network of ``0.0.0.0/0`` or ``::/0`` would allow all IPv4 and IPv6 networks +to query this server. This is on general a bad idea. -Set which networks or clients are allowed to query the DNS Server. Allow from all: +.. cfgcmd:: set service dns forwarding dnssec <off | process-no-validate | process | log-fail | validate> -.. code-block:: none +The PowerDNS Recursor has 5 different levels of DNSSEC processing, which can +be set with the dnssec setting. In order from least to most processing, these +are: - set service dns forwarding allow-from 0.0.0.0/0 +* **off** In this mode, no DNSSEC processing takes place. The recursor will not + set the DNSSEC OK (DO) bit in the outgoing queries and will ignore the DO and + AD bits in queries. -Example 1 -^^^^^^^^^ +* **process-no-validate** In this mode the Recursor acts as a "security aware, + non-validating" nameserver, meaning it will set the DO-bit on outgoing queries + and will provide DNSSEC related RRsets (NSEC, RRSIG) to clients that ask for + them (by means of a DO-bit in the query), except for zones provided through + the auth-zones setting. It will not do any validation in this mode, not even + when requested by the client. -Router with two interfaces eth0 (WAN link) and eth1 (LAN). Split DNS for example.com. +* **process** When dnssec is set to process the behaviour is similar to + process-no-validate. However, the recursor will try to validate the data if + at least one of the DO or AD bits is set in the query; in that case, it will + set the AD-bit in the response when the data is validated successfully, or + send SERVFAIL when the validation comes up bogus. -* DNS request for a local domain (example.com) get forwarded to 192.0.2.1 -* Other DNS requests are forwarded to Google's DNS servers. -* The IP address for the LAN interface is 192.168.0.1. +* **log-fail** In this mode, the recursor will attempt to validate all data it + retrieves from authoritative servers, regardless of the client's DNSSEC + desires, and will log the validation result. This mode can be used to + determine the extra load and amount of possibly bogus answers before turning + on full-blown validation. Responses to client queries are the same as with + process. -.. code-block:: none +* **validate** The highest mode of DNSSEC processing. In this mode, all queries + will be be validated and will be answered with a SERVFAIL in case of bogus + data, regardless of the client's request. + +.. note:: The famous UNIX/Linux ``dig`` tool sets the AD-bit in the query. This + might lead to unexpected query results when testing. Set ``+noad`` on the + ``dig`` commandline when this is the case. + +.. note:: The ``CD``-bit is honored correctly for process and validate. For + log-fail, failures will be logged too. + +.. cfgcmd:: set service dns forwarding ignore-hosts-file + +Do not use local ``/etc/hosts`` file in name resolution. VyOS DHCP server will +use this file to add resolvers to assigned addresses. - set service dns forwarding domain example.com server 192.0.2.1 - set service dns forwarding name-server 8.8.8.8 - set service dns forwarding name-server 8.8.4.4 - set service dns forwarding listen-address 192.168.0.1 - set service dns forwarding allow-from 0.0.0.0/0 +.. cfgcmd:: set service dns forwarding max-cache-entries -Example 2 -^^^^^^^^^ +Maximum number of DNS cache entries. 1 million per CPU core will generally +suffice for most installations. -Same as example 1 but with additional IPv6 addresses for Google's public DNS -servers. +.. cfgcmd:: set service dns forwarding negative-ttl -The IP addresses for the LAN interface are 192.168.0.1 and 2001:db8::1 +A query for which there is authoritatively no answer is cached to quickly deny +a record's existence later on, without putting a heavy load on the remote +server. In practice, caches can become saturated with hundreds of thousands of +hosts which are tried only once. This setting, which defaults to 3600 seconds, +puts a maximum on the amount of time negative entries are cached. + +.. cfgcmd:: set service dns forwarding listen-address + +Local IPv4 or IPv6 addresses to bind to - waiting on this address for incoming +connections. + +Example +======= + +Router with two interfaces eth0 (WAN link) and eth1 (LAN) does want to make +use of DNS split-horizon for example.com. + +* DNS request for example.com need to get forwarded to IPv4 address 192.0.2.254 + and IPv6 address 2001:db8:cafe::1 +* All other DNS requests are forwarded to DNS server listening on 192.0.2.1, + 192.0.2.2, 2001:db8::1:ffff and 2001:db8::2:ffff +* DNS server is listening on the LAN interface addresses only, 192.168.1.254 + for IPv4 and 2001:db8::ffff for IPv6 +* Only clients from the LAN segment (192.168.1.0/24) are allowed to use this + server .. code-block:: none - set service dns forwarding domain example.com server 192.0.2.1 - set service dns forwarding name-server 8.8.8.8 - set service dns forwarding name-server 8.8.4.4 - set service dns forwarding name-server 2001:4860:4860::8888 - set service dns forwarding name-server 2001:4860:4860::8844 - set service dns forwarding listen-address 2001:db8::1 - set service dns forwarding listen-address 192.168.0.1 - set service dns forwarding allow-from 0.0.0.0/0 + set service dns forwarding domain example.com server 192.0.2.254 + set service dns forwarding domain example.com server 2001:db8:cafe::1 + set service dns forwarding name-server 192.0.2.1 + set service dns forwarding name-server 192.0.2.2 + set service dns forwarding name-server 2001:db8::1:ffff + set service dns forwarding name-server 2001:db8::2:ffff + set service dns forwarding listen-address 192.168.1.254 + set service dns forwarding listen-address 2001:db8::ffff + set service dns forwarding allow-from 192.168.1.0/24 + set service dns forwarding allow-from 2001:db8::/64 + +Operation +========= + +.. opcmd:: reset dns forwarding <all | domain> + +Reset local DNS forwarding cache database. You can reset the cache for all +entries or only for entries to a specific domain. + +.. opcmd:: restart dns forwarding + +Restart DNS recursor process which also invalidates the cache. diff --git a/docs/services/dynamic-dns.rst b/docs/services/dynamic-dns.rst index f4968295..154f9023 100644 --- a/docs/services/dynamic-dns.rst +++ b/docs/services/dynamic-dns.rst @@ -1,9 +1,12 @@ +.. _dynamic-dns: + +########### Dynamic DNS ------------ +########### VyOS is able to update a remote DNS record when an interface gets a new IP -address. In order to do so, VyOS includes ddclient_, a perl script written for -this exact purpose. +address. In order to do so, VyOS includes ddclient_, a Perl script written for +this only one purpose. ddclient_ uses two methods to update a DNS record. The first one will send updates directly to the DNS daemon, in compliance with :rfc:`2136`. The second @@ -11,141 +14,148 @@ one involves a third party service, like DynDNS.com or any other similar website. This method uses HTTP requests to transmit the new IP address. You can configure both in VyOS. -VyOS CLI and RFC2136 -^^^^^^^^^^^^^^^^^^^^ +Configuration +============= -First, create an :rfc:`2136` config node : +:rfc:`2136` Based +----------------- -.. code-block:: none +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> - edit service dns dynamic interface eth0 rfc2136 <confignodename> +Create new :rfc:`2136` DNS update configuration which will update the IP address +assigned to `<interface>` on the service you configured under `<service-name>`. -Present your RNDC key to ddclient : +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> key <keyfile> -.. code-block:: none +File identified by `<keyfile>` containing the secret RNDC key shared with +remote DNS server. - set key /config/dyndns/mydnsserver.rndc.key +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> server <server> -Set the DNS server IP/FQDN : - -.. code-block:: none +Configure the DNS `<server>` IP/FQDN used when updating this dynamic assignemnt. - set server dns.mydomain.com +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> zone <zone> -Set the NS zone to be updated : +Configure DNS `<zone>` to be updated. -.. code-block:: none +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> record <record> - set zone mydomain.com +Configure DNS `<record>` which should be updated. This can be set multiple +times. -Set the records to be updated : +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> ttl <ttl> -.. code-block:: none +Configure optional TTL value on the given resource record. This defualts to 600 +seconds. - set record dyn - set record dyn2 +Example +^^^^^^^ -You can optionally set a TTL (note : default value is 600 seconds) : +* Register DNS record ``example.vyos.io`` on DNS server ``ns1.vyos.io`` +* Use auth key file at ``/config/auth/my.key`` +* Set TTL to 300 seconds .. code-block:: none - set ttl 600 + vyos@vyos# show service dns dynamic + interface eth0.7 { + rfc2136 VyOS-DNS { + key /config/auth/my.key + record example.vyos.io + server ns1.vyos.io + ttl 300 + zone vyos.io + } + } -This will generate the following ddclient config blocks: +This will render the following ddclient_ configuration entry: .. code-block:: none - server=dns.mydomain.com - protocol=nsupdate - password=/config/dyndns/mydnsserver.rndc.key - ttl=600 - zone=mydomain.com - dyn - server=dns.mydomain.com + # + # ddclient configuration for interface "eth0.7": + # + use=if, if=eth0.7 + + # RFC2136 dynamic DNS configuration for example.vyos.io.vyos.io + server=ns1.vyos.io protocol=nsupdate - password=/config/dyndns/mydnsserver.rndc.key - ttl=600 - zone=mydomain.com - dyn2 + password=/config/auth/my.key + ttl=300 + zone=vyos.io + example.vyos.io -You can also keep a different dns zone updated. Just create a new config node: +.. note:: You can also keep different DNS zone updated. Just create a new + config node: ``set service dns dynamic interface <interface> rfc2136 + <other-service-name>`` -.. code-block:: none +HTTP based services +------------------- - edit service dns dynamic interface eth0 rfc2136 <confignode2> +VyOS is also able to use any service relying on protocols supported by ddclient. -VyOS CLI and HTTP dynamic DNS services -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +To use such a service, one must define a login, password, one or multiple +hostnames, protocol and server. -VyOS is also able to use any service relying on protocols supported -by ddclient. +.. cfgcmd:: set service dns dynamic interface <interface> service <service> host-name <hostname> -To use such a service, you must define a login, a password, one or multiple -hostnames, a protocol and a server. +Setup the dynamic DNS hostname `<hostname>` associated with the DynDNS provider +identified by `<service>` when the IP address on interface `<interface>` +changes. -.. code-block:: none +.. cfgcmd:: set service dns dynamic interface <interface> service <service> login <username> - edit service dns dynamic interface eth0 service HeNet - set login my-login # set password my-password - set host-name my-tunnel-id - set protocol dyndns2 - set server ipv4.tunnelbroker.net +Configure `<username>` used when authenticating the update request for DynDNS +service identified by `<service>`. -VyOS is also shipped with a list of known services. You don't need to set the -protocol and server value as VyOS has defaults provided for those. These are -the services VyOS knows about: +.. cfgcmd:: set service dns dynamic interface <interface> service <service> password <password> -* afraid -* changeip -* dnspark -* dslreports -* dyndns -* easydns -* namecheap -* noip -* zoneedit +Configure `<password>` used when authenticating the update request for DynDNS +service identified by `<service>`. -To use DynDNS for example: +.. cfgcmd:: set service dns dynamic interface <interface> service <service> protocol <protocol> -.. code-block:: none +When a ``custom`` DynDNS provider is used the protocol used for communicating to +the provider must be specified under `<protocol>`. See the embedded completion +helper for available protocols. + +.. cfgcmd:: set service dns dynamic interface <interface> service <service> server <server> - edit service dns dynamic interface eth0 service dyndns - set login my-login - set password my-password - set host-name my-dyndns-hostname +When a ``custom`` DynDNS provider is used the `<server>` where update requests +are beeing sent to must be specified. -It's possible to use multiple services : +Example: +^^^^^^^^ + +Use DynDNS as your preferred provider: .. code-block:: none - edit service dns dynamic interface eth0 service dyndns - set login my-login - set password my-password - set host-name my-dyndns-hostname - edit service dns dynamic interface eth0 service HeNet - set login my-login - set password my-password - set host-name my-tunnel-id - set protocol dyndns2 - set server ipv4.tunnelbroker.net - -ddclient behind NAT -^^^^^^^^^^^^^^^^^^^ - -By default, ddclient will update a dynamic dns record using the IP address + set service dns dynamic interface eth0 service dyndns + set service dns dynamic interface eth0 service dyndns login my-login + set service dns dynamic interface eth0 service dyndns password my-password + set service dns dynamic interface eth0 service dyndns host-name my-dyndns-hostname + +.. note:: Multiple services can be used per interface. Just specify as many + serives per interface as you like! + +Running Behind NAT +------------------ + +By default, ddclient_ will update a dynamic dns record using the IP address directly attached to the interface. If your VyOS instance is behind NAT, your record will be updated to point to your internal IP. ddclient_ has another way to determine the WAN IP address. This is controlled -by these two options: +by: -.. code-block:: none +.. cfgcmd:: set service dns dynamic interface <interface> use-web url <url> + +Use configured `<url>` to determine your IP address. ddclient_ will load `<url>` +and tries to extract your IP address from the response. - set service dns dynamic interface eth0 use-web url - set service dns dynamic interface eth0 use-web skip +.. cfgcmd:: set service dns dynamic interface <interface> use-web skip <pattern> -ddclient_ will load the webpage at `[url]` and will try to extract an IP -address for the response. ddclient_ will skip any address located before the -string set in `[skip]`. +ddclient_ will skip any address located before the string set in `<pattern>`. -.. include:: references.rst +.. _ddclient: https://github.com/ddclient/ddclient diff --git a/docs/services/lldp.rst b/docs/services/lldp.rst index 3149e4ca..05c187b0 100644 --- a/docs/services/lldp.rst +++ b/docs/services/lldp.rst @@ -1,27 +1,28 @@ +.. _lldp: + +#### LLDP ----- +#### :abbr:`LLDP (Link Layer Discovery Protocol)` is a vendor-neutral link layer protocol in the Internet Protocol Suite used by network devices for advertising their identity, capabilities, and neighbors on an IEEE 802 local area network, -principally wired Ethernet.[1] The protocol is formally referred to by the IEEE +principally wired Ethernet. The protocol is formally referred to by the IEEE as Station and Media Access Control Connectivity Discovery specified in IEEE 802.1AB and IEEE 802.3-2012 section 6 clause 79. LLDP performs functions similar to several proprietary protocols, such as -`Cisco Discovery Protocol`_, `Foundry Discovery Protocol`_, -Nortel Discovery Protocol and Link Layer Topology Discovery. - -Information gathered -^^^^^^^^^^^^^^^^^^^^ +:abbr:`CDP (Cisco Discovery Protocol)`, :abbr:`FDP (Foundry Discovery Protocol)`, +:abbr:`NDP (Nortel Discovery Protocol)` and :abbr:`LLTD (Link Layer Topology +Discovery)`. -Information gathered with LLDP is stored in the device as a management -information database (MIB_) and can be queried with the Simple Network -Management Protocol (SNMP_) as specified in :rfc:`2922`. The topology of an +Information gathered with LLDP is stored in the device as a :abbr:`MIB +(Management Information Database)` and can be queried with :abbr:`SNMP (Simple +Network Management Protocol)` as specified in :rfc:`2922`. The topology of an LLDP-enabled network can be discovered by crawling the hosts and querying this database. Information that may be retrieved include: -* System name and description +* System Name and Description * Port name and description * VLAN name * IP management address @@ -31,67 +32,111 @@ database. Information that may be retrieved include: * Link aggregation Configuration -^^^^^^^^^^^^^ +============= -* Enable service with: +.. cfgcmd:: set service lldp - :code:`set service lldp` +Enable LLDP service -Options -******* +.. cfgcmd:: set service lldp management-address <address> -* Configure a Define management-address: +Define IPv4 management address transmitted via LLDP. - :code:`set service lldp management-address <x.x.x.x>` +.. cfgcmd:: set service lldp interface <interface> -* Define listening interfaces +Enable transmission of LLDP information on given `<interface>`. You can also +say ``all`` here so LLDP is turned on on every interface. - :code:`set service lldp interface <all|interface name>` +.. cfgcmd:: set service lldp interface <interface> disable -* LLDPd also implements an SNMP subagent. To Enable SNMP queries of the LLDP - database: +Disable transmit of LLDP frames on given `<interface>`. Useful to exclude +certain interfaces from LLDP when ``all`` have been enabled. - :code:`set service lldp snmp enable` +.. cfgcmd:: set service lldp snmp enable -* Enable optional/other protocols +Enable SNMP queries of the LLDP database - :code:`set service lldp legacy-protocols cdp` - Supported legacy protocols: +.. cfgcmd:: set service lldp legacy-protocols <cdp|edp|fdp|sonmp> - * ``cdp`` - Listen for CDP for Cisco routers/switches - * ``edp`` - Listen for EDP for Extreme routers/switches - * ``fdp`` - Listen for FDP for Foundry routers/switches - * ``sonmp`` - Listen for SONMP for Nortel routers/switches +Enable given legacy protocol on this LLDP instance. Legacy protocols include: +* ``cdp`` - Listen for CDP for Cisco routers/switches +* ``edp`` - Listen for EDP for Extreme routers/switches +* ``fdp`` - Listen for FDP for Foundry routers/switches +* ``sonmp`` - Listen for SONMP for Nortel routers/switches -Display neighbors -^^^^^^^^^^^^^^^^^ +Operation +========= -* Display with: +.. opcmd:: show lldp neighbors -``show lldp neighbors`` - -Exemple: +Displays information about all neighbors discovered via LLDP. .. code-block:: none vyos@vyos:~# show lldp neighbors Capability Codes: R - Router, B - Bridge, W - Wlan r - Repeater, S - Station - D - Docsis, T - Telephone, O - Other + D - Docsis, T - Telephone, O - Other + Device ID Local Proto Cap Platform Port ID --------- ----- ----- --- -------- ------- - swA309 eth0 LLDP ? Cisco IOS Software, GigE0/33 + Switch0815 eth0 LLDP B Cisco IOS Software, Gi0/4 +.. opcmd:: show lldp neighbors detail -* Options: +Get detailed information about LLDP neighbors. - * ``detail`` - Show lldp neighbors detail - * ``interface`` - Show LLDP for specified interface - -Troubleshooting -^^^^^^^^^^^^^^^ - -Use operational command ``show log lldp`` to display logs. +.. code-block:: none -.. include:: references.rst + vyos@vyos:~# show lldp neighbors detail + ------------------------------------------------------------------------------- + LLDP neighbors: + ------------------------------------------------------------------------------- + Interface: eth0, via: LLDP, RID: 1, Time: 12 days, xxxx:xxxx:40 + Chassis: + ChassisID: mac 00:50:40:20:03:00 + SysName: Switch0815 + SysDescr: Cisco IOS Software, C2960 Software (C2960-LANBASEK9-M), Version 15.0(2)SE11, RELEASE SOFTWARE (fc3) + Technical Support: http://www.cisco.com/techsupport + Copyright (c) 1986-2017 by Cisco Systems, Inc. + Compiled Sat 19-Aug-17 09:34 by prod_rel_team + MgmtIP: 192.0.2.201 + Capability: Bridge, on + Port: + PortID: ifname Gi0/4 + PortDescr: GigabitEthernet0/4 + TTL: 120 + PMD autoneg: supported: yes, enabled: yes + Adv: 10Base-T, HD: yes, FD: yes + Adv: 100Base-TX, HD: yes, FD: yes + Adv: 1000Base-T, HD: no, FD: yes + MAU oper type: 1000BaseTFD - Four-pair Category 5 UTP, full duplex mode + VLAN: 1, pvid: yes + LLDP-MED: + Device Type: Network Connectivity Device + Capability: Capabilities, yes + Capability: Policy, yes + Capability: Location, yes + Capability: Inventory, yes + LLDP-MED Network Policy for: Voice, Defined: no + Priority: Best effort + PCP: 0 + DSCP Value: 0 + LLDP-MED Network Policy for: Voice Signaling, Defined: no + Priority: Best effort + PCP: 0 + DSCP Value: 0 + Inventory: + Hardware Revision: WS-C2960G-8TC-L (PowerPC405):C0 + Software Revision: 15.0(2)SE11 + Manufacturer: Cisco Systems, Inc. + Model: WS-C2960G-8TC-L + +.. opcmd:: show lldp neighbors interface <interface> + +Show LLDP neighbors connected via interface `<interface>`. + +.. opcmd:: show log lldp + +Used for troubleshooting. diff --git a/docs/services/references.rst b/docs/services/references.rst index 7d9ae82c..704f33f7 100644 --- a/docs/services/references.rst +++ b/docs/services/references.rst @@ -1,6 +1,3 @@ -.. _`Cisco Discovery Protocol`: https://en.wikipedia.org/wiki/Cisco_Discovery_Protocol -.. _ddclient: https://sourceforge.net/p/ddclient/wiki/Home/ -.. _`Foundry Discovery Protocol`: https://en.wikipedia.org/wiki/Foundry_Discovery_Protocol .. _MIB: https://en.wikipedia.org/wiki/Management_information_base .. _SNMP: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol .. _SNMPv2: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2 diff --git a/docs/services/ssh.rst b/docs/services/ssh.rst index 3af71899..9a1418d3 100644 --- a/docs/services/ssh.rst +++ b/docs/services/ssh.rst @@ -1,9 +1,12 @@ +.. _ssh: + +### SSH ---- +### -Secure Shell (SSH_) is a cryptographic network protocol for operating network -services securely over an unsecured network.[1] The standard TCP port for SSH -is 22. The best known example application is for remote login to computer +:abbr:`SSH (Secure Shell)` is a cryptographic network protocol for operating +network services securely over an unsecured network. The standard TCP port for +SSH is 22. The best known example application is for remote login to computer systems by users. SSH provides a secure channel over an unsecured network in a client-server @@ -25,126 +28,126 @@ analysis. The encryption used by SSH is intended to provide confidentiality and integrity of data over an unsecured network, such as the Internet. Configuration -^^^^^^^^^^^^^ - -Enabling SSH only requires you to add ``service ssh port NN``, where 'NN' is -the port you want SSH to listen on. By default, SSH runs on port 22. - -.. code-block:: none - - set service ssh port 22 +============= -Options -******* +.. cfgcmd:: set service ssh port '<number>' -* Listening address - Specify the IPv4/IPv6 listening address for connection - requests. Multiple ``listen-address`` nodes can be defined. +Enabling SSH only requires you to specify the port ``<number>`` you want SSH to +listen on. By default, SSH runs on port 22. - :code:`set service ssh listen-address <address>` +.. cfgcmd:: set service ssh listen-address '<address>' -* Allow ``root`` login, this can be set to allow ``root`` logins on SSH - connections, however it is not advisable to use this setting as this bears - serious security risks. The default system user possesses all required - privileges. +Specify IPv4/IPv6 listen address of SSH server. Multiple addresses can be +defined. - :code:`set service ssh allow-root` +.. cfgcmd:: set service ssh ciphers '<cipher>' -* Allowed ciphers - A number of allowed ciphers can be specified, use multiple - occurrences to allow multiple ciphers. +Define allowed ciphers used for the SSH connection. A number of allowed ciphers +can be specified, use multiple occurrences to allow multiple ciphers. - :code:`set service ssh ciphers <cipher>` +* ``3des-cbc`` +* ``aes128-cbc`` +* ``aes192-cbc`` +* ``aes256-cbc`` +* ``aes128-ctr`` +* ``aes192-ctr`` +* ``aes256-ctr`` +* ``arcfour128`` +* ``arcfour256`` +* ``arcfour`` +* ``blowfish-cbc`` +* ``cast128-cbc`` - Available ciphers: +This could be used to harden security. - * `3des-cbc` - * `aes128-cbc` - * `aes192-cbc` - * `aes256-cbc` - * `aes128-ctr` - * `aes192-ctr` - * `aes256-ctr` - * `arcfour128` - * `arcfour256` - * `arcfour` - * `blowfish-cbc` - * `cast128-cbc` +.. cfgcmd:: set service ssh disable-password-authentication -* Disable password authentication - If SSH key authentication is set up, - password-based user authentication can be disabled. This hardens security! +Disable password based authentication. Login via SSH keys only. This hardens +security! - :code:`set service ssh disable-password-authentication` -* Disable host validation - Disable the host validation through reverse DNS - lookups. +.. cfgcmd: set service ssh disable-host-validation - :code:`set service ssh disable-host-validation` +Disable the host validation through reverse DNS lookups - can speedup login +time when reverse lookup is not possible. -* MAC algorithms - Specifies the available MAC (message authentication code) - algorithms. The MAC algorithm is used in protocol version 2 for data - integrity protection. Multiple algorithms can be entered. +.. cfgcmd:: set service ssh macs '<mac>' - :code:`set service ssh macs <macs>` +Specifies the available :abbr:`MAC (Message Authentication Code)` algorithms. +The MAC algorithm is used in protocol version 2 for data integrity protection. +Multiple algorithms can be provided. Supported MACs: - Supported MACs: +* ``hmac-md5`` +* ``hmac-md5-96`` +* ``hmac-ripemd160`` +* ``hmac-sha1`` +* ``hmac-sha1-96`` +* ``hmac-sha2-256`` +* ``hmac-sha2-512`` +* ``umac-64@openssh.com`` +* ``umac-128@openssh.com`` +* ``hmac-md5-etm@openssh.com`` +* ``hmac-md5-96-etm@openssh.com`` +* ``hmac-ripemd160-etm@openssh.com`` +* ``hmac-sha1-etm@openssh.com`` +* ``hmac-sha1-96-etm@openssh.com`` +* ``hmac-sha2-256-etm@openssh.com`` +* ``hmac-sha2-512-etm@openssh.com`` +* ``umac-64-etm@openssh.com`` +* ``umac-128-etm@openssh.com`` - * `hmac-md5` - * `hmac-md5-96` - * `hmac-ripemd160` - * `hmac-sha1` - * `hmac-sha1-96` - * `hmac-sha2-256` - * `hmac-sha2-512` - * `umac-64@openssh.com` - * `umac-128@openssh.com` - * `hmac-md5-etm@openssh.com` - * `hmac-md5-96-etm@openssh.com` - * `hmac-ripemd160-etm@openssh.com` - * `hmac-sha1-etm@openssh.com` - * `hmac-sha1-96-etm@openssh.com` - * `hmac-sha2-256-etm@openssh.com` - * `hmac-sha2-512-etm@openssh.com` - * `umac-64-etm@openssh.com` - * `umac-128-etm@openssh.com` +This could be used to harden security. +.. note:: VyOS 1.1 supported login as user ``root``. This has been removed due + to tighter security in VyOS 1.2. -Key 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`` which is in -three parts: +machine, which will (by default) save it as ``~/.ssh/id_rsa.pub``. - ``ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAA...VByBD5lKwEWB username@host.example.com`` +Every SSH key comes in three parts: -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. +``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. -**Assign SSH Key to user** +.. cfgcmd:: set system login user '<username>' authentication public-keys '<identifier>' key '<key>' -Under the user (in this example, ``vyos``), add the public key and the type. -The `identifier` is simply a string that is relevant to you. +Assign the SSH public key portion `<key>` identified by per-key `<identifier>` +to the local user `<username>`. -.. code-block:: none +.. cfgcmd:: set system login user '<username>' authentication public-keys '<identifier>' type '<type>' - set system login user vyos authentication public-keys 'identifier' key "AAAAB3Nz...." - set system login user vyos authentication public-keys 'identifier' type ssh-rsa" +Every SSH public key portion referenced by `<identifier>` requires the +configuration of the `<type>` of public-key used. This type can be any of: -You can assign multiple keys to the same user by changing the identifier. In -the following example, both Unicron and xrobau will be able to SSH into VyOS -as the ``vyos`` user using their own keys. +* ``ecdsa-sha2-nistp256`` +* ``ecdsa-sha2-nistp384`` +* ``ecdsa-sha2-nistp521`` +* ``ssh-dss`` +* ``ssh-ed25519`` +* ``ssh-rsa`` -.. code-block:: none +.. note:: You can assign multiple keys to the same user by using a unique + identifier per SSH key. - set system login user vyos authentication public-keys 'Unicron' key "AAAAB3Nz...." - set system login user vyos authentication public-keys 'Unicron' type ssh-rsa - set system login user vyos authentication public-keys 'xrobau' key "AAAAQ39x...." - set system login user vyos authentication public-keys 'xrobau' type ssh-rsa +Example +------- +In the following example, both User1 and User2 will be able to SSH into VyOS +as the ``vyos`` user using their 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 diff --git a/docs/services/tftp.rst b/docs/services/tftp.rst index 9ce46b02..c33d6c7c 100644 --- a/docs/services/tftp.rst +++ b/docs/services/tftp.rst @@ -1,42 +1,54 @@ -TFTP ----- +.. _tftp-server: -Trivial File Transfer Protocol (TFTP_) is a simple lockstep File Transfer -Protocol which allows a client to get a file from or put a file onto a remote -host. One of its primary uses is in the early stages of nodes booting from a -local area network. TFTP has been used for this application because it is very -simple to implement. +#### +TFTP +#### -Example -^^^^^^^ +:abbr:`TFTP (Trivial File Transfer Protocol)` is a simple, lockstep file +transfer protocol which allows a client to get a file from or put a file onto +a remote host. One of its primary uses is in the early stages of nodes booting +from a local area network. TFTP has been used for this application because it +is very simple to implement. -.. code-block:: none +Configuration +============= - # If you want to enable uploads, else TFTP server will act as read-only (optional) - set service tftp-server allow-upload +.. cfgcmd:: set service tftp-server directory '/config/tftpboot' - # Directory for TFTP server content - set service tftp-server directory '/config/tftpboot' +Enable TFTP service by specifying the directory which will be used to serve +files. - # On which addresses we want to listen for incoming TFTP connections? (mandatory) - set service tftp-server listen-address '2001:db8:ffee::1' - set service tftp-server listen-address '10.10.1.1' - -.. note:: Choose your ``directory`` location carefully or you will loose the +.. hint:: Choose your ``directory`` location carefully or you will loose the content on image upgrades. Any directory under ``/config`` is save at this will be migrated. +.. cfgcmd:: set service tftp-server listen-address '<address>' + +Configure the IPv4 or IPv6 listen address of the TFTP server. Multiple IPv4 and +IPv6 addresses can be given. There will be one TFTP server instances listening +on each IP address. + .. note:: Configuring a listen-address is essential for the service to work. +.. cfgcmd:: set service tftp-server allow-upload + +Optional, if you want to enable uploads, else TFTP server will act as read-only +server. + +Example +------- + +Provide TFTP server listening on both IPv4 and IPv6 addresses ``192.0.2.1`` and +``2001:db8::1`` serving the content from ``/config/tftpboot``. Uploading via +TFTP to this server is not allowed! + The resulting configuration will look like: .. code-block:: none vyos@vyos# show service tftp-server { - allow-upload directory /config/tftpboot - listen-address 2001:db8:ffee::1 - listen-address 10.10.1.1 + listen-address 2001:db8::1 + listen-address 192.0.2.1 } - diff --git a/docs/system/config-management.rst b/docs/system/config-management.rst index f087cb46..b8c1d309 100644 --- a/docs/system/config-management.rst +++ b/docs/system/config-management.rst @@ -1,33 +1,32 @@ .. _config-management: -Config Management ------------------ +######################## +Configuration Management +######################## +VyOS comes with an integrated versioning system for the system configuration. +The configurations are versioned locally for rollback but they can also be +stored on a remote host for archiving/backup reasons. -The following changes the number of commit revisions. In the default settings, 20 revisions are stored locally. +.. cfgcmd:: set system config-management commit-revisions <number> -.. code-block:: none +Change the number of commit revisions to `<number>`, the default setting for +this value is to store 20 revisions locally. - set system config-management commit-revisions 50 +.. cfgcmd:: set system config-management commit-archive location '<url>' -| If you want to save all config changes to a remote destination. Set the commit-archive location. Every time a commit is successfully the config.boot file will be copied to the defined destinations. +If you want to save all config changes to a remote destination. Set the +commit-archive location. Every time a commit is successfully the ``config.boot`` +file will be copied to the defined destination(s). The filename used on the +remote host used will be: ``config.boot-hostname.YYYYMMDD_HHMMSS`` +Destinations will be configured as any of the below :abbr:`URI (Uniform +Resource Identifier)` -.. code-block:: none +* ``scp://<user>:<passwd>@<host>/<dir>`` +* ``sftp://<user>:<passwd>@<host>/<dir>`` +* ``ftp://<user>:<passwd>@<host>/<dir>`` +* ``tftp://<host>/<dir>`` - set system config-management commit-archive location 'tftp://10.0.0.2' - -.. note:: the number of revisions don't effect the commit-archive: - -A commit look now like this: - -.. code-block:: none - - vyos@vyos-R1# commit - Archiving config... - tftp://10.0.0.2 OK - [edit] - vyos@vyos-R1# - -The filename has this format: config.boot-hostname.YYYYMMDD_HHMMSS
\ No newline at end of file +.. note:: The number of revisions don't effect the commit-archive.
\ No newline at end of file diff --git a/docs/system/syslog.rst b/docs/system/syslog.rst index c9dc8a1c..4c50f6c9 100644 --- a/docs/system/syslog.rst +++ b/docs/system/syslog.rst @@ -1,9 +1,8 @@ .. _syslog: - - +###### Syslog ------- +###### Per default VyOSs has minimal syslog logging enabled which is stored and rotated locally. Errors will be always logged to a local file, which includes @@ -11,150 +10,198 @@ rotated locally. Errors will be always logged to a local file, which includes To configure syslog, you need to switch into configuration mode. -Logging to serial console -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The below would log all messages to :code:`/dev/console`. - -.. code-block:: none - - set system syslog console facility all level all - -Use the **[tab]** function to display all facilities and levels which can -be configured. - -.. code-block:: none - - vyos@vyos# set system syslog console facility <TAB> - Possible completions: - > all All facilities excluding "mark" - > auth Authentication and authorization - > authpriv Non-system authorization - > cron Cron daemon - > daemon System daemons - > kern Kernel - > lpr Line printer spooler - > mail Mail subsystem - > mark Timestamp - > news USENET subsystem - > protocols depricated will be set to local7 - > security depricated will be set to auth - > syslog Authentication and authorization - > user Application processes - > uucp UUCP subsystem - > local0 Local facility 0 - > local1 Local facility 1 - > local2 Local facility 2 - > local3 Local facility 3 - > local4 Local facility 4 - > local5 Local facility 5 - > local6 Local facility 6 - > local7 Local facility 7 - - vyos@vyos# set system syslog console facility all level <TAB> - Possible completions: - emerg Emergency messages - alert Urgent messages - crit Critical messages - err Error messages - warning Warning messages - notice Messages for further investigation - info Informational messages - debug Debug messages - all Log everything - - -Logging to a custom file -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Logging to a custom file, rotation size and the number of rotate files left -on the system can be configured. - -.. code-block:: none - - set system syslog file <FILENAME> facility <FACILITY> level <LEVEL> - set system syslog file <FILENAME> archive file <NUMBER OF FILES> - set system syslog file FILENAME archive size <FILESIZE> - -The very same setting can be applied to the global configuration, to modify -the defaults for the global logging. - -Logging to a remote host -^^^^^^^^^^^^^^^^^^^^^^^^ +Logging +======= -Logging to a remote host leaves the local logging configuration intact, it -can be configured in parallel. You can log ro multiple hosts at the same time, -using either TCP or UDP. The default is sending the messages via UDP. +Syslog supports logging to multiple targets, those targets could be a plain +file on your VyOS installation itself, a serial console or a remote syslog +server which is reached via :abbr:`IP (Internet Protocol)` UDP/TCP. -**UDP** +Console +------- -.. code-block:: none +.. cfgcmd:: set system syslog console facility <keyword> level <keyword> - set system syslog host 10.1.1.1 facility all level all - <optional> - set system syslog host 10.1.1.1 facility all protocol udp +Log syslog messages to ``/dev/console``, for en explanation on +:ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords +see tables below. -**TCP** +Custom File +----------- -.. code-block:: none +.. cfgcmd:: set system syslog file <filename> facility <keyword> level <keyword> - set system syslog host 10.1.1.2 facility all level all - set system syslog host 10.1.1.2 facility all protocol tcp +Log syslog messages to file specified via `<filename>`, for en explanation on +:ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords see +tables below. -Logging to a local user account -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. cfgcmd:: set system syslog file <filename> archive size <size> -If logging to a local useraccount 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. +Syslog will write `<size>` kilobytes into the file specified by `<filename>`. +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 <filename> archive file <number> -.. code-block:: none +Syslog uses logrotate to rotate logiles after a number of gives bytes. We keep +as many as `<number>` rotated file before they are deleted on the system. - set system syslog user <LOCAL_USERNAME> facility <FACILITY> level <LEVEL> -Show logs -^^^^^^^^^ +Remote Host +----------- -Display log files on the console +Logging to a remote host leaves the local logging configuration intact, it +can be configured in parallel to a custom file or console logging. You can log +to multiple hosts at the same time, using either TCP or UDP. The default is +sending the messages via port 514/UDP. -.. code-block:: none - vyos@vyos:~$ show log - Possible completions: - <Enter> Execute the current command - all Show contents of all master log files - authorization Show listing of authorization attempts - cluster Show log for Cluster - conntrack-sync - Show log for Conntrack-sync - dhcp Show log for Dynamic Host Control Protocol (DHCP) - directory Show listing of user-defined log files - dns Show log for Domain Name Service (DNS) - file Show contents of user-defined log file - firewall Show log for Firewall - https Show log for Https - image Show logs from an image - lldp Show log for Lldp - nat Show log for Network Address Translation (NAT) - openvpn Show log for Openvpn - snmp Show log for Simple Network Monitoring Protocol (SNMP) - tail Monitor last lines of messages file - vpn Show log for Virtual Private Network (VPN) - vrrp Show log for Virtual Router Redundancy Protocol (VRRP) - webproxy Show log for Webproxy +.. cfgcmd:: set system syslog host <address> facility <keyword> level <keyword> -Show contents of a log file in an image -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Log syslog messages to remote host specified by `<address>`. 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 messages from a specified image can be displayed on the console: -.. code-block:: none +.. cfgcmd:: set system syslog host <address> facility <keyword> protocol <udp|tcp> - $ show log image <image name> - $ show log image <image name> [all | authorization | directory | file <file name> | tail <lines>] +Configure protocol used for communication to remote syslog host. This can be +either UDP or TCP. -Details of allowed parameters: + +Local User Account +------------------ + +.. cfgcmd:: set system syslog user <username> facility <keyword> level <keyword> + +If logging to a local user account is configured, all defined log messages are +display on the console if the local user is logged in, if the user is not +logged in, no messages are being displayed. For en explanation on +:ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords see +tables below. + +.. _syslog_facilities: + +Facilities +========== + +List of facilities used by syslog. Most facilities names are self explanatory. +Facilities local0 - local7 common usage is f.e. as network logs facilities for +nodes and network equipment. Generally it depends on the situation how to +classify logs and put them to facilities. See facilities more as a tool rather +than a directive to follow. + +Facilities can be adjusted to meet the needs of the user: + ++----------+----------+----------------------------------------------------+ +| Facility | Keyword | Description | +| Code | | | ++==========+==========+====================================================+ +| | all | All facilities | ++----------+----------+----------------------------------------------------+ +| 0 | kern | Kernel messages | ++----------+----------+----------------------------------------------------+ +| 1 | user | User-level messages | ++----------+----------+----------------------------------------------------+ +| 2 | mail | Mail system | ++----------+----------+----------------------------------------------------+ +| 3 | daemon | System daemons | ++----------+----------+----------------------------------------------------+ +| 4 | auth | Security/authentication messages | ++----------+----------+----------------------------------------------------+ +| 5 | syslog | Messages generated internally by syslogd | ++----------+----------+----------------------------------------------------+ +| 6 | lpr | Line printer subsystem | ++----------+----------+----------------------------------------------------+ +| 7 | news | Network news subsystem | ++----------+----------+----------------------------------------------------+ +| 8 | uucp | UUCP subsystem | ++----------+----------+----------------------------------------------------+ +| 9 | cron | Clock daemon | ++----------+----------+----------------------------------------------------+ +| 10 | security | Security/authentication messages | ++----------+----------+----------------------------------------------------+ +| 11 | ftp | FTP daemon | ++----------+----------+----------------------------------------------------+ +| 12 | ntp | NTP subsystem | ++----------+----------+----------------------------------------------------+ +| 13 | logaudit | Log audit | ++----------+----------+----------------------------------------------------+ +| 14 | logalert | Log alert | ++----------+----------+----------------------------------------------------+ +| 15 | clock | clock daemon (note 2) | ++----------+----------+----------------------------------------------------+ +| 16 | local0 | local use 0 (local0) | ++----------+----------+----------------------------------------------------+ +| 17 | local1 | local use 1 (local1) | ++----------+----------+----------------------------------------------------+ +| 18 | local2 | local use 2 (local2) | ++----------+----------+----------------------------------------------------+ +| 19 | local3 | local use 3 (local3) | ++----------+----------+----------------------------------------------------+ +| 20 | local4 | local use 4 (local4) | ++----------+----------+----------------------------------------------------+ +| 21 | local5 | local use 5 (local5) | ++----------+----------+----------------------------------------------------+ +| 22 | local6 | use 6 (local6) | ++----------+----------+----------------------------------------------------+ +| 23 | local7 | local use 7 (local7) | ++----------+----------+----------------------------------------------------+ + +.. _syslog_severity_level: + +Severity Level +============== + ++-------+---------------+---------+-------------------------------------------+ +| Value | Severity | Keyword | Description | ++=======+===============+=========+===========================================+ +| | | all | Log everything | ++-------+---------------+---------+-------------------------------------------+ +| 0 | Emergency | emerg | System is unusable - a panic condition | ++-------+---------------+---------+-------------------------------------------+ +| 1 | Alert | alert | Action must be taken immediately - A | +| | | | condition that should be corrected | +| | | | immediately, such as a corrupted system | +| | | | database. | ++-------+---------------+---------+-------------------------------------------+ +| 2 | Critical | crit | Critical conditions - e.g. hard drive | +| | | | errors. | ++-------+---------------+---------+-------------------------------------------+ +| 3 | Error | err | Error conditions | ++-------+---------------+---------+-------------------------------------------+ +| 4 | Warning | warning | Warning conditions | ++-------+---------------+---------+-------------------------------------------+ +| 5 | Notice | notice | Normal but significant conditions - | +| | | | conditions that are not error conditions, | +| | | | but that may require special handling. | ++-------+---------------+---------+-------------------------------------------+ +| 6 | Informational | info | Informational messages | ++-------+---------------+---------+-------------------------------------------+ +| 7 | Debug | debug | Debug-level messages - Messages that | +| | | | contain information normally of use only | +| | | | when debugging a program. | ++-------+---------------+---------+-------------------------------------------+ + + +Display Logs +============ + +.. opcmd:: show log [all | authorization | cluster | conntrack-sync | ...] + +Display log files of given category on the console. Use tab completion to get +a list of available categories. Thos categories could be: all, authorization, +cluster, conntrack-sync, dhcp, directory, dns, file, firewall, https, image +lldp, nat, openvpn, snmp, tail, vpn, vrrp + +If no option is specified, this defaults to `all`. + +.. opcmd:: show log image <name> [all | authorization | directory | file <file name> | tail <lines>] + +Log messages from a specified image can be displayed on the console. Details of +allowed parameters: .. list-table:: :widths: 25 75 @@ -173,5 +220,5 @@ Details of allowed parameters: * - <lines> - Number of lines to be displayed, default 10 - -When no options/parameters are used, the contents of the main syslog file are displayed. +When no options/parameters are used, the contents of the main syslog file are +displayed. |