diff options
Diffstat (limited to 'doc/userguide/configuration/multi-tenant.rst')
| -rw-r--r-- | doc/userguide/configuration/multi-tenant.rst | 249 |
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. |