Authentication OIDC Authentication VNS3 Licensing Access Management Clientpack Generation Installing HTTPS Firewall 2.0 Firewall AWS Specific features Firewall FWSets VNS3 Variables VNS3 Router IPsec Configuration IPsec Parameters VNS3 Peering Mesh Setting Topology Name VNS3 Overlay Network Snapshot Management VNS3 Event Alerting Network Address Translation Traffic inspection SNMP Support VNS3 BGP Configuration Guide Remote Support Resetting VNS3 Upgrading VNS3 Release Notes VNS3 EOL Policy and Milestones IPSec Connection Checklist VNS3 Known Issues VNS3 Specifications VNS3 VPN Client tools VNS3 Control Center VNS3 setup

Firewall 2.0

The VNS3 Firewall 2.0 was built from a decade of networking knowledge and aims to simplify your network policy and routing.

Definitions

Tables and Traffic Order

VNS3 has 5 system tables: PREROUTING, INPUT, FORWARD, OUTPUT and POSTROUTING. Traffic will move from table to table and through VNS3 matching against rules based on rule conditions and taking the defined rule action. A rule’s table and position determine when it will be matched against traffic.

There are three traffic paths: VNS3 Routing traffic, VNS3 terminating traffic and VNS3 originating traffic. These are defined as follows:

VNS3 Routing Traffic: This is traffic that originates outside of VNS3 and whose destination is outside VNS3. The table path is as follows:

1. PREROUTING
2. FORWARD
3. POSTROUTING

VNS3 Terminating Traffic: This is traffic that originates outside of VNS3 and whose destination is VNS3. The table path is as follows:

1. PREROUTING
2. INPUT

VNS3 Originating Traffic: This is traffic that originates in VNS3 and whose destination is outside VNS3. The table path is as follows:

1. OUTPUT
2. POSTROUTING

Rules

Rules comprise your VNS3 network policy. These rules determine which traffic goes where. Each rule has a table and position. A rule’s table and position determine when it will be matched against traffic. Rules are 0 indexed and ordered from least to greatest. This means the rule at position 0 will be matched first, then 1, then 2 etc. Rules can also be assigned to 1 or more groups or have comments for added explanation. Each rule is provided a unique id for targeting. Finally, rules can be in a state of either enabled or disabled.

Rule data resource:

• The original text of the rule (rule in the API)
• The resolved text of the rule and what is in use by the OS (rule_resolved in the API)
• An optional comment
• An optional list of groups the rule is in
• The table the rule is in
• The rule’s position in the root policy
• A unique id for the rule

Note You might be wondering why there is both a rule and a resolved rule. This is because the rule text is a simplified version of the rule and may be expanded for the OS or it may have variables defined in it that are resolved when the rule is created.

Adding a Rule

The VNS3 Console provides a easy way for constructing policy rules. From the Rules page, click Add Rule:

A rule is defined by 4 components:

1. A table in which the rule will be placed
2. A set of conditions (which can be empty) to match traffic with
3. An action such as ACCEPT or REJECT
4. A position where the default (-1) indicates the end of the root policy

From the new rule form you can search a few things about the system to more easily construct rules:

1. Variables - these are system variables and any user defined custom variables. They can be placed in rules which will be resolved at insertion time.
2. FWSets - these are the current VNS3 FWSets. They can be placed in conditions and are typically used as either a Source or Destination condition.
3. Subtables - these are the current VNS3 subtables that can be “jumped” to from rules in the rule action. e.g. -j ${subtable_MyGroup}

The form also provides some helpful hints on the right such as current interfaces or possible actions depending on the condition type or table.

Rule conditions

Rule conditions are how traffic is matched to rules. Here are some common conditions:

• Source (-s): This will match the source of the traffic. e.g. -s 10.0.0.0/24. You can also use fwset variables here for match entire fwset ranges. e.g. -s #{fwset_mynamedfwset}
• Destination (-d): This will match the destination of the traffic. e.g. -d 10.0.0.0/24. You can also use fwset variables here for match entire fwset ranges. e.g. -d #{fwset_mynamedfwset}
• Source port (–sport): This will match the source port of the traffic. e.g. --sport 4000
• Destination port (–dport): This will match the destination port of the traffic. e.g. --sport 443
• Incoming interface (-i): This will match traffic coming in on a certain interface. e.g. -i eth0
• Outgoing interface (-o): This will match traffic leaving on a certain interface. e.g. -o tun0
• Protocol (-p): This will match traffic of the provided protocol. e.g. -p udp

More to come

Rule actions

Rule actions define what to do with the traffic that matches the rule. Common actions are:

• ACCEPT: accept traffic. This will allow traffic to continue through firewall tables or potentially leave VNS3
• REJECT: reject traffic. This will prevent traffic, send a rejection response to the sender.
• DROP: drop traffic. This will silently drop traffic packets. This differents from reject as it does not inform the sender that their packets are being dropped.
• LOG: This will pass through traffic and log it to the server at /var/log/kern.log
• DNAT: This is only valid in prerouting table. This routes your traffic to a new destination. Specifically, this is changing the destination of the traffic.
• SNAT: This is only valid in postrouting table. This routes return traffic to a new destination. Specifically, this is changing the source of the traffic.
• COPY: Copy traffic to a This requires --to and --from arguments after the copy action: -j COPY --to 10.0.1.239 --from eth0

New rule expansions

The new firewall supports some useful “expansions”, making for nicer looking rules. Have a suggestion? Let us know. Current expansions:

Condition expansions

FWSet name expansion for source or destination

-s [FWset Name] => -m set --match-set [FWset Name] src

-d [FWset Name] => -m set --match-set [FWset Name] dst

Conntrack state

-ctrack [conn state, e.g. RELATED,ESTABLISHED] => -m conntrack --ctstate RELATED,ESTABLISHED

-state [states] => -m state --state [states]

Ping rules expansion - write 1 rule for multiple ping types. Default types are 0,3/4 and 8

-p ping (--icmp-type [0-9,]) => -p icmp (--icmp-type=0,3/4,8)

Action expansions

COPY for copying traffic from an interface to a destination

PREROUTING/POSTROUTING [conditions] -j COPY --from [interface] --to [address] => PREROUTING/POSTROUTING -i/-o [interface] [conditions] -j TEE --gateway [address]

MASQUERADE-ONCE will resolve the address of the interface specified and create a SNAT rule at creation time:

POSTROUTING [-o interface / conditions] -j MASQUERADE-ONCE ==> POSTROUTING [conditions] -j SNAT --to <fetched interface address>

LOOKUP will route traffic targeted by conditions to a specific route table. This is accomplished by three OS Rules. OS Rules are fetchable with the osview=true query param (GET api/v2/firewall/rules?osview=true).

PREROUTING/OUTPUT [conditions] -j LOOKUP --table [route table, e.g. plugin0] (--notrack) (--use-mark [number or hex between 4294901761 and 4294967295]])

This rule will expand to the following rules

• PREROUTING [conditions] -j NOTRACK will be added only with the --notrack flag
• PREROUTING -[conditions] -j MARK --set-mark <calculated mark or from use-mark>
• ip rule add from all fwmark <calculated mark or from use-mark> lookup [route table, e.g. plugin0]

Rule Groups

Rule Groups in the VNS3 Firewall serve as an organizational tool for network administrators, allowing easier and more effective categorization and management of firewall rules. Rule Groups are a logical construct, and have no effect on firewall behavior. They simply provide a means for grouping rules according to flows, functions, specific customers or connections, etc. This helps streamline the management of complex rule sets, making navigating and applying policies consistently across the network easier.

Import / Export

To import or export firewall root policy rules from the VNS3 Console, first click Advanced to expand the advanced options. Then click the Import/Export button.

Importing Rules

There are two methods for importing rules, by file import or text input. The file import supports both the json and text file type from the export.

Notes on import/export text file type parsing

This file type is similar to the old firewall input UI. This new input maps some file syntax into the rule data model:

1. The line number determines the position in the firewall.
2. Rules preceded by # are imported as disabled. A # line is determined to be a rule if it begins with one of the valid table names.
3. Lines preceded by # that are not rules are comments and will apply to the next valid rule in the list. Multiple lines of comments will be added to the next rule in the list.
4. If a comment contains the text groups=mygroupname,othergroup then the rule this comment applies to will be added to those groups

Exporting Rules

Rules can be exported as either JSON or Text. Note that exporting rules as a text file may lose some information about the rule. JSON file type is the preferred method.

API

The API provides the following endpoints for interacting with rules:

Rules collection: /api/v2/firewall/rules(?osview=true)

Supported methods

• GET for reading all rules. If osview=true, the Operation System rules be returned.
• POST for inserting a rule
• PUT for bulk overwrite of entire policy (careful!)

Rule resource: /api/v2/firewall/rules/:ruleid

Supported methods

• PUT for updating the state of the rule (enabled/disabled, comment or groups). You cannot edit the rule once created, you must delete and insert.
• DELETE for deleting rules

Rule resource: /api/v2/firewall/rules/export

Supported methods

• GET for downloading a JSON file or a text file that can be imported to another VNS3 controller

Rule resource: /api/v2/firewall/rules/import

Supported methods

• PUT for uploading a raw string of rules starting at a certain position

GET /api/v2/firewall/rules

{
    "response": [
        {
            "id": "87319bd7cf225e4",
            "rule": "PREROUTING -s 4.5.4.5/32 -j DNAT --to 3.3.3.3",
            "table": "prerouting",
            "rule_resolved": "PREROUTING -s 4.5.4.5/32 -j DNAT --to 3.3.3.3",
            "position": 0,
            "comment": "For routing traffic",
            "last_resolved": "2021-11-30T21:51:14.606Z",
            "disabled": false,
            "created_at": "2021-11-30T20:03:25.880Z",
            "groups": []
        },
        {
            "id": "622a549079e3279",
            "rule": "FORWARD_CUST -j ACCEPT",
            "table": "forward",
            "rule_resolved": "FORWARD_CUST -j ACCEPT",
            "position": 0,
            "comment": "heres a nice comment",
            "last_resolved": "2021-11-30T21:51:14.606Z",
            "disabled": false,
            "created_at": "2021-11-30T20:03:25.899Z",
            "groups": [
                "Bens test group"
            ]
        }
    ]
}

Sets

Firewall sets or FWSets are sets of objects such as IPs or ports that can be used for matching traffic to rules. These allow for faster traffic matching for your rules and provide an easy and efficient way to group people, machines or services. FWsets are unique by the name and cannot have spaces. You can also use variables in your FWSet entries. FWsets can optionally be sync’d to peered VNS3 controllers.

FWSet data resource:

• name - this is unique (case insensitive)
• description (optional)
• sync_mesh (optional, default false)
• a list of entries
  • entry
  • comment (optional)

Using in a rule

To use in a rule as either a source or destination, you may use it as a variable or as the fwset name directly:

Matching a set against source of traffic

INPUT -s ${fwset_myfwset} -j ACCEPT or INPUT -s name_of_fwset -j ACCEPT

Matching a set against destination of traffic

INPUT -d ${fwset_myfwset} -j ACCEPT or INPUT -d name_of_fwset -j ACCEPT

API

The API provides the following endpoints for interacting with fwsets:

FWsets collection: /api/v2/firewall/fwsets

Supported methods

• GET for reading all fwsets
• POST for creating new fwset

FWset resource: /api/v2/firewall/fwsets/:name(?osview=true)

Supported methods

• GET for reading fwset data and entries. OS view will return fwset entries returned from OS call.
• PUT for overwrite all entries or updating description (cannot edit name after creation)
• DELETE to delete entire fwset

FWset entries subcollection: /api/v2/firewall/fwsets/:name/entries

Supported methods

• POST for inserting
• DELETE to delete fwset entry. Expects JSON body: Payload: {"entry": "54.43.12.1"}

GET /api/v2/firewall/fwsets

{
    "response": [
        {
            "name": "App-Ports",
            "description": "",
            "created_at": "2021-11-30T20:03:25.845Z",
            "updated_at": "2021-11-30T20:03:25.845Z",
            "sync_mesh": false,
            "entries": [
                "6001",
                "7001"
            ],
            "size": 2,
            "type": "port"
        },
        {
            "name": "IP-Blacklist",
            "description": "A blacklist of known nefarious IPs",
            "created_at": "2021-12-01T22:35:47.103Z",
            "updated_at": "2021-12-01T22:35:47.103Z",
            "sync_mesh": true,
            "entries": [
                "174.120.121.4",
                "11.212.34.11",
                "54.43.12.1"
            ],
            "size": 3,
            "type": "net"
        }
    ]
}

Subtables

Subtables are custom tables of rules that can be directed to from rules in the VNS3 Root Policy. These are a more advanced feature of the VNS3 firewall. They are use when the Root VNS3 policy has lots of rules. Subtables can be used to improve the performance and organization of the root policy. That is the root policy can be reduced to fewer rules that route traffic to the subtable based on certain matching conditions. This improves performance by reducing the number of rules that are tried for matches against each packet.

Subtable data resource:

• name - this is unique (case insensitive)
• type this corresponds to a valid system table (prerouting, input, forward, output or postrouting) and determines the type of rules that can route traffic to this subtable.
• description (optional)
• a list of rules these have the same data as root rules except they cannot be associated with groups
  • rule (can include variables)
  • rule_resolved
  • disabled (true or false)
  • comment
  • position

Using in a rule

To direct traffic to your subtable you will “jump” to it from a rule in the VNS3 Root policy. That is, you will specify the name of the subtable in the action of the rule: PREROUTING -s 10.100.0.0/32 -j MYGROUP

Note The type of your subtable must correspond to table you are jumping from. For instance, in the above example, MYGROUP should be of the type prerouting.

API

The API provides the following endpoints for interacting with subtables:

Subtables collection: /api/v2/firewall/subtables

Supported methods

• GET for reading all subtables
• POST for creating new subtable

Subtable resource: /api/v2/firewall/subtables/:name(?osview=true)

Supported methods

• GET for reading subtable data and rules. OS View will return the active OS rules for each subtable rule.
• PUT for overwrite all rules or updating description (cannot edit name or type after creation)
• DELETE to delete entire subtable

Subtables rules subcollection: /api/v2/firewall/subtables/:name/rules

Supported methods

• POST for inserting new rule

Delete Subtables rule: /api/v2/firewall/subtables/:name/rules/:id

Supported methods

• DELETE to delete rule by id

GET /api/v2/firewall/subtables

{
    "response": [
        {
            "name": "MySubtable",
            "description": "Heres my description",
            "created_at": "2021-11-30T20:03:25.820Z",
            "updated_at": "2021-11-30T20:03:25.820Z",
            "rules": [
                {
                    "rule": "MySubtable -s 1.1.1.1 -d 2.2.2.2 -j DNAT --to 8.8.8.8",
                    "position": 0,
                    "comment": "",
                    "rule_resolved": "MySubtable -s 1.1.1.1 -d 2.2.2.2 -j DNAT --to 8.8.8.8",
                    "disabled": false,
                    "id": "ad3f114aa0bea55"
                }
            ],
            "type": "prerouting",
            "size": 1
        }
    ]
}

VNS3 Variables

The new firewall has added a concept of variables to VNS3. These can now be used in firewall rules, fwset entries and subtable rules for more easily building your policies. VNS3 provides system variables that are defined as a function of the state of the VNS3 server. You can also define custom variables for use in the firewall.

See the variables documentation page for more.

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

Upgrading to new Firewall

You can import a snapshot into a VNS3 Firewallv2 version (starting with X.Y.Z) and it will map your rules, fwsets and subtables (previously called subgroups) into the new data model. The previous version of the firewall was treated as a single file which could have comments (lines starting with #). Some things to note:

• Commented out rules such as # FORWARD_CUST -s 10.0.0.0/64 -j DROP will be created as disabled rules
• Comments that are not rules will be created as comments for the next valid rule line in your firewall file
• Consecutive non-rule comments will be concatenated and created as a comment for the next valid rule line in your firewall file
• Important You can view the old state of your firewall data by going to https://[vns3 host]:8000/firewall/old

Viewing old firewall files

The previous versions of the firewall stored firewall rules, fwsets and subtables (previously subgroups) were edited as “flat files” and can be reviewed as such by going to https://your-vns3-controller:8000/firewall/old.