Adding upstream version 2.2.0.upstream/2.2.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

4 files changed, 330 insertions, 0 deletions

diff --git a/doc/examples/agent/comments.json b/doc/examples/agent/comments.json
new file mode 100644
index 0000000..6f40bdb
--- /dev/null
+++ b/doc/examples/agent/comments.json
@@ -0,0 +1,58 @@
+// This is a example of a configuration for Control-Agent (CA) or simply Agent.
+// It uses embedded (i.e., which will be included in configuration objects
+// and not stripped by at lexical analysis) comments.
+
+{
+    "Control-agent":
+    {
+        // Global scope
+        "comment": "A Control Agent",
+
+        "http-host": "127.0.0.1",
+
+        // If enabling HA and multi-threading, the 8000 port is used by the HA
+        // hook library http listener. When using HA hook library with
+        // multi-threading to function, make sure the port used by dedicated
+        // listener is different (e.g. 8001) than the one used by CA. Note
+        // the commands should still be sent via CA. The dedicated listener
+        // is specifically for HA updates only.
+        "http-port": 8000,
+
+        // In authentication
+        "authentication":
+        {
+            "comment": "basic HTTP authentication",
+
+            "type": "basic",
+
+            // In basic HTTP authentication clients
+            "clients":
+            [
+                {
+                    "comment": "admin is authorized",
+                    "user": "admin",
+                    "password": "1234"
+                }
+            ]
+        },
+
+        // In control socket
+        "control-sockets":
+        {
+            "dhcp4":
+            {
+                "comment": "control socket for DHCP4 server",
+                "socket-type": "unix",
+                "socket-name": "/tmp/kea4-ctrl-socket"
+            }
+        },
+
+        // In loggers
+        "loggers": [
+            {
+                "comment": "A logger",
+                "name": "kea-ctrl-agent"
+            }
+        ]
+    }
+}
diff --git a/doc/examples/agent/https.json b/doc/examples/agent/https.json
new file mode 100644
index 0000000..c06039c
--- /dev/null
+++ b/doc/examples/agent/https.json
@@ -0,0 +1,32 @@
+// This is an example of a configuration for Control-Agent (CA) HTTPS i.e.
+// HTTP over TLS.
+{
+    "Control-agent":
+    {
+        // We need to specify where the agent should listen to incoming HTTP
+        // queries.
+        "http-host": "127.0.0.1",
+
+        // If enabling HA and multi-threading, the 8000 port is used by the HA
+        // hook library http listener. When using HA hook library with
+        // multi-threading to function, make sure the port used by dedicated
+        // listener is different (e.g. 8001) than the one used by CA. Note
+        // the commands should still be sent via CA. The dedicated listener
+        // is specifically for HA updates only.
+        "http-port": 8000,
+
+        // TLS trust anchor (Certificate Authority). This is a file name or
+        // (for OpenSSL only) a directory path.
+        "trust-anchor": "my-ca",
+
+        // TLS server certificate file name.
+        "cert-file": "my-cert",
+
+        // TLS server private key file name.
+        "key-file": "my-key",
+
+        // TLS require client certificates flag. Default is true and means
+        // require client certificates. False means they are optional.
+        "cert-required": true
+    }
+}
diff --git a/doc/examples/agent/rbac.json b/doc/examples/agent/rbac.json
new file mode 100644
index 0000000..1ac2453
--- /dev/null
+++ b/doc/examples/agent/rbac.json
@@ -0,0 +1,90 @@
+// This is an example of a configuration for Control-Agent (CA) using
+// the Role Based Access Control (RBAC) hook library.
+{
+    "Control-agent":
+    {
+        // We need to specify where the agent should listen to incoming HTTP
+        // queries.
+        "http-host": "127.0.0.1",
+
+        // If enabling HA and multi-threading, the 8000 port is used by the HA
+        // hook library http listener. When using HA hook library with
+        // multi-threading to function, make sure the port used by dedicated
+        // listener is different (e.g. 8001) than the one used by CA. Note
+        // the commands should still be sent via CA. The dedicated listener
+        // is specifically for HA updates only.
+        "http-port": 8000,
+
+        // TLS trust anchor (Certificate Authority). This is a file name or
+        // (for OpenSSL only) a directory path.
+        "trust-anchor": "my-ca",
+
+        // TLS server certificate file name.
+        "cert-file": "my-cert",
+
+        // TLS server private key file name.
+        "key-file": "my-key",
+
+        // TLS require client certificates flag. Default is true and means
+        // require client certificates. False means they are optional.
+        "cert-required": true,
+
+        // Add hooks here.
+        "hooks-libraries": [
+        {
+            "library": "/opt/lib/libca_rbac.so",
+            "parameters": {
+                // This section configures the RBAC hook library.
+                // Mandatory parameters.
+                "assign-role-method": "cert-subject",
+                "api-files": "/opt/share/kea/api",
+                // Optional parameters.
+                "require-tls": true,
+                "commands": [
+                {
+                    "name": "my-command",
+                    "access": "read",
+                    "hook": "my-hook"
+                } ],
+                "access-control-lists": [
+                {
+                    "my-none": { "not": "ALL" }
+                },{
+                    "another-none": { "and": [ "ALL", "NONE" ] }
+                },{
+                    "my-read": { "access": "read" }
+                } ],
+                "roles": [
+                {
+                    "name": "kea-client",
+                    "accept-commands":
+                    {
+                        "commands": [ "list-commands", "status-get" ]
+                    },
+                    "reject-commands": "NONE",
+                    "other-commands": "reject",
+                    "list-match-first": "accept",
+                    "response-filters": [ "list-commands" ]
+                },{
+                    "name": "admin",
+                    "accept-commands": "ALL",
+                    "reject-commands":
+                    {
+                        "hook": "cb_cmds"
+                    },
+                    "list-match-first": "reject"
+                } ],
+                "default-role":
+                {
+                    "accept-commands": "NONE",
+                    "reject-commands": "ALL"
+                },
+                "unknown-role":
+                {
+                    "accept-commands": "READ",
+                    "reject-commands": "WRITE"
+                }
+            }
+        } ]
+    }
+}
diff --git a/doc/examples/agent/simple.json b/doc/examples/agent/simple.json
new file mode 100644
index 0000000..6c5af60
--- /dev/null
+++ b/doc/examples/agent/simple.json
@@ -0,0 +1,150 @@
+// This is a simple example of a configuration for Control-Agent (CA) or simply
+// Agent. This server provides RESTful interface for all Kea servers.
+{
+    "Control-agent":
+    {
+        // We need to specify where the agent should listen to incoming HTTP
+        // queries.
+        "http-host": "127.0.0.1",
+
+        // If enabling HA and multi-threading, the 8000 port is used by the HA
+        // hook library http listener. When using HA hook library with
+        // multi-threading to function, make sure the port used by dedicated
+        // listener is different (e.g. 8001) than the one used by CA. Note
+        // the commands should still be sent via CA. The dedicated listener
+        // is specifically for HA updates only.
+        "http-port": 8000,
+
+        // Optional authentication.
+        "authentication":
+        {
+            // Required authentication type. The only supported value is
+            // basic for the basic HTTP authentication.
+            "type": "basic",
+
+            // An optional parameter is the basic HTTP authentication realm.
+            // Its default is "kea-control-agent".
+            "realm": "kea-control-agent",
+
+            // This optional parameter can be used to specify a common
+            // prefix for files handling client credentials.
+            "directory": "/tmp/kea-creds",
+
+            // This list specifies the user ids and passwords to use for
+            // basic HTTP authentication. If empty or not present any client
+            // is authorized.
+            "clients":
+            [
+                // This specifies an authorized client.
+                {
+                    "comment": "admin is authorized",
+
+                    // The user id must not be empty or contain the ':'
+                    // character. It is a mandatory parameter.
+                    "user": "admin",
+
+                    // If password is not specified an empty password is used.
+                    "password": "1234"
+                },
+
+                // This specifies a hiddent client.
+                {
+                    // The user id is the content of the file /tmp/kea-creds/hiddenu.
+                    "user-file": "hiddenu",
+
+                    // The password is the content of the file /tmp/kea-creds/hiddenp.
+                    "password-file": "hiddenp"
+                },
+
+                // This specifies a hidden client using a secret in a file.
+                {
+                    // The secret is the content of the file /tmp/kea-creds/hiddens
+                    // which must be in the <user-id>:<password> format.
+                    "password-file": "hiddens"
+                }
+            ]
+        },
+
+        // This map specifies where control channel of each server is configured
+        // to listen on. See 'control-socket' object in the respective
+        // servers. At this time the only supported socket type is "unix".
+        // Make sure that the Agent and respective servers configuration
+        // matches exactly, otherwise they won't be able to communicate.
+        // One extra feature that requires some explanation is
+        // user-context. This is a structure that you can define at
+        // global scope, in control sockets and others. It is parsed by
+        // Kea, but not used directly.  It is intended to keep anything
+        // you may want to put there - comments, extra designations,
+        // floor or department names etc. These structures will be made
+        // available to Kea hooks. A comment entry is translated into a
+        // user-context with a "comment" property so you can include
+        // comments inside the configuration itself.
+        "control-sockets":
+        {
+            // This is how the Agent can communicate with the DHCPv4 server.
+            "dhcp4":
+            {
+                "comment": "socket to DHCP4 server",
+                "socket-type": "unix",
+                "socket-name": "/tmp/kea4-ctrl-socket"
+            },
+
+            // Location of the DHCPv6 command channel socket.
+            "dhcp6":
+            {
+                "socket-type": "unix",
+                "socket-name": "/tmp/kea6-ctrl-socket"
+            },
+
+            // Location of the D2 command channel socket.
+            "d2":
+            {
+                "socket-type": "unix",
+                "socket-name": "/tmp/kea-ddns-ctrl-socket",
+                "user-context": { "in-use": false }
+            }
+        },
+
+        // CA is able to load hook libraries that augment its operation.
+        // The primary functionality is the ability to add new commands.
+        "hooks-libraries": [
+            // Hook libraries list may contain more than one library.
+            {
+                // The only necessary parameter is the library filename.
+                "library": "/opt/local/control-agent-commands.so",
+
+                // Some libraries may support parameters. Make sure you
+                // type this section carefully, as the CA does not validate
+                // it (because the format is library specific).
+                "parameters": {
+                    "param1": "foo"
+                }
+            }
+        ],
+
+        // Similar to other Kea components, CA also uses logging.
+        "loggers": [
+            {
+                "name": "kea-ctrl-agent",
+                "output_options": [
+                    {
+                        "output": "/var/log/kea-ctrl-agent.log",
+                        // Several additional parameters are possible in addition
+                        // to the typical output. Flush determines whether logger
+                        // flushes output to a file. Maxsize determines maximum
+                        // filesize before the file is being rotated. maxver
+                        // specifies the maximum number of rotated files being
+                        // kept.
+                        "flush": true,
+                        "maxsize": 204800,
+                        "maxver": 4,
+                        // We use pattern to specify custom log message layout
+                        "pattern": "%d{%y.%m.%d %H:%M:%S.%q} %-5p [%c/%i] %m\n"
+                    }
+                ],
+                "severity": "INFO",
+                "debuglevel": 0
+            }
+        ]
+    }
+}