11.5. Multi Tenancy

11.5.1. Introduction

Multi tenancy support allows for different rule sets with different rule vars. These tenants can then be assigned to VLANs or interfaces (devices).

11.5.2. YAML

In the main ("master") YAML, the suricata.yaml, a new section called "multi-detect" should be added.

Settings:

enabled: yes/no -> is multi-tenancy support enable
default: yes/no -> is the normal detect config a default 'fall back' tenant?
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
- id: tenant id
- yaml: separate yaml file with the tenant specific settings
mappings:
- vlan id or device
- tenant id: tenant to associate with the vlan id / 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"

    ...

11.5.2.1. vlanid

Assign tenants to vlan id's.

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.

11.5.2.2. device

Assign tenants to devices. A single tenant can be assigned to a device. Multiple devices can have the same tenant.

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.

11.5.3. 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

11.5.4. Unix Socket

11.5.4.1. 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

11.5.4.2. Unix socket runmode (pcap processing)

The Unix Socket "pcap-file" command can be used to select the tenant to inspect the pcap against:

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.

11.5.4.3. Live traffic mode

For live traffic currently only a vlan based multi-tenancy is supported.

The master yaml needs to have the selector set to "vlan".

11.5.4.4. Registration

Tenants can be mapped to vlan id's.

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.