VNS3 Variables
VNS3 Variables can be used in defining firewall rules, fwsets and subtables for more easily building your policies. VNS3 maintains a list of system variables which are defined as a function of the state of VNS3’s configuration. You can also define custom variables for use in VNS3.
Defining a custom variable
- Click on the Variables button from any of the Firewall pages
- To the top of the popup is a form New Custom Variable
- Enter your variable name and variable value and if this is a sync’d variable and click Save
A Note on variable naming conventions
Variables have specific, predictable names. The GET response is grouped by “collection”. The variable collections are:
- controller: VNS3 config and global state variables
- plugin_instances: IP addresses of your running plugin instances
- peering: peer names (dns or IP)
- clientpacks: Clientpack IPs
- clientpack_groups: These are groups of clientpack IPs defined by key, value tag pairs. e.g. all clientpacks with tag type=person
- fwsets: Names of fwsets
- subtables: Names of subtables
- custom: User defined variables
Using in a rule
Variables in rules should be used referenced as ${variable_name}. These will be expanded when the rule is enabled.
Some examples:
INPUT_CUST -d ${vns3_overlay_subnet} -j ACCEPT
PREROUTING -s ${fwset_blacklist} -j DROP
Variable Sync
Custom variables can be sync’d to other peered VNS3 controllers by checking the “Sync” box when saving a variable (VNS3 6.2). Here are a few notes on behavior:
- Creating a sync’d variable will send the variable to peers. This will overwrite any value by the same name on peered controllers. The syncing occurs over the peering connection and will take a few seconds.
- Desyncing a variable (unchecking “Mesh Sync”) will delete the variable on peers but not on the VNS3 controller on which the desync is saved.
- Deleting a sync’d variable will delete the variable on all VNS3 controllers in the mesh, including the local VNS3 controller from which the variable is deleted.
API
The API provides the following endpoints for interacting with variables:
Subtables collection: /api/system/variables
Supported methods
- GET for reading all variables. Example response provided below.
- POST for creating new variable. Payload is
{"name": "myhouse", "value": "64.12.53.12", "description": "IPaddress for my house", "sync": true/false} - DELETE for deleting a variable by name. Payload is
{"name": "myhouse"}
GET /api/system/variables
{
"response": {
"controller": [
{
"variable": "vns3_primary_private_ip",
"value": "10.0.1.224"
},
{
"variable": "vns3_overlay_subnet",
"value": "203.0.113.0/27",
"description": "Subnet used for clientpack and peer IP's"
},
{
"variable": "vns3_plugin_network",
"value": "198.51.100.0/28",
"description": "Plugin network subnet"
},
{
"variable": "vns3_public_ip",
"value": "54.174.246.212"
},
{
"variable": "vns3_subnet_gateway",
"value": "10.0.1.193",
"description": "Local subnet gateway for vlan"
}
],
"plugin_instances": [],
"peering": [
{
"variable": "peer_1_overlay_ip",
"value": "203.0.113.1"
},
{
"variable": "peer_2_overlay_ip",
"value": "203.0.113.2"
}
],
"ipsec": [
{
"variable": "ipsec_local_ip",
"value": "192.0.2.254",
"description": "IP used for Ipsec endpoint termination (on eth0)"
},
{
"variable": "ipsec_endpoint_3_ip",
"value": "198.2.5.2",
"description": "Ipsec endpoint [name=myendpoint] IP address"
},
{
"variable": "ipsec_endpoint_3_tunnel_17_local_subnet",
"value": "159.172.197.0/24"
},
{
"variable": "ipsec_endpoint_3_tunnel_17_remote_subnet",
"value": "10.0.0.0/8"
}
],
"clientpacks": [
{
"variable": "clientpack_203_0_113_10_ip",
"value": "203.0.113.10",
"description": "IP for clientpack 203_0_113_10"
},
{
"variable": "clientpack_203_0_113_11_ip",
"value": "203.0.113.11",
"description": "IP for clientpack 203_0_113_11"
}
],
"groups": [],
"fwsets": [
{
"variable": "fwset_bensports",
"value": "BensPorts",
"description": "FWset PORTS_ben ipset name"
},
{
"variable": "fwset_ipblacklist",
"value": "IPBlacklist",
"description": "FWset IPBlacklist ipset name"
}
],
"subtables": [
{
"variable": "subtable_mygroup",
"value": "MyGroup",
"description": "Subtable MyGroup name"
},
{
"variable": "subtable_mygroup",
"value": "MyGroup",
"description": "Subtable MyGroup name"
}
],
"custom": [
{
"variable": "custom_myhouse",
"value": "64.34.12.10",
"description": ""
}
]
}
}