summaryrefslogtreecommitdiff
path: root/docs/services
diff options
context:
space:
mode:
Diffstat (limited to 'docs/services')
-rw-r--r--docs/services/console-server.rst8
-rw-r--r--docs/services/dns-forwarding.rst24
-rw-r--r--docs/services/snmp.rst101
3 files changed, 69 insertions, 64 deletions
diff --git a/docs/services/console-server.rst b/docs/services/console-server.rst
index 17d1d4d5..7fc43f95 100644
--- a/docs/services/console-server.rst
+++ b/docs/services/console-server.rst
@@ -33,7 +33,7 @@ distributions.
For additional details you can refer to https://phabricator.vyos.net/T2490.
-.. opcmd:: show system usb
+.. opcmd:: show hardware usb
Retrieve a tree like representation of all connected USB devices.
@@ -42,7 +42,7 @@ For additional details you can refer to https://phabricator.vyos.net/T2490.
.. code-block:: none
- vyos@vyos:~$ show system usb
+ vyos@vyos:~$ show hardware usb
/: Bus 03.Port 1: Dev 1, Class=root_hub, Driver=ehci-pci/2p, 480M
|__ Port 1: Dev 2, If 0, Class=Hub, Driver=hub/4p, 480M
|__ Port 3: Dev 4, If 0, Class=Vendor Specific Class, Driver=qcserial, 480M
@@ -69,7 +69,7 @@ For additional details you can refer to https://phabricator.vyos.net/T2490.
|__ Port 4: Dev 7, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
-.. opcmd:: show system usb
+.. opcmd:: show hardware usb serial
Retrieve a list and description of all connected USB serial devices. The device name
displayed, e.g. `usb0b2.4p1.0` can be directly used when accessing the serial console
@@ -77,7 +77,7 @@ For additional details you can refer to https://phabricator.vyos.net/T2490.
.. code-block:: none
- vyos@vyos$ show system usb serial
+ vyos@vyos$ show hardware usb serial
Device Model Vendor
------ ------ ------
usb0b1.3p1.0 MC7710 Sierra Wireless, Inc.
diff --git a/docs/services/dns-forwarding.rst b/docs/services/dns-forwarding.rst
index a529f6a7..5c154fdf 100644
--- a/docs/services/dns-forwarding.rst
+++ b/docs/services/dns-forwarding.rst
@@ -11,7 +11,7 @@ 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.
-VyOS DNS forwarder does not require an upstream DNS server. It can serve as a
+The 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.
@@ -103,23 +103,23 @@ avoid to be tracked by the provider of your upstream DNS server.
.. cfgcmd:: set service dns forwarding listen-address
- Local IPv4 or IPv6 addresses to bind to - waiting on this address for
+ The local IPv4 or IPv6 addresses to bind the DNS forwarder to. The forwarder will listen 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.
+A VyOS router with two interfaces - eth0 (WAN) and eth1 (LAN) - is required to implement a split-horizon DNS configuration 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,
+In this scenario:
+
+* All DNS requests for example.com must be forwarded to a DNS server at 192.0.2.254
+ and 2001:db8:cafe::1
+* All other DNS requests will be forwarded to a different set of DNS servers at 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
+* The VyOS DNS forwarder will only listen for requests on the eth1 (LAN) interface addresses - 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
+* The VyOS DNS forwarder will only accept lookup requests from the LAN subnets - 192.168.1.0/24 and 2001:db8::/64
.. code-block:: none
@@ -139,9 +139,9 @@ Operation
.. opcmd:: reset dns forwarding <all | domain>
- Reset local DNS forwarding cache database. You can reset the cache for all
+ Resets the 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.
+ Restarts the DNS recursor process. This also invalidates the local DNS forwarding cache.
diff --git a/docs/services/snmp.rst b/docs/services/snmp.rst
index c27cf02a..3f445ea8 100644
--- a/docs/services/snmp.rst
+++ b/docs/services/snmp.rst
@@ -1,11 +1,14 @@
+.. _snmp:
+
+####
SNMP
-----
+####
-Simple Network Management Protocol (SNMP_) is an Internet Standard protocol
-for collecting and organizing information about managed devices on IP networks
-and for modifying that information to change device behavior. Devices that
-typically support SNMP include cable modems, routers, switches, servers,
-workstations, printers, and more.
+:abbr:`SNMP (Simple Network Management Protocol)` is an Internet Standard
+protocol for collecting and organizing information about managed devices on
+IP networks and for modifying that information to change device behavior.
+Devices that typically support SNMP include cable modems, routers, switches,
+servers, workstations, printers, and more.
SNMP is widely used in network management for network monitoring. SNMP exposes
management data in the form of variables on the managed systems organized in
@@ -23,7 +26,7 @@ management, including an application layer protocol, a database schema, and a
set of data objects.
Overview and basic concepts
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+===========================
In typical uses of SNMP, one or more administrative computers called managers
have the task of monitoring or managing a group of hosts or devices on a
@@ -63,15 +66,15 @@ network.
.. note:: VyOS SNMP supports both IPv4 and IPv6.
-SNMP protocol versions
-^^^^^^^^^^^^^^^^^^^^^^
+SNMP Protocol Versions
+======================
VyOS itself supports SNMPv2_ (version 2) and SNMPv3_ (version 3) where the
later is recommended because of improved security (optional authentication and
encryption).
SNMPv2
-^^^^^^
+------
SNMPv2 is the original and most commonly used version. For authorizing clients,
SNMP uses the concept of communities. Communities may have authorization set
@@ -88,7 +91,7 @@ router. Note that SNMPv2 also supports no encryption and always sends data in
plain text.
Example
-*******
+^^^^^^^
.. code-block:: none
@@ -116,7 +119,7 @@ Example
SNMPv3
-^^^^^^
+------
SNMPv3 (version 3 of the SNMP protocol) introduced a whole slew of new security
related features that have been missing from the previous versions. Security
@@ -137,60 +140,64 @@ The securityapproach in v3 targets:
* Authentication – to verify that the message is from a valid source.
Example
-*******
-
-.. code-block:: none
+^^^^^^^
- set service snmp v3 engineid '0x0aa0d6c6f450'
- set service snmp v3 group defaultgroup mode 'ro'
- set service snmp v3 group defaultgroup seclevel 'priv'
- set service snmp v3 group defaultgroup view 'defaultview'
- set service snmp v3 view defaultview oid '1'
+* Let SNMP daemon listen only on IP address 192.0.2.1
+* Configure new SNMP user named "vyos" with password "vyos12345678"
+* New user will use SHA/AES for authentication and privacy
- set service snmp v3 user testUser1 auth plaintext-key testUserKey1
- set service snmp v3 user testUser1 auth type 'md5'
- set service snmp v3 user testUser1 engineid '0x0aa0d6c6f450'
- set service snmp v3 user testUser1 group 'defaultgroup'
- set service snmp v3 user testUser1 mode 'ro'
- set service snmp v3 user testUser1 privacy type aes
- set service snmp v3 user testUser1 privacy plaintext-key testUserKey1
-
-After commit the resulting configuration will look like:
+.. code-block:: none
-.. note:: SNMPv3 keys won't we stored in plaintext. On ``commit`` the keys
- will be encrypted and the encrypted key is based on the engineid!
+ set service snmp listen-address 192.0.2.1
+ set service snmp location 'VyOS Datacenter'
+ set service snmp v3 engineid '000000000000000000000002'
+ set service snmp v3 group default mode 'ro'
+ set service snmp v3 group default view 'default'
+ set service snmp v3 user vyos auth plaintext-password 'vyos12345678'
+ set service snmp v3 user vyos auth type 'sha'
+ set service snmp v3 user vyos group 'default'
+ set service snmp v3 user vyos privacy plaintext-password 'vyos12345678'
+ set service snmp v3 user vyos privacy type 'aes'
+ set service snmp v3 view default oid 1
+
+After commit the plaintext passwords will be hashed and stored in your
+configuration. The resulting LCI config will look like:
.. code-block:: none
vyos@vyos# show service snmp
+ listen-address 172.18.254.201 {
+ }
+ location "Wuerzburg, Dr.-Georg-Fuchs-Str. 8"
v3 {
- engineid 0x0aa0d6c6f450
- group defaultgroup {
+ engineid 000000000000000000000002
+ group default {
mode ro
- seclevel priv
- view defaultview
+ view default
}
- user testUser1 {
+ user vyos {
auth {
- encrypted-key 0x3b68d4162c2c817b8e9dfb6f08583e5d
- type md5
+ encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe
+ type sha
}
- engineid 0x0aa0d6c6f450
- group defaultgroup
- mode ro
+ group default
privacy {
- encrypted-key 0x3b68d4162c2c817b8e9dfb6f08583e5d
+ encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe
type aes
}
}
- view defaultview {
+ view default {
oid 1 {
}
}
}
+You can test the SNMPv3 functionality from any linux based system, just run the
+following command: ``snmpwalk -v 3 -u vyos -a SHA -A vyos12345678 -x AES
+-X vyos12345678 -l authPriv 192.0.2.1 .1``
+
VyOS MIBs
-^^^^^^^^^
+=========
All SNMP MIBs are located in each image of VyOS here: ``/usr/share/snmp/mibs/``
@@ -200,9 +207,8 @@ you are be able to download the files with the a activate ssh service like this
scp -r vyos@your_router:/usr/share/snmp/mibs /your_folder/mibs
-
SNMP Extensions
-^^^^^^^^^^^^^^^
+===============
To extend SNMP agent functionality, custom scripts can be executed every time
the agent is being called. This can be achieved by using
@@ -230,7 +236,7 @@ contain the output of the extension.
NET-SNMP-EXTEND-MIB::nsExtendResult."my-extension" = INTEGER: 0
SolarWinds
-^^^^^^^^^^
+==========
If you happen to use SolarWinds Orion as NMS you can also use the Device
Templates Management. A template for VyOS can be easily imported.
@@ -255,7 +261,6 @@ following content:
</Configuration-Management>
.. _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
.. _SNMPv3: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3
generated by cgit v1.2.3 (git 2.39.1) at 2025-01-20 14:36:13 +0000