Merge branch 'master' of https://github.com/goodNETnick/vyos-documentation

7 files changed, 276 insertions, 4 deletions

diff --git a/docs/configuration/service/broadcast-relay.rst b/docs/configuration/service/broadcast-relay.rst
index df48bfd6..b6e2bed7 100644
--- a/docs/configuration/service/broadcast-relay.rst
+++ b/docs/configuration/service/broadcast-relay.rst
@@ -28,6 +28,11 @@ Configuration
    want to receive/relay packets on both `eth1` and `eth2` both interfaces need
    to be added.
 
+.. cfgcmd:: set service broadcast-relay id <n> address <ipv4-address>
+
+   Set the source IP of forwarded packets, otherwise original senders address
+   is used.
+
 .. cfgcmd:: set service broadcast-relay id <n> port <port>
 
    The UDP port number used by your apllication. It is mandatory for this kind
diff --git a/docs/configuration/service/conntrack-sync.rst b/docs/configuration/service/conntrack-sync.rst
index a7cd7060..1b72f8eb 100644
--- a/docs/configuration/service/conntrack-sync.rst
+++ b/docs/configuration/service/conntrack-sync.rst
@@ -114,11 +114,11 @@ Operation
     conntrack is not enabled. To enable conntrack, just create a NAT or a firewall
     rule. :cfgcmd:`set firewall state-policy established action accept`
 
-.. opcmd:: show conntrack-sync external-cache
+.. opcmd:: show conntrack-sync cache external
 
   Show connection syncing external cache entries
 
-.. opcmd:: show conntrack-sync internal-cache
+.. opcmd:: show conntrack-sync cache internal
 
   Show connection syncing internal cache entries
 
diff --git a/docs/configuration/service/eventhandler.rst b/docs/configuration/service/eventhandler.rst
new file mode 100644
index 00000000..15f08239
--- /dev/null
+++ b/docs/configuration/service/eventhandler.rst
@@ -0,0 +1,127 @@
+.. _event-handler:
+
+#############
+Event Handler
+#############
+
+*********************************
+Event Handler Technology Overview
+*********************************
+
+Event handler allows you to execute scripts when a string that matches a regex or a regex with 
+a service name appears in journald logs. You can pass variables, arguments, and a full matching string to the script.
+
+
+******************************
+How to configure Event Handler
+******************************
+
+    `1. Create an event handler`_
+
+    `2. Add regex to the script`_
+
+    `3. Add a full path to the script`_
+
+    `4. Add optional parameters`_
+
+*********************************
+Event Handler Configuration Steps
+*********************************
+
+1. Create an event handler
+==========================
+
+    .. cfgcmd:: set service event-handler event <event-handler name>
+
+    This is an optional command because the event handler will be automatically created after any of the next commands.
+
+
+2. Add regex to the script
+===========================================
+
+    .. cfgcmd:: set service event-handler event <event-handler name> filter pattern <regex>   
+
+    This is a mandatory command. Sets regular expression to match against log string message.
+    
+    .. note:: The regular expression matches if and only if the entire string matches the pattern.
+
+
+
+3. Add a full path to the script
+================================
+
+    .. cfgcmd:: set service event-handler event <event-handler name> script path <path to script>
+   
+    This is a mandatory command. Sets the full path to the script. The script file must be executable.
+
+
+   
+4. Add optional parameters
+==========================
+
+    .. cfgcmd:: set service event-handler event <event-handler name> filter syslog-identifier <sylogid name>
+
+    This is an optional command. Filters log messages by syslog-identifier.
+
+    .. cfgcmd:: set service event-handler event <event-handler name> script environment <env name> value <env value>
+
+    This is an optional command. Adds environment and its value to the script. Use separate commands for each environment.
+    
+    One implicit environment exists.
+    
+    * ``message``: Full message that has triggered the script.
+
+    .. cfgcmd:: set service event-handler event <event-handler name> script arguments <arguments>
+
+    This is an optional command. Adds arguments to the script. Arguments must be separated by spaces.
+
+    .. note:: We don't recomend to use arguments. Using environments is more preffereble.
+    
+
+*******
+Example
+*******
+
+    Event handler that monitors the state of interface eth0.
+
+    .. code-block:: none
+
+	set service event-handler event INTERFACE_STATE_DOWN filter pattern '.*eth0.*,RUNNING,.*->.*'
+	set service event-handler event INTERFACE_STATE_DOWN filter syslog-identifier 'netplugd'
+	set service event-handler event INTERFACE_STATE_DOWN script environment interface_action value 'down'
+	set service event-handler event INTERFACE_STATE_DOWN script environment interface_name value 'eth2'
+	set service event-handler event INTERFACE_STATE_DOWN script path '/config/scripts/eventhandler.py'
+
+    Event handler script
+
+    .. code-block:: none
+
+	#!/usr/bin/env python3
+	#
+	# VyOS event-handler script example
+	from os import environ
+	import subprocess
+	from sys import exit
+
+	# Perform actions according to requirements
+	def process_event() -> None:
+    	    # Get variables
+    	    message_text = environ.get('message')
+    	    interface_name = environ.get('interface_name')
+    	    interface_action = environ.get('interface_action')
+    	    # Print the message that triggered this script
+    	    print(f'Logged message: {message_text}')
+    	    # Prepare a command to run
+    	    command = f'sudo ip link set {interface_name} {interface_action}'.split()
+    	    # Execute a command
+    	    subprocess.run(command)
+
+	if __name__ == '__main__':
+    	    try:
+        	# Run script actions and exit
+        	process_event()
+    	        exit(0)
+    	    except Exception as err:
+        	# Exit properly in case if something in the script goes wrong
+            	print(f'Error running script: {err}')
+            	exit(1)
diff --git a/docs/configuration/service/https.rst b/docs/configuration/service/https.rst
index 22533db5..08b16575 100644
--- a/docs/configuration/service/https.rst
+++ b/docs/configuration/service/https.rst
@@ -28,6 +28,10 @@ Configuration
    Set the listen port of the local API, this has no effect on the
    webserver. The default is port 8080
 
+.. cfgcmd:: set service https api socket
+
+   Use local socket for API
+
 .. cfgcmd:: set service https api strict
 
    Enforce strict path checking
@@ -89,4 +93,4 @@ To use this full configuration we asume a public accessible hostname.
    set service https virtual-host rtr01 listen-address 198.51.100.2
    set service https virtual-host rtr01 listen-port 11443
    set service https virtual-host rtr01 server-name rtr01.example.com
-   set service https api-restrict virtual-host rtr01.example.com
+   set service https api-restrict virtual-host rtr01
diff --git a/docs/configuration/service/index.rst b/docs/configuration/service/index.rst
index 11a1a118..8607490d 100644
--- a/docs/configuration/service/index.rst
+++ b/docs/configuration/service/index.rst
@@ -25,3 +25,4 @@ Service
    ssh
    tftp-server
    webproxy
+   eventhandler
diff --git a/docs/configuration/service/monitoring.rst b/docs/configuration/service/monitoring.rst
index 7396f142..755669e1 100644
--- a/docs/configuration/service/monitoring.rst
+++ b/docs/configuration/service/monitoring.rst
@@ -1,10 +1,111 @@
 Monitoring
 ----------
 
-Monitoring functionality with ``telegraf`` and ``InfluxDB 2`` is provided.
+Azure-data-explorer
+===================
+Telegraf output plugin azure-data-explorer_
+
+.. cfgcmd:: set service monitoring telegraf azure-data-explorer authentication client-id <client-id>
+
+   Authentication application client-id.
+
+.. cfgcmd:: set service monitoring telegraf azure-data-explorer authentication client-secret <client-secret>
+
+   Authentication application client-secret.
+
+.. cfgcmd:: set service monitoring telegraf azure-data-explorer authentication tenant-id <tenant-id>
+
+   Authentication application tenant-id
+
+.. cfgcmd:: set service monitoring telegraf azure-data-explorer database <name>
+
+   Remote databe name.
+
+.. cfgcmd:: set service monitoring telegraf azure-data-explorer group-metrics <single-table | table-per-metric>
+
+   Type of metrics grouping when push to Azure Data Explorer. The default is
+   ``table-per-metric``.
+
+.. cfgcmd:: set service monitoring telegraf azure-data-explorer table <name>
+
+   Name of the single table Only if set group-metrics single-table.
+
+.. cfgcmd:: set service monitoring telegraf azure-data-explorer url <url>
+
+   Remote URL.
+
+Prometheus-client
+=================
+Telegraf output plugin prometheus-client_
+
+.. cfgcmd:: set service monitoring telegraf prometheus-client
+
+   Output plugin Prometheus client
+
+.. cfgcmd:: set service monitoring telegraf prometheus-client allow-from <prefix>
+
+   Networks allowed to query this server
+
+.. cfgcmd:: set service monitoring telegraf prometheus-client authentication username <username>
+
+   HTTP basic authentication username
+
+.. cfgcmd:: set service monitoring telegraf prometheus-client authentication password <password>
+
+   HTTP basic authentication username
+
+.. cfgcmd:: set service monitoring telegraf prometheus-client listen-address <address>
+
+   Local IP addresses to listen on
+
+.. cfgcmd:: set service monitoring telegraf prometheus-client metric-version <1 | 2>
+
+   Metris version, the default is ``2``
+
+.. cfgcmd:: set service monitoring telegraf prometheus-client port <port>
+
+   Port number used by connection, default is ``9273``
+
+Example:
+
+.. code-block:: none
+
+  set service monitoring telegraf prometheus-client
+
+.. code-block:: none
+
+  vyos@r14:~$ curl --silent localhost:9273/metrics | egrep -v "#" |  grep cpu_usage_system
+  cpu_usage_system{cpu="cpu-total",host="r14"} 0.20040080160320556
+  cpu_usage_system{cpu="cpu0",host="r14"} 0.17182130584191915
+  cpu_usage_system{cpu="cpu1",host="r14"} 0.22896393817971655
+
+Splunk
+======
+Telegraf output plugin splunk_. HTTP Event Collector.
+
+.. cfgcmd:: set service monitoring telegraf splunk authentication insecure
+
+   Use TLS but skip host validation
+
+.. cfgcmd:: set service monitoring telegraf splunk authentication token <token>
+
+   Authorization token
+
+.. cfgcmd:: set service monitoring telegraf splunk authentication url <url>
+
+   Remote URL to Splunk collector
+
+Example:
+
+.. code-block:: none
+
+  set service monitoring telegraf splunk authentication insecure
+  set service monitoring telegraf splunk authentication token 'xxxxf5b8-xxxx-452a-xxxx-43828911xxxx'
+  set service monitoring telegraf splunk url 'https://192.0.2.10:8088/services/collector'
 
 Telegraf
 ========
+Monitoring functionality with ``telegraf`` and ``InfluxDB 2`` is provided.
 Telegraf is the open source server agent to help you collect metrics, events
 and logs from your routers.
 
@@ -43,3 +144,7 @@ An example of a configuration that sends ``telegraf`` metrics to remote
   set service monitoring telegraf port '8086'
   set service monitoring telegraf source 'all'
   set service monitoring telegraf url 'http://r1.influxdb2.local'
+
+.. _azure-data-explorer: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/azure_data_explorer
+.. _prometheus-client: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/prometheus_client
+.. _splunk: https://www.splunk.com/en_us/blog/it/splunk-metrics-via-telegraf.html
\ No newline at end of file
diff --git a/docs/configuration/service/ssh.rst b/docs/configuration/service/ssh.rst
index ad410a3c..baf17035 100644
--- a/docs/configuration/service/ssh.rst
+++ b/docs/configuration/service/ssh.rst
@@ -109,6 +109,36 @@ Configuration
 
   Specify name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance.
 
+Dynamic-protection
+==================
+Protects host from brute-force attacks against
+SSH. Log messages are parsed, line-by-line, for recognized patterns. If an
+attack, such as several login failures within a few seconds, is detected, the
+offending IP is blocked. Offenders are unblocked after a set interval.
+
+.. cfgcmd:: set service ssh dynamic-protection
+
+  Allow ``ssh`` dynamic-protection.
+
+.. cfgcmd:: set service ssh dynamic-protection allow-from <address | prefix>
+
+  Whitelist of addresses and networks. Always allow inbound connections from
+  these systems.
+
+.. cfgcmd:: set service ssh dynamic-protection block-time <sec>
+
+  Block source IP in seconds. Subsequent blocks increase by a factor of 1.5
+  The default is 120.
+
+.. cfgcmd:: set service ssh dynamic-protection detect-time <sec>
+
+  Remember source IP in seconds before reset their score. The default is 1800.
+
+.. cfgcmd:: set service ssh dynamic-protection threshold <sec>
+
+  Block source IP when their cumulative attack score exceeds threshold. The
+  default is 30.
+
 Operation
 =========