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

config/mt: Add vlan-pair MT selector #9729

Closed
wants to merge 2 commits into from
Closed

config/mt: Add vlan-pair MT selector #9729

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
8b3642d
doc/mt: Document vlan-pair selector
jlucovsky Aug 4, 2023
599ece5
detect/mt: Add support for vlan-pair 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
80 changes: 73 additions & 7 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-pair 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 @@ -29,13 +29,14 @@ Settings:
* `mappings`:

* VLAN id or device: The outermost VLAN is used to match.
* VLAN inner id: Required with the selector ``vlan-pair``; both VLAN values are used to match.
* tenant id: tenant to associate with the VLAN id or device

::

multi-detect:
enabled: yes
#selector: direct # direct or vlan
#selector: direct # direct or vlan, vlan-pair
selector: vlan
loaders: 3

Expand All @@ -55,6 +56,36 @@ Settings:
- vlan-id: 1112
tenant-id: 3


This example uses the VLAN pair selector:

::

multi-detect:
enabled: yes
selector: vlan-pair
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
Copy link
Member

Choose a reason for hiding this comment

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

wondering if it would be better to have a new vlan-id-pair name here, with a value of an array? Or something like "qinq": [ 1000, 1 ]

Copy link
Member

Choose a reason for hiding this comment

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

How long til we'll need qinqinqinqinqinqinq? I like the qinq name here where the value is an array. Limited to 2 for now perhaps, but could grow.

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 like both ideas and I suggest vlan-id-tuple: [1000, 1] along with changing the selector name from vlan-pair to vlan-tuple

Copy link
Member

Choose a reason for hiding this comment

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

It would be nice if the selector value, and the name of the field for that select could be the same, however we don't have that for vlan and vlan-id now. If vlan-tuple it could be nice to have:

selector: vlan-tuple
mappings:
- vlan-tuple: [..]

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 like that suggestion @jasonish -- will do.

vlan-id-inner: 1
tenant-id: 1
- vlan-id: 2000
vlan-id-inner: 1
tenant-id: 2
- vlan-id: 1112
vlan-id-inner: 1
tenant-id: 3


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

Expand Down Expand Up @@ -97,17 +128,43 @@ 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-pair`` 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-pair`` selector.

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.

vlan-id-inner
~~~~~~~~~~~~~

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

Example of VLAN mapping::

mappings:
- vlan-id: 1000
vlan-id-inner: 0
tenant-id: 1
- vlan-id: 2000
vlan-id-inner: 3000
tenant-id: 2
- vlan-id: 1112
vlan-id-inner: 3112
tenant-id: 3

The mappings can also be modified over the unix socket, see below.
Expand Down Expand Up @@ -195,25 +252,34 @@ 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-pair`` for the ``selector`` setting.

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

Tenants can be mapped to vlan ids.

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

register-tenant-handler <tenant id> vlan <vlan id>
register-tenant-handler <tenant id> vlan-pair <vlan id>
Copy link
Member

Choose a reason for hiding this comment

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

I find it confusing that we speak of pair but have a singular value

Copy link
Member

Choose a reason for hiding this comment

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

also think it would be best to not mix these with the simple vlan examples, but have it separately

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Thanks for the catch. Actually, it's register-tenant-handler <tenant id> vlan-pair <vlan id> <vlan inner id>

I'll separate the examples so it's clearer.


::

register-tenant-handler 1 vlan 1000
register-tenant-handler 1 vlan-pair 1000

::

``unregister-tenant-handler <tenant id> vlan <vlan id>``
unregister-tenant-handler <tenant id> vlan <vlan id>
unregister-tenant-handler <tenant id> vlan-pair <vlan id>

::

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

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