Show pageOld revisionsBacklinksBack to top This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong. ====== WireGuard VPN Configuration ====== AstLinux now supports the [[https://www.wireguard.com/|WireGuard VPN]]. WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography. WireGuard was created by Jason A. Donenfeld. !!Info ->!! Currently (March 2020) WireGuard is included in Linux 5.6 and onward. Backports for older kernels are also maintained. Be certain to perform your own due diligence and testing of what could become the premier VPN type across most all platforms. !!Note: AstLinux 1.3.2 or later is required, new features with 1.3.5 or later!! !!Note: AstLinux 1.3.6 or later!! supports **Reload WireGuard VPN** !!Note: AstLinux 1.3.7 or later!! supports **WG->Local** firewall rules ===== WireGuard Initial Configuration ===== Select the Network Tab in the web interface.\\ {{:userdoc:ipv6-tunnel-network-tab.jpg?nolink|Network Tab}} Locate the WireGuard VPN entry within **Network Services: -> VPN Type:**\\ {{:userdoc:wireguard-vpn-enabled-network-tab.jpg?nolink|WireGuard VPN Enable Config}} Check "WireGuard VPN" and click on **WireGuard Configuration** {{:userdoc:wireguard-vpn-initial-config.png?nolink|WireGuard VPN Initial Config}} Fill in the "IPv4 Address", click "Save Settings" and then "Restart VPN". WireGuard VPN is now running, but by default no mobile clients or remote peers are defined. Next, you can define a "Mobile Client" or "Remote Peer" or both. A "Mobile Client" is a single IP endpoint peer, like an Android or iOS mobile device, very easy to manage. A "Remote Peer" can be a full network peer, possibly another AstLinux box, more powerful but somewhat more complex to manage. !!Note ->!! Mobile Clients are automatically assigned a unique IP address in the range of ''.101'' to ''.199'' for the last octet (example here: ''10.4.0.101'' to ''10.4.0.199''). Best practice is to refrain from using IP's in this range for both this tunnel's "IPv4 Address" (above) and Remote Peer's IP address so both configuration types can coexist. Similarly for IPv6 the Mobile Client reserved range is ''...:0101'' to ''...:0199''. ===== WireGuard Mobile Client Configuration ===== !!Note: AstLinux 1.3.5 or later!! supports mobile client configuration. First, examine the default options used for newly created clients: {{:userdoc:wireguard-vpn-mobile-client-defaults.png?nolink|WireGuard Mobile Client Defaults}} * Server Hostname: The publicly reachable DNS name that the remote client will connect to. A static IPv4 or IPv6 address may be used, but an IPv6 address must be enclosed with square brackets (IPv6 example: ''[2001:0db8::1]''). * Client Routing: Specify how newly created clients should route traffic. * "Split", the client should route only AstLinux access and DNS lookups over the VPN * "Full", the client should route all traffic over the VPN !!Tip ->!! The defaults only apply to newly created clients. The client's configuration can be changed later via "Edit Peer". By default, there are no Mobile Client Credentials... {{:userdoc:wireguard-vpn-mobile-client-empty-cred.png?nolink|WireGuard Mobile Client Credentials}} As an example, user "fred" has an iPad which is granted VPN access, create a "New Client" named "iPad-fred"... {{:userdoc:wireguard-vpn-mobile-client-new-cred.png?nolink|WireGuard Mobile Client Credentials}} Clients can be just as easily removed by checking the box under "Delete" and clicking "Delete Checked". !!Important ->!! As Mobile Clients are created and deleted, the WireGuard VPN is updated in realtime, so a "Restart VPN" is **NOT** required when managing mobile clients. This is a very useful feature allowing mobile clients to be managed without disrupting other active WireGuard VPN users. While this step can be typically skipped, those curious on what "Edit Peer" displays is as follows... ## WireGuard VPN Peer ## Client: iPad-fred ## [Peer] PublicKey = YC5Vpz48DX/EKfpcPhi1KM69587y2eOLRbIgnZz1smE= AllowedIPs = 10.4.0.137/32 PersistentKeepalive = 0 [Remote_Peer] Endpoint = pbx.example.com:51820 PublicKey = obniQZbYFxcW00pBCNS6Mpxpoom33v9kIDUuzsPnd1w= AllowedIPs = 10.4.0.10/32, 192.168.101.0/24 PersistentKeepalive = 0 [Remote_Config] Address = 10.4.0.137/24 DNS = 10.4.0.10 * The ''[Peer]'' section defines the AstLinux WireGuard configuration, and should not ever be edited. * The ''[Remote_Peer]'' section defines what is exported as client credentials ''[Peer]'' section, you may edit the ''AllowedIPs'' entry if needed. * The ''[Remote_Config]'' section defines what is exported as client credentials included in the ''[Interface]'' section, you may edit the ''DNS'' entry if needed. \\ The final step for each Mobile Client is to download the client's credentials by clicking on "Download", a ''.zip'' file will be downloaded. !!Important ->!! The downloaded credentials ''.zip'' file must be handled securely as it's contents are not encrypted. View the enclosed ''README.txt'' file for more info. The extracted folder contains the following three files... {{:userdoc:wireguard-vpn-mobile-client-cred-files.png?nolink|WireGuard Mobile Credential Files}} * ''iPad-fred.conf'' - The Mobile Client's WireGuard configuration in plain text. * ''iPad-fred.png'' - A PNG graphics file containing a QR code of the ''iPad-fred.conf'' text. Scanning the QR code with your mobile device is a secure method to import the credentials. * ''README.txt'' - A text file describing the files. !!Note ->!! While the QR code PNG file looks obfuscated to the human eye, keep it secure. Using the WireGuard App on your mobile device, import the credentials... scan the QR code or securely import the ''.conf'' file. Your VPN tunnel should work immediately, initiated by the mobile client. \\ ===== WireGuard Remote Peer Configuration ===== !!Note ->!! Defining remote peers is optional when Mobile Clients are defined. By default no remote peers are defined. Click on **Edit Peer Config** and view the commented example peer. ## WireGuard VPN Peers ## ## Example: ## Uncomment and replace the entries with your Peer's configuration #[Peer] #PublicKey = HIgo9xNzJMWLKASShiTqIybxZ0U3wGLiUeJ1PKf8ykw= #Endpoint = 10.10.1.60:51820 #AllowedIPs = 10.4.0.2/32, 192.168.200.1/24 #PersistentKeepalive = 0 Uncomment ''[Peer]'' and uncomment and define the the ''PublicKey'' and ''AllowedIPs'' entries. !!Tip ->!! ''PublicKey'' is the public key of the **remote** peer. !!Tip ->!! ''AllowedIPs'' are a comma-separated list of IPv4 and/or IPv6 address/networks that are allowed into the VPN tunnel, destined to the remote peer. The ''Endpoint'' entry is optional, define it if the peer has a known IP Address or DNS name. If the peer is a roaming road-warrior, leave ''Endpoint'' commented-out. The ''PersistentKeepalive'' entry is optional, a non-zero value in seconds will send keep-alive packets to the remote peer //(rarely needed)//. Note that when multiple peers are defined, the corresponding ''AllowedIPs'' operate as a sort of routing table, uniquely directing routed packets to only one peer or no peers (dropped). When you have finished editing the remote peer(s) in the Edit tab, "Save Changes" and then restart the WireGuard VPN: {{:userdoc:wireguard-vpn-edit-restart.jpg?nolink|Restart WireGuard VPN}} !!Note: AstLinux 1.3.6 or later!! supports **Reload WireGuard VPN** for those situations when only peers are edited, added or removed. **Reload WireGuard VPN** will apply the peer changes without interrupting currently active peers. If Tunnel/Interface/Firewall Options are changed, you must use **Restart WireGuard VPN** to apply changes. ===== WireGuard Configuration Options ===== {{:userdoc:wireguard-vpn-tunnel.png?nolink|WireGuard VPN Tunnel Options}} * IPv4 Address: Define an IPv4 address which configures the WireGuard tunnel device ''wg0'' network. Required. * IPv4 NetMask: Define an IPv4 netmask which configures the WireGuard tunnel device ''wg0'' network, defaults to ''255.255.255.0'' * IPv6/nn Address: Define if you have an IPv4/IPv6 system and want to create a IPv6 WireGuard tunnel device ''wg0'' network. * IPv4/IPv6 Routes: Usually leave this empty and check "Automatic Routes:". Manually defining routes may be useful in special situations. * Automatic Routes: When checked, automatically create routes using the ''AllowedIPs'' entries for all the peers. This setting is ignored if "IPv4/IPv6 Routes" is defined. * DNS Update: When checked, peer endpoints with DNS names will be continually updated after the peer becomes inactive. //(Rarely needed)// !!Note ->!! If an ''AllowedIPs'' entry specifies a ''/0'' default route, no automatic route will be created for that entry. {{:userdoc:wireguard-vpn-interface.png?nolink|WireGuard VPN Interface Options}} * Interface Device: Set the tunnel interface device, currently only ''wg0'' is shown. * Interface MTU: Usually leave this as "default" and let WireGuard determine the best MTU. Setting this to less than ''1420'' may be useful in special situations. * UDP Listen Port: Set the UDP port number the service listens on, defaults to ''51820''. {{:userdoc:wireguard-vpn-firewall.png?nolink|WireGuard VPN Firewall Options}} * External Hosts: Define a space separated list of allowed IPv4/IPv6 addresses via the external interface. The external firewall rules are automatically created by the [[userdoc:tt_firewall_plugins#wireguard-vpn|wireguard-vpn plugin]] . The firewall must be enabled, see the "Enable Firewall" section below for more info. !!Tip ->!! Allow any external IPv4-only address by defining "External Hosts:" to ''0.0.0.0/0'' !!Tip ->!! Allow any external IPv6-only address by defining "External Hosts:" to ''::/0'' !!Tip ->!! Allow any external IPv4/IPv6 address by defining "External Hosts:" to ''0/0'' * Redirect Ports: Choose pre-defined UDP ports on the external interface to redirect to the "UDP Listen Port". This is useful when a remote client using public WiFi with restrictive outbound port filtering can use alternate outbound ports to the standard WireGuard VPN endpoint. {{:userdoc:wireguard-vpn-firewall-redirect-ports.png?nolink|WireGuard VPN Firewall Redirect Ports}} * Peer Isolation: Choose to "Pass" or "Deny" Peer->Peer traffic. "Deny" isolates connected peers, blocking access with each other. !!Note: AstLinux 1.3.7 or later!! supports **WG->Local** firewall rules. {{:userdoc:wireguard-vpn-firewall-wg-local.png?nolink&621|WireGuard VPN Firewall WG->Local}} * Firewall Rules: Choose either "Deny WG->Local" or "Pass WG->Local", with which the TCP/UDP fields apply to. !!Important ->!! The default policy is to allow all **WG->Local** traffic unless "Pass WG->Local" is defined, then the default policy is to deny all **WG->Local** traffic. ICMP Echo Request (ping) packets are allowed and rate-limited for **WG->Local** traffic, regardless of the "Firewall Rules:" choice. * TCP: Define ''TCP'' rules of the form; host1,host2~port1,port2 host3,host4~port3,port4 ... * UDP: Define ''UDP'' rules of the form; host1,host2~port1,port2 host3,host4~port3,port4 ... !!Tip ->!! Allow SSH and DNS traffic, deny all other traffic ... choose "Pass WG->Local" and set ''TCP'' to ''0/0~22,53'' and ''UDP'' to ''0/0~53'' !!Tip ->!! Deny HTTP/HTTPS traffic, allow all other traffic ... choose "Deny WG->Local" and set ''TCP'' to ''0/0~80,443'' !!Tip ->!! Click on the blue ''(i)'' icon for detailed help. \\ {{:userdoc:wireguard-vpn-public-key.png?nolink|WireGuard VPN Public Key}} When WireGuard VPN is active, a "This Peer's Public Key:" entry is shown, for easy copy/paste to remote peer configurations. ===== Enable Firewall ===== The firewall must be enabled for the WireGuard VPN to operate properly. The WireGuard VPN device ''wg0'' is treated as a LAN internal interface, which by default is isolated from all other LAN internal interfaces, but does by default have full access to the AstLinux box itself if the peer's ''AllowedIPs'' allows it. The firewall can be configured to allow the WireGuard VPN tunnel to pass packets to any one of the configured physical LAN interfaces. For example... Network tab -> Firewall Configuration:\\ {{:userdoc:wireguard-vpn-firewall-enable.png?nolink|}} Click on **Firewall Configuration**\\ {{:userdoc:wireguard-vpn-firewall-lan.png?nolink|}} Additionally, the WireGuard VPN tunnel is NAT'ed via the external interface, such that if an exiting IPv4 tunnel packet is routed out through the external interface it will have a NAT'ed path back into the tunnel. ===== Optional Action Script ===== Optionally, if there exists an executable ''/mnt/kd/wireguard.script'' script file it will be called after the VPN is up and before the VPN is down. After the VPN is up, the arguments passed to the script are: POST_UP interface Before the VPN is down, the arguments passed to the script are: PRE_DOWN interface !!Note: AstLinux 1.3.4 or later!! also supports actions ''PRE_UP'' and ''POST_DOWN'' \\ Example ''/mnt/kd/wireguard.script'' script: //(make it executable)// #!/bin/sh ## Action: PRE_UP POST_UP PRE_DOWN POST_DOWN ACTION="$1" ## WireGuard Interface: (ex. wg0) INTERFACE="$2" if [ "$ACTION" = "POST_UP" ]; then logger -t wireguard -p kern.info "WireGuard VPN is started on '$INTERFACE' interface." elif [ "$ACTION" = "PRE_DOWN" ]; then logger -t wireguard -p kern.info "WireGuard VPN is stopping '$INTERFACE' interface." fi !!Tip ->!! For special routing situations, using ''/mnt/kd/wireguard.script'' you can mark wireguard traffic on ''POST_UP'' with: wg set "$INTERFACE" fwmark 51820 and add ''ip rule add ...'' ''fwmark 51820 '' rules on ''POST_UP'' and remove the same rules on ''PRE_DOWN''. \\ ===== WireGuard Client Support ===== WireGuard is now available for [[https://www.wireguard.com/install/|iOS / Android / macOS / Windows]] installation. Each client is open source and free to use. \\ ===== Additional Documentation ===== [[https://git.zx2c4.com/WireGuard/about/src/tools/wg.8|man wg.8]] [[https://www.wireguard.com/performance/#benchmarking|Benchmarks]] [[https://www.ericlight.com/wireguard-part-three-troubleshooting.html|Troubleshooting]] //(Ignore Proxy ARP comments)// userdoc/tt_wireguard_vpn.txt Last modified: 2020/03/30 09:33by abelbeck