persistent keepalive: documentation

Signed-off-by: Jason A. Donenfeld <Jason@zx2c4.com>

diff --git a/src/wg.8 b/src/wg.8
index eee6d7bc0544fe212fa54129c21e245fc2953b08..347fb275f9efa30c991ec6a70e823bb6b88fc29e 100644 (file)
--- a/src/wg.8
+++ b/src/wg.8
@@ -36,7 +36,7 @@ Sub-commands that take an INTERFACE must be passed a WireGuard interface.
 .SH COMMANDS
 
 .TP
-\fBshow\fP { \fI<interface>\fP | \fIall\fP | \fIinterfaces\fP } [\fIpublic-key\fP | \fIprivate-key\fP | \fIpreshared-key\fP | \fIlisten-port\fP | \fIpeers\fP | \fIendpoints\fP | \fIallowed-ips\fP | \fIlatest-handshake\fP | \fIbandwidth\fP]
+\fBshow\fP { \fI<interface>\fP | \fIall\fP | \fIinterfaces\fP } [\fIpublic-key\fP | \fIprivate-key\fP | \fIpreshared-key\fP | \fIlisten-port\fP | \fIpeers\fP | \fIendpoints\fP | \fIallowed-ips\fP | \fIlatest-handshake\fP | \fIpersistent-keepalive\fP | \fIbandwidth\fP]
 Shows current WireGuard configuration of specified \fI<interface>\fP.
 If no \fI<interface>\fP is specified, \fI<interface>\fP defaults to \fIall\fP.
 If \fIinterfaces\fP is specified, prints a list of all WireGuard interfaces,
@@ -49,7 +49,7 @@ newlines and tabs, meant to be used in scripts.
 Shows the current configuration of \fI<interface>\fP in the format described
 by \fICONFIGURATION FILE FORMAT\fP below.
 .TP
-\fBset\fP \fI<interface>\fP [\fIlisten-port\fP \fI<port>\fP] [\fIprivate-key\fP \fI<file-path>\fP] [\fIpreshared-key\fP \fI<file-path>\fP] [\fIpeer\fP \fI<base64-public-key>\fP [\fIremove\fP] [\fIendpoint\fP \fI<ip>:<port>\fP] [\fIallowed-ips\fP \fI<ip1>/<cidr1>\fP[,\fI<ip2>/<cidr2>\fP]...] ]...
+\fBset\fP \fI<interface>\fP [\fIlisten-port\fP \fI<port>\fP] [\fIprivate-key\fP \fI<file-path>\fP] [\fIpreshared-key\fP \fI<file-path>\fP] [\fIpeer\fP \fI<base64-public-key>\fP [\fIremove\fP] [\fIendpoint\fP \fI<ip>:<port>\fP] [\fIpersistent-keepalive\fP \fI<interval seconds>\fP] [\fIallowed-ips\fP \fI<ip1>/<cidr1>\fP[,\fI<ip2>/<cidr2>\fP]...] ]...
 Sets configuration values for the specified \fI<interface>\fP. Multiple
 \fIpeer\fPs may be specified, and if the \fIremove\fP argument is given
 for a peer, that peer is removed, not configured. If \fIlisten-port\fP
@@ -66,7 +66,14 @@ you may safely pass in a string by specifying as \fIprivate-key\fP or
 layer of symmetric-key cryptography to be mixed into the already existing
 public-key cryptography, for post-quantum resistance. If \fIallowed-ips\fP
 is specified, but the value is the empty string, all allowed ips are removed
-from the peer.
+from the peer. The use of \fIpersistent-keepalive\fP is optional and is by
+default off; setting it to 0 or "off", disables it. Otherwise it represents,
+in seconds, between 10 and 3600 inclusive, how often to send an empty UDP
+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.
 .TP
 \fBsetconf\fP \fI<interface>\fP \fI<configuration-filename>\fP
 Sets the current configuration of \fI<interface>\fP to the contents of
@@ -134,6 +141,14 @@ Endpoint \(em 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.
+.IP \(bu
+PersistentKeepalive \(em a seconds interval, between 10 and 3600 inclusive, of
+how often to send an empty UDP 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 "off", this option is disabled. By default or
+when unspecified, this option is off. Optional.
 
 .SH CONFIGURATION FILE FORMAT EXAMPLE
 This example may be used as a model for writing configuration files.