Page MenuHomeFreeBSD

wg(4): Add a man page
ClosedPublic

Authored by gbe on Dec 27 2020, 4:51 PM.

Details

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

Diff Detail

Repository
R10 FreeBSD src repository
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

gbe requested review of this revision.Dec 27 2020, 4:51 PM
brueffer added inline comments.
share/man/man4/wg.4
46

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

81

Pre-shared

122

pre-shared

212

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

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 marked 4 inline comments as done.Jan 3 2021, 10:45 AM
gbe added inline comments.
share/man/man4/wg.4
212

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 added inline comments.
share/man/man4/wg.4
158–159
PUBx="``ifconfig wgx | awk '/wgpubkey/ { print $2 }'`"

is a more stable parser.

gbe marked an inline comment as done.

Update the example

  • Replace the wgpubkey retrieval to the one Lutz has provided
  • Use wg0 and wg1 interfaces instead of wg1 and wg2
gbe marked an inline comment as done.Jan 3 2021, 11:45 AM
gbe added inline comments.
share/man/man4/wg.4
158–159

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

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

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

gbe marked an inline comment as done.
  • wg(4): Provide a list of ifconfig options and simplify the EXAMPLES section
gbe marked 2 inline comments as done.Jan 30 2021, 5:45 PM

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

gbe marked 2 inline comments as done.Jan 30 2021, 5:46 PM
gbe added a subscriber: debdrup.
This revision is now accepted and ready to land.Jan 30 2021, 6:02 PM
This revision was automatically updated to reflect the committed changes.