wg(4): Add a man page

[gbe]

Summary

Add a man page for the recently introduced WireGuard kernel driver.

It would be nice if some could update the example, since I was no able
to get it working. The rdomain stuff is OpenBSD specific, but rest should
have been worked.

Obtained from: OpenBSD

Test Plan

mandoc output review and 'mandoc -Tlint' checks

[gbe]

• Grammar fix

[brueffer]

share/man/man4/wg.4

47

Here and in all other ".Nm wg" cases just .Nm is enough, since above it has been defined as "wg".

82

Pre-shared

123

pre-shared

213

Any reason to specifically reference pf, but not ipf or ipfw?

[gbe]

Update to include @brueffer suggestions

• Only use .Nm (with wg) since is defined at the top of the man page
• preshared -> pre-shared
• also mention ipf and ipfw

[gbe]

share/man/man4/wg.4

213

The SEE ALSO list was entirely taken from the OpenBSD version. I have included ipf and ipfw in the new revision of this differential.

[donner]

share/man/man4/wg.4

159–160

PUBx="``ifconfig wgx | awk '/wgpubkey/ { print $2 }'`"

is a more stable parser.

[gbe]

Update the example

• Replace the wgpubkey retrieval to the one Lutz has provided
• Use wg0 and wg1 interfaces instead of wg1 and wg2

[gbe]

share/man/man4/wg.4

159–160

I updated the example with your shell command. Did you have any idea why the generation if the interfaces fails?

% ifconfig wg0 create wgport 7111 wgkey openssl rand -base64 32
ifconfig: fdUc4AW+MLdUpDGrQrHc47YlN3kAR73hKyMokSdJzxA=: bad value

[donner]

The example is more instructive, if it is split between two machines and follow the two step setup. Do not try to automate the communication by a script, it's erronous and not instructive. Remember to always use documentaion IP addresses (RFC 5737)

In order to connect two machines (A and B), create an interface first:

A# ifconfig wg0 create wgport $port wgkey "$(openssl rand -base64 32)"
A# ifconfig wg0 inet 192.0.2.1/32 alias

and on the other one

B# ifconfig wg0 create wgport $port wgkey "$(openssl rand -base64 32)"
B# ifconfig wg0 inet 192.0.2.2/32 alias

Then obtain the relevant information from the interface output

A# ifconfig wg0
... show the example output ...
A# ifconfig em0 inet # external interface
... show the example output ...

Now you need to communicate the the external IP, the wgport and the wgkey paramaters to your peer.
Each party finish the setup by supplying the peer's information.
A# ifconfig wg0 wgpeer "peerkey" wgendpoint "externalpeerip" "peerport" wgaip "peerip"
and
B# ifconfig wg0 wgpeer "peerkey" wgendpoint "externalpeerip" "peerport" wgaip "peerip"

Now you can ping to the other side.
A# ping "peerip"

share/man/man4/wg.4

149

It's probably more instructive to have a parametric script, which creates one endpoint only. And then run this script on two machines in order to demonstrate the use case for the reader of the man page.

163–164

That's a dangerous syntax. Please stick to

ifconfig wg0 inet 192.168.5.1/24 alias

[donner]

Please add the description of the parameters (wgkey, wgport, ...) or point to the appropriate part in ifconfig(8) man page.

[gbe]

• wg(4): Provide a list of ifconfig options and simplify the EXAMPLES section

[gbe]

@donner I added the ifconfig options as requested, they are different in comparison to OpenBSD, so thanks for pointing this out.

share/man/man4/wg.4

149

I reworked the EXAMPLES to demonstrated the basic usage.

163–164

I reworked the EXAMPLES to demonstrated the basic usage.

[debdrup]

Looks good to me.

[ygy]

Looks good to me!