discrepancy between groff and mandoc for html rendering of wg-quick(8)

discrepancy between groff and mandoc for html rendering of wg-quick(8)

[Jason A. Donenfeld]

Compare:

[mandoc] https://manpages.debian.org/testing/wireguard-tools/wg-quick.8.en.html
[groff] https://git.zx2c4.com/wireguard-tools/about/src/man/wg-quick.8

Look at the "EXAMPLES" section. Notice weird line break issues with mandoc.

Is this a man page source bug or a mandoc bug?

Source is here: https://git.zx2c4.com/wireguard-tools/tree/src/man/wg-quick.8

Thanks,
Jason
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: discrepancy between groff and mandoc for html rendering of wg-quick(8)

[Jan Stary]

On Feb 11 23:59:21, Jason@zx2c4.com wrote:
> [mandoc] https://manpages.debian.org/testing/wireguard-tools/wg-quick.8.en.html

That is not the output of mandoc -Thmtl as such.
That's mandoc's html output inset into a debian webpage.

> [groff] https://git.zx2c4.com/wireguard-tools/about/src/man/wg-quick.8

That is not the output of gorff -Thmtl -mman either.
That's groff's html output inset into a webpage.

> Look at the "EXAMPLES" section. Notice weird line break issues with mandoc.
> Is this a man page source bug or a mandoc bug?
> Source is here: https://git.zx2c4.com/wireguard-tools/tree/src/man/wg-quick.8

Take that source, produce the two html outputs

	mandoc -Thtml wg-quick.8 > wg.mandoc.html
	groff  -Thtml -mman wg-quick.8 > wg.groff.html

and compare the results. They are different,
but none has the line breaks in EXAMPLES.

Jan

--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: discrepancy between groff and mandoc for html rendering of wg-quick(8)

[Ingo Schwarze]

Hi Jan, hi Jason,

Jan Stary wrote on Wed, Feb 12, 2020 at 08:02:29AM +0100:
> On Feb 11 23:59:21, Jason@zx2c4.com wrote:

>> [mandoc] https://manpages.debian.org/testing/wireguard-tools/wg-quick.8.en.html

> That is not the output of mandoc -Thmtl as such.
> That's mandoc's html output inset into a debian webpage.

While that is true, it is not really relevant.

The OP did find a bug in mandoc, which you can see by comparing the
output from the following two commands, even with mandoc -current:

   $ printf "A\n.br\nB\n" | mandoc -T html
   $ printf "A\n.br\n B\n" | mandoc -T html

In the second case, the <br/> element is missing between the "A" and the "B",
even though in terminal output mode (i.e. without the -T html), the line
break is correctly emitted in both cases.

A first superficial inspection reveals that the validation module is
probably making invalid assumptions that leading whitespace on an input
line automatically implies a line break for all output modes, which is
not true for HTML.

I'll need to have a closer look how to fix this; i'm not yet sure whether
the validator or the formatter or both need to be changed.

>> [groff] https://git.zx2c4.com/wireguard-tools/about/src/man/wg-quick.8

> That is not the output of gorff -Thmtl -mman either.
> That's groff's html output inset into a webpage.

Again, not really relevant.  It does show that groff respects the .br
request, which, of course, is not surprising at all.

>> Look at the "EXAMPLES" section. Notice weird line break issues with mandoc.
>> Is this a man page source bug or a mandoc bug?
>> Source is here: https://git.zx2c4.com/wireguard-tools/tree/src/man/wg-quick.8

> Take that source, produce the two html outputs
> 
> 	mandoc -Thtml wg-quick.8 > wg.mandoc.html
> 	groff  -Thtml -mman wg-quick.8 > wg.groff.html
> 
> and compare the results. They are different,
> but none has the line breaks in EXAMPLES.

According to my testing, "groff -Thtml -mman wg-quick.8"
does produce the expected line breaks, e.g.:

  [...]
  <h2>EXAMPLES
  [...]
  <p style="margin-left:11%; margin-top: 1em">[Peer] <br>
  PublicKey = GtL7fZc/bLnqZldpVofMCD6hDjrK28SsdLxevJ+qtKU=
  <br>
  PresharedKey = /UwcSPg38hW/D9Y3tcS1FOV0K1wuURMbS0sesJEP5ak=
  <br>
  AllowedIPs = 0.0.0.0/0 <br>
  Endpoint = demo.wireguard.com:51820</p>

I think we are talking about the <br> lines before and after "PresharedKey",
for example.

So the bug report is clearly valid and also precise enough to help
me fix it.

Thanks for the report,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: discrepancy between groff and mandoc for html rendering of wg-quick(8)

[Jan Stary]

On Feb 12 08:02:30, hans@stare.cz wrote:
> > Look at the "EXAMPLES" section. Notice weird line break issues with mandoc.

I thought Jason meant the

  (Note that the above command will add and update peers but will not remove
  peers.)

which I don't see in either.
Sorry for the misunderstanding.

	Jan

--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: discrepancy between groff and mandoc for html rendering of wg-quick(8)

[Ingo Schwarze]

Hi Jan,

Jan Stary wrote on Wed, Feb 12, 2020 at 04:14:32PM +0100:

> I thought Jason meant the
> 
>   (Note that the above command will add and update peers but will not remove
>   peers.)
> 
> which I don't see in either.

While that line may indeed wrap onto two lines when displayed in
the context of manpages.debian.org (depending on the font, the CSS,
and the browser), that's merely normal line wrapping and not a hard
line break.  So you are right, neither groff nor mandoc emit a <br>
element in that line, and they also shouldn't.

> Sorry for the misunderstanding.

No problem.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: discrepancy between groff and mandoc for html rendering of wg-quick(8)

[Ingo Schwarze]

Hello Jason,

Jason A. Donenfeld wrote on Tue, Feb 11, 2020 at 11:59:21PM +0100:

> Compare:
> 
> [mandoc] https://manpages.debian.org/testing/wireguard-tools/wg-quick.8.en.html
> [groff] https://git.zx2c4.com/wireguard-tools/about/src/man/wg-quick.8
> 
> Look at the "EXAMPLES" section. Notice weird line break issues with mandoc.

Closer inspection revealed that it is actually fine that the roff
validation module in mandoc (roff_validate.c) removes the redundant
.br requests, but there was a bug in the man(7) HTML formatter
(man_html.c), forgetting to actually break the line.

The commit appended below fixes the bug.

Thank you for reporting!

> Is this a man page source bug or a mandoc bug?

Foremost, it was a mandoc bug.

Besides, while the following man(7) code in wg-quick(8) isn't incorrect,
it isn't good style either:

 ----- 8< ----- schnipp ----- >8 ----- 8< ----- schnapp ----- >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
 ----- 8< ----- schnipp ----- >8 ----- 8< ----- schnapp ----- >8 -----

Blank lines are bad style in manual pages outside no-fill mode.
Forcing line breaks with leading whitespace is also bad style in
manual pages.  The .br requests are redundant and look quite ugly.
Using font escapes instead of font macros is bad style in manual
pages.  So it would be better to write this:

 ----- 8< ----- schnipp ----- >8 ----- 8< ----- schnapp ----- >8 -----
The following might be used for connecting as a client to a VPN gateway
for tunneling all traffic:
.PP \" optional, can be left out
.RS 4n \" the 4n is optional, give no arg to get the default indentation
.nf
[Interface]
.B Address = 10.200.100.8/24
.B BDNS = 10.200.100.1
[...]
.fi
.RE
.PP
[...]
 ----- 8< ----- schnipp ----- >8 ----- 8< ----- schnapp ----- >8 -----

(Bold face isn't really needed in an example either, but oh well...)

Anyway, bad style in a manual page is no excuse
for mandoc misformatting it.

Yours,
  Ingo


Log Message:
-----------
In roff, a space character at the beginning of an input line requires 
starting a new output line, and merely starting a new line of HTML 
code isn't sufficient to achieve that.  Solve this in the same way
as mdoc_html.c already does it, by printing a <br/> element.
Fixing a bug reported by Jason A. Donenfeld <Jason at zx2c4 dot com>
in the wg-quick(8) manual page on manpages.debian.org.

Modified Files:
--------------
    mandoc:
        man_html.c

Revision Data
-------------
Index: man_html.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/man_html.c,v
retrieving revision 1.174
retrieving revision 1.175
diff -Lman_html.c -Lman_html.c -u -p -r1.174 -r1.175
--- man_html.c
+++ man_html.c
@@ -1,7 +1,7 @@
 /*	$Id$ */
 /*
  * Copyright (c) 2008-2012, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
- * Copyright (c) 2013-2015, 2017-2019 Ingo Schwarze <schwarze@openbsd.org>
+ * Copyright (c) 2013-2015, 2017-2020 Ingo Schwarze <schwarze@openbsd.org>
  *
  * Permission to use, copy, modify, and distribute this software for any
  * purpose with or without fee is hereby granted, provided that the above
@@ -178,7 +178,7 @@ print_man_node(MAN_ARGS)
 		}
 		if (*n->string == ' ' && n->flags & NODE_LINE &&
 		    (h->flags & HTML_NONEWLINE) == 0)
-			print_endline(h);
+			print_otag(h, TAG_BR, "");
 		else if (n->flags & NODE_DELIMC)
 			h->flags |= HTML_NOSPACE;
 		t = h->tag;
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: discrepancy between groff and mandoc for html rendering of wg-quick(8)

[Stephen Gregoratto]

Echoing what Ingo said, it is better form to format code blocks... as a
block. That's true of any markup format. So, I took the time to go
through wg-quick(8) and fix these sections. I also took the time to
"enhance" the rest of the manual by looking at the output of mandoc's
mdoc -> man conversion and adjusting accordingly. See the replied patch.
-- 
Stephen Gregoratto
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

[PATCH] Fix formatting in wg-quick(8)

[Stephen Gregoratto]

- 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

Re: [PATCH] Fix formatting in wg-quick(8)

[Raf Czlonka]

On Thu, Feb 13, 2020 at 04:49:21AM GMT, Stephen Gregoratto wrote:
> [...]
> +.TH WG-QUICK 8 "2019-02-13" ZX2C4 "WireGuard"
                     ^^
Hi Stephen,

Haven't checked the rest but you got the year wrong :^)

Regards,

Raf
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: [PATCH] Fix formatting in wg-quick(8)

[Jason A. Donenfeld]

Hi Stephen,

Thanks for the patch! I really appreciate it. A few comments in-line
below. Could you CC v2 of this to wireguard@lists.zx2c4.com?

Also, how would you feel about doing the same to wg.8 (in the same
repo)? It has basically the same set of issues.

Jason

On Thu, Feb 13, 2020 at 5:50 AM Stephen Gregoratto <dev@sgregoratto.me> wrote:
>
> - 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.
> ---

This commit needs your `Signed-off-by: Stephen Gregoratto
<dev@sgregoratto.me>` line at the bottom for it to be accepted.

>  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"

It's 2020 now, but what would you think of retaining the original
date? Or do you usually bump it on every change? I'm not sure what the
convention is.

>  .SH NAME
> -wg-quick - set up a WireGuard interface simply
> -
> +\fBwg-quick\fR
> +\- set up a WireGuard interface simply

Similar change needed for wg(8) too of course.

>  .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

Doing it like this is a lot more readable. Thanks.

> -
>  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).

Looks like you removed the (8) on wg-quick there by accident.

> -
> +.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

Never seen these three modifiers. They set spacing somehow?

> +[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

You've ordered these alphabetically, but the original ordering was
chosen deliberately.

>  was written by
> --
> 2.25.0

Thanks again!
Jason
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: discrepancy between groff and mandoc for html rendering of wg-quick(8)

[Jason A. Donenfeld]

Hi Ingo,

On Wed, Feb 12, 2020 at 10:44 PM Ingo Schwarze <schwarze@usta.de> wrote:
> The commit appended below fixes the bug.

Great! Thanks so much for fixing. I forwarded your email to a debian
fella. Maybe they'll apply it to whatever they're using.

> Besides, while the following man(7) code in wg-quick(8) isn't incorrect,
> it isn't good style either:

Indeed the manual wg-quick.8 and wg.8 files are really grotesque. I
write latex but not groff and wasn't sure which conventions to use.
Any cleanup help is greatly appreciated! Thanks for the suggestions
you provided.

> (Bold face isn't really needed in an example either, but oh well...)

It is. In this case, it's showing a wg(8)-style config file with two
wg-quick(8) additions. The additions are made bold to distinguish
them.

Thanks a bunch,
Jason
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: [PATCH] Fix formatting in wg-quick(8)

[Ingo Schwarze]

Hi,

Stephen Gregoratto wrote on Thu, Feb 13, 2020 at 03:49:21PM +1100:

> I also took the time to "enhance" the rest of the manual by looking
> at the output of mandoc's mdoc -> man conversion and adjusting
> accordingly.

That's a bad idea.  Automatically generating high-quality man(7) code
is hard, and "mandoc -T man" does not attempt that.  All it does is
generating code that is portable, but not necessarily good style.

> - Wrap all text at 80 chars.
> - Put all config examples/code in their blocks

Yes.

>   and eliminate the use of explicit breaks (.br).

Using .br is sometimes OK in man(7) code, but abused here.

> - Replace all empty lines with explicit paragraph breaks.

Yes.

> - 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"

Raf already mentioned s/2019/2020/.

>  .SH NAME
> -wg-quick - set up a WireGuard interface simply
> -
> +\fBwg-quick\fR

No, don't do this.  If you want it bold, use

.B wg-quick

> +\- 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]

Absolutely not.  Make this

  .B wg-quick
  .RB [ up
  |
  .B down
  |
  .B save
  |
  .BR strip ]
  .RI [ config_name
  |
  .IR interface ]

There should not be whitespace inside brackets.
To join words using different fonts, use the font alternating macros.
As you said, words that have to be typed verbatim are bold.
Argument placeholders are italic, but not all caps.
Avoid misleading placeholders like config_file,
the argument is merely a name, and you only get the file when
appending ".conf".

>  .SH DESCRIPTION
> -

Yes.

>  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

Make this

  Use
  .B up
  to add and set up an interface, and use
  .B down
  to tear down and

> +remove an interface. Running \fBup\fP adds a WireGuard interface, brings up the

New sentence, new line:

  remove an interface.
  Running
  .B up
  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

I'm not mentioning repeated issues every time.

> +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

No, this is a hyphen, not a minus:

  .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

  .I config_name
  is the name of a configuration.
  Appending ".conf" yields the name of the configuration file.

"Whose" sounds strange to me in this context: a file is not a person.

[...]
> +.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

Better use .B.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: [PATCH] Fix formatting in wg-quick(8)

[Jason A. Donenfeld]

One thing I should mention is the work here will lead to BSD
improvements. Both wg.8 and wg-quick.8 are in FreeBSD and OpenBSD
ports trees. We're working on some native kernel stuff for OpenBSD
stuff, so I could imagine at some point in a year from now this making
its way into OpenBSD proper.

https://git.zx2c4.com/wireguard-tools/tree/src/man/wg.8
https://git.zx2c4.com/wireguard-tools/tree/src/man/wg-quick.8

At the moment these are our only man pages, but if you guys lay down
some clear consistency with them, I'll ensure that future additions
match your conventions.
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: [PATCH] Fix formatting in wg-quick(8)

[Ingo Schwarze]

Hi Jason,

Jason A. Donenfeld wrote on Thu, Feb 13, 2020 at 05:31:41PM +0100:
> On Thu, Feb 13, 2020 at 5:50 AM Stephen Gregoratto <dev@sgregoratto.me> wrote:

>> +.TH WG-QUICK 8 "2019-02-13" ZX2C4 "WireGuard"

> It's 2020 now, but what would you think of retaining the original
> date? Or do you usually bump it on every change? I'm not sure what the
> convention is.

The .TH macro is supposed to contain the date of the last change.

If you want to explain when something was first implemented,
you can do that below ".SH HISTORY".

>> +.PP
>> +The following might be used for connecting as a client to a VPN gateway for
>> +tunneling all traffic:
>> +.nf
>> +.sp
>> +.RS 6n

> Never seen these three modifiers. They set spacing somehow?

Not sure what you mean by "modifiers".
.nf and .sp are roff(7) requests, .RS is a man(7) macro,
and 6n is a scaling width.

  https://man.openbsd.org/roff.7#nf
  https://man.openbsd.org/roff.7#sp
  https://man.openbsd.org/man.7#RS_2
  https://man.openbsd.org/roff.7#Scaling_Widths

>>  .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

> You've ordered these alphabetically, but the original ordering was
> chosen deliberately.

Sorting first by section, then alphabetically is done by convention.
For example, see this style guide:

  https://mandoc.bsd.lv/mdoc/style/see_also.html

The reason is that the number of references ought to be small,
so deliberate ordering adds little value, and a fixed ordering
results in a more predictable experience for the reader.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: [PATCH] Fix formatting in wg-quick(8)

[Ingo Schwarze]

Hi Jason,

Jason A. Donenfeld wrote on Thu, Feb 13, 2020 at 07:00:33PM +0100:

> One thing I should mention is the work here will lead to BSD
> improvements. Both wg.8 and wg-quick.8 are in FreeBSD and OpenBSD
> ports trees. We're working on some native kernel stuff for OpenBSD
> stuff, so I could imagine at some point in a year from now this making
> its way into OpenBSD proper.

Oh wow.  I wasn't aware of that, but it appears that both Ted Unangst
(tedu@) and Jasper Lievisse Adriaanse (jasper@) are interested.
And when Tedu says that something is simple, that is high praise.

Don't underestimate the difficulty of getting something into the
OpenBSD kernel, though.  We deleted support for kernel modules many
years ago and they won't come back.  So, while you might get away
with making a kernel module for FreeBSD, for OpenBSD the code quality
needs to be sufficient to be included in every kernel for all users,
by default.  Also, subsystem design and code quality is very strictly
audited and enforced in the kernel.  So try to coordinate early
with kernel developers, to avoid later disappointments and wasted
effort by developing in some direction and finding out later that
parts of the design require tweaks.  Tedu is a good person to ask
what to coordinate with whom; if you get people like claudio@ or
bluhm@ or dlg@ to help and to review early drafts of code, prospects
increase substantially.  Neither me nor Jasper work in the kernel.

> https://git.zx2c4.com/wireguard-tools/tree/src/man/wg.8
> https://git.zx2c4.com/wireguard-tools/tree/src/man/wg-quick.8
> 
> At the moment these are our only man pages, but if you guys lay down
> some clear consistency with them, I'll ensure that future additions
> match your conventions.

Don't worry too much about manual pages.  While we also require
manual pages that are complete, correct, and concise, that will not
make your project fail: you will get help with that when needed:
ask me when in doubt.  It is much harder to get stuff ready for
kernel commits than to get the documentation into shape.

That said, in OpenBSD, we strongly prefer mdoc(7) manual pages over
man(7); though when outside suppliers only provide man(7), that can
be imported, too.  FreeBSD, NetBSD, DragonFly BSD, and Illumos also
prefer mdoc(7) over man(7), though maybe not quite as strongly as
OpenBSD.  Either way, mdoc(7) is easier to learn and write than
man(7), produces output of considerably better quality, and if some
of the platforms you want to support require man(7), you can readily
generate that from mdoc(7) with mandoc(1).  The most prominent
platform i'm aware of that doesn't support mdoc(7) is commercial
Oracle Solaris; certainly all BSDs, MacOS, and all Linux distros
support mdoc(7).  I'm not sure about commercial AIX and HP-UX.

So you might want to consider maintaining your manual pages
in mdoc(7) format right from the start - that's better for all
BSDs, no worse for Linux, and you can use automatic conversion
for whatever other, more obscure systems you want to support.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: [PATCH] Fix formatting in wg-quick(8)

[Jason A. Donenfeld]

Hi Ingo,

On Thu, Feb 13, 2020 at 8:34 PM Ingo Schwarze <schwarze@usta.de> wrote:
> Don't underestimate the difficulty of getting something into the
> OpenBSD kernel, though.  We deleted support for kernel modules many
> years ago and they won't come back.  So, while you might get away
> with making a kernel module for FreeBSD, for OpenBSD the code quality
> needs to be sufficient to be included in every kernel for all users,
> by default.  Also, subsystem design and code quality is very strictly
> audited and enforced in the kernel.  So try to coordinate early
> with kernel developers, to avoid later disappointments and wasted
> effort by developing in some direction and finding out later that
> parts of the design require tweaks.  Tedu is a good person to ask
> what to coordinate with whom; if you get people like claudio@ or
> bluhm@ or dlg@ to help and to review early drafts of code, prospects
> increase substantially.  Neither me nor Jasper work in the kernel.

Yea, we're not half-assing this, and we'll reach out to the right
people at the right time and start showing up to conferences and stuff
to suss out the finer points. The Linux module took 4 years to get in.
We've learned some lessons. I think things will go well with OpenBSD.
I'll start sending emails when I have coherent things to say. For now,
though, the stuff in ports works fine.


> Don't worry too much about manual pages.  While we also require
> manual pages that are complete, correct, and concise, that will not
> make your project fail: you will get help with that when needed:
> ask me when in doubt.  It is much harder to get stuff ready for
> kernel commits than to get the documentation into shape.

Yes, well aware that development is the focus. No need for lessons
here. We're taking that extremely seriously, have worked hard for the
last 4 years at it, and intend to continue to do so with OpenBSD.

However, I do care about the finer details, and one of these is
documentation. Every time I open up my hand-crafted man page files, I
want to close them, because the markup is such an eyesore. Any help at
cleaning this up would be most welcome.


> That said, in OpenBSD, we strongly prefer mdoc(7) manual pages over
> man(7); though when outside suppliers only provide man(7), that can
> be imported, too.  FreeBSD, NetBSD, DragonFly BSD, and Illumos also
> prefer mdoc(7) over man(7), though maybe not quite as strongly as
> OpenBSD.  Either way, mdoc(7) is easier to learn and write than
> man(7), produces output of considerably better quality, and if some
> of the platforms you want to support require man(7), you can readily
> generate that from mdoc(7) with mandoc(1).  The most prominent
> platform i'm aware of that doesn't support mdoc(7) is commercial
> Oracle Solaris; certainly all BSDs, MacOS, and all Linux distros
> support mdoc(7).  I'm not sure about commercial AIX and HP-UX.
>
> So you might want to consider maintaining your manual pages
> in mdoc(7) format right from the start - that's better for all
> BSDs, no worse for Linux, and you can use automatic conversion
> for whatever other, more obscure systems you want to support.

Interesting I hadn't ever considered this because I didn't know about
it. I can open mdoc files with the man utility? Right now I appreciate
that installation of man pages just requires copying a file. I'd like
to retain this quality for as long as possible, but with the caveat
that the actual markup of that file should be nice and maintainable.
For that reason, I really appreciate what Stephen has begun here, and
I hope that miniproject continues through til completion.

Jason
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: [PATCH] Fix formatting in wg-quick(8)

[Ingo Schwarze]

Hi Jason,

Jason A. Donenfeld wrote on Thu, Feb 13, 2020 at 08:55:10PM +0100:

> Yea, we're not half-assing this, and we'll reach out to the right
> people at the right time and start showing up to conferences and stuff
> to suss out the finer points. The Linux module took 4 years to get in.
> We've learned some lessons. I think things will go well with OpenBSD.
> I'll start sending emails when I have coherent things to say. For now,
> though, the stuff in ports works fine.

That sounds great all around.

> However, I do care about the finer details, and one of these is
> documentation.

That's good, too.  OpenBSD cares about detail, and it cares about
documentation.

> Every time I open up my hand-crafted man page files, I
> want to close them, because the markup is such an eyesore.

Yes, man(7) source code tends to not be very pretty even when
well-written.

> Interesting I hadn't ever considered this because I didn't know about
> it. I can open mdoc files with the man utility?

I assume you mean "read" when you say "open"; to open them for
editing, you would instead use any text editor you like, for example
vi(1) or emacs(1).

On any BSD, any Linux, on Illumos, and on commercial Oracle Solaris 11:
yes, any installation of man(1) you might have will display mdoc(7)
just fine.  On most BSDs, man(1) will use mandoc(1) for formatting.
On most Linuxes, man(1) will use groff(1) by default for formatting,
but groff(1) has been supporting mdoc(7) for about three decades
now.

If you use MacOS, it will work, too, but there might be occasional
formatting problems.  In general, code quality in MacOS tends to
limp along behind FreeBSD, often being outdated by roughly a decade
even in the newest MacOS releases.  But you can easily fix that by
installing an up-to-date groff or mandoc.

If you use commercial Oracle Solaris 10 or older, you need to install
a better man(1) or teach it to use groff.  For AIX and HP-UX, i
don't really know, but if there are issues, installing a modern
groff or mandoc will almost certainly cure them, too.

> Right now I appreciate that installation of man pages just requires
> copying a file.

Absolutely.  That's exactly the same with mdoc(7) as with man(7),
except with the system man(1) on systems like Solaris 10 and maybe
AIX and HP-UX.

> I'd like to retain this quality for as long as possible,

Indeed, i see no reason not to.  OpenBSD, FreeBSD, NetBSD, and
Illumos do just that all the time with all their manual pages.

> but with the caveat that the actual markup of that file should be
> nice and maintainable.

I guess mdoc(7) would fit that bill.

You see this in the editor:
  https://cvsweb.bsd.lv/mandoc/mdoc.7?rev=HEAD

And you see this in man(1):
  https://man.openbsd.org/mdoc.7

> For that reason, I really appreciate what Stephen has begun here, and
> I hope that miniproject continues through til completion.

Do you want somebody to have a go at converting your two files
to mdoc(7)?

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: [PATCH] Fix formatting in wg-quick(8)

[Jason A. Donenfeld]

Hi Ingo,

On Thu, Feb 13, 2020 at 11:28 PM Ingo Schwarze <schwarze@usta.de> wrote:
> On any BSD, any Linux, on Illumos, and on commercial Oracle Solaris 11:
> yes, any installation of man(1) you might have will display mdoc(7)
> just fine.  On most BSDs, man(1) will use mandoc(1) for formatting.
> On most Linuxes, man(1) will use groff(1) by default for formatting,
> but groff(1) has been supporting mdoc(7) for about three decades
> now.

That all sounds perfect. Out of the box support for a better set of
macros on all the platforms I care about. I just tried pasting the
hello world example from the mdoc manual preference, and man(1)
handled it without a hitch.

> If you use MacOS, it will work, too, but there might be occasional
> formatting problems.

I suppose we can just hack around these, should they come up.

> Do you want somebody to have a go at converting your two files
> to mdoc(7)?

That would be terrific! Thank you.

I'm happy to be going this route, rather than giving up and succumbing
to docbook or asciidoc or a similar cop out. Seems like mdoc has all
the right semantic markup for what we need.

Jason
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: [PATCH] Fix formatting in wg-quick(8)

[Jan Stary]

On Feb 13 23:28:45, schwarze@usta.de wrote:
> If you use MacOS, it will work, too, but there might be occasional
> formatting problems.  In general, code quality in MacOS tends to
> limp along behind FreeBSD, often being outdated by roughly a decade
> even in the newest MacOS releases.

The very latest macOS (10.15.2), for example,
comes with groff 1.19.2, released in 2005.

Yeah.

--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: [PATCH] Fix formatting in wg-quick(8)

[Steffen Nurpmeso]

Jan Stary wrote in
<20200213224459.GA93280@www.stare.cz>:
 |On Feb 13 23:28:45, schwarze@usta.de wrote:
 |> If you use MacOS, it will work, too, but there might be occasional
 |> formatting problems.  In general, code quality in MacOS tends to
 |> limp along behind FreeBSD, often being outdated by roughly a decade
 |> even in the newest MacOS releases.
 |
 |The very latest macOS (10.15.2), for example,
 |comes with groff 1.19.2, released in 2005.
 |
 |Yeah.

Not at all.

--steffen
|
|Der Kragenbaer,                The moon bear,
|der holt sich munter           he cheerfully and one by one
|einen nach dem anderen runter  wa.ks himself off
|(By Robert Gernhardt)
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: [PATCH] Fix formatting in wg-quick(8)

[Anthony J. Bentley]

Jason A. Donenfeld writes:
> It's 2020 now, but what would you think of retaining the original
> date? Or do you usually bump it on every change? I'm not sure what the
> convention is.

Convention is to bump date on every change.

> Looks like you removed the (8) on wg-quick there by accident.

Usually the section is dropped when referring to self. I made the same
change independently before seeing this email.

> You've ordered these alphabetically, but the original ordering was
> chosen deliberately.

Alphabetical is another strongly held convention, so much so that mandoc
gives a warning about it.

Ingo Schwarze writes:
> Do you want somebody to have a go at converting your two files
> to mdoc(7)?

My attempt is below. One of the more difficult mdoc conversions I've
done!

Some thoughts that came up during the process:

- There were a few places like this where I wasn't sure if squeezing Ar
  in there might be overkill:

    Upon bringing the interface up, this runs
    .Ql resolvconf -a tun.INTERFACE -m 0 -x
    and upon bringing it down, this runs
    .Ql resolvconf -d tun.INTERFACE .

- Does the config file support statements across multiple lines (with
  backslash or some such)? Then we could avoid the ugly wrapping in
  wg-quick(8)'s EXAMPLES.

- Wasn't there discussion on the Groff list about moving to title case
  instead of all caps in section headers? Is that something we want to
  encourage in downstream manuals?

- Not sure of my use of Bro/Brc.

- The hanging indent in long tag list items seems problematic here.
  Suggestions?

Pages below--directly, not as a diff, since files are entirely different.


.Dd February 13, 2020
.Dt WG 8
.Os
.Sh NAME
.Nm wg
.Nd set and retrieve configuration of WireGuard interfaces
.Sh SYNOPSIS
.Nm wg
.Op Ar COMMAND
.Op Ar OPTIONS ...
.Op Ar ARGS ...
.Sh DESCRIPTION
.Nm wg
is the configuration utility for getting and setting the configuration of
WireGuard tunnel interfaces.
The interfaces themselves can be added and removed using
.Xr ip-link 8
and their IP addresses and routing tables can be set using
.Xr ip-address 8
and
.Xr ip-route 8 .
The
.Nm
utility provides a series of sub-commands for changing WireGuard-specific
aspects of WireGuard interfaces.
.Pp
If no
.Ar COMMAND
is specified,
.Ar COMMAND
defaults to
.Cm show .
Sub-commands that take an
.Ar interface
must be passed a WireGuard interface.
.Sh COMMANDS
.Bl -tag -width Ds
.It Cm show Bro Ar interface | Cm all | interfaces Brc Oo Cm public-key | \
private-key | listen-port | fwmark | peers | preshared-keys | endpoints | \
allowed-ips | latest-handshakes | persistent-keepalive | transfer | dump Oc
Shows current WireGuard configuration and runtime information of specified
.Ar interface .
If no interface is specified,
.Ar interface
defaults to
.Cm all .
If
.Cm interfaces
is specified, prints a list of all WireGuard interfaces,
one per line, and quits.
If no options are given after the interface specification, then prints a list
of all attributes in a visually pleasing way meant for the terminal.
Otherwise, prints specified information grouped by newlines and tabs,
meant to be used in scripts.
For this script-friendly display, if
.Cm all
is specified,
then the first field for all categories of information is the interface name.
If
.Cm dump
is specified, then several lines are printed;
the first contains in order separated by tab:
private-key, public-key, listen-port, fwmark.
Subsequent lines are printed for each peer
and contain in order separated by tab:
public-key, preshared-key, endpoint, allowed-ips, latest-handshake,
transfer-rx, transfer-tx, persistent-keepalive.
.It Cm showconf Ar interface
Shows the current configuration of
.Ar interface
in the format described by
.Sx CONFIGURATION FILE FORMAT
below.
.It Cm set Ar interface Oo Cm listen-port Ar port Oc Oo Cm fwmark Ar fwmark Oc \
Oo Cm private-key Ar file-path Oc Oo peer Ar base64-public-key Oo Cm remove Oc \
Oo Cm preshared-key Ar file-path Oc Oo Cm endpoint Ar ip : Ns Ar port Oc \
Oo Cm persistent-keepalive Ar interval_seconds Oc Oo Cm allowed-ips Ar ip1 Ns \
/ Ns Ar cidr1 Ns Oo \&, Ns Ar ip2 Ns / Ns Ar cidr2 Ar ... Oc Oc Oc Ar ...
Sets configuration values for the specified
.Ar interface .
Multiple
Ar peer Ns s
may be specified, and if the
.Cm remove
argument is given for a peer, that peer is removed, not configured.
If
.Cm listen-port
is not specified, or set to 0,
the port will be chosen randomly when the interface comes up.
Both
.Cm private-key
and
.Cm preshared-key
must be files, because command line arguments are not considered private on
most systems but if you are using
.Xr bash 1 ,
you may safely pass in a string by specifying as
.Cm private-key
or
.Cm preshared-key
the expression:
.Ql <(echo PRIVATEKEYSTRING) .
If
.Pa /dev/null
or another empty file is specified as the filename for either
.Cm private-key
or
.Cm preshared-key ,
the key is removed from the device.
The use of
.Cm preshared-key
is optional, and may be omitted;
it adds an additional layer of symmetric-key cryptography to be mixed into
the already existing public-key cryptography, for post-quantum resistance.
If
.Cm allowed-ips
is specified, but the value is the empty string,
all allowed ips are removed from the peer.
The use of
.Cm persistent-keepalive
is optional and is by default off; setting it to 0 or
.Ql off
disables it.
Otherwise it represents, in seconds, between 1 and 65535 inclusive,
how often to send an authenticated empty packet to the peer, for the purpose of
keeping a stateful firewall or NAT mapping valid persistently.
For example, if the interface very rarely sends traffic,
but it might at anytime receive traffic from a peer, and it is behind NAT,
the interface might benefit from having a persistent keepalive interval
of 25 seconds; however, most users will not need this.
The use of
.Cm fwmark
is optional and is by default off; setting it to 0 or
.Ql off
disables it.
Otherwise it is a 32-bit fwmark for outgoing packets
and may be specified in hexadecimal by prepending
.Ql 0x .
.It Cm setconf Ar interface configuration-filename
Sets the current configuration of
.Ar interface
to the contents of
.Ar configuration-filename ,
which must be in the format described by
.Sx CONFIGURATION FILE FORMAT
below.
.It Cm addconf Ar interface configuration-filename
Appends the contents of
.Ar configuration-filename ,
which must be in the format described by
.Sx CONFIGURATION FILE FORMAT
below, to the current configuration of
.Ar interface .
.It Cm syncconf Ar interface configuration-filename
Like
.Cm setconf ,
but reads back the existing configuration first and only makes changes that are
explicitly different between the configuration file and the interface.
This is much less efficient than
.Cm setconf ,
but has the benefit of not disrupting current peer sessions.
The contents of
.Ar configuration-filename
must be in the format described by
.Sx CONFIGURATION FILE FORMAT
below.
.It Cm genkey
Generates a random
.Em private
key in base64 and prints it to standard output.
.It Cm genpsk
Generates a random
.Em preshared
key in base64 and prints it to standard output.
.It Cm pubkey
Calculates a
.Em public
key and prints it in base64 to standard output from a corresponding
.Em private
key (generated with
.Cm genkey )
given in base64 on standard input.
.Pp
A private key and a corresponding public key
may be generated at once by calling:
.Pp
.Dl $ umask 077
.Dl $ wg genkey | tee private.key | wg pubkey > public.key
.It Cm help
Shows usage message.
.El
.Sh CONFIGURATION FILE FORMAT
The configuration file format is based on INI.
There are two top level sections \(em
.Ic Interface
and
.Ic Peer .
Multiple
.Ic Peer
sections may be specified, but only one
.Ic Interface
section may be specified.
.Pp
The
.Ar Interface
section may contain the following fields:
.Bl -tag -width Ds
.It Ic PrivateKey
A base64 private key generated by
.Ql wg genkey .
Required.
.It Ic ListenPort
A 16-bit port for listening.
Optional; if not specified, chosen randomly.
.It Ic FwMark
A 32-bit fwmark for outgoing packets.
If set to 0 or
.Ql off ,
this option is disabled.
May be specified in hexadecimal by prepending
.Ql 0x .
Optional.
.El
.Pp
The
.Ic Peer
sections may contain the following fields:
.Bl -tag -width Ds
.It Ic PublicKey
A base64 public key calculated by
.Ql wg pubkey
from a private key,
and usually transmitted out of band to the author of the configuration file.
Required.
.It Ic PresharedKey
A base64 preshared key generated by
.Ql wg genpsk .
Optional, and may be omitted.
This option adds an additional layer of symmetric-key cryptography
to be mixed into the already existing public-key cryptography,
for post-quantum resistance.
.It Ic AllowedIPs
A comma-separated list of IP (v4 or v6) addresses with CIDR masks
from which incoming traffic for this peer is allowed
and to which outgoing traffic for this peer is directed.
The catch-all
.Ql 0.0.0.0/0
may be specified for matching all IPv4 addresses, and
.Ql ::/0
may be specified for matching all IPv6 addresses.
May be specified multiple times.
.It Ic Endpoint
An endpoint IP or hostname, followed by a colon, and then a port number.
This endpoint will be updated automatically to the most recent source IP
address and port of correctly authenticated packets from the peer.
Optional.
.It Ic PersistentKeepalive
A seconds interval, between 1 and 65535 inclusive, of how often to send an
authenticated empty packet to the peer for the purpose of keeping a stateful
firewall or NAT mapping valid persistently.
For example, if the interface very rarely sends traffic, but it might at
anytime receive traffic from a peer, and it is behind NAT, the interface might
benefit from having a persistent keepalive interval of 25 seconds.
If set to 0 or
.Ql off ,
this option is disabled.
By default or when unspecified, this option is off.
Most users will not need this.
Optional.
.El
.Sh CONFIGURATION FILE FORMAT EXAMPLE
This example may be used as a model for writing configuration files,
following an INI-like syntax.
Characters after and including a
.Ql #
are considered comments and are thus ignored.
.Bd -literal -offset Ds
[Interface]
PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk=
ListenPort = 51820
    
[Peer]
PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=
Endpoint = 192.95.5.67:1234
AllowedIPs = 10.192.122.3/32, 10.192.124.1/24
    
[Peer]
PublicKey = TrMvSoP4jYQlY6RIzBgbssQqY3vxI2Pi+y71lOWWXX0=
Endpoint = [2607:5300:60:6b0::c05f:543]:2468
AllowedIPs = 10.192.122.4/32, 192.168.0.0/16
    
[Peer]
PublicKey = gN65BkIKy1eCE9pP1wdc8ROUtkHLF2PfAqYdyYBz6EA=
Endpoint = test.wireguard.com:18981
AllowedIPs = 10.10.10.230/32
.Ed
.Sh DEBUGGING INFORMATION
Sometimes it is useful to have
information on the current runtime state of a tunnel.
When using the Linux kernel module on a kernel that supports dynamic debugging,
debugging information can be written into
.Xr dmesg 1
by running as root:
.Pp
.Dl # modprobe wireguard && \e
.Dl echo module wireguard +p > /sys/kernel/debug/dynamic_debug/control
.Pp
On userspace implementations, it is customary to set the
.Ev LOG_LEVEL
environment variable to
.Cm debug .
.Sh ENVIRONMENT VARIABLES
.Bl -tag -width Ds
.It Ev WG_COLOR_MODE
If set to
.Cm always ,
always print ANSI colorized output.
If set to
.Cm never ,
never print ANSI colorized output.
If set to
.Cm auto ,
something invalid, or unset,
then print ANSI colorized output only when writing to a TTY.
.It Ev WG_HIDE_KEYS
If set to
.Cm never ,
then the pretty-printing
.Cm show
sub-command will show private and preshared keys in the output.
If set to
.Cm always ,
something invalid, or unset, then private and preshared keys will be printed as
.Ql Pq hidden .
.It Ev WG_ENDPOINT_RESOLUTION_RETRIES
If set to an integer or to
.Cm infinity ,
DNS resolution for each peer's endpoint will be retried that many times
for non-permanent errors, with an increasing delay between retries.
If unset, the default is 15 retries.
.El
.Sh SEE ALSO
.Xr ip 8 ,
.Xr ip-address 8 ,
.Xr ip-link 8 ,
.Xr ip-route 8 ,
.Xr wg-quick 8
.Sh AUTHORS
.An -nosplit
.Nm
was written by
.An Jason A. Donenfeld Aq Mt Jason@zx2c4.com .
For updates and more information, a project page is available
.Lk https://www.wireguard.com/ on the World Wide Web .


.Dd February 13, 2020
.Dt WG-QUICK 8
.Os
.Sh NAME
.Nm wg-quick
.Nd set up a WireGuard interface simply
.Sh SYNOPSIS
.Nm wg-quick
.Op Cm up | down | save | strip
.Op Ar CONFIG_FILE | INTERFACE
.Sh DESCRIPTION
This is an extremely simple script for easily bringing up a WireGuard interface,
suitable for a few common use cases.
.Pp
Use
.Cm up
to add and set up an interface, and use
.Cm down
to tear down and remove an interface.
Running
.Cm up
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
.Cm down
optionally saves the current configuration, removes the WireGuard interface,
and optionally runs pre/post down scripts.
Running
.Cm save
saves the configuration of an existing interface
without bringing the interface down.
Use
.Cm strip
to output a configuration file with all
.Nm wg-quick Ns -specific
options removed, suitable for use with
.Xr wg 8 .
.Pp
.Ar CONFIG_FILE
is a configuration file, whose filename is the interface name followed by
.Ql .conf .
Otherwise,
.Ar INTERFACE
is an interface name, with configuration found at
.Pa /etc/wireguard/INTERFACE.conf ,
searched first, followed by distro-specific search paths.
.Pp
Generally speaking,
this utility is just a simple script that wraps invocations to
.Xr wg 8
and
.Xr ip 8
in order to set up a WireGuard interface.
It is designed for users with simple needs,
and users with more advanced needs are highly encouraged to use a more
specific tool, a more complete network manager, or otherwise just use
.Xr wg 8
and
.Xr ip 8 ,
as usual.
.Sh CONFIGURATION
The configuration file adds a few extra configuration values
to the format understood by
.Xr 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
.Xr 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
.Xr ip-rule 8
to handle overriding of the default gateway.
.Pp
The configuration file will be passed directly to
.Xr wg 8 Ns 's
.Cm setconf
sub-command, with the exception of the following additions to the
.Ic Interface
section,
which are handled by this tool:
.Bl -tag -width Ds
.It Ic Address
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.
.It Ic DNS
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
.Ql resolvconf -a tun.INTERFACE -m 0 -x
and upon bringing it down, this runs
.Ql resolvconf -d tun.INTERFACE .
If these particular invocations of
.Xr resolvconf 8
are undesirable, the
.Ic PostUp
and
.Ic PostDown
keys below may be used instead.
.It Ic MTU
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.
.It Ic Table
Controls the routing table to which routes are added.
There are two special values:
.Cm off
disables the creation of routes altogether, and
.Cm auto
(the default) adds routes to the default table
and enables special handling of default routes.
.It Ic PreUp, PostUp, PreDown, PostDown
Script snippets which will be executed by
.Xr bash 1
before/after setting up/tearing down the interface,
most commonly used to configure custom DNS options or firewall rules.
The special string
.Ql %i
is expanded to
.Ar INTERFACE .
Each one may be specified multiple times,
in which case the commands are executed in order.
.It Ic SaveConfig
If set to
.Cm true ,
the configuration is saved from the current state of the interface upon
shutdown.
.El
.Pp
Recommended
.Ar INTERFACE
names include
.Ql wg0
or
.Ql wgvpn0
or even
.Ql 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
.Ql cincinnati ,
.Ql nyc ,
or
.Ql paris ,
if that's somehow desirable.
.Sh EXAMPLES
These examples draw on the same syntax found for
.Xr wg 8 ,
and a more complete description may be found there.
Bold lines below are for options that extend
.Xr wg 8 .
.Pp
The following might be used
for connecting as a client to a VPN gateway for tunneling all traffic:
.Bd -literal -offset Ds
[Interface]
Address = 10.200.100.8/24
DNS = 10.200.100.1
PrivateKey = oK56DE9Ue9zK76rAc8pBl6opph+1v36lm7cXXsQKrQM=

[Peer]
PublicKey = GtL7fZc/bLnqZldpVofMCD6hDjrK28SsdLxevJ+qtKU=
PresharedKey = /UwcSPg38hW/D9Y3tcS1FOV0K1wuURMbS0sesJEP5ak=
AllowedIPs = 0.0.0.0/0
Endpoint = demo.wireguard.com:51820
.Ed
.Pp
The
.Ic Address
field is added here in order to set up the address for the interface.
The
.Ic DNS
field indicates that a DNS server for the interface should be configured via
.Xr resolvconf 8 .
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
.Dq kill-switch ,
in order to prevent the flow of unencrypted packets through the non-WireGuard
interfaces, by adding the following two
.Ic PostUp
and
.Ic PreDown
lines to the
.Ql [Interface]
section:
.Bd -literal -offset Ds
PostUp = iptables -I OUTPUT ! -o %i -m mark ! --mark $(wg show %i fwmark) -m addrtype ! --dst-type LOCAL -j REJECT
PreDown = iptables -D OUTPUT ! -o %i -m mark ! --mark $(wg show %i fwmark) -m addrtype ! --dst-type LOCAL -j REJECT
.Ed
.Pp
The
.Ic PostUp
and
.Ic PreDown
fields have been added to specify an
.Xr iptables 8
command which, when used with interfaces that have a peer that specifies
0.0.0.0/0 as part of the
.Ic AllowedIPs ,
works together with
.Nm wg-quick Ns '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
.Xr ip6tables 8 .
.Pp
Or, perhaps it is desirable to store private keys in encrypted form,
such as through use of
.Xr pass 1 :
.Bd -literal -offset Ds
PostUp = wg set %i private-key <(pass WireGuard/private-keys/%i)
.Ed
.Pp
For use on a server,
the following is a more complicated example involving multiple peers:
.Bd -literal -offset Ds
[Interface]
Address = 10.192.122.1/24
Address = 10.10.0.1/16
SaveConfig = true
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
.Ed
.Pp
Notice the two
.Ic Address
lines at the top, and that
.Ic SaveConfig
is set to
.Cm true ,
indicating that the configuration file should be saved on shutdown using the
current status of the interface.
.Pp
A combination of the
.Ic Table ,
.Ic PostUp ,
and
.Ic 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:
.Bd -literal -offset Ds
[Interface]
Address = 10.192.122.1/24
PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk=
ListenPort = 51820
Table = 1234
PostUp = ip rule add ipproto tcp dport 22 table 1234
PreDown = ip rule delete ipproto tcp dport 22 table 1234

[Peer]
PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=
AllowedIPs = 0.0.0.0/0
.Ed
These configuration files may be placed in any directory,
putting the desired interface name in the filename:
.Pp
.Dl # wg-quick up /path/to/wgnet0.conf
.Pp
For convenience, if only an interface name is supplied,
it automatically chooses a path in
.Pa /etc/wireguard/ :
.Pp
.Dl # wg-quick up wgnet0
.Pp
This will load the configuration file
.Pa /etc/wireguard/wgnet0.conf .
.Pp
The
.Cm strip
command is useful for reloading configuration files without disrupting active
sessions:
.Pp
.Dl # wg addconf wgnet0 <(wg-quick strip wgnet0)
.Pp
(Note that the above command will add and update peers
but will not remove peers.)
.Sh SEE ALSO
.Xr ip 8 ,
.Xr ip-address 8 ,
.Xr ip-link 8 ,
.Xr ip-route 8 ,
.Xr ip-rule 8 ,
.Xr resolvconf 8 ,
.Xr wg 8
.Sh AUTHORS
.An -nosplit
.Nm wg-quick
was written by
.An Jason A. Donenfeld Aq Mt Jason@zx2c4.com .
For updates and more information, a project page is available
.Lk https://www.wireguard.com/ on the World Wide Web .
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: [PATCH] Fix formatting in wg-quick(8)

[Jason A. Donenfeld]

Hey Anthony,

Thanks for doing this. Looks like a step in the right direction.

A quick look indicates some weird changes, though:
- The ... in the command summary is now underlined and inside the [ ],
which seems different from other man pages on my machine.
- You got rid of the specifically bolded lines in some of the wg-quick
examples. As stated elsewhere in this thread, those are intentional.
- One of the wg-quick examples doesn't have a trailing new line,
making it look awkward with the next paragraph.
- You now put quotes around referenced commands instead of underlines.
Is that normal?
- IP addresses are now quoted instead of underlined. Is that normal?
It certainly sticks out less.
- You got rid of the <carrots> for sub command arguments. Is that
correct? Other commands seem to use the <carrots>.
- The indented example commands are no longer "blue", which seems odd.
- While some things are now quoted that were previously underlined,
other things that were emboldened are now quoted. What's up here?

Did you change any wording at all? It's quite important to me that the
actual words don't change at all without an explicit patch for that so
it can be reviewed. In other words, I don't want wording changes
sneaking in with the typesetting rewrite.

Again, thanks a lot for working on this. I really appreciate it.

Jason
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: [PATCH] Fix formatting in wg-quick(8)

[Ingo Schwarze]

Hi Jason,

Jason A. Donenfeld wrote on Fri, Feb 14, 2020 at 12:08:32PM +0100:

> Thanks for doing this. Looks like a step in the right direction.
> 
> A quick look indicates some weird changes, though:
> - The ... in the command summary

You mean, in the SYNOPSIS?

> is now underlined

Yes, that's the usual convention.  It is a placeholder, so it should
be set with .Ar and consequently in italics.

> and inside the [ ],

Yes, that's the usual convention, and it also makes sense logically.
If you don't provide even a single option, you cannot possibly provide
more than one option.

> which seems different from other man pages on my machine.

It looks like you copied unusual or low-quality examples.

> - You got rid of the specifically bolded lines in some of the wg-quick
> examples. As stated elsewhere in this thread, those are intentional.

Restored.

I don't think bold font is needed in example blocks that would become
bold as a whole: that would look rather heavy, and no distinction
needs to be made there.  Then again, your call.

> - One of the wg-quick examples doesn't have a trailing new line,
> making it look awkward with the next paragraph.

.Pp inserted

> - You now put quotes around referenced commands instead of underlines.
> Is that normal?

You mean, as in this description:

  PrivateKey
    A base64 private key generated by 'wg genkey'.
    Required.

It should probably just be

  A base64 private key generated by
  .Ic genkey .

But i think Anthony did not want to change the wording.  He could have
gone for

  A base64 private key generated by
  .Nm
  .Ic genkey .

which would be most logical, but he chose to treat it as an in-line
example command instead, which is commonly marked up with .Ql.

Using italics here would clearly be wrong.  This is not a placeholder
for something else.

> - IP addresses are now quoted instead of underlined. Is that normal?
> It certainly sticks out less.

I'm not aware of any established convention for IP adresses.  The reason
probably is that specific IP addresses rarely appear in manual
pages.  Usually, manual pages contain placeholders for IP addresses
to be filled in by users.

When it's a fixed string like 0.0.0.0/0 or ::/0, it could be marked
up with .Cm.  Using .Ql as Anthony chose to feels acceptable, too.

You could maybe argue an IP address is a bit like a file and use .Pa,
but it wouldn't be my first choice.  If you want fixed IPs to stick
out, bold would seem more natural than italics, so i'd prefer .Cm
over .Pa.

> - You got rid of the <carrots> for sub command arguments. Is that
> correct?

Yes.

> Other commands seem to use the <carrots>.

It is a bad habit seen in a few manual pages, but not very widespread
and certainly not recommended.

The mdoc(7) manual page specifically advises against it:

  https://man.openbsd.org/mdoc.7#Aq_2

  "Never wrap Ar in Aq."

> - The indented example commands are no longer "blue", which seems odd.

I don't understand what you mean by "blue".

> - While some things are now quoted that were previously underlined,
> other things that were emboldened are now quoted. What's up here?

Standard markup, see mdoc(7):

  Ql line
    In-line literal display.  This can be used for complete command
    invocations and for multi-word code examples when an indented
    display is not desired.

For example, that applies to:

  <(echo PRIVATEKEYSTRING)
  wg genkey
  (hidden)
  resolvconf -a tun.INTERFACE -m 0 -x

For stuff like

  off
  0x
  0.0.0.0/0
  ::/0

i might use .Cm, but that's really a minor detail.

Italics are certainly overused in the manual pages you now have in git.

> Did you change any wording at all?

I don't think Anthony changed any wording, at least i don't see any
wording changes.  He even stuck to the existing punctuation.

> It's quite important to me that the
> actual words don't change at all without an explicit patch for that so
> it can be reviewed. In other words, I don't want wording changes
> sneaking in with the typesetting rewrite.
> 
> Again, thanks a lot for working on this. I really appreciate it.

I suggest that you apply the minor corrections appended below to
what Anthony sent and commit the result.  After that, having the
main conversion out of the way, further refinement can be done with
individual patches.

Yours,
  Ingo


--- wg.bentley.8.orig	Fri Feb 14 14:28:31 2020
+++ wg.bentley.8	Fri Feb 14 14:54:38 2020
@@ -79,7 +79,7 @@
 Sets configuration values for the specified
 .Ar interface .
 Multiple
-Ar peer Ns s
+.Ar peer Ns s
 may be specified, and if the
 .Cm remove
 argument is given for a peer, that peer is removed, not configured.
@@ -202,7 +202,7 @@
 section may be specified.
 .Pp
 The
-.Ar Interface
+.Ic Interface
 section may contain the following fields:
 .Bl -tag -width Ds
 .It Ic PrivateKey
--- wg-quick.bentley.8.orig	Fri Feb 14 14:28:57 2020
+++ wg-quick.bentley.8	Fri Feb 14 15:38:28 2020
@@ -161,8 +161,10 @@
 for connecting as a client to a VPN gateway for tunneling all traffic:
 .Bd -literal -offset Ds
 [Interface]
+.Bf Sy
 Address = 10.200.100.8/24
 DNS = 10.200.100.1
+.Ef
 PrivateKey = oK56DE9Ue9zK76rAc8pBl6opph+1v36lm7cXXsQKrQM=
 
 [Peer]
@@ -226,9 +228,11 @@
 the following is a more complicated example involving multiple peers:
 .Bd -literal -offset Ds
 [Interface]
+.Bf Sy
 Address = 10.192.122.1/24
 Address = 10.10.0.1/16
 SaveConfig = true
+.Ef
 PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk=
 ListenPort = 51820
 
@@ -267,14 +271,17 @@
 Address = 10.192.122.1/24
 PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk=
 ListenPort = 51820
+.Bf Sy
 Table = 1234
 PostUp = ip rule add ipproto tcp dport 22 table 1234
 PreDown = ip rule delete ipproto tcp dport 22 table 1234
+.Ef
 
 [Peer]
 PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=
 AllowedIPs = 0.0.0.0/0
 .Ed
+.Pp
 These configuration files may be placed in any directory,
 putting the desired interface name in the filename:
 .Pp
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: [PATCH] Fix formatting in wg-quick(8)

[Ingo Schwarze]

Hi Anthony,

Anthony J. Bentley wrote on Thu, Feb 13, 2020 at 09:00:19PM -0700:

> My attempt is below.

Thanks!

> - There were a few places like this where I wasn't sure if squeezing Ar
>   in there might be overkill:
> 
>     Upon bringing the interface up, this runs
>     .Ql resolvconf -a tun.INTERFACE -m 0 -x
>     and upon bringing it down, this runs
>     .Ql resolvconf -d tun.INTERFACE .

Right, these are somewhat ugly.  Long in-line code examples tend
to look ugly in general, but where they can't be avoided, .Ql is
the right macro to use.  This can hardly be improved without
rewording the text, which you rightly avoided during the conversion.

It is technically possible to use .Ar inside .Ql, but i'd say
it is better avoided.

> - Does the config file support statements across multiple lines (with
>   backslash or some such)? Then we could avoid the ugly wrapping in
>   wg-quick(8)'s EXAMPLES.
> 
> - Wasn't there discussion on the Groff list about moving to title case
>   instead of all caps in section headers? Is that something we want to
>   encourage in downstream manuals?

Not yet, maybe in the future.  Groff now supports the new way.
Support in mandoc is still pending.  Before advertising it widely,
we should make a decision for OpenBSD base.

> - Not sure of my use of Bro/Brc.

Usually, such braces are not needed, we almost never use them in
OpenBSD base.  Then again, you didn't want to change the wording
or the punctuation, and retaining them isn't wrong.  If you want
curlies here, then .Bro is the right macro.

> - The hanging indent in long tag list items seems problematic here.
>   Suggestions?

As any other details, that can be polished after commit.

Ultimately, i would probably recommend something like

  .It Ic set Ar interface Op Ar options
  Set configuration values for the specified
  .Ar interface .
  .Pp
  The options are as follows:
  .Bl -tag -width Ds
  .It Cm fwmark Ar fwmark
  The 32-bit [replace jargon word by an actual description]
  for outgoing packets, either as a decimal integer or as a
  hexadecimal integer starting with
  .Ql 0x .
  The default is 0 [which disables the feature; or even better, say
  more precisely what it means when this feature is "off"].
  The special value
  .Cm off
  is an alias for 0 [or even better, deprecate the duplication
  in the user interface and stop documenting it].
  .It Cm listen-port Ar port
  [A description is missing here what it means.]
  The default is 0, which causes a port to be chosen randomly when
  the interface comes up.
  .It [...]

and so one.  Usually, tagged lists are more readable than long
paragraphs of prose with keywords scattered in the middle.

Yes, i do think the page still needs some work after this initial
conversion, also regarding the content, but that is better done in
multiple steps, each patch focussed on one aspect, with careful
review of each patch.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: [PATCH] Fix formatting in wg-quick(8)

[Anthony J. Bentley]

Hi Jason,

Forgive brevity, I have no computer this weekend.

Jason A. Donenfeld writes:
> - You got rid of the specifically bolded lines in som
> e of the wg-quick
> examples. As stated elsewhere in this thread, those a
> re intentional.

Sorry, I overlooked that.

> - One of the wg-quick examples doesn't have a trailin
> g new line,
> making it look awkward with the next paragraph.

Mistake, I think Ingo corrected it.

> - The ... in the command summary is now underlined an
> d inside the [ ],
> which seems different from other man pages on my mach
> ine.
> - You now put quotes around referenced commands inste
> ad of underlines.
> Is that normal?
> - IP addresses are now quoted instead of underlined. 
> Is that normal?
> It certainly sticks out less.
> - You got rid of the <carrots> for sub command argume
> nts. Is that
> correct? Other commands seem to use the <carrots>.
> - The indented example commands are no longer "blue",
>  which seems odd.
> - While some things are now quoted that were previous
> ly underlined,
> other things that were emboldened are now quoted. Wha
> t's up here?

These formatting changes more or less come with the
mdoc semantic markup. This is consistent with BSD man
page style. There are some conflicts with the non-mdoc
way of doing things perhaps. In general I think the
semantics are worth it (especially with mandoc's
searching, tagging, HTML generation capabilities).

> Did you change any wording at all? It's quite importa
> nt to me that the
> actual words don't change at all without an explicit 
> patch for that so
> it can be reviewed. In other words, I don't want word
> ing changes
> sneaking in with the typesetting rewrite.

Except where I introduced semantic markup, I tried to
keep things the same. It's possible there's a place or
two where I changed something without thinking. But I
tried to avoid it.

> Again, thanks a lot for working on this. I really app
> reciate it.

Side note... last time I poked at WireGuard manpages, it resulted in
this commit:
https://github.com/openbsd/src/commit/df9a9479ddee899e1995f8eba1983628deecbec6

-- 
Anthony J. Bentley
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

[PATCH v2] Rewrite wg-quick.8 in mdoc

[Stephen Gregoratto]

Since the program arguments are semantically marked-up as such, I've
made them lower-case so the manual isn't yelling at us.

Some of text has been reworded slightly to better fit manpage
conventions. I've also wrapped the text to 80 chars.

Signed-off-by: Stephen Gregoratto <dev@sgregoratto.me>
---
For some reason, groff produces this warning, even though it's formatted
correctly:

troff: wg-quick.8:314: name expected (got '\c'): treated as missing

I'm working on simplifying the structure of wg.8 in addition to
rewriting it, which will take some time.

 src/man/wg-quick.8 | 564 ++++++++++++++++++++++++---------------------
 1 file changed, 303 insertions(+), 261 deletions(-)

diff --git a/src/man/wg-quick.8 b/src/man/wg-quick.8
index c38c7d9..2ed90a5 100644
--- a/src/man/wg-quick.8
+++ b/src/man/wg-quick.8
@@ -1,277 +1,319 @@
-.TH WG-QUICK 8 "2016 January 1" ZX2C4 "WireGuard"
-
-.SH NAME
-wg-quick - set up a WireGuard interface simply
-
-.SH SYNOPSIS
-.B wg-quick
-[
-.I up
-|
-.I down
-|
-.I save
-|
-.I strip
-] [
-.I CONFIG_FILE
-|
-.I INTERFACE
-]
-
-.SH DESCRIPTION
-
+.Dd February 14, 2020
+.Dt WG-QUICK 8
+.Os
+.Sh NAME
+.Nm wg-quick
+.Nd set up a WireGuard interface simply
+.Sh SYNOPSIS
+.Nm
+.Op Cm up | down | sconfig-file
+.Op Ar config-file
+.Op Ar interface
+.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
+.Cm up
+to add and set up an interface, and use
+.Cm down
+to tear down and remove an interface.
+Running
+.Cm up
+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
+.Cm down
+optionally saves the current configuration, removes the WireGuard interface, and
+optionally runs pre/post down scripts.
+Running
+.Cm save
+saves the configuration of an existing interface without bringing the interface
+down.
+Use
+.Cm strip
+to output a configuration file with all
+.Nm Ns -specific
 options removed, suitable for use with
-.BR wg (8).
-
-\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
-.BR wg (8)
+.Xr wg 8 .
+.Pp
+.Ar config-file
+is a configuration file, whose filename is the interface name followed by
+.Ql \&.conf .
+Otherwise,
+.Ar interface
+is an interface name, with configuration found at
+.Pa /etc/wireguard/interface.conf ,
+searched first, followed by distro-specific search paths.
+.Pp
+Generally speaking, this utility is just a simple script that wraps invocations
+to
+.Xr wg 8
 and
-.BR ip (8)
-in order to set up a WireGuard interface. It is designed for users with simple
-needs, and users with more advanced needs are highly encouraged to use a more
-specific tool, a more complete network manager, or otherwise just use
-.BR wg (8)
+.Xr ip 8
+in order to set up a WireGuard interface.
+It is designed for users with simple needs, and users with more advanced needs
+are highly encouraged to use a more specific tool, a more complete network
+manager, or otherwise just use
+.Xr wg 8
 and
-.BR ip (8),
+.Xr ip 8
 as usual.
-
-.SH CONFIGURATION
-
-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)
+.Sh CONFIGURATION
+The configuration file adds a few extra configuration values to the format
+understood by
+.Xr 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
+.Xr 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
+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)
+.Xr ip-rule 8
 to handle overriding of the default gateway.
-
-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:
-
-.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.
-.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
-.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.
-.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'
+.Pp
+The configuration file will be passed directly to
+.Xr wg 8 Ap s
+.Cm setconf
+sub-command, with the exception of the following additions to the INTERFACE
+section, which are handled by this tool:
+.Bl -tag -width Ds
+.It Cm Address
+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.
+.It Cm DNS
+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
+.Pp
+.Dl resolvconf -a tun.interface -m 0 -x
+.Pp
+and upon
+bringing it down, this runs
+.Pp
+.Dl resolvconf -d tun.interface .
+.Pp
+If these particular invocations of
+.Xr resolvconf 8
+are undesirable, the
+.Cm PostUp
+and
+.Cm PostDown
+keys below may be used instead.
+.It Cm MTU
+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.
+.It Cm Table
+Controls the routing table to which routes are added.
+There are two special values:
+.Cm off
+disables the creation of routes altogether, and
+.Cm auto
 (the default) adds routes to the default table and enables special handling of
 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.
-.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'.
+.It Cm PreUp , PostUp , PreDown , PostDown
+Script snippets which will be executed by
+.Xr bash 1
+before/after setting up/tearing down the interface, most commonly used to
+configure custom DNS options or firewall rules.
+The special string
+.Ql %i
+is expanded to
+.Ar interface .
+Each one may be specified multiple times, in which case the commands are
+executed in order.
+.It Cm SaveConfig
+If set to
+.Cm true ,
+the configuration is saved from the current state of the interface upon
+shutdown.
+.El
+.Pp
+Recommended
+.Ar interface
+names include
+.Ql wg0
+or
+.Ql wgvpn0
+or even
+.Ql 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
-
+any free-form string [a-zA-Z0-9_=+.-]{1,15} will work.
+So even interface names corresponding to geographic locations would suffice,
+such as
+.Ql cincinnati , nyc
+or
+.Ql 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
-.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
-.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 `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
-.BR ip6tables (8).
-
-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
+.Xr wg 8 ,
+and a more complete description may be found there.
+.Pp
+The following might be used for connecting as a client to a VPN gateway for
+tunneling all traffic:
+.Bd -literal -offset indent
+[Interface]
+Address = 10.200.100.8/24
+DNS = 10.200.100.1
+PrivateKey = oK56DE9Ue9zK76rAc8pBl6opph+1v36lm7cXXsQKrQM=
+
+[Peer]
+PublicKey = GtL7fZc/bLnqZldpVofMCD6hDjrK28SsdLxevJ+qtKU=
+PresharedKey = /UwcSPg38hW/D9Y3tcS1FOV0K1wuURMbS0sesJEP5ak=
+AllowedIPs = 0.0.0.0/0
+Endpoint = demo.wireguard.com:51820
+.Ed
+.Pp
+The
+.Cm Address
+field is added here in order to set up the address for the interface.
+The
+.Cm DNS
+field indicates that a DNS server for the interface should
+be configured via
+.Xr resolvconf 8 .
+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
+.Dq kill-switch ,
+in order to prevent the flow of unencrypted packets through the non-WireGuard
+interfaces, by adding the following two lines
+.Cm PostUp
+and
+.Cm PreDown
+lines to
+.Cm [Interface]
+section:
+.Bd -literal -offset indent
+PostUp = iptables -I OUTPUT ! -o %i -m mark ! --mark $(wg show %i fwmark) -m addrtype ! --dst-type LOCAL -j REJECT
+PreDown = iptables -D OUTPUT ! -o %i -m mark ! --mark $(wg show %i fwmark) -m addrtype ! --dst-type LOCAL -j REJECT
+.Ed
+.Pp
+The
+.Cm PostUp
+and
+.Cm PreDown
+fields have been added to specify an
+.Xr iptables 8
+command which, when used with interfaces that have a peer that specifies
+0.0.0.0/0 as part of the
+.Cm AllowedIPs ,
+works together with
+.Nm Ap 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
+.Xr ip6tables 8 .
+.Pp
+Or, perhaps it is desirable to store private keys in encrypted form, such as
+through use of
+.Xr pass 1 :
+.Pp
+.Dl PostUp = wg set %i private-key <(pass WireGuard/private-keys/%i)
+.Pp
+For use on a server, the following is a more complicated example involving
+multiple peers:
+.Bd -literal -offset indent
+[Interface]
+Address = 10.192.122.1/24
+Address = 10.10.0.1/16
+SaveConfig = true
+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
+.Ed
+.Pp
+Notice the two
+.Cm Address
+lines at the top, and that
+.Cm SaveConfig
+is set to
+.Cm true ,
+indicating that the configuration file should be saved on shutdown using
+the current status of the interface.
+.Pp
+A combination of the
+.Cm Table , PostUp
+and
+.Cm 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
-
-This will load the configuration file `/etc/wireguard/wgnet0.conf'.
-
-The \fIstrip\fP command is useful for reloading configuration files without disrupting active
+.Bd -literal -offset indent
+[Interface]
+Address = 10.192.122.1/24
+PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk=
+ListenPort = 51820
+Table = 1234
+PostUp = ip rule add ipproto tcp dport 22 table 1234
+PreDown = ip rule delete ipproto tcp dport 22 table 1234
+
+[Peer]
+PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=
+AllowedIPs = 0.0.0.0/0
+.Ed
+.Pp
+These configuration files may be placed in any directory, putting the desired
+interface name in the filename:
+.Pp
+.Dl # wg-quick up /path/to/wgnet0.conf
+.Pp
+For convenience, if only an interface name is supplied, it automatically chooses
+a path in
+.Pa /etc/wireguard :
+.Pp
+.Dl # wg-quick up wgnet0
+.Pp
+This will load the configuration file
+.Pa /etc/wireguard/wgnet0.conf .
+.Pp
+The
+.Cm strip
+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.)
-
-.SH SEE ALSO
-.BR wg (8),
-.BR ip (8),
-.BR ip-link (8),
-.BR ip-address (8),
-.BR ip-route (8),
-.BR ip-rule (8),
-.BR resolvconf (8).
-
-.SH AUTHOR
-.B wg-quick
-was written by
-.MT Jason@zx2c4.com
-Jason A. Donenfeld
-.ME .
-For updates and more information, a project page is available on the
-.UR https://\:www.wireguard.com/
-World Wide Web
-.UE .
+.Pp
+.Dl # wg addconf wgnet0 <(wg-quick strip wgnet0)
+.Pp
+(Note that the above command will add and update peers but will not remove
+peers.)
+.Sh SEE ALSO
+.Xr pass 1 ,
+.Xr ip 8 ,
+.Xr ip-address 8 ,
+.Xr ip-link 8 ,
+.Xr ip-route 8 ,
+.Xr ip-rule 8 ,
+.Xr iptables 8 ,
+.Xr resolvconf 8 ,
+.Xr wg 8
+.Pp
+For updates and more information, a project page is available at
+.Lk https://www.wireguard.com .
+.Sh AUTHORS
+The
+.Nm
+program was written by
+.An Jason A. Donenfeld Aq Mt Jason@zx2c4.com .
-- 
2.25.0

--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: [PATCH v2] Rewrite wg-quick.8 in mdoc

[Jason A. Donenfeld]

Hi Stephen,

Thanks for doing this. I appreciate it. I can manually diff the text
to the old one if you insist, but I'd really prefer to see either a
list of what text you changed or having the type setting and the text
change done in separate commits. Alternatively, if you refuse to do
that, I'll manually diff, but I'd rather not if you can remember what
you changed.

>  I'm working on simplifying the structure of wg.8 in addition to
> rewriting it, which will take some time.

If there are any changes to content, rather than just the typesetting,
please make this separate commits.

Jason
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: [PATCH v2] Rewrite wg-quick.8 in mdoc

[Stephen Gregoratto]

Hi Jason,

On Sat Feb 15, 2020 at 8:53 PM, Jason A. Donenfeld wrote:
> Thanks for doing this. I appreciate it. I can manually diff the text
> to the old one if you insist, but I'd really prefer to see either a
> list of what text you changed or having the type setting and the text
> change done in separate commits.

The changes made are very minor:

The config_file and interface arguments were made lowercase, and all
mention of them in the rest of the manual has been changed as well.

The interface additions were changed from a bulleted list to a
definition list, where the additions were the definitions.

I removed the boldening in the examples along with the sentance:
  
  "Bold lines below are for options that extend wg(8)."

The justification was that since the [interface] additions were
properly marked up in the example explanations, having the lines be
emboldened was redundant. You can see the difference better when viewing
them as PDF's through groff side-by-side. If you'd like I can revert
this.

As mentioned by Ingo, more manual references were added to the SEE ALSO
section, with them being sorted in section-name order. I also moved the
link to the project page into this section, and dropped the "World Wide
Web" bit.

Finally, the AUTHORS section was reworded slightly:

 original:  "wg-quick was written by..."
 new:       "The wg-quick program was written by..."

This is a convention for system programs.


As for Anthony's work, this seems to be a case of "convergent
evolution," since our work is very similar ;). I think if I combine the
best parts of both, along with Ingo's comments, I could prepare a final
patch for wg-quick. I'm not sure if everyone that helped needs to sign
off on the patch, but I'll make sure they're mentioned.

For the next patch, would you like to see the list above in the commit
message?
-- 
Stephen Gregoratto
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: [PATCH v2] Rewrite wg-quick.8 in mdoc

[Ingo Schwarze]

Hi,

i think Jason should simply commit Anthony's work because that's
what i verified in detail (given that it arrived a day earlier).
There is no point in attempting to merge large patches out of the
tree: that would be tedious and error-prone.

Just let Jason do the commits to his own repo.  Discussing commit
messages and adding signed-off lines is a waste of time.

Once the conversion is committed, people can submit smaller patches
to improve things further.  Those will be much easier to review.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv