vpn.conf : Configuration variables Settings are modified in vpn.conf. Multiple entries can be entered for each setting by separating the entries with spaces. Click here to see all the settings. FORCED_SOURCE_INTERFACE Force all traffic coming from a source interface through the VPN. Default LAN is br0, and other LANs are brX, where X = VLAN number. Format: [INTERFACE NAME] Example: FORCED_SOURCE_INTERFACE="br6 br8" FORCED_SOURCE_IPV4 Force all traffic coming from a source IPv4 through the VPN. IP can be entered in CIDR format to cover a whole subnet. Format: [IP/nn] Example: FORCED_SOURCE_IPV4="192.168.1.1/32 192.168.3.0/24" FORCED_SOURCE_IPV6 Force all traffic coming from a source IPv6 through the VPN. IP can be entered in CIDR format to cover a whole subnet. Format: [IP/nn] Example: FORCED_SOURCE_IPV6="fd00::2/128 2001:1111:2222:3333::/56" FORCED_SOURCE_MAC Force all traffic coming from a source MAC through the VPN. Format: [MAC] Example: FORCED_SOURCE_MAC="00:aa:bb:cc:dd:ee 30:08:d7:aa:bb:cc" FORCED_DESTINATIONS_IPV4 Force IPv4 destinations to the VPN for all VPN-forced clients. Format: [IP/nn] Example: FORCED_DESTINATIONS_IPV4="1.1.1.1" FORCED_DESTINATIONS_IPV6 Force IPv6 destinations to the VPN for all VPN-forced clients. Format: [IP/nn] Example: FORCED_DESTINATIONS_IPV6="2001:1111:2222:3333::2" FORCED_LOCAL_INTERFACE Force local UDM traffic going out of these interfaces to go through the VPN instead, for both IPv4 and IPv6 traffic. This does not include routed traffic, only local traffic generated by the UDM. For UDM-Pro, set to "eth8" for WAN1/Ethernet port, or "eth9" for WAN2/SFP+ port, or "eth8 eth9" for both. For UDM Base, set to "eth1" for the WAN port. Format: [INTERFACE NAME] Example: FORCED_LOCAL_INTERFACE="eth8 eth9" EXEMPT_SOURCE_IPV4 Exempt IPv4 sources from the VPN. This allows you to create exceptions to the force rules above. For example, if you forced a whole interface with FORCED_SOURCE_INTERFACE, you can selectively choose clients from that VLAN to exclude. Format: [IP/nn] Example: EXEMPT_SOURCE_IPV4="192.168.1.2/32 192.168.3.8/32" EXEMPT_SOURCE_IPV6 Exempt IPv6 sources from the VPN. This allows you to create exceptions to the force rules above. Format: [IP/nn] Example: EXEMPT_SOURCE_IPV6="2001:1111:2222:3333::2 2001:1111:2222:3333::10" EXEMPT_SOURCE_MAC Exempt MAC sources from the VPN. This allows you to create exceptions to the force rules above. Format: [MAC] Example: EXEMPT_SOURCE_MAC="00:aa:bb:cc:dd:ee 30:08:d7:aa:bb:cc" EXEMPT_SOURCE_IPV4_PORT Exempt an IPv4:Port source from the VPN. This allows you to create exceptions on a port basis, so you can selectively choose which services on a client to tunnel through the VPN and which to tunnel through the default LAN/WAN. For example, you can tunnel all traffic through the VPN for some client, but have port 22 still be accessible over the LAN/WAN so you can SSH to it normally. A single entry can have up to 15 multiple ports by separating the ports with commas. Ranges of ports can be defined with a colon like 5000:6000, and take up two ports in the entry. Protocol can be tcp, udp or both. Format: [tcp/udp/both]-[IP Source]-[port1,port2:port3,port4,...] Example: EXEMPT_SOURCE_IPV4_PORT="tcp-192.168.1.1-22,32400,80:90,443 both-192.168.1.3-53" EXEMPT_SOURCE_IPV6_PORT Exempt an IPv6:Port source from the VPN. This allows you to create exceptions on a port basis, so you can selectively choose which services on a client to tunnel through the VPN and which to tunnel through the default LAN/WAN. A single entry can have up to 15 multiple ports by separating the ports with commas. Ranges of ports can be defined with a colon like 5000:6000, and take up two ports in the entry. Protocol can be tcp, udp or both. Format: [tcp/udp/both]-[IP Source]-[port1,port2:port3,port4,...] Example: EXEMPT_SOURCE_IPV6_PORT="tcp-fd00::69-22,32400,80:90,443 both-fd00::2-53" EXEMPT_SOURCE_MAC_PORT Exempt a MAC:Port source from the VPN. This allows you to create exceptions on a port basis, so you can selectively choose which services on a client to tunnel through the VPN and which to tunnel through the default LAN/WAN. A single entry can have up to 15 multiple ports by separating the ports with commas. Ranges of ports can be defined with a colon like 5000:6000, and take up two ports in the entry. Protocol can be tcp, udp or both. Format: [tcp/udp/both]-[MAC Source]-[port1,port2:port3,port4,...] Example: EXEMPT_SOURCE_MAC_PORT="both-30:08:d7:aa:bb:cc-22,32400,80:90,443" EXEMPT_DESTINATIONS_IPV4 Exempt IPv4 destinations from the VPN for all VPN-forced clients. Format: [IP/nn] Example: EXEMPT_DESTINATIONS_IPV4="192.168.1.0/24 10.0.5.3/32" EXEMPT_DESTINATIONS_IPV6 Exempt IPv6 destinations from the VPN for all VPN-forced clients. Format: [IP/nn] Example: EXEMPT_DESTINATIONS_IPV6="fd62:1200:1300:1400::2/32 2001:1111:2222:3333::/56" FORCED_IPSETS Force these IP sets through the VPN. IP sets need to be created before this script is run or the script will error. IP sets can be updated externally and will be matched dynamically. Each IP set entry consists of the IP set name and whether to match on source or destination for each field in the IP set. Note: These IP sets will be forced for every VPN-forced client. If you want to force different IP sets for different clients, use `CUSTOM_FORCED_RULES_IPV4` and `CUSTOM_FORCED_RULES_IPV6` below. src/dst needs to be specified for each IP set field. Format: Format: [IPSet Name]:[src/dst,src/dst,...] Example: FORCED_IPSETS="VPN_FORCED:dst IPSET_NAME:src,dst" EXEMPT_IPSETS Exempt these IP sets from the VPN. IP sets need to be created before this script is run or the script will error. IP sets can be updated externally and will be matched dynamically. Each IP set entry consists of the IP set name and whether to match on source or destination for each field in the IP set. Enable NAT hairpin by exempting UBIOS_ADDRv4_ethX:dst for IPv4 or UBIOS_ADDRv6_ethX:dst for IPv6 (where X = 8 for RJ45, or 9 for SFP+ WAN). For IPv6 prefix delegation, exempt UBIOS_ADDRv6_brX, where X = VLAN number (0 = LAN). To allow communication with your VLAN subnets without hardcoding the subnets, exempt the UBIOS_NETv4_brX:dst ipset for IPv4 or UBIOS_NETv6_brX:dst for IPv6. Note: These IP sets will be exempt for every VPN-forced client. If you want to exempt different IP sets for different clients, use `CUSTOM_EXEMPT_RULES_IPV4` and `CUSTOM_EXEMPT_RULES_IPV6` below. src/dst needs to be specified for each IP set field. Format: Format: [IPSet Name]:[src/dst,src/dst,...] Example: EXEMPT_IPSETS="VPN_EXEMPT:dst IPSET_NAME:src,dst" EXEMPT_IPSETS="UBIOS_ADDRv4_eth8:dst UBIOS_ADDRv6_br0:dst UBIOS_NETv4_br0:dst UBIOS_NETv4_br5:dst" CUSTOM_FORCED_RULES_IPV4 Custom IPv4 rules that will be forced to the VPN. The format of these rules is the matching portion of the iptables command, without the table, chain, and jump target. Multiple rules can be added on separate lines. These rules are added to the mangle table and the PREROUTING chain. Opening and closing quotation marks must not be removed if using multiple lines. Format: Format: [Matching portion of iptables command] Example: CUSTOM_FORCED_RULES_IPV4=" -s 192.168.1.6 -p tcp -s 192.168.1.10 --dport 443 -m set --match-set VPN_FORCED dst -i br6 " CUSTOM_FORCED_RULES_IPV6 Custom IPv6 rules that will be forced to the VPN. The format of these rules is the matching portion of the iptables command, without the table, chain, and jump target. Multiple rules can be added on separate lines. These rules are added to the mangle table and the PREROUTING chain. Opening and closing quotation marks must not be removed if using multiple lines. Format: Format: [Matching portion of iptables command] Example: CUSTOM_FORCED_RULES_IPV6=" -s fd62:1200:1300:1400::2/32 -p tcp -s fd62:1200:1300:1400::10 --dport 443 -m set --match-set VPN_FORCED dst -i br6 " CUSTOM_EXEMPT_RULES_IPV4 Custom IPv4 rules that will be exempt from the VPN. The format of these rules is the matching portion of the iptables command, without the table, chain, and jump target. Multiple rules can be added on separate lines. These rules are added to the mangle table and the PREROUTING chain. Opening and closing quotation marks must not be removed if using multiple lines. Format: Format: [Matching portion of iptables command] Example: CUSTOM_EXEMPT_RULES_IPV4=" -s 192.168.1.6 -p tcp -s 192.168.1.10 --dport 443 -m set --match-set VPN_EXEMPT dst -i br6 " CUSTOM_EXEMPT_RULES_IPV6 Custom IPv6 rules that will be exempt from the VPN. The format of these rules is the matching portion of the iptables command, without the table, chain, and jump target. Multiple rules can be added on separate lines. These rules are added to the mangle table and the PREROUTING chain. Opening and closing quotation marks must not be removed if using multiple lines. Format: Format: [Matching portion of iptables command] Example: CUSTOM_EXEMPT_RULES_IPV6=" -s fd62:1200:1300:1400::2/32 -p tcp -s fd62:1200:1300:1400::10 --dport 443 -m set --match-set VPN_EXEMPT dst -i br6 " PORT_FORWARDS_IPV4 Forward ports on the VPN side to a local IPv4:port. Not all VPN providers support port forwards. The ports are usually given to you on the provider's portal. Only one port per entry. Protocol can be tcp, udp or both. Format: [tcp/udp/both]-[VPN Port]-[Forward IP]-[Forward Port] Example: PORT_FORWARDS_IPV4="tcp-21674-192.168.1.1-50001 tcp-31683-192.168.1.1-22" PORT_FORWARDS_IPV6 Forward ports on the VPN side to a local IPv6:port. Not all VPN providers support port forwards. The ports are usually given to you on the provider's portal. Only one port per entry. Protocol can be tcp, udp or both. Format: [tcp/udp/both]-[VPN Port]-[Forward IP]-[Forward Port] Example: PORT_FORWARDS_IPV6="tcp-21674-2001:aaa:bbbb:2acc::69-50001 tcp-31456-2001:aaa:bbbb:2acc::70-443" DNS_IPV4_IP, DNS_IPV4_PORT Redirect DNS IPv4 traffic of VPN-forced clients to this IP and port. If set to "DHCP", the DNS will try to be obtained from the DHCP options that the VPN server sends. DHCP option is only supported for OpenVPN or OpenConnect. If set to "REJECT", DNS requests over IPv6 will be blocked instead. Note that many VPN providers redirect all DNS traffic to their servers, so redirection to other IPs might not work on all providers. DNS redirects to a local address, or rejecting DNS traffic works for all providers. Make sure to set DNS_IPV4_INTERFACE if redirecting to a local DNS address. Format: [IP] or "DHCP" or "REJECT" Example: DNS_IPV4_IP="1.1.1.1" Example: DNS_IPV4_IP="DHCP" Example: DNS_IPV4_IP="REJECT" Example: DNS_IPV4_PORT=53 DNS_IPV4_INTERFACE Set this to the interface (brX) the IPv4 DNS is on if it is a local IP. Leave blank for non-local DNS. Local DNS redirects will not work without specifying the interface. Format: [brX] Example: DNS_IPV4_INTERFACE="br0" DNS_IPV6_IP, DNS_IPV6_PORT Redirect DNS IPv6 traffic of VPN-forced clients to this IP and port. If set to "DHCP", the DNS will try to be obtained from the DHCP options that the VPN server sends. DHCP option is only supported for OpenConnect. If set to "REJECT", DNS requests over IPv6 will be blocked instead. The REJECT option is recommended to be enabled for VPN providers that don't support IPv6, to eliminate any IPv6 DNS leaks. Note that many VPN providers redirect all DNS traffic to their servers, so redirection to other IPs might not work on all providers. DNS redirects to a local address, or rejecting DNS traffic works for all providers. Make sure to set DNS_IPV6_INTERFACE if redirecting to a local DNS address. Format: [IP] or "DHCP" or "REJECT" Example: DNS_IPV6_IP="2606:4700:4700::64" Example: DNS_IPV6_IP="REJECT" Example: DNS_IPV6_PORT=53 DNS_IPV6_INTERFACE Set this to the interface (brX) the IPv6 DNS is on if it is a local IP. Leave blank for non-local DNS. Local DNS redirects will not work without specifying the interface. Format: [brX] Example: DNS_IPV6_INTERFACE="br0" KILLSWITCH Enable killswitch which adds an iptables rule to reject VPN-destined traffic that doesn't go out of the VPN. Format: 0 or 1 Example: KILLSWITCH=1 REMOVE_KILLSWITCH_ON_EXIT Remove the killswitch on exit. It is recommended to set this to 0 so that the killswitch is not removed in case the openvpn client crashes, disconnects, or restarts. Setting this to 1 will remove the killswitch when the openvpn client restarts, which means clients might be able to communicate with your default WAN and leak your real IP while the openvpn client is restarting. Format: 0 or 1 Example: REMOVE_KILLSWITCH_ON_EXIT=0 REMOVE_STARTUP_BLACKHOLES Enable this if you added blackhole routes in the Unifi Settings to prevent Internet access at system startup before the VPN script runs. This option removes the blackhole routes to restore Internet access after the killswitch has been enabled. If you do not set this to 1, openvpn will not be able to connect at startup, and your Internet access will never be enabled until you manually remove the blackhole routes. Set this to 0 only if you did not add any blackhole routes in Step 6 of the boot script instructions above. Format: 0 or 1 Example: REMOVE_STARTUP_BLACKHOLES=1 DISABLE_BLACKHOLE Set this to 1 to disable the VPN blackhole routes that are added (the blackhole routes help prevent VPN-forced clients from accessing the Internet if the VPN routes are not added because an error). Format: 0 (default) or 1 Example: DISABLE_BLACKHOLE=0 VPN_PROVIDER The VPN provider you are using with this script. Format: "openvpn" for OpenVPN (default), "openconnect" for OpenConnect, "external" for WireGuard or StrongSwan, or "nexthop" for an external VPN client connected to another computer on your network. Example: VPN_PROVIDER="openvpn" VPN_ENDPOINT_IPV4 If using "external" for VPN_PROVIDER, set this to the VPN endpoint's IPv4 address so that the gateway route can be automatically added for the VPN endpoint. OpenVPN and OpenConnect automatically passes the VPN endpoint IP to the script and will override this value. This option must be defined if using nexthop VPN_PROVIDER. For StrongSwan, this option must be commented out for auto-assignment from StrongSwan. Format: [IP] Example: VPN_ENDPOINT_IPV4="2.2.2.2" VPN_ENDPOINT_IPV6 If using "external" for VPN_PROVIDER, set this to the VPN endpoint's IPv6 address so that the gateway route can be automatically added for the VPN endpoint. OpenVPN and OpenConnect automatically passes the VPN endpoint IP to the script and will override this value. This option must be defined if using nexthop VPN_PROVIDER. For StrongSwan, this option must be commented out for auto-assignment from StrongSwan. Format: [IP] Example: VPN_ENDPOINT_IPV6="2606:43:ee::23" GATEWAY_TABLE Set this to the route table that contains the gateway route, "auto", or "disabled". The Ubiquiti route table are "201" if you're using Ethernet, "202" for SFP+, and "203" for U-LTE. Default is "auto" which works with WAN failover and automatically changes the endpoint via gateway route when the WAN or gateway routes changes. Set to "disabled" for nexthop option to connect to a LAN computer. Format: [Route Table Number] or "auto" (default), or "disabled". Example: GATEWAY_TABLE="auto" GATEWAY_TABLE="201" DISABLE_DEFAULT_ROUTE Set this to 1 to disable adding the default route. This means only non-default routes the VPN sends will be added. This option only works for OpenVPN and OpenConnect. For WireGuard, modify the AllowedIPs variable in your wireguard config so WireGuard doesn't add default routes. Format: 0 (default) or 1 Example: DISABLE_DEFAULT_ROUTE=1 WATCHER_TIMER Set this to the timer to use for the rule watcher (in seconds). The script will wake up every N seconds to re-add rules if they're deleted by the system, or change gateway routes if they changed. Default is 1 second. Format: [Seconds] Example: WATCHER_TIMER=1 BYPASS_MASQUERADE_IPV4 Bypass masquerade (SNAT) for these IPv4s. This option should only be used if your VPN server is setup to know how to route the subnet you do not want to masquerade (e.g.: the "iroute" option in OpenVPN). Set this option to ALL to disable masquerading completely. Format: [IP/nn] or "ALL" Example: BYPASS_MASQUERADE_IPV4="10.100.1.0/24" BYPASS_MASQUERADE_IPV6 Bypass masquerade (SNAT) for these IPv6s. This option should only be used if your VPN server is setup to know how to route the subnet you do not want to masquerade (e.g.: the "iroute" option in OpenVPN). Set this option to ALL to disable masquerading completely. Format: [IP/nn] or "ALL" Example: BYPASS_MASQUERADE_IPV6="fd64::/64" ROUTE_TABLE The custom route table number. If you are running multiple openvpn clients, this needs to be unique for each client. Format: [Number] Example: ROUTE_TABLE=101 MARK The firewall mark that will be used to mark the packets destined to the VPN. If you are running multiple openvpn clients, this needs to be unique for each client. Format: [Hex number] Example: MARK=0x9 PREFIX The prefix that will be used when adding custom iptables chains. If you are running multiple openvpn clients, this needs to be unique for each client. Format: [Prefix] Example: PREFIX=VPN_ PREF The preference that will be used when adding the policy-based routing rule. It should preferably be less than the UDM rules seen when running "ip rule". Format: [Number] Example: PREF=99 DEV The name of the VPN tunnel device to use for openvpn. If you are running multiple openvpn clients, this needs to be unique for each client. This variable needs to be passed to openvpn via the --dev option or openvpn will default to tun0. Format: [tunX] Example: DEV=tun0 MSS_CLAMPING_IPV4 & MSS_CLAMPING_IPV6 Set the MSS clamping on packets going out the VPN tunnel. Usually, it is not needed to set this manually, but some VPN connections stall if the MSS clamping is not set correctly. Typical values range from 1240 to 1460, but it could be lower. Format: [Number] Example: MSS_CLAMPING_IPV4="1380" MSS_CLAMPING_IPV6="1380" hooks_pre_up, hooks_up, hooks_down, hooks_force_down These functions can be defined in your vpn.conf file and will be called when the VPN is brought down or up. For examples on how to use these hooks, please see https://github.com/peacey/split-vpn/blob/main/vpn/vpn.conf.filled.sample. There are four hooks that you can use: 1. The pre-up hook (hooks_pre_up) is called before the VPN connects if you used the pre-up line in your run script. 2. The up hook (hooks_up) is called after the VPN connects. 3. The down hook (hooks_down) is called when the VPN disconnects or exits (but not forced down). 4. The force-down hook (hooks_force_down) is called when the VPN is forced down using the updown.sh force-down command.