Bug 253866 - if_wg(4) manpage: fix typo and example command
Summary: if_wg(4) manpage: fix typo and example command
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Some People
Assignee: Guangyuan Yang
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2021-02-26 09:46 UTC by Sergey Akhmatov
Modified: 2021-03-11 18:11 UTC (History)
7 users (show)

See Also:


Attachments
wg(4) manpage fix (842 bytes, patch)
2021-02-26 09:46 UTC, Sergey Akhmatov
no flags Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Sergey Akhmatov 2021-02-26 09:46:28 UTC
Created attachment 222840 [details]
wg(4) manpage fix

- typo: "listing port" should be "listening"
- "public-key" keyword is missing in example
Comment 1 Guangyuan Yang freebsd_committer 2021-02-28 18:42:44 UTC
This looks fine to me. +gbe what do you think?
Comment 2 Gordon Bergling freebsd_committer 2021-03-03 17:16:32 UTC
(In reply to Guangyuan Yang from comment #1)

The examples are correct, I just verified them. listing-port is so correct and if the example is executed as stated, the following interface is created.

wg0: flags=8080a0<NOARP,MULTICAST> metric 0 mtu 1420
	options=880000<LINKSTATE>
	groups: wg
	listen-port: 54321
	public-key:  0BJLbbnoA4Bt3fXWiRCFdcKq4xXu8fGYwbmJPZMik1U=
	media: Ethernet autoselect (25GBase-ACC <full-duplex>)
	status: active
	nd6 options=21<PERFORMNUD,AUTO_LINKLOCAL>

The 'public-key' keyword could somehow integrated in the manual page, but for the mentioned examples the public-key is generated based on the private-key of wg interface.
Comment 3 Sergey Akhmatov 2021-03-04 16:21:56 UTC
(In reply to Gordon Bergling from comment #2)
Hello,

Example configuring wg0 interface is correct, the problem is with adding peers.

My steps to reproduce, are exact copy-paste from man if_wg (FreeBSD bsd-current 14.0-CURRENT FreeBSD 14.0-CURRENT #5 main-n245256-37cd6c20dbc):
# ifconfig wg0 create listen-port 54321 private-key `openssl rand -base64 32`

Checking created interface:
# ifconfig wg0
wg0: flags=8080a0<NOARP,MULTICAST> metric 0 mtu 1420
        options=880000<LINKSTATE>
        groups: wg
        listen-port: 54321
        private-key: SKQetK9X4MaHh7bXE/Y6mRgtZylRH5mp9Fj+reRP0no=
        public-key:  13+dUrtLJ6kt+mbWmGJeBppliygNq4WhmjOXjO4xrkA=
        media: Ethernet autoselect (25GBase-ACC <full-duplex>)
        status: active
        nd6 options=29<PERFORMNUD,IFDISABLED,AUTO_LINKLOCAL>

Adding peer from manpage example:
# ifconfig wg0 peer '7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=' endpoint 10.0.1.100 allowed-ips 192.168.2.100/32
ifconfig: 7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=: bad value

Adding "public-key" before the key itself:
# ifconfig wg0 peer public-key '7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=' endpoint 10.0.1.100 allowed-ips 192.168.2.100/32
ifconfig: bad endpoint format 10.0.1.100 - no port delimiter found

Better, but we are still missing portnumber for peer. Adding port:
# ifconfig wg0 peer public-key '7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=' endpoint 10.0.1.100:54321 allowed-ips 192.168.2.100/32
[Peer]
PublicKey = 7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=
Endpoint = 10.0.1.100:54321
AllowedIPs = 192.168.2.100/32


Now it's OK.

Could you please review it once more and point me if I'm doing something wrong. I'll update patch, adding portnumber to peer IP if needed.

And, BTW, the term "listing port" just doesn't make any sense to me in this context:
"listen-port
   The listing port of the wg interface."
English is not my native, but could you explain why is it correct? There is not a single word "listing" in wireguard doc (https://www.wireguard.com/papers/wireguard.pdf), while "listening port" would make sense here.
Comment 4 Gordon Bergling freebsd_committer 2021-03-04 20:25:33 UTC
(In reply to Sergey Akhmatov from comment #3)

Thanks for opening that bug again. Your are right that the mentioned examples in the manual page aren't consistent. I will come up with a man page update the upcoming weekend and add you as reviewer on the FreeBSD Phabricator.

For the man page update we have to separate ifconfig syntax strangeness, but I think this is logical.

Thanks for having an eye on the details.
Comment 5 Daniel Ebdrup Jensen freebsd_committer 2021-03-05 12:33:30 UTC
Shouldn't this also go in releng/13.0 so it'll be in 13.0-RELEASE?
Comment 6 Gordon Bergling freebsd_committer 2021-03-06 14:16:35 UTC
(In reply to Daniel Ebdrup Jensen from comment #5)

Thats correct, the man page update is upcoming.
Comment 7 commit-hook freebsd_committer 2021-03-07 19:30:51 UTC
A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/src/commit/?id=f7bfe310191c8292da51c8da166a521ff16e0e46

commit f7bfe310191c8292da51c8da166a521ff16e0e46
Author:     Gordon Bergling <gbe@FreeBSD.org>
AuthorDate: 2021-03-07 19:27:59 +0000
Commit:     Gordon Bergling <gbe@FreeBSD.org>
CommitDate: 2021-03-07 19:27:59 +0000

    wg(4): Fix an example in the manual page

    The example in the manual page of wg(4) for connecting to a
    peer was missing the 'public-key' ifconfig(8) keyword and for the
    addressed peer the port must be specified.

    PR:     253866
    Reported by:    Sergey Akhmatov <sergey at akhmatov dot ru>
    Reviewed by:    debdrup
    MFC after:      3 days
    Differential Revision:  https://reviews.freebsd.org/D29115

 share/man/man4/wg.4 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Comment 8 crest 2021-03-08 13:12:34 UTC
Is there an example to remove a peer or update a peer's endpoint address and port?
Comment 9 crest 2021-03-08 13:21:03 UTC
And the manpage should probably warn users lock down the permissions on /etc/rc.conf before they put the private key in it.
Comment 10 Kyle Evans freebsd_committer 2021-03-09 03:13:06 UTC
(In reply to crest from comment #8)

There's currently no way with ifconfig(8) to remove a peer; I'll plumb that through next.

AFAICT, updating a peer should just be to specify the parameters again; if the public-key exists, it should update endpoint/allowed-ip.
Comment 11 crest 2021-03-10 14:21:21 UTC
But what about removing attributes or peers e.g. removing an allowed IP from a peer or the persistent keepalive interval? Are users to supposed to set all of peer attributes if they mention the peer or even set the whole interface configuration at once and have ifconfig remove everything neither changed nor repeated?
Comment 12 commit-hook freebsd_committer 2021-03-11 17:44:04 UTC
A commit in branch stable/13 references this bug:

URL: https://cgit.FreeBSD.org/src/commit/?id=b97735743718e13ac8662930d7aa2cb2e495d563

commit b97735743718e13ac8662930d7aa2cb2e495d563
Author:     Gordon Bergling <gbe@FreeBSD.org>
AuthorDate: 2021-03-07 19:27:59 +0000
Commit:     Gordon Bergling <gbe@FreeBSD.org>
CommitDate: 2021-03-11 17:43:25 +0000

    wg(4): Fix an example in the manual page

    The example in the manual page of wg(4) for connecting to a
    peer was missing the 'public-key' ifconfig(8) keyword and for the
    addressed peer the port must be specified.

    PR:     253866
    Reported by:    Sergey Akhmatov <sergey at akhmatov dot ru>
    Reviewed by:    debdrup
    Differential Revision:  https://reviews.freebsd.org/D29115

    (cherry picked from commit f7bfe310191c8292da51c8da166a521ff16e0e46)

 share/man/man4/wg.4 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Comment 13 commit-hook freebsd_committer 2021-03-11 18:04:09 UTC
A commit in branch releng/13.0 references this bug:

URL: https://cgit.FreeBSD.org/src/commit/?id=2b1bcf70b4d1a8ef62415cbb89890f08ae57a447

commit 2b1bcf70b4d1a8ef62415cbb89890f08ae57a447
Author:     Gordon Bergling <gbe@FreeBSD.org>
AuthorDate: 2021-03-07 19:27:59 +0000
Commit:     Gordon Bergling <gbe@FreeBSD.org>
CommitDate: 2021-03-11 18:02:51 +0000

    wg(4): Fix an example in the manual page

    The example in the manual page of wg(4) for connecting to a
    peer was missing the 'public-key' ifconfig(8) keyword and for the
    addressed peer the port must be specified.

    PR:     253866
    Reported by:    Sergey Akhmatov <sergey at akhmatov dot ru>
    Approved by:    re (gjb)
    Reviewed by:    debdrup
    Differential Revision:  https://reviews.freebsd.org/D29115

    (cherry picked from commit f7bfe310191c8292da51c8da166a521ff16e0e46)

 share/man/man4/wg.4 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Comment 14 Gordon Bergling freebsd_committer 2021-03-11 18:11:03 UTC
The examples in the manual page are fixed. Please submit a new PR for further changes to the manual page.