Module Name: src
Committed By: riastradh
Date: Thu Aug 20 21:36:00 UTC 2020
Modified Files:
src/distrib/sets/lists/man: mi
src/share/man/man4: Makefile
src/usr.sbin/wg-keygen: wg-keygen.8
src/usr.sbin/wgconfig: wgconfig.8
Added Files:
src/share/man/man4: wg.4
Log Message:
Fill out WireGuard man pages.
To generate a diff of this commit:
cvs rdiff -u -r1.1698 -r1.1699 src/distrib/sets/lists/man/mi
cvs rdiff -u -r1.706 -r1.707 src/share/man/man4/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man4/wg.4
cvs rdiff -u -r1.1 -r1.2 src/usr.sbin/wg-keygen/wg-keygen.8
cvs rdiff -u -r1.1 -r1.2 src/usr.sbin/wgconfig/wgconfig.8
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/man/mi
diff -u src/distrib/sets/lists/man/mi:1.1698 src/distrib/sets/lists/man/mi:1.1699
--- src/distrib/sets/lists/man/mi:1.1698 Thu Aug 20 21:28:01 2020
+++ src/distrib/sets/lists/man/mi Thu Aug 20 21:35:59 2020
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1698 2020/08/20 21:28:01 riastradh Exp $
+# $NetBSD: mi,v 1.1699 2020/08/20 21:35:59 riastradh Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@@ -2032,6 +2032,7 @@
./usr/share/man/cat4/wds.0 man-sys-catman .cat
./usr/share/man/cat4/we.0 man-sys-catman .cat
./usr/share/man/cat4/wedge.0 man-sys-catman .cat
+./usr/share/man/cat4/wg.0 man-sys-catman .cat
./usr/share/man/cat4/wi.0 man-sys-catman .cat
./usr/share/man/cat4/wm.0 man-sys-catman .cat
./usr/share/man/cat4/wmidell.0 man-sys-catman .cat
@@ -5165,6 +5166,7 @@
./usr/share/man/html4/wds.html man-sys-htmlman html
./usr/share/man/html4/we.html man-sys-htmlman html
./usr/share/man/html4/wedge.html man-sys-htmlman html
+./usr/share/man/html4/wg.html man-sys-htmlman html
./usr/share/man/html4/wi.html man-sys-htmlman html
./usr/share/man/html4/wm.html man-sys-htmlman html
./usr/share/man/html4/wmidell.html man-sys-htmlman html
@@ -8230,6 +8232,7 @@
./usr/share/man/man4/wds.4 man-sys-man .man
./usr/share/man/man4/we.4 man-sys-man .man
./usr/share/man/man4/wedge.4 man-sys-man .man
+./usr/share/man/man4/wg.4 man-sys-man .man
./usr/share/man/man4/wi.4 man-sys-man .man
./usr/share/man/man4/wm.4 man-sys-man .man
./usr/share/man/man4/wmidell.4 man-sys-man .man
Index: src/share/man/man4/Makefile
diff -u src/share/man/man4/Makefile:1.706 src/share/man/man4/Makefile:1.707
--- src/share/man/man4/Makefile:1.706 Sun Jul 26 15:13:09 2020
+++ src/share/man/man4/Makefile Thu Aug 20 21:36:00 2020
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.706 2020/07/26 15:13:09 jdolecek Exp $
+# $NetBSD: Makefile,v 1.707 2020/08/20 21:36:00 riastradh Exp $
# @(#)Makefile 8.1 (Berkeley) 6/18/93
MAN= aac.4 ac97.4 acardide.4 aceride.4 acphy.4 \
@@ -70,7 +70,7 @@ MAN= aac.4 ac97.4 acardide.4 aceride.4 a
vald.4 valz.4 veriexec.4 vga.4 vge.4 viaide.4 video.4 \
vio9p.4 vioif.4 viomb.4 viornd.4 vioscsi.4 virt.4 virtio.4 \
vlan.4 vmmon.4 vmnet.4 vnd.4 voodoofb.4 vr.4 vte.4 \
- wapbl.4 wb.4 wbsio.4 wd.4 wdc.4 wi.4 wm.4 wpi.4 \
+ wapbl.4 wb.4 wbsio.4 wd.4 wdc.4 wg.4 wi.4 wm.4 wpi.4 \
wsbell.4 wscons.4 wsdisplay.4 wsfont.4 wskbd.4 wsmouse.4 wsmux.4 \
xbox.4 xge.4 \
yds.4 ym.4 \
Index: src/usr.sbin/wg-keygen/wg-keygen.8
diff -u src/usr.sbin/wg-keygen/wg-keygen.8:1.1 src/usr.sbin/wg-keygen/wg-keygen.8:1.2
--- src/usr.sbin/wg-keygen/wg-keygen.8:1.1 Thu Aug 20 21:28:02 2020
+++ src/usr.sbin/wg-keygen/wg-keygen.8 Thu Aug 20 21:36:00 2020
@@ -1,4 +1,4 @@
-.\" $NetBSD: wg-keygen.8,v 1.1 2020/08/20 21:28:02 riastradh Exp $
+.\" $NetBSD: wg-keygen.8,v 1.2 2020/08/20 21:36:00 riastradh Exp $
.\"
.\" Copyright (C) Ryota Ozaki <[email protected]>
.\" All rights reserved.
@@ -27,29 +27,50 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd December 12, 2018
+.Dd August 20, 2020
.Dt WG-KEYGEN 8
.Os
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh NAME
.Nm wg-keygen
-.Nd generates keys used by WireGuard interfaces.
+.Nd generate keys for WireGuard interfaces
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh SYNOPSIS
.Nm
+.Nm Fl Fl pub
+.Nm Fl Fl psk
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh DESCRIPTION
.Nm
-generates a private key and a preshared key used by a WireGuard interface.
-It also generates a public key from a given private key.
+generates keys for WireGuard.
+.Bl -tag -width abcd
+.It Nm
+Generate a private key and print it to standard output.
+.It Nm Fl Fl pub
+Read a private key from standard input, and print the corresponding
+public key to standard output.
+.It Nm Fl Fl psk
+Generate a preshared key and print it to standard output.
+.El
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh EXAMPLES
+See
+.Xr wg 4
+for example usage.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh SEE ALSO
.Xr wg 4 ,
.Xr wgconfig 8
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh HISTORY
The
.Nm
command first appeared in
-.Nx 9.0 .
+.Nx 10.0 .
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh AUTHORS
The
.Nm
-command is written by
+command was written by
.An Ryota Ozaki
.Aq [email protected] .
Index: src/usr.sbin/wgconfig/wgconfig.8
diff -u src/usr.sbin/wgconfig/wgconfig.8:1.1 src/usr.sbin/wgconfig/wgconfig.8:1.2
--- src/usr.sbin/wgconfig/wgconfig.8:1.1 Thu Aug 20 21:28:02 2020
+++ src/usr.sbin/wgconfig/wgconfig.8 Thu Aug 20 21:36:00 2020
@@ -1,4 +1,4 @@
-.\" $NetBSD: wgconfig.8,v 1.1 2020/08/20 21:28:02 riastradh Exp $
+.\" $NetBSD: wgconfig.8,v 1.2 2020/08/20 21:36:00 riastradh Exp $
.\"
.\" Copyright (C) Ryota Ozaki <[email protected]>
.\" All rights reserved.
@@ -27,29 +27,135 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd December 12, 2018
+.Dd August 20, 2020
.Dt WGCONFIG 8
.Os
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh NAME
.Nm wgconfig
.Nd configure WireGuard interface parameters
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh SYNOPSIS
-.Nm
-.Ar interface
+.Nm Ar wgN Op Cm "show all"
+.\"
+.Nm Ar wgN Cm "show peer" Ar name Op Fl Fl show-preshared-key
+.\"
+.Nm Ar wgN Cm "show private-key"
+.\"
+.Nm Ar wgN Cm "set private-key" Ar "filename"
+.\"
+.Nm Ar wgN Cm "set listen-port" Ar port
+.\"
+.Nm Ar wgN Cm "add peer" Ar name Ar pubkey
+.Op Fl Fl preshared-key Ns = Ns Ar filename
+.Op Fl Fl endpoint Ns = Ns Ar ip : Ns Ar port
+.Op Fl Fl allowed-ips Ns = Ns Ar ip1 Ns / Ns Ar cidr1 Ns Op , Ns Ar ip2 Ns / Ns Ar cidr2 Ns ,...
+.\"
+.Nm Ar wgN Cm "delete peer" Ar name
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh DESCRIPTION
+The
+.Nm
+utility is used to configure or display a WireGuard
+.Xr wg 4
+interface's parameters and status.
+Every
+.Xr wg 4
+interface can be configured with an IP address using
+.Xr ifconfig 8 ,
+a private key generated with
+.Xr wg-keygen 8 ,
+an optional listen port,
+and a collection of peers.
+Each peer has a public key and allowed IP addresses, and may optionally
+have a fixed endpoint IP address and a preshared secret key.
+.Pp
+The following commands are supported:
+.Bl -tag -width abcd
+.It Cm "show all"
+Show all WireGuard peers.
+No secret keys are included in the output.
+.It Cm "show peer" Ar name Op Fl Fl show-preshared-key
+Show the peer named
+.Ar name .
+By default, no secret keys are included in the output.
+With
+.Fl Fl show-preshared-key ,
+also display the secret preshared key that the peer was configured to
+have with the
+.Fl Fl preshared-key
+option to
+.Nm Ar wgN Cm "add peer" .
+.It Cm "show private-key"
+Show the private key that was set with
+.Nm Ar wgN Cm "set private-key" .
+.It Cm "set listen-port" Ar port
+Set the UDP port number that
+.Ar wgN
+listens for incoming WireGuard sessions on.
+This allows a peer to start a new session without having a specific
+endpoint IP address configured.
+.It Cm "add peer" Ar name Ar pubkey Op options...
+Add a peer.
+The argument
+.Ar name
+may be passed to
+.Nm Ar wgN Cm "show peer"
+and
+.Nm Ar wgN Cm "delete peer" .
+The argument
+.Ar pubkey
+is the peer's base64-encoded public key, as printed by
+.Nm wg-keygen Fl Fl pub .
+.Pp
+The following options may be specified:
+.Bl -tag -width abcd
+.It Fl Fl preshared-key-file Ns = Ns Ar filename
+Set a secret preshared key generated by
+.Nm wg-keygen Fl Fl psk .
+.Pp
+If the preshared key can be arranged in advance on a medium not subject
+to eavesdropping, then it defends against possible future quantum
+cryptanalysis of the X25519 key agreement.
+WireGuard still uses X25519 key agreements in order to erase past
+session keys so that past session transcripts remain secret should one
+of the endpoints be compromised in the future; the preshared key is an
+additional measure on top.
+.It Fl Fl endpoint Ns = Ns Ar ip : Ns Ar port
+Set the peer's endpoint address outside the tunnel.
+This is optional for a VPN server if the WireGuard interface is
+configured to listen on a port number.
+.It Fl Fl allowed-ips Ns = Ns Ar ip1 Ns / Ns Ar cidr1 Ns Op , Ns Ar ip2 Ns / Ns Ar cidr2 Ns ,...
+Set the IP address ranges that the peer is allowed to select inside the
+tunnel.
+.El
+.It Cm "delete peer" Ar name
+Delete the peer
+.Ar name
+previously added with
+.Nm Cm "add peer" Ar name .
+.El
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh EXAMPLES
+See
+.Xr wg 4
+for an example network topology and
.Nm
-is used to configure a WireGuard interface parameters.
+usage.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh SEE ALSO
.Xr wg 4 ,
.Xr wg-keygen 8
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh HISTORY
The
.Nm
command first appeared in
-.Nx 9.0 .
+.Nx 10.0 .
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh AUTHORS
The
.Nm
-command is written by
+command was written by
.An Ryota Ozaki
.Aq [email protected] .
Added files:
Index: src/share/man/man4/wg.4
diff -u /dev/null src/share/man/man4/wg.4:1.1
--- /dev/null Thu Aug 20 21:36:00 2020
+++ src/share/man/man4/wg.4 Thu Aug 20 21:36:00 2020
@@ -0,0 +1,157 @@
+.\" $NetBSD: wg.4,v 1.1 2020/08/20 21:36:00 riastradh Exp $
+.\"
+.\" Copyright (c) 2020 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd August 20, 2020
+.Dt WG 4
+.Os
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh NAME
+.Nm wg
+.Nd WireGuard virtual private network
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh SYNOPSIS
+.Cd pseudo-device wg
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh DESCRIPTION
+The
+.Nm
+interface implements the WireGuard point-to-point roaming-capable
+virtual private network tunnel, configured with
+.Xr ifconfig 8
+and
+.Xr wgconfig 8 .
+.Pp
+Packets exchanged on a
+.Nm
+interface are authenticated and encrypted with a secret key negotiated
+with the peer, and the encapsulation is exchanged over IP or IPv6 using
+UDP.
+.Pp
+Every
+.Xr wg 4
+interface can be configured with an IP address using
+.Xr ifconfig 8 ,
+a private key generated with
+.Xr wg-keygen 8 ,
+an optional listen port,
+and a collection of peers.
+.Pp
+Each peer configured on an
+.Nm
+interface has a public key and a range of IP addresses the peer is
+allowed to use for its
+.Nm
+interface inside the tunnel.
+Each peer may also optionally have a preshared secret key and a fixed
+endpoint IP address outside the tunnel.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh EXAMPLES
+Typical network topology:
+.Bd -literal
+wm0 = 1.2.3.4 bge0 = 4.3.2.1
+
+Stationary server: Roaming client:
++---------+ +---------+
+| A | | B |
+|---------| |---------|
+| [wm0]-------------internet--------[bge0] |
+| [wg0] port 1234 - - - (tunnel) - - - - - - [wg0] |
+| 10.0.1.0 | 10.0.1.1 |
+| | | | |
++--[wm1]--+ +-----------------+ +---------+
+ | | VPN 10.0.1.0/24 |
+ | +-----------------+
++-----------------+
+| LAN 10.0.0.0/24 |
++-----------------+
+.Ed
+.Pp
+Generate key pairs on A and B:
+.Bd -literal
+A# wg-keygen > /etc/wireguard/wg0
+A# wg-keygen --pub < /etc/wireguard/wg0 > /etc/wireguard/wg0.pub
+A# cat /etc/wireguard/wg0.pub
+N+B4Nelg+4ysvbLW3qenxIwrJVE9MdjMyqrIisH7V0Y=
+
+B# wg-keygen > /etc/wireguard/wg0
+B# wg-keygen --pub < /etc/wireguard/wg0 > /etc/wireguard/wg0.pub
+B# cat /etc/wireguard/wg0.pub
+X7EGm3T3IfodBcyilkaC89j0SH3XD6+/pwvp7Dgp5SU=
+.Ed
+.Pp
+Configure A to listen on port 1234 and allow connections from B to
+appear in the 10.0.1.0/24 subnet:
+.Bd -literal
+A# ifconfig wg0 create 10.0.1.0/24
+A# wgconfig wg0 set private-key /etc/wireguard/wg0
+A# wgconfig wg0 set listen-port 1234
+A# wgconfig wg0 add peer B \e
+ X7EGm3T3IfodBcyilkaC89j0SH3XD6+/pwvp7Dgp5SU= \e
+ --allowed-ips=10.0.1.1/32
+A# ifconfig wg0 up
+A# ifconfig wg0
+wg0: flags=0x51<UP,POINTOPOINT,RUNNING> mtu 1420
+ inet 10.0.1.0/24 -> flags 0
+.Ed
+.Pp
+Configure B to connect to A at 1.2.3.4 on port 1234 and the packets can
+begin to flow:
+.Bd -literal
+B# ifconfig wg0 create 10.0.1.1/24
+B# wgconfig wg0 set private-key /etc/wireguard/wg0
+B# wgconfig wg0 add peer A \e
+ N+B4Nelg+4ysvbLW3qenxIwrJVE9MdjMyqrIisH7V0Y= \e
+ --allowed-ips=10.0.1.0/32 \e
+ --endpoint=1.2.3.4:1234
+B# ifconfig wg0 up
+B# ifconfig wg0
+wg0: flags=0x51<UP,POINTOPOINT,RUNNING> mtu 1420
+ inet 10.0.1.1/24 -> flags 0
+B# ping -n 10.0.1.0
+PING 10.0.1.0 (10.0.1.0): 56 data bytes
+64 bytes from 10.0.1.0: icmp_seq=0 ttl=255 time=2.721110 ms
+...
+.Ed
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh SEE ALSO
+.Xr wg-keygen 8 ,
+.Xr wgconfig 8
+.Rs
+.%T WireGuard: fast, modern, secure VPN tunnel
+.%U https://www.wireguard.com/
+.Re
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh HISTORY
+The
+.Nm
+interface first appeared in
+.Nx 10.0 .
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh AUTHORS
+The
+.Nm
+interface was implemented by
+.An Ryota Ozaki Aq Mt [email protected] .
