From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from out5-smtp.messagingengine.com (out5-smtp.messagingengine.com [66.111.4.29]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id b8fc4d00 for ; Wed, 12 Feb 2020 23:50:29 -0500 (EST) Received: from compute6.internal (compute6.nyi.internal [10.202.2.46]) by mailout.nyi.internal (Postfix) with ESMTP id 80F1F22015; Wed, 12 Feb 2020 23:50:29 -0500 (EST) Received: from mailfrontend2 ([10.202.2.163]) by compute6.internal (MEProxy); Wed, 12 Feb 2020 23:50:29 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sgregoratto.me; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; s=fm2; bh=2wL7QUYn1QFqe HE2pO+MgMPF8OodfEL2RfWCiavXhI0=; b=P5nCEOTd6cbpv+dxMKggInvmorIf9 j3xrUrsvLuGlrx6GtPFjaqorce/s5xdHQSI4zutdfdmqOfNebjOd08vL7e8BPDfp SRxJysewIjCw/+sKdALj8QyiX1s/imBY+EmsjCJsgnSOdZuXJV/nImWFjpjKEWhc Qt8YTkrJFnTrvymh9bIE0VwIEAFHQBpbEjHEQuYnKRdH2KMKcCpLL0tx4q2KN4+N oKzm1IZmrQnzk7fZQBWwjPk/RxFcelzWoSgJUF50020Vf3TG6gIzYkYJbHmS10hK qqLSVt+NZwpwgeuIPuAGRujDwdAgVbLAFHwwNGjFkZBg7kaI6iBjG+3dA== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:date:from :in-reply-to:message-id:mime-version:references:subject:to :x-me-proxy:x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s= fm2; bh=2wL7QUYn1QFqeHE2pO+MgMPF8OodfEL2RfWCiavXhI0=; b=E+5qWKyV MU5qKIzhI+O7LPMU8HsTzYQEgBYGiXMGCrOBgwyH9LFYbpO65vkfYlVw45VAlU1a igBSHQggvC82xBYAOinNbGCWIYWBHG59D+zeWlBBkA2h7t/VWl5eqiefVblzzucx fkgbKTIsL4XkD9azt6wy4rN+v7g6APmOcbEsrd9Tz5jAi9D32rF+wc2JGDerGjBa T9Eo4EMjXDKA3VrZJabKnqIAJzM0is5TiFNiZtzIKnGjNkFc4mX2J23IgDZRJYyA LQJ6SqzhkuB1h7B7zcs4wQyjOX4FWAkBO+2Gm+t1o5Fk4WEo8OgN3iEQwwp25RXa S7xtEkQgVapVWw== X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedugedrieejgdejjecutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecunecujfgurhephffvufffkffojghfggfgsedtkeertd ertddtnecuhfhrohhmpefuthgvphhhvghnucfirhgvghhorhgrthhtohcuoeguvghvsehs ghhrvghgohhrrghtthhordhmvgeqnecuffhomhgrihhnpeifihhrvghguhgrrhgurdgtoh hmpdgtohhnfhdrrhgvnecukfhppeehkedrudejledrgeegrddujedvnecuvehluhhsthgv rhfuihiivgeptdenucfrrghrrghmpehmrghilhhfrhhomhepphgvrhhsohhnrghlsehsgh hrvghgohhrrghtthhordhmvg X-ME-Proxy: Received: from localhost (172.44.179.58.sta.dodo.net.au [58.179.44.172]) by mail.messagingengine.com (Postfix) with ESMTPA id 6E58630600DC; Wed, 12 Feb 2020 23:50:28 -0500 (EST) From: Stephen Gregoratto To: discuss@mandoc.bsd.lv Cc: Jason@zx2c4.com, Stephen Gregoratto Subject: [PATCH] Fix formatting in wg-quick(8) Date: Thu, 13 Feb 2020 15:49:21 +1100 Message-Id: <20200213044921.8115-1-dev@sgregoratto.me> X-Mailer: git-send-email 2.25.0 In-Reply-To: <20200213042900.2ed2sbhglg5uzjq5@BlackBox> References: <20200213042900.2ed2sbhglg5uzjq5@BlackBox> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Transfer-Encoding: 8bit - Wrap all text at 80 chars. - Put all config examples/code in their blocks and eliminate the use of explicit breaks (.br). - Replace all empty lines with explicit paragraph breaks. - Simplify synopsis formatting. Command modifiers are now emboldened, based on output from mandoc's mdoc -> man conversion. --- src/man/wg-quick.8 | 394 +++++++++++++++++++++------------------------ 1 file changed, 186 insertions(+), 208 deletions(-) diff --git a/src/man/wg-quick.8 b/src/man/wg-quick.8 index c38c7d9..215e789 100644 --- a/src/man/wg-quick.8 +++ b/src/man/wg-quick.8 @@ -1,46 +1,35 @@ -.TH WG-QUICK 8 "2016 January 1" ZX2C4 "WireGuard" - +.TH WG-QUICK 8 "2019-02-13" ZX2C4 "WireGuard" .SH NAME -wg-quick - set up a WireGuard interface simply - +\fBwg-quick\fR +\- set up a WireGuard interface simply .SH SYNOPSIS -.B wg-quick -[ -.I up -| -.I down -| -.I save -| -.I strip -] [ -.I CONFIG_FILE -| -.I INTERFACE -] - +\fBwg-quick\fR +[\fBup\fR\ |\ \fBdown\fR\ |\ \fBsave\fR\ |\ \fBstrip\fR] +[\fICONFIG-FILE\fR] +[\fIINTERFACE\fR] .SH DESCRIPTION - This is an extremely simple script for easily bringing up a WireGuard interface, suitable for a few common use cases. - -Use \fIup\fP to add and set up an interface, and use \fIdown\fP to tear down and remove -an interface. Running \fIup\fP adds a WireGuard interface, brings up the interface with the -supplied IP addresses, sets up mtu and routes, and optionally runs pre/post up scripts. Running \fIdown\fP -optionally saves the current configuration, removes the WireGuard interface, and optionally -runs pre/post down scripts. Running \fIsave\fP saves the configuration of an existing -interface without bringing the interface down. Use \fIstrip\fP to output a configuration file -with all -.BR wg-quick (8)-specific +.PP +Use \fBup\fP to add and set up an interface, and use \fBdown\fP to tear down and +remove an interface. Running \fBup\fP adds a WireGuard interface, brings up the +interface with the supplied IP addresses, sets up mtu and routes, and optionally +runs pre/post up scripts. Running \fBdown\fP optionally saves the current +configuration, removes the WireGuard interface, and optionally runs pre/post +down scripts. Running \fBsave\fP saves the configuration of an existing +interface without bringing the interface down. Use \fBstrip\fP to output a +configuration file with all +.BR wg-quick \-specific options removed, suitable for use with .BR wg (8). - +.PP \fICONFIG_FILE\fP is a configuration file, whose filename is the interface name -followed by `.conf'. Otherwise, \fIINTERFACE\fP is an interface name, with configuration -found at `/etc/wireguard/\fIINTERFACE\fP.conf', searched first, followed by distro-specific -search paths. - -Generally speaking, this utility is just a simple script that wraps invocations to +followed by `.conf'. Otherwise, \fIINTERFACE\fP is an interface name, with +configuration found at `/etc/wireguard/\fIINTERFACE\fP.conf', searched first, +followed by distro-specific search paths. +.PP +Generally speaking, this utility is just a simple script that wraps invocations +to .BR wg (8) and .BR ip (8) @@ -51,40 +40,40 @@ specific tool, a more complete network manager, or otherwise just use and .BR ip (8), as usual. - .SH CONFIGURATION - -The configuration file adds a few extra configuration values to the format understood by +The configuration file adds a few extra configuration values to the format +understood by .BR wg (8) in order to configure additional attributes of an interface. It handles the values that it understands, and then it passes the remaining ones directly to .BR wg (8) for further processing. - +.PP It infers all routes from the list of peers' allowed IPs, and automatically adds them to the system routing table. If one of those routes is the default route (0.0.0.0/0 or ::/0), then it uses .BR ip-rule (8) to handle overriding of the default gateway. - +.PP The configuration file will be passed directly to \fBwg\fP(8)'s `setconf' -sub-command, with the exception of the following additions to the \fIInterface\fP section, -which are handled by this tool: - +sub-command, with the exception of the following additions to the +\fBInterface\fP section, which are handled by this tool: .IP \(bu -Address \(em a comma-separated list of IP (v4 or v6) addresses (optionally with CIDR masks) -to be assigned to the interface. May be specified multiple times. +Address \(em a comma-separated list of IP (v4 or v6) addresses (optionally with +CIDR masks) to be assigned to the interface. May be specified multiple times. .IP \(bu -DNS \(em a comma-separated list of IP (v4 or v6) addresses to be set as the interface's -DNS servers. May be specified multiple times. Upon bringing the interface up, this runs -`resolvconf -a tun.\fIINTERFACE\fP -m 0 -x` and upon bringing it down, this runs -`resolvconf -d tun.\fIINTERFACE\fP`. If these particular invocations of +DNS \(em a comma-separated list of IP (v4 or v6) addresses to be set as the +interface's DNS servers. May be specified multiple times. Upon bringing the +interface up, this runs `resolvconf -a tun.\fIINTERFACE\fP -m 0 -x` and upon +bringing it down, this runs `resolvconf -d tun.\fIINTERFACE\fP`. If these +particular invocations of .BR resolvconf (8) are undesirable, the PostUp and PostDown keys below may be used instead. .IP \(bu -MTU \(em if not specified, the MTU is automatically determined from the endpoint addresses -or the system default route, which is usually a sane choice. However, to manually specify -an MTU to override this automatic discovery, this value may be specified explicitly. +MTU \(em if not specified, the MTU is automatically determined from the endpoint +addresses or the system default route, which is usually a sane choice. However, +to manually specify an MTU to override this automatic discovery, this value may +be specified explicitly. .IP \(bu Table \(em Controls the routing table to which routes are added. There are two special values: `off' disables the creation of routes altogether, and `auto' @@ -93,178 +82,167 @@ default routes. .IP \(bu PreUp, PostUp, PreDown, PostDown \(em script snippets which will be executed by .BR bash (1) -before/after setting up/tearing down the interface, most commonly used -to configure custom DNS options or firewall rules. The special string `%i' -is expanded to \fIINTERFACE\fP. Each one may be specified multiple times, in which case -the commands are executed in order. +before/after setting up/tearing down the interface, most commonly used to +configure custom DNS options or firewall rules. The special string `%i' is +expanded to \fIINTERFACE\fP. Each one may be specified multiple times, in which +case the commands are executed in order. .IP \(bu -SaveConfig \(em if set to `true', the configuration is saved from the current state of the -interface upon shutdown. - -.P -Recommended \fIINTERFACE\fP names include `wg0' or `wgvpn0' or even `wgmgmtlan0'. -However, the number at the end is in fact optional, and really -any free-form string [a-zA-Z0-9_=+.-]{1,15} will work. So even interface names corresponding -to geographic locations would suffice, such as `cincinnati', `nyc', or `paris', if that's -somehow desirable. - +SaveConfig \(em if set to `true', the configuration is saved from the current +state of the interface upon shutdown. +.PP +Recommended \fIINTERFACE\fP names include `wg0' or `wgvpn0' or even +`wgmgmtlan0'. However, the number at the end is in fact optional, and really +any free-form string [a-zA-Z0-9_=+.-]{1,15} will work. So even interface names +corresponding to geographic locations would suffice, such as `cincinnati', +`nyc', or `paris', if that's somehow desirable. .SH EXAMPLES - These examples draw on the same syntax found for .BR wg (8), -and a more complete description may be found there. Bold lines below are for options that extend +and a more complete description may be found there. Bold lines below are for +options that extend .BR wg (8). - -The following might be used for connecting as a client to a VPN gateway for tunneling all -traffic: - - [Interface] -.br - \fBAddress = 10.200.100.8/24\fP -.br - \fBDNS = 10.200.100.1\fP -.br - PrivateKey = oK56DE9Ue9zK76rAc8pBl6opph+1v36lm7cXXsQKrQM= -.br - -.br - [Peer] -.br - PublicKey = GtL7fZc/bLnqZldpVofMCD6hDjrK28SsdLxevJ+qtKU= -.br - PresharedKey = /UwcSPg38hW/D9Y3tcS1FOV0K1wuURMbS0sesJEP5ak= -.br - AllowedIPs = 0.0.0.0/0 -.br - Endpoint = demo.wireguard.com:51820 -.br - -The `Address` field is added here in order to set up the address for the interface. The `DNS` field -indicates that a DNS server for the interface should be configured via +.PP +The following might be used for connecting as a client to a VPN gateway for +tunneling all traffic: +.nf +.sp +.RS 6n +[Interface] +\fBAddress = 10.200.100.8/24\fP +\fBDNS = 10.200.100.1\fP +PrivateKey = oK56DE9Ue9zK76rAc8pBl6opph+1v36lm7cXXsQKrQM= + +[Peer] +PublicKey = GtL7fZc/bLnqZldpVofMCD6hDjrK28SsdLxevJ+qtKU= +PresharedKey = /UwcSPg38hW/D9Y3tcS1FOV0K1wuURMbS0sesJEP5ak= +AllowedIPs = 0.0.0.0/0 +Endpoint = demo.wireguard.com:51820 +.RE +.fi +.PP +The `Address` field is added here in order to set up the address for the +interface. The `DNS` field indicates that a DNS server for the interface should +be configured via .BR resolvconf (8). -The peer's allowed IPs entry implies that this interface should be configured as the default gateway, -which this script does. - -Building on the last example, one might attempt the so-called ``kill-switch'', in order -to prevent the flow of unencrypted packets through the non-WireGuard interfaces, by adding the following -two lines `PostUp` and `PreDown` lines to the `[Interface]` section: - - \fBPostUp = iptables -I OUTPUT ! -o %i -m mark ! --mark $(wg show %i fwmark) -m addrtype ! --dst-type LOCAL -j REJECT\fP -.br - \fBPreDown = iptables -D OUTPUT ! -o %i -m mark ! --mark $(wg show %i fwmark) -m addrtype ! --dst-type LOCAL -j REJECT\fP -.br - +The peer's allowed IPs entry implies that this interface should be configured as +the default gateway, which this script does. +.PP +Building on the last example, one might attempt the so-called ``kill-switch'', +in order to prevent the flow of unencrypted packets through the non-WireGuard +interfaces, by adding the following two lines `PostUp' and `PreDown' lines to +the `[Interface]' section: +.nf +.sp +.RS 6n +\fBPostUp = iptables -I OUTPUT ! -o %i -m mark ! --mark $(wg show %i fwmark) -m addrtype ! --dst-type LOCAL -j REJECT\fP +\fBPreDown = iptables -D OUTPUT ! -o %i -m mark ! --mark $(wg show %i fwmark) -m addrtype ! --dst-type LOCAL -j REJECT\fP +.RE +.fi +.PP The `PostUp' and `PreDown' fields have been added to specify an .BR iptables (8) -command which, when used with interfaces that have a peer that specifies 0.0.0.0/0 as part of the -`AllowedIPs', works together with wg-quick's fwmark usage in order to drop all packets that -are either not coming out of the tunnel encrypted or not going through the tunnel itself. (Note -that this continues to allow most DHCP traffic through, since most DHCP clients make use of PF_PACKET -sockets, which bypass Netfilter.) When IPv6 is in use, additional similar lines could be added using +command which, when used with interfaces that have a peer that specifies +0.0.0.0/0 as part of the `AllowedIPs', works together with wg-quick's fwmark +usage in order to drop all packets that are either not coming out of the tunnel +encrypted or not going through the tunnel itself. (Note that this continues to +allow most DHCP traffic through, since most DHCP clients make use of PF_PACKET +sockets, which bypass Netfilter.) When IPv6 is in use, additional similar lines +could be added using .BR ip6tables (8). - -Or, perhaps it is desirable to store private keys in encrypted form, such as through use of +.PP +Or, perhaps it is desirable to store private keys in encrypted form, such as +through use of .BR pass (1): - - \fBPostUp = wg set %i private-key <(pass WireGuard/private-keys/%i)\fP -.br - -For use on a server, the following is a more complicated example involving multiple peers: - - [Interface] -.br - \fBAddress = 10.192.122.1/24\fP -.br - \fBAddress = 10.10.0.1/16\fP -.br - \fBSaveConfig = true\fP -.br - PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk= -.br - ListenPort = 51820 -.br - -.br - [Peer] -.br - PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg= -.br - AllowedIPs = 10.192.122.3/32, 10.192.124.1/24 -.br - -.br - [Peer] -.br - PublicKey = TrMvSoP4jYQlY6RIzBgbssQqY3vxI2Pi+y71lOWWXX0= -.br - AllowedIPs = 10.192.122.4/32, 192.168.0.0/16 -.br - -.br - [Peer] -.br - PublicKey = gN65BkIKy1eCE9pP1wdc8ROUtkHLF2PfAqYdyYBz6EA= -.br - AllowedIPs = 10.10.10.230/32 - -Notice the two `Address' lines at the top, and that `SaveConfig' is set to `true', indicating -that the configuration file should be saved on shutdown using the current status of the -interface. - -A combination of the `Table', `PostUp', and `PreDown' fields may be used for policy routing -as well. For example, the following may be used to send SSH traffic (TCP port 22) traffic -through the tunnel: - - [Interface] -.br - Address = 10.192.122.1/24 -.br - PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk= -.br - ListenPort = 51820 -.br - \fBTable = 1234\fP -.br - \fBPostUp = ip rule add ipproto tcp dport 22 table 1234\fP -.br - \fBPreDown = ip rule delete ipproto tcp dport 22 table 1234\fP -.br - -.br - [Peer] -.br - PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg= -.br - AllowedIPs = 0.0.0.0/0 - -These configuration files may be placed in any directory, putting the desired interface name -in the filename: - -\fB # wg-quick up /path/to/wgnet0.conf\fP - -For convenience, if only an interface name is supplied, it automatically chooses a path in -`/etc/wireguard/': - -\fB # wg-quick up wgnet0\fP - +.PP +.RS 6n +\fBPostUp = wg set %i private-key <(pass WireGuard/private-keys/%i)\fP +.RE +.PP +For use on a server, the following is a more complicated example involving +multiple peers: +.nf +.sp +.RS 6n +[Interface] +\fBAddress = 10.192.122.1/24\fP +\fBAddress = 10.10.0.1/16\fP +\fBSaveConfig = true\fP +PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk= +ListenPort = 51820 + +[Peer] +PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg= +AllowedIPs = 10.192.122.3/32, 10.192.124.1/24 + +[Peer] +PublicKey = TrMvSoP4jYQlY6RIzBgbssQqY3vxI2Pi+y71lOWWXX0= +AllowedIPs = 10.192.122.4/32, 192.168.0.0/16 + +[Peer] +PublicKey = gN65BkIKy1eCE9pP1wdc8ROUtkHLF2PfAqYdyYBz6EA= +AllowedIPs = 10.10.10.230/32 +.RE +.fi +.PP +Notice the two `Address' lines at the top, and that `SaveConfig' is set to +`true', indicating that the configuration file should be saved on shutdown using +the current status of the interface. +.PP +A combination of the `Table', `PostUp', and `PreDown' fields may be used for +policy routing as well. For example, the following may be used to send SSH +traffic (TCP port 22) traffic through the tunnel: +.nf +.sp +.RS 6n +[Interface] +Address = 10.192.122.1/24 +PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk= +ListenPort = 51820 +\fBTable = 1234\fP +\fBPostUp = ip rule add ipproto tcp dport 22 table 1234\fP +\fBPreDown = ip rule delete ipproto tcp dport 22 table 1234\fP + +[Peer] +PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg= +AllowedIPs = 0.0.0.0/0 +.RE +.fi +.PP +These configuration files may be placed in any directory, putting the desired +interface name in the filename: +.PP +.RS 6n +# wg-quick up /path/to/wgnet0.conf +.RE +.PP +For convenience, if only an interface name is supplied, it automatically chooses +a path in `/etc/wireguard/': +.PP +.RS 6n +# wg-quick up wgnet0 +.RE +.PP This will load the configuration file `/etc/wireguard/wgnet0.conf'. - -The \fIstrip\fP command is useful for reloading configuration files without disrupting active -sessions: - -\fB # wg addconf wgnet0 <(wg-quick strip wgnet0)\fP - -(Note that the above command will add and update peers but will not remove peers.) - +.PP +The \fBstrip\fP command is useful for reloading configuration files without +disrupting active sessions: +.PP +.RS 6n +# wg addconf wgnet0 <(wg-quick strip wgnet0) +.RE +.PP +(Note that the above command will add and update peers but will not remove +peers.) .SH SEE ALSO -.BR wg (8), +.BR pass (1), .BR ip (8), -.BR ip-link (8), .BR ip-address (8), +.BR ip-link (8), .BR ip-route (8), .BR ip-rule (8), -.BR resolvconf (8). - +.BR iptables (8), +.BR resolvconf (8), +.BR wg (8) .SH AUTHOR .B wg-quick was written by -- 2.25.0 -- To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv