Subnet division rules
The subnet division rule is a feature introduced in OpenWISP 22.05 in the Controller module, this feature aims at making it easy to provision an arbitrary number of subnets and IP addresses to each device, these provisioned subnets and addresses are then added to the configuration variables (as system defined variables) of the device and can be used in its configuration or even in configuration templates.
Enabling the subnet division rule app
If you are using the official
OpenWISP ansible role,
this feature is not enabled by default,
to enable it just set the
configuration variable to
true in your playbook.
On docker-openwisp2 this feature is enabled by default.
Configuring the automatic provisioning of subnets and IPs
This guide will help you configure automatic provisioning of subnets and IPs for devices.
1. Create a Subnet and a Subnet Division Rule
Create a master subnet under which automatically generated subnets will be provisioned.
Note: Choose the size of the subnet appropriately considering your use case.
On the same page, add a subnet division rule that will be used to provision subnets under the master subnet.
The type of subnet division rule controls when subnets and IP addresses will be provisioned for a device.
The subnet division rule types currently implemented are described below.
Device Subnet Division Rule
This rule type is triggered whenever a device
config.Config model) is created for
the organization specified in the rule.
Creating a new rule of “Device” type will also provision subnets and IP addresses for existing devices of the organization automatically.
Note: a device without a configuration will not trigger this rule.
VPN Subnet Division Rule
This rule is triggered when a VPN client template is assigned to a device, provided the VPN server to which the VPN client template relates to has the same subnet for which the subnet division rule is created.
Note: This rule will only work for WireGuard and VXLAN over WireGuard VPN servers.
In this example, VPN subnet division rule is used.
2. Create a VPN Server
Now create a VPN Server and choose the previously created master subnet as the subnet for this VPN Server.
3. Create a VPN Client Template
Create a template, setting the Type field to VPN Client and VPN field to use the previously created VPN Server.
Note: You can also check the Enable by default field if you want to automatically apply this template to devices that will register in future.
4. Apply VPN Client Template to Devices
With everything in place, you can now apply the VPN Client Template to devices.
After saving the device, you should see all provisioned Subnets and IPs for this device under System Defined Variables.
Voila! You can now use these variables in configuration of the device. Refer to How to use configuration variables section of this documentation to learn how to use configuration variables.
Important notes for using Subnet Division
In the above example Subnet, VPN Server, and VPN Client Template belonged to the default organization. You can use Systemwide Shared Subnet, VPN Server, or VPN Client Template too, but Subnet Division Rule will be always related to an organization. The Subnet Division Rule will only be triggered when such VPN Client Template will be applied to a Device having the same organization as Subnet Division Rule.
You can also use the configuration variables for provisioned subnets and IPs in the Template. Each variable will be resolved differently for different devices. E.g.
OW_subnet1_ip1will resolve to
10.0.0.1for one device and
10.0.0.55for another. Every device gets its own set of subnets and IPs. But don’t forget to provide the default fall back values in the “default values” template field (used mainly for validation).
The Subnet Division Rule will automatically create a reserved subnet, this subnet can be used to provision any IP addresses that have to be created manually. The rest of the master subnet address space must not be interfered with or the automation implemented in this module will not work.
The above example used VPN subnet division rule. Similarly, device subnet division rule can be used, which only requires creating a subnet and a subnet division rule.
Limitations of Subnet Division
In the current implementation, it is not possible to change “Size”, “Number of Subnets” and “Number of IPs” fields of an existing subnet division rule due to following reasons:
Allowing to change size of provisioned subnets of an existing subnet division rule will require rebuilding of Subnets and IP addresses which has possibility of breaking existing configurations.
Number of Subnets
Allowing to decrease number of subnets of an existing subnet division rule can create patches of unused subnets dispersed everywhere in the master subnet. Allowing to increase number of subnets will break the continuous allocation of subnets for every device. It can also break configuration of devices.
Number of IPs
Allowing to decrease number of IPs of an existing subnet division rule will lead to deletion of IP Addresses which can break configuration of devices being used. It is allowed to increase number of IPs.
If you want to make changes to any of above fields, delete the existing rule and create a new one. The automation will provision for all existing devices that meets the criteria for provisioning. WARNING: It is possible that devices get different subnets and IPs from previous provisioning.