Adding upstream version 1:7.0.3.upstream/1%7.0.3

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 249 insertions, 0 deletions

diff --git a/doc/userguide/configuration/multi-tenant.rst b/doc/userguide/configuration/multi-tenant.rst
new file mode 100644
index 0000000..1058468
--- /dev/null
+++ b/doc/userguide/configuration/multi-tenant.rst
@@ -0,0 +1,249 @@
+Multi Tenancy
+=============
+
+Introduction
+------------
+
+Multi tenancy support allows different tenants to use different
+rule sets with different rule variables.
+
+Tenants are identified by their `selector`; a `selector` can be
+a VLAN, interface/device, or from a pcap file ("direct").
+
+YAML
+----
+
+Add a new section in the main ("master") Suricata configuration file -- ``suricata.yaml`` -- named ``multi-detect``.
+
+Settings:
+
+* `enabled`: yes/no -> is multi-tenancy support enabled
+* `selector`: direct (for unix socket pcap processing, see below), VLAN or device
+* `loaders`: number of `loader` threads, for parallel tenant loading at startup
+* `tenants`: list of tenants
+* `config-path`: path from where the tenant yamls are loaded
+
+  * id: tenant id (numeric values only)
+  * yaml: separate yaml file with the tenant specific settings
+
+* `mappings`:
+
+  * VLAN id or device: The outermost VLAN is used to match.
+  * tenant id: tenant to associate with the VLAN id or device
+
+::
+
+  multi-detect:
+    enabled: yes
+    #selector: direct # direct or vlan
+    selector: vlan
+    loaders: 3
+
+    tenants:
+    - id: 1
+      yaml: tenant-1.yaml
+    - id: 2
+      yaml: tenant-2.yaml
+    - id: 3
+      yaml: tenant-3.yaml
+
+    mappings:
+    - vlan-id: 1000
+      tenant-id: 1
+    - vlan-id: 2000
+      tenant-id: 2
+    - vlan-id: 1112
+      tenant-id: 3
+
+The tenant-1.yaml, tenant-2.yaml, tenant-3.yaml each contain a partial
+configuration:
+
+::
+
+  # Set the default rule path here to search for the files.
+  # if not set, it will look at the current working dir
+  default-rule-path: /etc/suricata/rules
+  rule-files:
+    - rules1
+
+  # You can specify a threshold config file by setting "threshold-file"
+  # to the path of the threshold config file:
+  # threshold-file: /etc/suricata/threshold.config
+
+  classification-file: /etc/suricata/classification.config
+  reference-config-file: /etc/suricata/reference.config
+
+  # Holds variables that would be used by the engine.
+  vars:
+
+    # Holds the address group vars that would be passed in a Signature.
+    # These would be retrieved during the Signature address parsing stage.
+    address-groups:
+
+      HOME_NET: "[192.168.0.0/16,10.0.0.0/8,172.16.0.0/12]"
+
+      EXTERNAL_NET: "!$HOME_NET"
+
+      ...
+
+    port-groups:
+
+      HTTP_PORTS: "80"
+
+      SHELLCODE_PORTS: "!80"
+
+      ...
+
+vlan-id
+~~~~~~~
+
+Assign tenants to VLAN ids. Suricata matches the outermost VLAN id with this value.
+Multiple VLANs can have the same tenant id. VLAN id values must be between 1 and 4094.
+
+Example of VLAN mapping::
+
+    mappings:
+    - vlan-id: 1000
+      tenant-id: 1
+    - vlan-id: 2000
+      tenant-id: 2
+    - vlan-id: 1112
+      tenant-id: 3
+
+The mappings can also be modified over the unix socket, see below.
+
+Note: can only be used if ``vlan.use-for-tracking`` is enabled.
+
+device
+~~~~~~
+
+Assign tenants to devices. A single tenant can be assigned to a device.
+Multiple devices can have the same tenant id.
+
+Example of device mapping::
+
+    mappings:
+    - device: ens5f0
+      tenant-id: 1
+    - device: ens5f1
+      tenant-id: 3
+
+The mappings are static and cannot be modified over the unix socket.
+
+Note: Not currently supported for IPS.
+
+Note: support depends on a capture method using the 'livedev' API. Currently
+these are: pcap, AF_PACKET, PF_RING and Netmap.
+
+Per tenant settings
+-------------------
+
+The following settings are per tenant:
+
+* default-rule-path
+* rule-files
+* classification-file
+* reference-config-file
+* threshold-file
+* address-vars
+* port-vars
+
+Unix Socket
+-----------
+
+Registration
+~~~~~~~~~~~~
+
+``register-tenant <id> <yaml>``
+
+Examples:
+
+::
+
+  register-tenant 1 tenant-1.yaml
+  register-tenant 2 tenant-2.yaml
+  register-tenant 3 tenant-3.yaml
+  register-tenant 5 tenant-5.yaml
+  register-tenant 7 tenant-7.yaml
+
+``unregister-tenant <id>``
+
+::
+
+  unregister-tenant 2
+  unregister-tenant 1
+
+Unix socket runmode (pcap processing)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Unix Socket ``pcap-file``  command is used to associate the tenant with
+the pcap:
+
+::
+
+  pcap-file traffic1.pcap /logs1/ 1
+  pcap-file traffic2.pcap /logs2/ 2
+  pcap-file traffic3.pcap /logs3/ 3
+  pcap-file traffic4.pcap /logs5/ 5
+  pcap-file traffic5.pcap /logs7/ 7
+
+This runs the traffic1.pcap against tenant 1 and it logs into /logs1/,
+traffic2.pcap against tenant 2 and logs to /logs2/ and so on.
+
+Live traffic mode
+~~~~~~~~~~~~~~~~~
+
+Multi-tenancy supports both VLAN and devices with live traffic.
+
+In the master configuration yaml file, specify ``device`` or ``vlan`` for the ``selector`` setting.
+
+Registration
+~~~~~~~~~~~~
+
+Tenants can be mapped to vlan ids.
+
+``register-tenant-handler <tenant id> vlan <vlan id>``
+
+::
+
+  register-tenant-handler 1 vlan 1000
+
+``unregister-tenant-handler <tenant id> vlan <vlan id>``
+
+::
+
+  unregister-tenant-handler 4 vlan 1111
+  unregister-tenant-handler 1 vlan 1000
+
+The registration of tenant and tenant handlers can be done on a
+running engine.
+
+Reloads
+~~~~~~~
+
+Reloading all tenants:
+
+``reload-tenants``
+
+::
+
+  reload-tenants
+
+Reloading a single tenant:
+
+``reload-tenant <tenant id> [yaml path]``
+
+::
+
+  reload-tenant 1 tenant-1.yaml
+  reload-tenant 5
+
+The ``[yaml path]`` is optional. If it isn't provided, the original path of
+the tenant will be used during the reload.
+
+Eve JSON output
+---------------
+
+When multi-tenant support is configured and the detect engine is active then
+all EVE-types that report based on flows will also report the corresponding
+``tenant_id`` for events matching a tenant configuration.