diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/Makefile | 10 | ||||
| -rw-r--r-- | man/wgconfd.5.scd | 128 | ||||
| -rw-r--r-- | man/wgconfd.8.scd | 55 |
3 files changed, 193 insertions, 0 deletions
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) |