12.5. Multi Tenancy

12.5.1. 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").

12.5.2. 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"

    ...

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

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

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

12.5.4. Unix Socket

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

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

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

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

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

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