From: Stephen Morris Date: Thu, 10 Jul 2014 10:33:32 +0000 (+0100) Subject: [3466] Edits to the documentation made as part of the review. X-Git-Tag: trac3482_base~84^2 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=ea3e3f0469085a93e0eedd92146fec5163aadbbc;p=thirdparty%2Fkea.git [3466] Edits to the documentation made as part of the review. --- diff --git a/doc/guide/keactrl.xml b/doc/guide/keactrl.xml index 2b358b7d87..02e01a4624 100644 --- a/doc/guide/keactrl.xml +++ b/doc/guide/keactrl.xml @@ -5,73 +5,79 @@ ]> - Managing Kea Servers With keactrl + Managing Kea with keactrl
Overview keactrl is a shell script which controls the startup, shutdown - and reconfiguration of the Kea servers, i.e. kea-dhcp4, - kea-dhcp6 and kea-dhcp-ddns. It also - provides the means for checking the current status of the servers and - returns the information whether the servers are active or inactive - and also configuration data being used. + and reconfiguration of the Kea servers (kea-dhcp4, + kea-dhcp6 and kea-dhcp-ddns). It + also provides the means for checking the current status of the servers + and determining the configuration files in use.
- Command line options - The usage of the keactrl is: - + Command Line Options + keactrl is run as follows: + keactrl <command> [-c keactrl-config-file] [-s server[,server,..]] - + - The <command> specifies the one of the commands + <command> is the one of the commands described in . - The [-c keactrl-config-file] parameter overrides - the default location of the keactrl configuration - file. + The optional -c keactrl-config-file switch + allows specification of an alternate keactrl + configuration file. (--ctrl-config is a synonym for + -c.) In the absence of -c, + keactrl will use the default configuration + file [kea-install-dir]/etc/kea/keactrl.conf. - The [-s server[,server ...]] parameter overrides - the list of servers to which the command is issued. + The optional -s server[,server ...] switch selects + the servers to which the command is issued. If absent, + the command is sent to all servers enabled in the keactrl + configuration file. (--server is a synonym for + -s.) If multiple servers are specified, they + should be separated by commas with no intervening spaces.
- keactrl Configuration File + The keactrl Configuration File - keactrl starts servers in background and returns. Depending on the - needs of the server's Administrator it is possible to select which - of them are started and which are not. This is specified in the - keactrl.conf file which by default is installed - in [kea-install-dir]/etc/kea/. + Depending on requirements, not all of the available servers need + be run. The keactrl configuration file sets which servers are + enabled and which are disabled. The default configuration + file is [kea-install-dir]/etc/kea/keactrl.conf, + but this can be overridden on a per-command basis using the + -c switch. - The default keactrl.conf file holds the following - configuration: - + The contents of keactrl.conf are: + # This is a configuration file for keactrl script which controls # the startup, shutdown, reconfiguration and gathering the status # of the Kea servers. # prefix holds the location where the Kea is installed. -prefix=/home/marcin/devel/kea-build +prefix=/usr/local # Location of Kea configuration file. kea_config_file=${prefix}/etc/kea/kea.conf # Location of Kea binaries. exec_prefix=${prefix} -dhcp4_srv=${exec_prefix}/sbin/kea/b10-dhcp4 -dhcp6_srv=${exec_prefix}/sin/kea/b10-dhcp6 -dhcp_ddns_srv=${exec_prefix}/sbin/kea/b10-dhcp-ddns +dhcp4_srv=${exec_prefix}/sbin/kea/kea-dhcp4 +dhcp6_srv=${exec_prefix}/sin/kea/kea-dhcp6 +dhcp_ddns_srv=${exec_prefix}/sbin/kea/kea-dhcp-ddns # Start DHCPv4 server? dhcp4=yes @@ -84,27 +90,27 @@ dhcp_ddns=yes # Be verbose? kea_verbose=no - + The dhcp4, dhcp6 and dhcp_ddns parameters set to "yes" configure keactrl to manage (start, reconfigure) all servers, - i.e. kea-dhcp4, kea-dhcp6 and + i.e. kea-dhcp4, kea-dhcp6 and kea-dhcp-ddns. When any of these parameters is set to - "no" the keactrl will skip starting or reconfiguring - the corresponding server. + "no" the keactrl will ignore + the corresponding server when starting or reconfiguring Kea. - By default, Kea processes managed by keactrl are - located in the [kea-install-dir]/sbin. This - should work for most of the installations. However, if the default - location needs to be altered for any reason, it can be achieved by - modifying the paths specified with the dhcp4_srv, + By default, Kea servers managed by keactrl are + located in [kea-install-dir]/sbin. This + should work for most of the installations. If the default + location needs to be altered for any reason, the paths + specified with the dhcp4_srv, dhcp6_srv and dhcp_ddns_srv - parameters. + parameters should be modified. @@ -116,7 +122,7 @@ kea_verbose=no - The verbosity for the server is specified when it is started. Once + The verbosity for the server is set when it is started. Once started, the verbosity can be only changed by stopping the server and starting it again with the new value of the kea_verbose parameter. @@ -141,103 +147,102 @@ kea_verbose=no status - returns the status of the servers (active - or inactive) and the keactrl configuration data. + or inactive) and the names of the configuration files in use. - The typical output from the keactrl when starting + Typical output from keactrl when starting the servers looks similar to the following: - + $ keactrl start -INFO/keactrl: Starting b10-dhcp4 -c /usr/local/etc/kea/kea.conf -INFO/keactrl: Starting b10-dhcp6 -c /usr/local/etc/kea/kea.conf -INFO/keactrl: Starting b10-dhcp-ddns -c /usr/local/etc/kea/kea.conf - +INFO/keactrl: Starting kea-dhcp4 -c /usr/local/etc/kea/kea.conf +INFO/keactrl: Starting kea-dhcp6 -c /usr/local/etc/kea/kea.conf +INFO/keactrl: Starting kea-dhcp-ddns -c /usr/local/etc/kea/kea.conf + The following command stops all servers: - + $ keactrl stop INFO/keactrl: Skip sending signal 15 to process kea-dhcp6: process is not running - + Note that the stop will attempt to stop all servers - regrdless if they are "enabled" in the keactrl.conf - or not. If any of the servers is not running, the informational message + regrdless of whether they are "enabled" in the keactrl.conf. + If any of the servers is not running, an informational message is displayed as in the stop command output above. - As already mentioned, the reconfiguration of each Kea server is triggered - by the SIGHUP signal. The reload command sends - the SIGHUP signal to selected servers (running and "enabled" through the - keactrl.conf configuration file). When the server - receives the SIGHUP signal it re-reads its configuration file and if - the new configuration is valid it uses the new configuration. Use the - following command to trigger reconfiguration of the servers: - + As already mentioned, the reconfiguration of each Kea server is + triggered by the SIGHUP signal. The reload + command sends the SIGHUP signal to the servers that are enabled in + the keactrl configuration file and are + currently running. When a server receives the SIGHUP signal it + re-reads its configuration file and, if the new configuration is + valid, uses the new configuration. A reload is executed as follows: + $ keactrl reload - + - Currently keactrl doesn't report configuration - failures when the server is started or reconfigured. In order to - check if the server's configuration succeeded the Kea log file - must be examined for errors. The default location of the log file is - [kea-install-dir]/var/kea/kea.log. + Currently keactrl does not report configuration + failures when the server is started or reconfigured. To check if + the server's configuration succeeded the Kea log must be examined + for errors. By default, this is written to the syslog file. - Sometimes it is useful to check which servers are running. One of the - cases is when one needs to verify if the server successfully started as - a result of executing keactrl start command. The - typical output from the status command looks like - this: - + Sometimes it is useful to check which servers are running. The + status reports this, typical output looking like: + $ keactrl status DHCPv4 server: active DHCPv6 server: inactive DHCP DDNS: active Kea configuration file: /usr/local/etc/kea/kea.conf keactrl configuration file: /usr/local/etc/kea/keactrl.conf - +
- Overriding Servers Selection + Overriding the Server Selection - The [-s server[,server]] command line option - allows for selecting the servers to which the - keactrl command is issued. For example: - + The optional -s switch allows + the selection of the servers to which keactrl + command is issued. For example, + $ keactrl stop -s dhcp4,dhcp6 - - instructs the keactrl to only stop the + + ... instructs keactrl to stop the kea-dhcp4 and kea-dhcp6 servers and leave the kea-dhcp-ddns running. - Similarly: - + Similarly, + $ keactrl start -s dhcp4,dhcp_ddns - - will only start the kea-dhcp4 and + + ... will only start the kea-dhcp4 and kea-dhcp-ddns servers and not - kea-dhcp6. Note that the start - and reload commands are different from - stop in such a way that for the former - keactrl will also check if the specified server - is enabled in the keactrl.conf configuration file. - If it is not enabled it will not be started (or reconfigured) even if - listed after the -s command line option. For the - stop command it is not checked if the server is - enabled in the configuration file and all the listed servers will be - stopped. + kea-dhcp6. + + + Note that the behavior of the -s switch + with the start and reload commands + is different to its behavior with the stop command. + On start and reload, + keactrl will check if the servers given as + parameters to the -s switch are + enabled in the keactrl configuration file: + if not, the server will be ignored. For stop however, + this check is not made: the command is applied to all listed servers, + regardless of whether they have been enabled in the file. diff --git a/src/bin/keactrl/keactrl.xml b/src/bin/keactrl/keactrl.xml index e461b92a97..1164baaab3 100644 --- a/src/bin/keactrl/keactrl.xml +++ b/src/bin/keactrl/keactrl.xml @@ -30,7 +30,7 @@ keactrl - Shell script for managing the Kea servers + Shell script for managing Kea @@ -52,24 +52,21 @@ DESCRIPTION - keactrl is a shell script which controls the startup, - shutdown and reconfiguration of the Kea servers, i.e. - kea-dhcp4, kea-dhcp6 and - kea-dhcp-ddns. It also provides the means for - checking the current status of the servers and returns the information - whether the servers are active or inactive and also configuration data - being used. + keactrl is a shell script which controls the startup, shutdown + and reconfiguration of the Kea servers (kea-dhcp4, + kea-dhcp6 and kea-dhcp-ddns). It + also provides the means for checking the current status of the servers + and determining the configuration files in use. CONFIGURATION FILE - keactrl starts servers in background and returns. - Depending on the needs of the server's Administrator it is possible - to select which of them are started and which are not. This is - specified in the keactrl.conf file which by default - is installed in [kea-install-dir]/etc/kea/. + Depending on requirements, not all of the available servers need + be run. The keactrl configuration file sets which servers are + enabled and which are disabled. By default the configuration + file is [kea-install-dir]/etc/kea/keactrl.conf. See the Kea Administrator's Guide for the documentation of the parameters @@ -91,21 +88,21 @@ start - Start servers. + Start the servers. stop - Stop servers. + Stop the servers. reload - Reconfigure servers. + Instructs the servers to re-read the kea configuration file. @@ -126,8 +123,9 @@ - Override the default location of the keactrl - configuration file. + Specify the keactrl configuration file. Without + this switch, the keactrl will attempt to use the + file [kea-install-dir]/etc/kea/keactrl.conf. @@ -136,8 +134,9 @@ - Specify a comma separated list of servers to which the command - should be issued. The acceptable values are: + Specifies a subset of the enabled servers to which the command should be issued. + The list of servers should be separated by commas with no intervening spaces. + Acceptable values are: