From 6a7b1aba8b9acbdcb403642a4904d9dc8670c63b Mon Sep 17 00:00:00 2001
From: Simon Zolin <s.zolin@adguard.com>
Date: Wed, 24 Apr 2019 17:58:04 +0300
Subject: [PATCH] + doc: clients

---
 AGHTechDoc.md | 138 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 138 insertions(+)

diff --git a/AGHTechDoc.md b/AGHTechDoc.md
index e88bb055..62ea41d4 100644
--- a/AGHTechDoc.md
+++ b/AGHTechDoc.md
@@ -12,6 +12,12 @@ Contents:
 * Updating
 	* Get version command
 	* Update command
+* Device Names and Per-client Settings
+	* Per-client settings
+	* Get list of clients
+	* Add client
+	* Update client
+	* Delete client
 * Enable DHCP server
 	* "Check DHCP" command
 	* "Enable DHCP" command
@@ -420,3 +426,135 @@ Step 2.
 If we would set a different IP address, we'd need to replace the IP address for the current network configuration.  But currently this step isn't necessary.
 
 	ip addr replace dev eth0 192.168.0.1/24
+
+
+## Device Names and Per-client Settings
+
+When a client requests information from DNS server, he's identified by IP address.
+Administrator can set a name for a client with a known IP and also override global settings for this client.  The name is used to improve readability of DNS logs: client's name is shown in UI next to its IP address.  The names are loaded from 3 sources:
+* automatically from "/etc/hosts" file.  It's a list of `IP<->Name` entries which is loaded once on AGH startup from "/etc/hosts" file.
+* automatically using rDNS.  It's a list of `IP<->Name` entries which is added in runtime using rDNS mechanism when a client first makes a DNS request.
+* manually configured via UI.  It's a list of client's names and their settings which is loaded from configuration file and stored on disk.
+
+### Per-client settings
+
+UI provides means to manage the list of known clients (List/Add/Update/Delete) and their settings.  These settings are stored in configuration file as an array of objects.
+
+Notes:
+
+* `name`, `ip` and `mac` values are unique.
+
+* `ip` & `mac` values can't be set both at the same time.
+
+* If `mac` is set and DHCP server is enabled, IP is taken from DHCP lease table.
+
+* If `use_global_settings` is true, then DNS responses for this client are processed and filtered using global settings.
+
+* If `use_global_settings` is false, then the client-specific settings are used to override (disable) global settings.  For example, if global setting `parental_enabled` is true, then per-client setting `parental_enabled:false` can disable Parental Control for this specific client.
+
+
+### Get list of clients
+
+Request:
+
+	GET /control/clients
+
+Response:
+
+	200 OK
+
+	{
+	clients: [
+		{
+			name: "client1"
+			ip: "..."
+			mac: "..."
+			use_global_settings: true
+			filtering_enabled: false
+			parental_enabled: false
+			safebrowsing_enabled: false
+			safesearch_enabled: false
+		}
+	]
+	auto_clients: [
+		{
+			name: "host"
+			ip: "..."
+			source: "etc/hosts" || "rDNS"
+		}
+	]
+	}
+
+
+### Add client
+
+Request:
+
+	POST /control/clients/add
+
+	{
+		name: "client1"
+		ip: "..."
+		mac: "..."
+		use_global_settings: true
+		filtering_enabled: false
+		parental_enabled: false
+		safebrowsing_enabled: false
+		safesearch_enabled: false
+	}
+
+Response:
+
+	200 OK
+
+Error response (Client already exists):
+
+	400
+
+
+### Update client
+
+Request:
+
+	POST /control/clients/update
+
+	{
+		name: "client1"
+		data: {
+			name: "client1"
+			ip: "..."
+			mac: "..."
+			use_global_settings: true
+			filtering_enabled: false
+			parental_enabled: false
+			safebrowsing_enabled: false
+			safesearch_enabled: false
+		}
+	}
+
+Response:
+
+	200 OK
+
+Error response (Client not found):
+
+	400
+
+
+### Delete client
+
+Request:
+
+	POST /control/clients/delete
+
+	{
+		name: "client1"
+	}
+
+Response:
+
+	200 OK
+
+Error response (Client not found):
+
+	400