Migrate new file structure to crux (#435)

* order workflows and add submodule

* rename gitmodules file

* delete docs/.gitignore

* add vyos custom linter

* correct __pycache__ in gitignore

* add test-coverage.py

* move draw.io folder

* arrange changelog, install history and about

* arrange: firewall

* arrange: highavailability

* arrange: loadbalancing

* arrange: nat

* arrange: services

* sort configexamples and configuration interfaces

* wireles: rename wireless

* rearrange: Protocols and Policy

* rearrange: Firewall and Zone Policy

* rearrange: Interfaces

* rearrange: Interfaces

* rearrange: dynamic DNS

* hostinfo: add page to index

* rearrange: appendix

* venv: add Pipfile

* rearrange: contributing

* index: remove debugging

* rearrange: fix all figure and refs

* rearrange: commandtree

* fix: cli, openvpn, install headline level

* protocols: change headline

* firewall: move mss clamping

* ip: separate ipv4 and ipv6

* arp: move to static page

* igmp: rename multicast page

* Update to year 2021

1 files changed, 245 insertions, 0 deletions

diff --git a/docs/configuration/service/snmp.rst b/docs/configuration/service/snmp.rst
new file mode 100644
index 00000000..6418a516
--- /dev/null
+++ b/docs/configuration/service/snmp.rst
@@ -0,0 +1,245 @@
+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.
+
+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
+a management information base (MIB_) which describe the system status and
+configuration. These variables can then be remotely queried (and, in some
+circumstances, manipulated) by managing applications.
+
+Three significant versions of SNMP have been developed and deployed. SNMPv1 is
+the original version of the protocol. More recent versions, SNMPv2c and SNMPv3,
+feature improvements in performance, flexibility and security.
+
+SNMP is a component of the Internet Protocol Suite as defined by the Internet
+Engineering Task Force (IETF). It consists of a set of standards for network
+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
+computer network. Each managed system executes a software component called an
+agent which reports information via SNMP to the manager.
+
+An SNMP-managed network consists of three key components:
+
+* Managed devices
+* Agent - software which runs on managed devices
+* Network management station (NMS) - software which runs on the manager
+
+A managed device is a network node that implements an SNMP interface that
+allows unidirectional (read-only) or bidirectional (read and write) access to
+node-specific information. Managed devices exchange node-specific information
+with the NMSs. Sometimes called network elements, the managed devices can be
+any type of device, including, but not limited to, routers, access servers,
+switches, cable modems, bridges, hubs, IP telephones, IP video cameras,
+computer hosts, and printers.
+
+An agent is a network-management software module that resides on a managed
+device. An agent has local knowledge of management information and translates
+that information to or from an SNMP-specific form.
+
+A network management station executes applications that monitor and control
+managed devices. NMSs provide the bulk of the processing and memory resources
+required for network management. One or more NMSs may exist on any managed
+network.
+
+.. figure:: /_static/images/service_snmp_communication_principles_diagram.png
+   :scale: 20 %
+   :alt: Principle of SNMP Communication
+
+   Image thankfully borrowed from
+   https://en.wikipedia.org/wiki/File:SNMP_communication_principles_diagram.PNG
+   which is under the GNU Free Documentation License
+
+.. note:: VyOS SNMP supports both IPv4 and IPv6.
+
+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
+to read only (this is most common) or to read and write (this option is not
+actively used in VyOS).
+
+SNMP can work synchronously or asynchronously. In synchronous communication,
+the monitoring system queries the router periodically. In asynchronous, the
+router sends notification to the "trap" (the monitoring host).
+
+SNMPv2 does not support any authentication mechanisms, other than client source
+address, so you should specify addresses of clients allowed to monitor the
+router. Note that SNMPv2 also supports no encryption and always sends data in
+plain text.
+
+Example
+*******
+
+.. code-block:: none
+
+  # Define a community
+  set service snmp community routers authorization ro
+
+  # Allow monitoring access from the entire network
+  set service snmp community routers network 192.0.2.0/24
+  set service snmp community routers network 2001::db8:ffff:eeee::/64
+
+  # Allow monitoring access from specific addresses
+  set service snmp community routers client 203.0.113.10
+  set service snmp community routers client 203.0.113.20
+
+  # Define optional router information
+  set service snmp location "UK, London"
+  set service snmp contact "admin@example.com"
+
+  # Trap target if you want asynchronous communication
+  set service snmp trap-target 203.0.113.10
+
+  # Listen only on specific IP addresses (port defaults to 161)
+  set service snmp listen-address 172.16.254.36 port 161
+  set service snmp listen-address 2001:db8::f00::1
+
+
+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
+was one of the biggest weakness of SNMP until v3. Authentication in SNMP
+Versions 1 and 2 amounts to nothing more than a password (community string)
+sent in clear text between a manager and agent. Each SNMPv3 message contains
+security parameters which are encoded as an octet string. The meaning of these
+security parameters depends on the security model being used.
+
+The securityapproach in v3 targets:
+
+* Confidentiality – Encryption of packets to prevent snooping by an
+  unauthorized source.
+
+* Integrity – Message integrity to ensure that a packet has not been tampered
+  while in transit including an optional packet replay protection mechanism.
+
+* 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'
+
+  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:
+
+.. 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!
+
+.. code-block:: none
+
+  vyos@vyos# show service snmp
+   v3 {
+       engineid 0x0aa0d6c6f450
+       group defaultgroup {
+           mode ro
+           seclevel priv
+           view defaultview
+       }
+       user testUser1 {
+           auth {
+               encrypted-key 0x3b68d4162c2c817b8e9dfb6f08583e5d
+               type md5
+           }
+           engineid 0x0aa0d6c6f450
+           group defaultgroup
+           mode ro
+           privacy {
+               encrypted-key 0x3b68d4162c2c817b8e9dfb6f08583e5d
+               type aes
+           }
+       }
+       view defaultview {
+           oid 1 {
+           }
+       }
+   }
+
+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 ``arbitrary extension
+commands``_. The first step is to create a functional script of course, then
+upload it to your VyOS instance via the command ``scp your_script.sh
+vyos@your_router:/config/user-data``. Once the script is uploaded, it needs to
+be configured via the command below.
+
+
+.. code-block:: none
+
+  set service snmp script-extensions extension-name my-extension script your_script.sh
+  commit
+
+
+The OID ``.1.3.6.1.4.1.8072.1.3.2.3.1.1.4.116.101.115.116``, once called, will
+contain the output of the extension.
+
+.. code-block:: none
+
+  root@vyos:/home/vyos# snmpwalk -v2c  -c public 127.0.0.1 nsExtendOutput1
+  NET-SNMP-EXTEND-MIB::nsExtendOutput1Line."my-extension" = STRING: hello
+  NET-SNMP-EXTEND-MIB::nsExtendOutputFull."my-extension" = STRING: hello
+  NET-SNMP-EXTEND-MIB::nsExtendOutNumLines."my-extension" = INTEGER: 1
+  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.
+
+Create a file named ``VyOS-1.3.6.1.4.1.44641.ConfigMgmt-Commands`` using the
+following content:
+
+.. code-block:: none
+
+  <Configuration-Management Device="VyOS" SystemOID="1.3.6.1.4.1.44641">
+      <Commands>
+          <Command Name="Reset" Value="set terminal width 0${CRLF}set terminal length 0"/>
+          <Command Name="Reboot" Value="reboot${CRLF}Yes"/>
+          <Command Name="EnterConfigMode" Value="configure"/>
+          <Command Name="ExitConfigMode" Value="commit${CRLF}exit"/>
+          <Command Name="DownloadConfig" Value="show configuration commands"/>
+          <Command Name="SaveConfig" Value="commit${CRLF}save"/>
+          <Command Name="Version" Value="show version"/>
+          <Command Name="MenuBased" Value="False"/>
+          <Command Name="VirtualPrompt" Value=":~"/>
+      </Commands>
+  </Configuration-Management>
+
+.. include:: references.rst