diff options
Diffstat (limited to 'doc/examples/agent')
| -rw-r--r-- | doc/examples/agent/comments.json | 58 | ||||
| -rw-r--r-- | doc/examples/agent/https.json | 32 | ||||
| -rw-r--r-- | doc/examples/agent/rbac.json | 90 | ||||
| -rw-r--r-- | doc/examples/agent/simple.json | 150 |
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 + } + ] + } +} |