aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--.gitignore1
-rw-r--r--man/Makefile10
-rw-r--r--man/wgconfd.5.scd128
-rw-r--r--man/wgconfd.8.scd55
-rw-r--r--src/main.rs2
5 files changed, 195 insertions, 1 deletions
diff --git a/.gitignore b/.gitignore
index b1c7301..34bcd30 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
/Cargo.lock
/target
+/man/*.[1-8]
**/*.rs.bk
diff --git a/man/Makefile b/man/Makefile
new file mode 100644
index 0000000..fcea268
--- /dev/null
+++ b/man/Makefile
@@ -0,0 +1,10 @@
+PAGES = wgconfd.5 wgconfd.8
+
+.PHONY: all clean
+all: $(PAGES)
+
+clean:
+ rm $(PAGES)
+
+%: %.scd
+ scdoc < $< > $@
diff --git a/man/wgconfd.5.scd b/man/wgconfd.5.scd
new file mode 100644
index 0000000..15c19e9
--- /dev/null
+++ b/man/wgconfd.5.scd
@@ -0,0 +1,128 @@
+wgconfd(5)
+
+# NAME
+
+wgconfd - configuration file
+
+# GLOBAL OPTIONS
+
+The following global options are available:
+
+*min_keepalive*
+ The minimum value for the persistent keepalive timeout, in seconds. Any peer
+ with a smaller timeout uses this one instead. Set to 0 to disable the
+ timeout altogether.
+
+ Default: _10_
+
+*max_keepalive*
+ The maximum value for the persistent keepalive timeout, in seconds. Any peer
+ with a larger (or missing) timeout uses this one instead. If set to 0, there
+ is no maximum.
+
+ Default: _0_
+
+*refresh_sec*
+ The time between configuration updates, in seconds.
+
+ Default: _1200_
+
+*cache_directory*
+ Path to the cache directory.
+
+ Default: _$CACHE_DIRECTORY_
+
+*runtime_directory*
+ Path to the runtime state directory.
+
+ Default: _$RUNTIME_DIRECTORY_
+
+# SOURCE SECTIONS
+
+Sources are defined in *[[source]]* sections. The following options are available:
+
+*name*
+ The name used to identify the source in logs and in the cache. All sources
+ should have distinct names. Should only contain characters that can be put
+ in a filename. Required.
+
+*url*
+ The URL of the source. It must point to a JSON file following the format
+ described in the README.
+
+*ipv4*
+ A list of allowed IPv4 networks, each of the form _"ADDR/LEN"_. All of the
+ address bits after the prefix must be set to 0.
+
+ If a source tries to assign a range of addresses to a peer and that range
+ has addresses that are not listed in the *ipv4* configuration option, the
+ entire range is discarded.
+
+ Default: _[]_
+
+*ipv6*
+ A list of allowed IPv6 networks, each of the form _"ADDR/LEN"_. All of the
+ address bits after the prefix must be set to 0.
+
+ If a source tries to assign a range of addresses to a peer and that range
+ has addresses that are not listed in the *ipv6* configuration option, the
+ entire range is discarded.
+
+ Default: _[]_
+
+*psk*
+ Path to a file containing the default preshared key used for all peers
+ defined by this source.
+
+ Default: no preshared key
+
+*required*
+ Boolean. If set to true, *wgconfd*(8) will fail to start if fetching the
+ source fails.
+
+ Default: _false_
+
+*allow_road_warriors*
+ Boolean. If set to false, road warriors from this source will not be allowed
+ to use this interface machine as their base peer.
+
+ Default: _true_
+
+# PEER SECTIONS
+
+In some cases one may want to override some settings for individual peers.
+This can be achieved through *[[peer]]* sections:
+
+*public_key*
+ The public key of the peer for which the overrides apply, as a base64
+ encoded string.
+
+ Required.
+
+*source*
+ If specified, ignore attempts by other sources to define this peer. Note
+ that even if this is set, other sources can add allowed IP addresses for
+ the peer by creating road warriors.
+
+ Default: do not restrict source
+
+*endpoint*
+ Override the endpoint address of the peer.
+
+ Default: use the endpoint address from the source
+
+*psk*
+ Path to a preshared key to use for this peer.
+
+ Default: the PSK of the source, if any
+
+*keepalive*
+ Override the persistent keepalive timeout for this peer. The value here is
+ not affected by the *min_keepalive* and *max_keepalive* configuration
+ options.
+
+ Default: the keepalive value from the source, or infinite if not set,
+ restricted by *min_keepalive* and *max_keepalive*
+
+Note that having a *[[peer]]* section is not enough to create a peer - it must
+also exist in one of the sources.
diff --git a/man/wgconfd.8.scd b/man/wgconfd.8.scd
new file mode 100644
index 0000000..216bbd2
--- /dev/null
+++ b/man/wgconfd.8.scd
@@ -0,0 +1,55 @@
+wgconfd(8)
+
+# NAME
+
+wgconfd - configuration manager for WireGuard
+
+# SYNOPSIS
+
+*wgconfd* _IFNAME_ _CONFIG_++
+*wgconfd* --cmdline _IFNAME_ _ARGS_...++
+*wgconfd* --check-source _PATH_
+
+# DESCRIPTION
+
+In the 1st and 2nd form, run wgconfd on the network interface named IFNAME. In
+the 1st form, CONFIG is the path to the configuration file, the format of which
+is described in *wgconfd*(5). In the 2nd form, the configuration is provided on
+the command line. The way this is done is described in the _COMMAND-LINE
+CONFIGURATION_ section.
+
+In the 3rd form, wgconfd checks the validity of a source JSON. PATH is a path
+to a local file.
+
+# COMMAND-LINE CONFIGURATION
+
+While the usual way to configure wgconfd is through a file, in some cases it
+is easier to pass everything on the command line. The arguments consist of a
+sequence of global options, sources, and peers:
+
+ min_keepalive _SEC_++
+max_keepalive _SEC_++
+refresh_sec _SEC_++
+source _NAME_ _URL_ [psk _PATH_] [ipv4 _NET_,_NET_,...] [ipv6 _NET_,_NET_,...] [required] [allow_road_warriors | deny_road_warriors]++
+peer _PUBKEY_ [endpoint _IP_:_PORT_] [psk _PATH_] [keepalive _SEC_] [source _NAME_]
+
+# EXIT VALUE
+
+When managing an interface, wgconfd does not exit. When checking the validity of
+a source, a nonzero exit status would indicate a problem with the source.
+
+# ENVIRONMENT
+
+*wgconfd* uses the following environment variables:
+
+ WG - the *wg*(8) command. Used for configuring the interface. Default: _wg_
+
+ CURL - the *curl*(1) command. Used for fetching sources. Default: _curl_
+
+ CACHE_DIRECTORY - the path where sources are cached.
+
+ RUNTIME_DIRECTORY - the path where the runtime state is preserved.
+
+# SEE ALSO
+
+*wgconfd*(5), *wg*(8), *curl*(1)
diff --git a/src/main.rs b/src/main.rs
index 5cdaa40..9d93116 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -161,8 +161,8 @@ fn help(argv0: &str, args: Vec<OsString>) -> i32 {
"\
Usage:
{} IFNAME CONFIG - run daemon on interface
- {} --check-source PATH - validate source JSON
{} --cmdline IFNAME ... - run daemon using config passed as arguments
+ {} --check-source PATH - validate source JSON
",
argv0, argv0, argv0
);