|author||Matt Dunwoodie <firstname.lastname@example.org>||2020-05-18 23:32:19 +1000|
|committer||Matt Dunwoodie <email@example.com>||2020-05-18 23:57:03 +1000|
|parent||Use distinct hashtables for rate limiting v4/v6 (diff)|
Update ifconfig.8 and wg.4
2 files changed, 170 insertions, 195 deletions
diff --git a/src/patches/ifconfig_8.patch b/src/patches/ifconfig_8.patch
index cf71e08..7b468c6 100644
@@ -1,5 +1,5 @@
diff --git a/sbin/ifconfig/ifconfig.8 b/sbin/ifconfig/ifconfig.8
-index 8a5025f8bdf..841756ef490 100644
+index 8a5025f8bdf..29edeb60793 100644
@@ -207,7 +207,8 @@ At least the following devices can be created on demand:
@@ -12,7 +12,7 @@ index 8a5025f8bdf..841756ef490 100644
.It Cm debug
Enable driver-dependent debugging code; usually, this turns on
extra console error logging.
-@@ -2042,6 +2043,145 @@ Clear the tag value.
+@@ -2042,6 +2043,129 @@ Clear the tag value.
Packets on a VLAN interface without a tag set will use a value of
0 in their headers.
@@ -24,14 +24,15 @@ index 8a5025f8bdf..841756ef490 100644
+.Op Cm wgkey Ar privatekey
+.Op Cm wgport Ar port
+.Op Cm wgrtable Ar rtable
-+.Oo Oo Fl Oc Ns Cm wgpeer Ar publickey
++.Oo Fl Oc Ns Cm wgpeer Ar publickey
+.Op Cm wgpsk Ar presharedkey
+.Op Fl wgpsk
+.Op Cm wgpka Ar persistent-keepalive
-+.Op Cm wgendpoint Ar ip port
++.Op Cm wgpip Ar ip port
+.Op Cm wgaip Ar allowed-ip/prefix
+.Op Fl wgpeerall
-+.Op Cm wgconf
+.nr nS 0
@@ -42,118 +43,101 @@ index 8a5025f8bdf..841756ef490 100644
+.It Cm wgkey Ar privatekey
+Set the local private key of the interface to
+.Ar privatekey .
-+This is a random 32 byte value, encoded as base64. The corresponding
-+public key must be distributed to peers that this interface intends to
-+communicate with. It may be generated as such:
++This is a random 32 byte value, encoded as base64.
++It may be generated as follows:
+.Dl $ openssl rand -base64 32
+A valid Curve25519 key is required to have 5 bits set to specific
-+values. This is done by the interface, so it is safe to provide a random
-+32 byte base64 string. Once set, the corresponding public key will be
-+returned in the interface status.
++This is done by the interface, so it is safe to provide a random
++32 byte base64 string.
++Once set, the corresponding public key will be displayed
++in the interface status; it must be distributed to peers
++that this interface intends to communicate with.
+.It Cm wgport Ar port
-+Set the UDP port that the tunnel operates on to
-+.Ar port .
-+The interface will bind to INADDR_ANY and IN6ADDR_ANY_INIT.
++Set the UDP
++that the tunnel operates on.
++The interface will bind to
++.Dv IN6ADDR_ANY_INIT .
++If no port is configured, one will be chosen automatically.
+.It Cm wgrtable Ar rtable
+Use routing table
-+instead of the default table for the tunnel. The tunnel does not need
-+to terminate in the same routing domain as the interface itself.
++instead of the default table for the tunnel.
++The tunnel does not need to terminate in the same routing domain as the
+can be set to any valid routing table ID; the corresponding routing
+domain is derived from this table.
+.It Cm wgpeer Ar publickey
-+Select the peer to perform the subsequent operations on. This will
-+create a peer with associated
-+.Ar publickey ,
-+if it does not yet exist. This can be specified multiple times in a
-+single command and the key is specified as 32 bytes, base64 encoded
++Select the peer to perform the subsequent operations on.
++This creates a peer with the associated 32 byte, base64 encoded
++if it does not yet exist.
++This option can be specified multiple times in a single command.
+.It Cm -wgpeer Ar publickey
+Remove the peer with the associated
++.Ar publickey .
+.It Cm -wgpeerall
-+Remove all peers from the interface
++Remove all peers from the interface.
-+The following commands are used to configure peers for the interface.
-+Each interface can have multiple peers. In order to add a peer, a
++The following options configure peers for the interface.
++Each interface can have multiple peers.
++In order to add a peer, a
-+argument must be specified, followed by its configuration options.
++option must be specified, followed by its configuration options.
+.Bl -tag -width Ds
+.It Cm wgpsk Ar presharedkey
-+Set the preshared key for the peer. This is a random 32 byte, base64
-+encoded string that both ends must agree on. It offers a post-quantum
-+resistance to the Diffie-Hellman exchange. If there is no preshared key,
-+the exact same handshake is performed, however the preshared key is set
-+to all zero. This can be generated in the same way as
++Set the preshared key for the peer.
++This is a random 32 byte, base64 encoded string
++that both ends must agree on.
++It offers a post-quantum resistance to the Diffie-Hellman exchange.
++If there is no preshared key, the exact same handshake is performed,
++however the preshared key is set to all zero.
++This can be generated in the same way as
+.Ar privatekey .
+.It Cm -wgpsk
+Remove the preshared key from the specified peer.
+.It Cm wgpka Ar persistent-keepalive
-+Set the interval that a keepalive should be sent at. By setting the
-+interval to 0, the functionality is disabled. This is often used to
-+ensure a peer will be accessible when protected by a firewall, as is
-+when behind a NAT address. A value of 25 is commonly used.
-+.It Cm wgendpoint Ar ip port
-+Set the endpoint to send the encapsulated packets to. If the
-+peer changes address, the local interface will update the address after
-+receiving a correctly authenticated packet. The IP address can be either
++Set the interval of additional keepalive packets in seconds.
++By default this functionality is disabled, equivalent to a value of 0.
++This is often used to ensure a peer will be accessible when protected by
++a firewall, as is when behind a NAT address.
++A value of 25 is commonly used.
++.It Cm wgpip Ar ip port
++Set the IP address and port to send the encapsulated packets to.
++If the peer changes address, the local interface will update the address
++after receiving a correctly authenticated packet.
++The IP address can be either
+IPv4 or IPv6, and the port is a regular 16 bit UDP port.
+.It Cm wgaip Ar allowed-ip/prefix
-+Add an allowed-ip to the peer. This indicates the IP addresses a peer
-+is allowed to send from. That is, in order for an incoming packet from
-+a peer to reach the interface, the decryped IP source address must be in
-+the peer's allowed-ip list. Both IPv4 and IPv6 addresses are supported.
++Set the allowed IPs for the peer.
++The allowed IPs indicate the IP addresses a peer is allowed to send
++That is, in order for an incoming packet from a peer to reach the host,
++the decryped IP source address must be in the peer's
-+The allowed-ip list also provides an outgoing routing table for outgoing
-+packets. Overlapping ranges can be configured, with packets being
-+directed to the most specific route. Likewise, packets can only be
-+received from the most specific route.
++list also provides an outgoing routing table for outgoing packets.
++Overlapping ranges can be configured, with packets being
++directed to the most specific route.
++Likewise, packets can only be received for the most specific route.
-+Unlike the other commands, the following command receives input from
-+stdin. This allows very fast configuration with a large number of
-+.Bl -tag -width Ds
-+.It Cm wgconf
-+When specified, this will cause
-+to read from stdin the following directives. The usage of the
-+directives is aligned with their usage above. Peer specific directives
-+.Cm wgpsk ,
-+.Cm wgendpoint ,
++Both IPv4 and IPv6 addresses are supported.
++To set multiple allowed IPs, specify the
-+must not precede a
-+directive and will only apply to the single
-+.Cm wgpeer .
-+When this command is used, all previously existing peers and
-+allowed-ips will be overwritten.
-+Any of the following directives may be used, limited to one per line:
-+.Cm wgkey Ar privatekey
-+.Cm wgport Ar port
-+.Cm wgrtable Ar rtable
-+.Cm wgpeer Ar publickey
-+.Cm wgpsk Ar presharedkey
-+.Cm wgendpoint Ar ip port
-+.Cm wgaip Ar allowed-ip/prefix
-+.Cm # Ar comment
++option multiple times in the same
@@ -1,4 +1,18 @@
+.\" Copyright (c) 2020 Matt Dunwoodie <firstname.lastname@example.org>
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.Dd $Mdocdate: Feb 14 2020 $
.Dt WG 4
@@ -18,18 +32,18 @@ Noise protocol framework.
Each interface is able to connect to a number of endpoints, relying on
an internal routing table to direct outgoing IP traffic to the correct
-endpoint. Incoming traffic is also matched against this routing table
+Incoming traffic is also matched against this routing table
and dropped if the source does not match the corresponding output route.
The interfaces can be created at runtime using the
-.Ic ifconfig wg Ns Ar N Ic create
+.Ic ifconfig Cm wg Ns Ar N Cm create
command or by setting up a
.Xr hostname.if 5
configuration file for
.Xr netstart 8 .
The interface itself can be configured with
-.Xr ifconfig 8 ;
-see it's manual page for more information.
+.Xr ifconfig 8 .
Support is also available in the
package by using the
@@ -41,69 +55,74 @@ utilities.
interfaces support the following
.Xr ioctl 2 Ns s :
-.Bl -tag -width indent -offset 3n
+.Bl -tag -width Ds -offset indent
.It Dv SIOCSWG Fa "struct wg_data_io *"
Set the device configuration.
.It Dv SIOCGWG Fa "struct wg_data_io *"
Get the device configuration.
-WireGuard is designed as a small, secure, easy to use VPN. It operates at IP
-level, supporting both IPv4, IPv6.
-The following items give a brief overview of WireGuard features:
+WireGuard is designed as a small, secure, easy to use VPN.
+It operates at the IP level, supporting both IPv4 and IPv6.
+The following list provides a brief overview of WireGuard terminology:
.Bl -tag -width indent -offset 3n
-A peer is a host that the interface creates a connection with. There is
-no concept of client/server as both ends of the connection are equal. An
-interface may have multiple peers.
+A peer is a host that the interface creates a connection with.
+There is no concept of client/server as both ends of the connection
+An interface may have multiple peers.
-Each interface has a private key and corresponding public key. The
-public key is used to identify the interface to other peers.
+Each interface has a private key and corresponding public key.
+The public key is used to identify the interface to other peers.
+.It Preshared key
In addition to the interface keys, each peer pair can have a
-unique preshared key. This key is used in the handshake to provide
-post-quantum security. It is optional, however recommended.
-Allowed-IPs dictate the tunneled IP addresses each peer is allowed to
-send from. After decryption, all packets have their source IP address
-checked against the sending peer's allowed IPs list. This list is
-hierarchical, allowing peers to have overlapping ranges, with the most
-specific range taking precedence. They can be thought of like a routing
+unique preshared key.
+This key is used in the handshake to provide post-quantum security.
+It is optional, however recommended.
+.It Allowed IPs
+Allowed IPs dictate the tunneled IP addresses each peer is allowed to
+After decryption, all packets have their source IP address
+checked against the sending peer's allowed IPs list.
+This list is hierarchical, allowing peers to have overlapping ranges,
+with the most specific range taking precedence.
+They can be thought of like a routing
table, as outgoing packets are also matched against this list to
determine which peer to send to.
-To make it clear, this does not correspond to the IP address that UDP
+This does not correspond to the IP address that UDP
packets are sent to or received from, but rather the IP addresses that
are encapsulated in the tunnel.
In order to establish a set of shared secret keys, two peers perform a
-handshake. This occurs every 2 minutes while traffic is being sent. If
-no traffic is being sent, then no handshake occurs. When traffic
-resumes, a new handshake is performed. Each handshake generates a new
+This occurs every 2 minutes while traffic is being sent.
+If no traffic is being sent, then no handshake occurs.
+When traffic resumes, a new handshake is performed.
+Each handshake generates a new
set of ephemeral keys to provide forward secrecy.
Due to the handshake behavior, there is no connected or disconnected
-state. Thus WireGuard is considered "connection-less".
-Keys for WireGuard can be generated from any sufficiently secure random
-source. The Curve25519 keys and the preshared keys are both 32 bytes
+Private keys for WireGuard can be generated from any sufficiently
+secure random source.
+The Curve25519 keys and the preshared keys are both 32 bytes
long and are commonly encoded in base64 for ease of use.
Keys can be generated with
.Xr openssl 1
.Dl $ openssl rand -base64 32
-It should be noted that not all 32 byte strings are valid Curve25519
-keys. The key must be an element of a finite set, which is achieved by
-setting specific bits in the string. The interface will perform this for
-you, so you may just pass a 32 byte random string. This does not apply
-to the preshared key.
-It goes without saying that these keys must be kept private.
+Note that not all 32 byte strings are valid Curve25519 keys.
+Specific bits must be set in the string.
+All the same, a random 32 string can be passed because
+the interface automatically sets the required bits.
+This does not apply to the preshared key.
When an interface has a private key set with
.Nm wgkey ,
@@ -112,37 +131,14 @@ public key is shown in the status output of the interface, like so:
.Bd -literal -offset indent
wgkey (pub) NW5l2q2MArV5ZXpVXSZwBOyqhohOf8ImDgUB+jPtJps=
-.Xr ifconfig 8
-supports a number of directives and can be summarised with:
-.Bd -filled -offset indent
-.Op Cm wgkey Ar privatekey
-.Op Cm wgport Ar port
-.Op Cm wgrtable Ar rtable
-.Oo Oo Fl Oc Ns Cm wgpeer Ar publickey
-.Op Cm wgpsk Ar presharedkey
-.Op Fl wgpsk
-.Op Cm wgpka Ar persistent-keepalive
-.Op Cm wgpip Ar ip port
-.Op Cm wgaip Ar allowed-ip/prefix
-.Op Fl wgaipall Oc
-.Op Fl wgpeerall
-.Op Cm wgconf
-For further detail, please see
-.Xr ifconfig 8 .
-The following script will create two
interfaces in separate
-.Xr rdomain 4
-.Bd -literal -offset indent
+.Xr rdomain 4 Ns s ,
+which is of no practical use
+but demonstrates two interfaces on the same machine:
ifconfig wg1 create wgport 111 wgkey `openssl rand -base64 32` rdomain 1
@@ -151,69 +147,57 @@ ifconfig wg2 create wgport 222 wgkey `openssl rand -base64 32` rdomain 2
PUB1="`ifconfig wg1 | grep 'wgkey (pub)' | cut -d ' ' -f 3`"
PUB2="`ifconfig wg2 | grep 'wgkey (pub)' | cut -d ' ' -f 3`"
-ifconfig wg1 wgpeer $PUB2 wgpip 127.0.0.1 222 wgaip 192.168.5.2/32
-ifconfig wg2 wgpeer $PUB1 wgpip 127.0.0.1 111 wgaip 192.168.5.1/32
+ifconfig wg1 wgpeer $PUB2 wgendpoint 127.0.0.1 222 wgaip 192.168.5.2/32
+ifconfig wg2 wgpeer $PUB1 wgendpoint 127.0.0.1 111 wgaip 192.168.5.1/32
ifconfig wg1 192.168.5.1/24
ifconfig wg2 192.168.5.2/24
-After this, it should be possible to ping one interface from the other,
+After this, ping one interface from the other:
.Bd -literal -offset indent
route -T1 exec ping 192.168.5.2
-The two interfaces are able to communicate over the UDP tunnel which
-resides in the default
+The two interfaces are able to communicate through the UDP tunnel
+which resides in the default
.Xr rdomain 4 .
-This example carries no practical use apart from demonstrating two
-interfaces on the same machine. You can see the listening sockets with
-.Xr netstat 1 .
+Show the listening sockets:
.Bd -literal -offset indent
interface supports runtime debugging, which can be enabled with:
-.Bd -literal -offset indent
-ifconfig wgN debug
-Some common error messages you may face are detailed below:
-.Bl -tag -width indent -offset 3n
+.D1 Ic ifconfig Cm wg Ns Ar N Cm debug
+Some common error messages include:
.It "Handshake for peer X did not complete after 5 seconds, retrying"
-Peer X did not reply to our initiation packet. This may be caused by
-but not limited to the following:
+Peer X did not reply to our initiation packet, for example because:
-The peer does not have the local interface configured as a peer. Peers
-must be able to mutally authenticate each other.
+The peer does not have the local interface configured as a peer.
+Peers must be able to mutally authenticate each other.
The peer endpoint IP address is incorrectly configured.
-There are firewall rules preventing communication between hosts
+There are firewall rules preventing communication between hosts.
.It "Invalid handshake initiation"
-The incoming handshake packet could not be processed. This is likely
-due to the local interface not containing the correct public key for
+The incoming handshake packet could not be processed.
+This is likely due to the local interface not containing
+the correct public key for the peer.
.It "Invalid initiation MAC"
-The incoming handshake initiation packet had an invalid MAC. This is
-likely because the initiation sender has the wrong public key for the
+The incoming handshake initiation packet had an invalid MAC.
+This is likely because the initiation sender has the wrong public key
+for the handshake receiver.
.It "Packet has unallowed src IP from peer X"
-An incoming data packet, after decryption has a source IP address that
-is not assigned to Peer X's allowed-ips.
+After decryption, an incoming data packet has a source IP address that
+is not assigned to the allowed IPs of Peer X.
-Addtionally, if you attempt to bring up the interface and it does not
-appear to be working, More specifically the IFF_RUNNING flag is not set
-on the interface, then check that no other services or daemons are
-running on the chosen
.Sh SEE ALSO
.Xr inet 4 ,
.Xr ip 4 ,
@@ -229,4 +213,11 @@ port.
-.An Matt Dunwoodie <email@example.com> .
+driver was developed by
+.An Matt Dunwoodie Aq Mt firstname.lastname@example.org
+based on code written by
+.An Jason A. Donenfeld Aq Mt Jason@zx2c4.com .