aboutsummaryrefslogtreecommitdiffstats
path: root/docs/ip-request.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/ip-request.md')
-rw-r--r--docs/ip-request.md104
1 files changed, 101 insertions, 3 deletions
diff --git a/docs/ip-request.md b/docs/ip-request.md
index d6f6933..1db0e07 100644
--- a/docs/ip-request.md
+++ b/docs/ip-request.md
@@ -1,5 +1,11 @@
# Dynamic IP address allocation
+This document describes version 1 of the wg-dynamic `request_ip`
+command.
+
+See protocol.md for a general description of the protocol.
+
+
## Server
The wg-dynamic server is a daemon responsible for handing out IP
@@ -109,7 +115,99 @@ interface.
## Protocol
-Example:
+A client requests an IP address lease by sending a request\_ip
+command. The request\_ip command accepts the following attributes, all
+optional:
+
+IP addresses are expressed in CIDR notation. A point in time is
+expressed as seconds since the epoch (1970-01-01 UTC). When this
+document talks about current time, the current time of the computers
+clock in UTC is what's being refered to.
+
+- ipv4 (optional)
+
+ IPv4 address hint in CIDR notation. The client would like to have
+ this IPv4 address to use. The server MUST NOT honour the request for
+ this particular address unless the client already has got a valid
+ lease for it.
+
+- ipv6 (optional)
+
+ IPv6 address hint in CIDR notation. The client would like to have
+ this IPv6 address to use.
+
+- leasetime (optional)
+
+ Lease time hint in seconds. The client would like the lease to be
+ valid for at least this long.
+
+The server response to a request\_ip command contains an errno
+attribute and, if the request was succesful, up to four attributes
+containing the result:
+
+- ipv4
+
+ IPv4 address for the client to use. Unless the IPv4 address hint in
+
+- ipv6
+
+ IPv6 address for the client to use.
+
+- leasestart
+
+ The start time of the lease.
+
+ A client receiving a response with a leasestart that deviates from
+ current time of the client by more than 15 seconds MUST use current
+ time instead of leasestart.
+
+- leasetime
+
+ The number of seconds that this lease is valid, starting from
+ leasestart.
+
+- errno
+
+ Errno is 0 for a successful operation.
+
+At least one of the ipv4 and ipv6 attributes in a response with
+errno=0 MUST be a valid address picked by random from the pool of free
+addresses. This does not appliy for addresses chosen from a valid
+address hint received in the request, see above
+
+leasestart MUST be the current time of the server.
+
+TODO: put restrictions on leasetime, minimal or maximal?
+
+
+If the request failed, errno is != 0 and an errmsg attribute is
+included in the response:
+
+- errno
+
+ A positive integer indicating what made the request fail. The
+ following error codes are defined:
+
+ - 1: Undefined internal error
+ - 2: Out of IP addresses
+
+- errmsg
+
+ A text suitable for a human, describing what made the request fail.
+
+### Example
+
+client -> server request
+
+ request_ip=1
+ [empty line]
+
+server -> client response
- client -> server: request_ip=1\n\n
- server -> client: request_ip=1\nipv4=192.168.47.11/32\nipv6=fd00::4711/128\nleasestart=1555074514\nleasetime=3600\nerrno=0\n\n
+ request_ip=1
+ ipv4=192.168.47.11/32
+ ipv6=fd00::4711/128
+ leasestart=1555074514
+ leasetime=3600
+ errno=0
+ [empty line]