suricata/doc/userguide/configuration/multi-tenant.rst

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.