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.