Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

config/mt: Add vlan-tuple MT selector #9747

Closed
wants to merge 2 commits into from
Closed

config/mt: Add vlan-tuple MT selector #9747

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e96db4f
doc/mt: Document vlan-tuple selector
jlucovsky Aug 4, 2023
54a8b2d
detect/mt: Add support for vlan-tuple selector
jlucovsky Aug 4, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 100 additions & 8 deletions doc/userguide/configuration/multi-tenant.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Add a new section in the main ("master") Suricata configuration file -- ``surica
Settings:

* `enabled`: yes/no -> is multi-tenancy support enabled
* `selector`: direct (for unix socket pcap processing, see below), VLAN or device
* `selector`: direct (for unix socket pcap processing, see below), vlan, vlan-tuple 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
Expand All @@ -27,15 +27,30 @@ Settings:
* yaml: separate yaml file with the tenant specific settings

* `mappings`:
* tenant id: tenant to associate with the VLAN id or device

Tenant mappings depend on the type of selector used:

* `vlan` or `device`
jlucovsky marked this conversation as resolved.
Show resolved Hide resolved

* VLAN id or device: The outermost VLAN is used to match.
* tenant id: tenant to associate with the VLAN id or device
jlucovsky marked this conversation as resolved.
Show resolved Hide resolved

* `vlan-tuple`

* VLAN tuple: Specify the VLAN identifiers -- outermost to innermost, e.g., `[3000, 1]` will match when the
outermost VLAN id is 3000 and the innermost VLAN id is 1. The special value of `0` means "any VLAN in that position" will match.
Note that there must the same number of layers of VLAN encapsulation as there are values in the tuple.


* `[0, 302]` will match any packet with an innermost VLAN id of `302` on packets that are QinQ..
* `[3000, 0]` will match any packet with an outermost VLAN id of `3000` on packets that are QinQ..
* `[3000, 1000, 40]` will match any packet with 3-VLAN identifiers of outermost `3000`, middle `1000` and innermost `40`.

::

multi-detect:
enabled: yes
#selector: direct # direct or vlan
#selector: direct # direct or vlan, vlan-tuple
jlucovsky marked this conversation as resolved.
Show resolved Hide resolved
selector: vlan
loaders: 3

Expand All @@ -55,6 +70,33 @@ Settings:
- vlan-id: 1112
tenant-id: 3


This example uses the VLAN tuple selector for packets encapsulated with two VLAN ids:

::

multi-detect:
enabled: yes
selector: vlan-tuple
loaders: 3

tenants:
- id: 1
yaml: tenant-1.yaml
- id: 2
yaml: tenant-2.yaml
- id: 3
yaml: tenant-3.yaml
Comment on lines +74 to +89
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This part is a bit confusing to me, maybe because of the example only actually having the id word for the tenant ids...

Maybe if we add a generic format to the VLAN-tuple [outtermost-id, middle-id, innermost-id] this could help remove ambiguity when reading this example?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that using id in the tenants section and tenant-id in the mappings section is a bit confusing.

I can change this but am concerned about support for existing multi-tenant configurations.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm.. Maybe just some addition to the documentation, to highlight /dismiss the confusion?


mappings:
- vlan-tuple: [1000, 1]
tenant-id: 1
- vlan-tuple: [2000, 1]
tenant-id: 2
- vlan-tuple: [1112, 1]
tenant-id: 3


The tenant-1.yaml, tenant-2.yaml, tenant-3.yaml each contain a partial
configuration:

Expand Down Expand Up @@ -97,8 +139,11 @@ configuration:
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.
Assign tenants to VLAN ids. Suricata matches the outermost VLAN id with this value with
the selector ``vlan`` (default); the selector ``vlan-tuple`` should be used if QinQ is deployed and requires both
the inner and outer VLAN id values to match to determine the tenant.
Multiple VLANs can have the same tenant id. VLAN id values must be between 1 and 4094 with the ``vlan`` selector.
A wildcard value of ``00`` can be used with the ``vlan-tuple`` selector.

Example of VLAN mapping::

Expand All @@ -114,6 +159,26 @@ The mappings can also be modified over the unix socket, see below.

Note: can only be used if ``vlan.use-for-tracking`` is enabled.

vlan-tuple
~~~~~~~~~~

The ``vlan-tuple`` tag can only used with the ``vlan-tuple`` selector. The value will be used
to match with the innermost VLAN. Values of ``0`` will match any VLAN value.

Example of VLAN mapping::

mappings:
- vlan-tuple: [1000, 0]
tenant-id: 1
- vlan-tuple: [2000, 3000]
tenant-id: 2
- vlan-tuple: [1112, 3112]
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.
jlucovsky marked this conversation as resolved.
Show resolved Hide resolved

device
~~~~~~

Expand Down Expand Up @@ -195,26 +260,53 @@ 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.
In the master configuration yaml file, specify ``device``, ``vlan`` or ``vlan-tuple`` for the ``selector`` setting.

Registration
~~~~~~~~~~~~

Tenants can be mapped to vlan ids.

``register-tenant-handler <tenant id> vlan <vlan id>``

Examples using the ``vlan`` selector:

::

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 <tenant id> vlan <vlan id>

::

unregister-tenant-handler 4 vlan 1111
unregister-tenant-handler 1 vlan 1000


Examples using the ``vlan-tuple`` selector:

::

register-tenant-handler <tenant id> vlan-tuple <vlan outer id> <vlan inner id>
jlucovsky marked this conversation as resolved.
Show resolved Hide resolved

::

register-tenant-handler 1 vlan-tuple 1000

::

unregister-tenant-handler <tenant id> vlan-tuple <vlan outer id> <vlan inner id>

::

unregister-tenant-handler 4 vlan-tuple 1111 1
unregister-tenant-handler 1 vlan-tuple 1000 2

The registration of tenant and tenant handlers can be done on a
running engine.

Expand Down
10 changes: 10 additions & 0 deletions python/suricata/sc/specs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,11 @@
"type": int,
"required": 0,
},
{
"name": "hargs_extra",
"type": int,
"required": 0,
},
],
"register-tenant-handler": [
{
Expand All @@ -89,6 +94,11 @@
"type": int,
"required": 0,
},
{
"name": "hargs_extra",
"type": int,
"required": 0,
},
],
"unregister-tenant": [
{
Expand Down
Loading
Loading