From 61901bed7dcda15ae24503180c951e2cebdc2896 Mon Sep 17 00:00:00 2001
From: Linus Nordberg <linus@nordberg.se>
Date: Mon, 6 May 2019 17:48:56 +0200
Subject: Add to the request_ip protocol spec

---
 docs/ip-request.md | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file 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]
-- 
cgit v1.2.3-59-g8ed1b