From 7cfa4d756a4035b3dab2e3cd32144f2f72610e98 Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Thu, 4 Sep 2025 10:58:46 +0200 Subject: [PATCH 1/2] [#1844] New DHCP and DNS sections in ARM --- doc/user/dhcp.rst | 920 ++++++++++++++++++++++++++++++++++++++ doc/user/dns.rst | 384 ++++++++++++++++ doc/user/index.rst | 3 +- doc/user/managing-kea.rst | 378 ---------------- doc/user/overview.rst | 292 ++++++------ doc/user/usage.rst | 615 +++---------------------- 6 files changed, 1502 insertions(+), 1090 deletions(-) create mode 100644 doc/user/dhcp.rst create mode 100644 doc/user/dns.rst delete mode 100644 doc/user/managing-kea.rst diff --git a/doc/user/dhcp.rst b/doc/user/dhcp.rst new file mode 100644 index 000000000..ec9b9b41c --- /dev/null +++ b/doc/user/dhcp.rst @@ -0,0 +1,920 @@ +.. _dhcp: + +**** +DHCP +**** + +Kea DHCP Integration with Stork +=============================== + +Earlier Kea versions than 3.0.0 exposed the control API via the Kea Control Agent +daemon. Communication with the other Kea daemons was routed through that daemon. +Later Kea versions introduced a direct control channel to the Kea daemons (i.e., +DHCP, D2, and NETCONF). The use of the Kea Control Agent is now deprecated. + +.. note:: + + Stork requires the use of the Kea Control Agent to connect to the Kea daemons. + Support for the communication over the direct control channel is currently + under development. + +Kea instance detection begins by looking for the ``kea-ctrl-agent`` process, +which is expected to run with the ``-c`` parameter specifying the path to the +Kea Control Agent configuration file. Stork agent then reads the following +configuration parameters from this file: + +- ``http-host`` and ``http-port`` - the address and port of the HTTP Kea CA interface, +- ``control-sockets`` - the control sockets for the Kea daemons, +- ``authentication`` - the authentication credentials to use to connect to the Kea daemons. + +The ``control-sockets`` structure contains the names of the Kea daemons that +Stork can connect to. Default Kea Control Agent configuration sometimes contain +the configurations of the daemons that are not intended to run. It is recommended +to remove (or comment out) those configurations to eliminate unwanted warnings +from Stork about inactive daemons. + +Subnets and Networks +==================== + +IPv4 and IPv6 Subnets per Kea Application +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +One of the primary configuration aspects of any network is the layout +of IP addressing. This is represented in Kea with IPv4 and IPv6 +subnets. Each subnet represents addresses used on a physical +link. Typically, certain parts of each subnet ("pools") are delegated +to the DHCP server to manage. Stork is able to display this +information. + +One way to inspect the subnets and pools within Kea is by looking at +each Kea application to get an overview of the configurations a +specific Kea application is serving. A list of configured subnets on +that specific Kea application is displayed. The following picture +shows a simple view of the Kea DHCPv6 server running with a single +subnet, with three pools configured in it. + +.. figure:: ./static/kea-subnets6.png + :alt: View of subnets assigned to a single Kea application + +IPv4 and IPv6 Subnets in the Whole Network +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is convenient to see a complete overview of all subnets +configured in the network that are being monitored by Stork. Once at least one +machine with the Kea application running is added to Stork, click on +the ``DHCP`` menu and choose ``Subnets`` to see all available subnets. The +view shows all IPv4 and IPv6 subnets, with the address pools and links +to the applications that are providing them. An example view of all +subnets in the network is presented in the figure below. + +.. figure:: ./static/kea-subnets-list.png + :alt: List of all subnets in the network + +Stork provides filtering capabilities; it is possible to +choose to see IPv4 only, IPv6 only, or both. There is also an +omnisearch box available where users can type a search string. +For strings of four characters or more, the filtering takes place +automatically, while shorter strings require the user to hit +Enter. For example, in the above example it is possible to show only +the first (192.0.2.0/24) subnet by searching for the *0.2* string. One +can also search for specific pools, and easily filter the subnet with +a specific pool, by searching for part of the pool range, +e.g. *3.200*. The input box accepts a text string that can be a part of the +subnet or shared network name. + +Stork displays pool utilization for each subnet, with +the absolute number of addresses allocated and usage percentage. +There are two thresholds: 80% (warning; the pool utilization +bar turns orange) and 90% (critical; the pool utilization bar +turns red). + +Subnet Names +~~~~~~~~~~~~ + +Kea allows storing any arbitrary data related to a subnet in the ``user-context`` +field. This field is a JSON object. It may be used to store some metadata about +the subnet, such as the name of the location where the subnet is used, the name +of the department, name of related service or any other information that is +useful for the network administrator. + +Stork displays the subnet's user context on the subnet page. Additionally, the +value of the ``subnet-name`` key is displayed in the subnet list view. This +allows the network administrator to quickly identify the subnet by its name. + +The subnet name can be used to filter the subnets on the subnet list page and +in the global search box. + +IPv4 and IPv6 Networks +~~~~~~~~~~~~~~~~~~~~~~ + +Kea uses the concept of a shared network, which is essentially a stack +of subnets deployed on the same physical link. Stork +retrieves information about shared networks and aggregates it across all +configured Kea servers. The ``Shared Networks`` view allows the +inspection of networks and the subnets that belong in them. Pool +utilization is shown for each subnet. + +.. _creating-subnets: + +Creating Subnets +~~~~~~~~~~~~~~~~ + +Stork can configure new subnets in Kea instances with the Subnet Commands (``subnet_cmds``) +hook library loaded. Navigate to ``DHCP -> Subnets`` to display the subnets list, and click +the ``New Subnet`` button. The opened form initially contains only an input box where +a subnet prefix must be specified. It can be an IPv4 address (e.g., ``192.0.2.0/24``) or +IPv6 prefix (e.g., ``2001:db8:1::/64``). Click the ``Proceed`` button to expand the +form and enter the remaining subnet configuration information. + +The Stork subnet form allows the user to specify a common subnet configuration that +can be instantly populated to multiple DHCP servers. Configuring the same subnet in +multiple Kea instances is specific to the deployments where service redundancy is +required (e.g. deployments using High Availability or with a shared lease database). +When configuring a new subnet it is possible to select multiple DHCP servers +in the ``Assignments`` panel, and the subnet is populated to these servers. Please +note that the list of servers only contains those matching the subnet prefix +(IPv4 or IPv6). Additionally, only servers running the ``subnet_cmds`` hook library +are listed. + +The new subnet may be assigned to a shared network in the ``Subnet`` panel. The Shared +Network dropdown list may be empty for two reasons: + +- There are no shared networks in the selected Kea instances. +- Some Kea instances selected for the subnet lack a shared-network specification. + +If there are no shared networks, simply create one before creating the subnet. +If the shared-network specification is absent, update the shared network and assign it to all servers +to which the subnet will be assigned. As an example, suppose we want to add a new subnet and assign +it to both ``server 1`` and ``server 2``. If this subnet is currently only on the shared +network that is assigned to ``server 1``, we must first edit the shared network and add its +assignment to ``server 2``. Then we can create a new subnet and assign it to both +``server 1`` and ``server 2``, and the shared networks list should now contain our shared network. +Select this shared network from the list in the subnet form. + +Once a shared network is selected, subnet assignments cannot be changed. To +change an assignment, first unassign the subnet from the shared network by clicking the +X button to the right of the selected shared network name. Once the shared network +has been removed, the subnet assignments can now be changed. + +The subnet usually comes with one or more address pools (both IPv4 and IPv6), and it may +also contain delegated prefix pools (IPv6 only). The DHCP servers assign leases +to the clients from the resources available in these pools. The address pool boundaries +are specified as a pair of addresses (i.e. first and last address). Both addresses +must match the subnet prefix (i.e. must be within this subnet), and the first address must be +lower than or equal to the last address. If the first and last addresses are the same, the +pool contains exactly one address. Empty pools are not allowed. + +In some deployments, multiple DHCP servers can share the same subnets but may +include different pools. In this scenario, administrators can avoid the conflict +whereby two servers offer the same address (from overlapping pools) to different +clients. Stork allows the assignment of a pool to a subset +of the DHCP servers assigned to the subnet. If the pool should be included in +all servers, pick all servers in the pool's ``Assignments`` panel. Note that, in addition to +specifying the pool boundaries and assignments, each expandable pool panel also +allows the specification of some pool-level configuration parameters, +such as ``Client Class`` and ``Pool ID``. It is also possible to specify pool-level +DHCP options. + +Create more pools as needed using the ``Add Pool`` button. Click ``Delete Pool`` +to remove a selected pool from the subnet. + +Delegated prefix pools can be added for IPv6 subnets. The delegated prefix pool +boundaries are specified differently than the address pool boundaries; also, the +delegated prefix pool prefix does not have to match (belong to) the subnet prefix. +The delegated prefix pool comprises an actual prefix (e.g. ``3000::/64``) and +a delegated prefix length (e.g. ``96``). The delegated prefix length must be +greater than or equal to the prefix length; in the examples above, ``96 > 64``. If they are +equal, the delegated prefix pool contains exactly one prefix. + +`RFC 6603 `_ describes the mechanism +to exclude one specific prefix from a delegated prefix set in DHCPv6. +This prefix can be optionally specified as an ``Excluded Prefix`` for a delegated +prefix pool. This prefix must belong to the delegated prefix and its length must be +greater than the delegated prefix length. + +The Kea subnet configuration contains ``DHCP Parameters`` which include different +aspects of lease assignment in that subnet. By default, each DHCP server in the +subnet gets the same values of the DHCP parameters. In some cases, however, an +administrator can choose to specify different values for the same parameter on +different servers. Checking the ``Unlock`` box for specific parameters splits +the form for these parameters, so different values can be specified for different +servers in the input boxes. + +The ``DHCP Options`` panel allows specified DHCP options to be returned to +the clients connected to the subnet. In most cases, these options are common +for different servers assigned to the subnet. However, it is possible to differentiate +some options using a mechanism similar to the one described above for ``DHCP Parameters``. +Click ``Unlock setting DHCP options for individual servers`` and set the respective option +sets for different servers. + +Each DHCP option specification begins with the selection of the option code from the dropdown +list. The input boxes displayed below the option code represent the option fields carried +by the option. Fill in these fields with values appropriate for the option. + +If a DHCP option carries an array of fields, only the input box for the first field +is initially displayed. To add more fields to the array, expand the dropdown list +below the option code selector and select the correct option field type to +be added to the array. The option fields and the options can also be removed from +the form. + +When the subnet form is complete, click the ``Submit`` button to save +the subnet and send it to the Kea servers. The ``Submit`` button is disabled if +the form has any invalid entries. + +Updating Subnets +~~~~~~~~~~~~~~~~ + +To update an existing subnet configuration, click on the subnet in the dashboard +or in the subnets list to display detailed information about the subnet. +Click the ``Edit`` button to open the subnet update form. Note that only subnets +on servers with the ``subnet_cmds`` hook library loaded can +be updated. + +Subnet configuration is described in detail in the :ref:`creating-subnets` section. +Here, we focus on the process of updating a subnet. + +A subnet prefix cannot be modified for an updated subnet. To increase +or decrease a subnet prefix length, simply create a new subnet and delete the +existing one. + +If a shared network field is cleared for the updated subnet, this subnet is +removed from the shared network on the Kea servers. If another shared network +is selected instead, the subnet is first removed from the existing shared +network and then added to the newly selected shared network. + +A pool can be deleted from a subnet; however, it is important to understand the +ramifications. While the pool itself is removed from the configuration instantly, +the leases allocated in this pool are not. Kea maintains these leases in the lease +database and clients continue using these leases, until the leases expire or +the clients attempt to renew them. Lease extensions from the deleted pools are +refused to renewing clients; they will be allocated new leases from +the existing pools. + +Use the ``Revert Changes`` button to remove all edits and restore +the original subnet information. Use ``Cancel`` to close the page +without applying any changes. + +Deleting Subnets +~~~~~~~~~~~~~~~~ + +To delete a subnet from Stork and the Kea instances, navigate to the subnet view +from the dashboard or the subnets list and select the desired subnet. Click the +``Delete`` button and confirm the removal of the subnet from all Kea instances. +Deleting a subnet requires the Kea servers with the subnet to have +the ``subnet_cmds`` hook library loaded. + +Creating Shared Networks +~~~~~~~~~~~~~~~~~~~~~~~~ + +Stork can configure new shared networks in the Kea instances with the ``subnet_cmds`` +hook libraries. The shared networks group subnets with common configuration parameters, +and provide a common address space for the DHCP clients connected to different +subnets. To create a shared network, navigate to the shared networks list (``DHCP -> Shared Networks``) and click +the ``New Shared Network`` button. + +A shared network must be assigned to one or more DHCP servers selected in the ``Assignments`` +panel. All servers must be of the same kind (DHCPv4 or DHCPv6), so after selecting +the first server the list is limited to other servers of the same kind. The shared network +is created in all of the selected Kea servers. + +A shared network name is mandatory. It is an arbitrary value that must be unique among +the servers connected to Stork. + +The ``DHCP Parameters`` and ``DHCP Options`` specified for the shared network are common +for all subnets later added to this shared network. However, these parameters and options +specified at the subnet level override the common shared network-level values. + +Similarly to :ref:`creating-subnets`, it is possible to unlock selected parameters and +options, and to specify different values for different servers holding the shared network +configuration. + +When the form is ready, click the ``Submit`` button to create the shared network in Stork and +the Kea instances. This button is disabled if +the form has any invalid entries. + +Updating Shared Networks +~~~~~~~~~~~~~~~~~~~~~~~~ + +To update an existing shared network configuration, click on the shared network in the dashboard +or in the shared networks list to display detailed information about the shared network. +Click the ``Edit`` button to open the shared-network update form. Note that only shared networks +on servers with the ``subnet_cmds`` hook library loaded can +be updated. + +Removing the shared network from a server (in the ``Assignments`` panel) also removes +the subnets belonging to this shared network from the server. They are added back +when the server is added to the shared network. + +Update the shared network as needed and click ``Submit`` to save the changes in +Stork and in the Kea instances. + +Deleting Shared Networks +~~~~~~~~~~~~~~~~~~~~~~~~ + +To delete a shared network from Stork and the Kea instances, navigate to the shared networks view +from the dashboard or the shared networks list and select the desired shared network. Click the +``Delete`` button and confirm the removal of the shared network from all Kea instances. +Deleting a shared network requires the Kea servers with the shared network to have +the ``subnet_cmds`` hook library loaded. + +Deleting a shared network also deletes all subnets it includes. To +preserve the subnets from the deleted shared network, click on each subnet +belonging to it, edit the subnet, clear the shared network selection in the +``Subnet`` panel, and save the subnet changes before deleting the empty shared network. + +Host Reservations +================= + +Listing Host Reservations +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Kea DHCP servers can be configured to assign static resources or parameters to the +DHCP clients communicating with the servers. Most commonly these resources are the +IP addresses or delegated prefixes; however, Kea also allows assignment of hostnames, +PXE boot parameters, client classes, DHCP options, and other parameters. The mechanism by which +a given set of resources and/or parameters is associated with a given DHCP client +is called "host reservations." + +A host reservation consists of one or more DHCP identifiers used to associate the +reservation with a client, e.g. MAC address, DUID, or client identifier; +and a collection of resources and/or parameters to be returned to the +client if the client's DHCP message is associated with the host reservation by one +of the identifiers. Stork can detect existing host reservations specified both in +the configuration files of the monitored Kea servers and in the host database +backends accessed via the Kea Host Commands hook library. + +All reservations detected by Stork can be listed by selecting the ``DHCP`` +menu option and then selecting ``Host Reservations``. + +The first column in the presented view displays one or more DHCP identifiers +for each host in the format ``hw-address=0a:1b:bd:43:5f:99``, where +``hw-address`` is the identifier type. In this case, the identifier type is +the MAC address of the DHCP client for which the reservation has been specified. +Supported identifier types are described in the following sections of the Kea +Administrator Reference Manual (ARM): +`Host Reservations in DHCPv4 `_ +and `Host Reservations in DHCPv6 `_. + +The next two columns contain the static assignments of the IP addresses and/or +prefixes delegated to the clients. There may be one or more such IP reservations +for each host. + +The ``Hostname`` column contains an optional hostname reservation, i.e., the +hostname assigned to the particular client by the DHCP servers via the +Hostname or Client FQDN option. + +The ``Global/Subnet`` column contains the prefixes of the subnets to which the reserved +IP addresses and prefixes belong. If the reservation is global, i.e., is valid +for all configured subnets of the given server, the word "global" is shown +instead of the subnet prefix. + +Finally, the ``App Name`` column includes one or more links to +Kea applications configured to assign each reservation to the +client. The number of applications is typically greater than one +when Kea servers operate in the High Availability setup. In this case, +each of the HA peers uses the same configuration and may allocate IP +addresses and delegated prefixes to the same set of clients, including +static assignments via host reservations. If HA peers are configured +correctly, the reservations they share will have two links in the +``App Name`` column. Next to each link there is a label indicating +whether the host reservation for the given server has been specified +in its configuration file or a host database (via the Host Commands +hook library). + +The ``Filter Hosts`` input box is located above the ``Hosts`` table. It +allows hosts to be filtered by identifier types, identifier values, IP +reservations, and hostnames, and by globality, i.e., ``is:global`` and ``not:global``. +When filtering by DHCP identifier values, it is not necessary to use +colons between the pairs of hexadecimal digits. For example, the +reservation ``hw-address=0a:1b:bd:43:5f:99`` will be found +whether the filtering text is ``1b:bd:43`` or ``1bbd43``. + +The filtering mechanism also recognizes a set of keywords that can be +used in combination with integer values to search host reservations by +selected properties. For example, type: + + - ``appId:2`` to search the host reservations belonging to the app with ID 2. + - ``subnetId:78`` to search the host reservations in subnet with ID 78. In this + case the ID is the one assigned to the subnet by Stork. + - ``keaSubnetId:123`` to search the host reservations in subnets with ID 123 + assigned in the Kea configurations. + + +Host Reservation Usage Status +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Clicking on a selected host in the host reservations list opens a new tab +that shows host details. The tab also includes information about +reserved address and delegated prefix usage. Stork needs to query the Kea +servers to gather the lease information for each address and prefix in the +selected reservation; it may take several seconds or longer before this +information is available. The lease information can be refreshed using the +``Leases`` button at the bottom of the tab. + +The usage status is shown next to each IP address and delegated prefix. +Possible statuses and their meanings are listed in the table below. + +.. table:: Possible IP reservation statuses + :widths: 10 90 + + +-----------------+---------------------------------------------------------------+ + | Status | Meaning | + +=================+===============================================================+ + | ``in use`` | There are valid leases assigned to the client. The client | + | | owns the reservation, or the reservation includes the | + | | ``flex-id`` or ``circuit-id`` identifier, making it impossible| + | | to detect conflicts (see note below). | + +-----------------+---------------------------------------------------------------+ + | ``expired`` | At least one of the leases assigned to the client owning | + | | the reservation is expired. | + +-----------------+---------------------------------------------------------------+ + | ``declined`` | The address is declined on at least one of the Kea servers. | + +-----------------+---------------------------------------------------------------+ + | ``in conflict`` | At least one of the leases for the given reservation is | + | | assigned to a client that does not own this reservation. | + +-----------------+---------------------------------------------------------------+ + | ``unused`` | There are no leases for the given reservation. | + +-----------------+---------------------------------------------------------------+ + +View status details by expanding a selected address or delegated prefix row. +Clicking on the selected address or delegated prefix navigates to the leases +search page, where all leases associated with the address or prefix can be +listed. + +.. note:: + + Detecting ``in conflict`` status is currently not supported for host + reservations with the ``flex-id`` or ``circuit-id`` identifiers. If there are + valid leases for such reservations, they are marked ``in use`` regardless + of whether the conflict actually exists. + +Sources of Host Reservations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two ways to configure Kea servers to use host reservations. First, +the host reservations can be specified within the Kea configuration files; see +`Host Reservations in DHCPv4 `_ +for details. The other way is to use a host database backend, as described in +`Storing Host Reservations in MySQL or PostgreSQL `_. +The second solution requires the given Kea server to be configured to use the +Host Commands hook library (``host_cmds``). This library implements control commands used +to store and fetch the host reservations from the host database to which the Kea +server is connected. If the ``host_cmds`` hook library is not loaded, Stork +only presents the reservations specified within the Kea configuration files. + +Stork periodically fetches the reservations from the host database backends +and updates them in the local database. The default interval at which Stork +refreshes host reservation information is set to 60 seconds. This means that +an update in the host reservation database is not visible in Stork until +up to 60 seconds after it was applied. This interval is configurable in the +Stork interface. + +.. note:: + + The list of host reservations must be manually refreshed by reloading the + browser page to see the most recent updates fetched from the Kea servers. + +Creating Host Reservations +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Navigate to ``DHCP -> Host Reservations`` to view the list of host reservations. +Clicking the ``New Host`` button opens a tab where a new +host reservation can be specified on one or more Kea servers. These Kea servers must be +configured to use the Host Commands hooks library; only servers with ``host_cmds`` +loaded are available for selection in the ``DHCP Servers`` dropdown. + +Both subnet-level and global host reservations can be created. Setting the +``Global reservation`` option disables subnet selection. Use the ``Subnet`` +dropdown to select a subnet-level reservation. If the desired subnet is +not displayed in the dropdown, the selected DHCP servers may not include this +subnet in their configuration. + +To associate the new host reservation with a DHCP client, select +one of the identifier types supported by Kea; the available identifiers vary +depending on whether the selected servers are running DHCPv4 or DHCPv6. The identifier +can be specified using ``hex`` or ``text`` format. For example, the ``hw-address`` +is typically specified as a string of hexadecimal digits, such as ``ab:76:54:c6:45:31``. +In that case, select the ``hex`` option. Some identifiers, e.g. ``circuit-id``, are +often specified using "printable characters," e.g. ``circuit-no-1``. In that case, +select the ``text`` option. Please refer to +`Host Reservations in DHCPv4 `_ +and `Host Reservations in DHCPv6 `_ +for more details regarding the allowed DHCP identifiers and their formats. + +Next, specify the actual reservations. It is possible +to specify at most one IPv4 address, but multiple IPv6 addresses and delegated prefixes +can be indicated. + +The DHCPv4 ``siaddr``, ``sname``, and ``file`` fields can be statically assigned to +clients using host reservations. The relevant values in Kea and Stork are +``Next Server``, ``Server Hostname``, and ``Boot File Name``. Those values can only +be set for DHCPv4 servers; when editing a DHCPv6 host, those fields are not available. + +It is possible to associate one or more client classes with a host. Kea servers +assign these classes to DHCP packets received from the client that has +the host reservation. Client classes are typically defined in the Kea +configurations, but not always. For example, built-in classes like +``DROP`` have no explicit definitions in configuration files. +Click the ``List`` button to select client classes from the list of +classes explicitly defined in the configurations of the monitored Kea servers. +Select the desired class names and click ``Insert``. If the desired class +name is not on the list, type the class name directly in the +input box and press Enter. Click on the X icon next to the class name +to delete it from the host reservation. + +DHCP options can be added to the host reservation by clicking the ``Add Option`` +button; the list of standard DHCP options is available via the dropdown. +However, if the list is missing a desired option, simply +type the option code in the dropdown. The ``Always Send`` checkbox specifies +whether the option should always be returned to a DHCP client assigned this +host reservation, regardless of whether the client requests this option from +the DHCP server. + +Stork recognizes standard DHCP option formats. After selecting an option +code, the form is adjusted to include option fields suitable for the selected +option. If the option payload comprises an array of option fields, only the +first field (or the first group of the record field) is displayed by default. +Use the ``Add `` button below the option code to add more fields +to the array. + +.. note:: + + Currently, Stork does not verify whether the specified options comply + with the formats specified in the RFCs, nor does it check them against the + runtime option definitions configured in Kea. If the wrong option + format is specified, Stork tries to send the option to Kea for verification, + but Kea rejects the new reservation. The reservation can be submitted + again after correcting the option payload. + +Use the ``Add `` button to add suboptions to a DHCP option. +Stork supports top-level options with a maximum of two levels of suboptions. + +If a host reservation is configured on several DHCP servers, all the +servers typically comprise the same set of parameters (i.e. IP addresses, hostname, +boot fields, client classes, and DHCP options). By default, creating a new +host reservation for multiple servers sends an identical copy of the host +reservation to each. It is possible to specify a different set of boot fields, +client classes, or options for different servers by selecting +``Configure individual server values`` at the top of the form. In this case, +specify the complete sets of boot fields, client classes, and options +for each DHCP server. Leaving them blank for some servers means that these +servers receive no boot fields, classes, or DHCP options with the reservation. + +Updating Host Reservations +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In a selected host reservation's view, click the ``Edit`` button to +edit the host reservation information. The page automatically toggles editing +DHCP options individually for each server (see above) when it detects different +option sets on different servers using the reservation. Besides editing the +host reservation information, it is also possible to deselect some of the +servers (using the DHCP Servers dropdown), which deletes the reservation +from these servers. + +Use the ``Revert Changes`` button to remove all edits and restore +the original host reservation information. Use ``Cancel`` to close the page +without applying any changes. + +Deleting Host Reservations +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To delete a host reservation from all DHCP servers for which it is configured, +click on the reservation in the host reservations list. Click the ``Delete`` +button at the bottom of the page and confirm the reservation deletion. Note that this +operation cannot be undone; the reservation is removed from the DHCP servers' +databases. To restore the reservation, it must be re-created. + +Migrating Host Reservations +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Stork can migrate host reservations from the Kea JSON configuration file into +the Kea host database. This feature is available on the host list page. The +hosts to be migrated are selected using the list filter. The filter may be +configured to select all hosts from a given subnet, Kea server, or by free text +search. The migration process starts when the ``Migrate`` button is clicked and +it is performed in the background. + +The host reservations that reside both in the Kea JSON configuration file and in the +host database and are different from each other (are conflicting) cannot be +migrated. They will be skipped and the migration process will continue with the +remaining host reservations. The user needs to resolve the conflicts manually +to migrate such reservations. + +During the migration process, the Stork server stops pulling the data from Kea +and locks the Kea daemons for modification. The lock is released when the +migration process is finished. +Therefore, the changes in the host reservations cannot be immediately seen in +the host reservations list, because the data is not pulled from Kea. Instead, +the migration progress may be monitored in the "Config Migration" page. + +If any errors occur during the migration, the summary and list of them are +displayed in the "Config Migration" page. In this case, the user should fix +the errors and re-run the migration process. Also, if the server is shut +down or restarted during the migration, the process may be safely +repeated. + +The migration can be interrupted anytime by clicking the ``Cancel`` button. + +Stork migrates the host reservations by sending the command to the Kea. The Kea +must be configured to use the ``host_cmds`` hook library. First, the host +reservations are recreated in the host database, and then they are removed from +the JSON configuration. The host reservations are processed in batches of 100 +reservations. + +The migration process sends the ``config-write`` command at the end of each +batch. It is not recommended to alter the Kea configuration during the +migration process, especially the host reservations should not be modified +or deleted. + +Leases +====== + +Lease Search +~~~~~~~~~~~~ + +Stork can search DHCP leases on monitored Kea servers, which is helpful +for troubleshooting issues with a particular IP address or delegated prefix. +It is also helpful in resolving lease allocation issues for certain DHCP clients. +The search mechanism utilizes Kea control commands to find leases on the monitored +servers. Operators must ensure that any Kea servers on which they intend to search +the leases have the `Lease Commands hook library `_ loaded. Stork cannot search leases on Kea instances without +this library. + +The lease search is available via the ``DHCP -> Lease Search`` menu. Enter one +of the searched lease properties in the search box: + +- IPv4 address, e.g. ``192.0.2.3`` +- IPv6 address or delegated prefix without prefix length, ``2001:db8::1`` +- MAC address, e.g. ``01:02:03:04:05:06`` +- DHCPv4 Client Identifier, e.g. ``01:02:03:04`` +- DHCPv6 DUID, e.g. ``00:02:00:00:00:04:05:06:07`` +- Hostname, e.g. ``myhost.example.org`` + +All identifier types can also be specified using notation with spaces, +e.g. 01 02 03 04 05 06, or notation with hexadecimal digits only, e.g. 010203040506. + +To search all declined leases, type ``state:declined`` in the search box. Be aware that this query may +return a large result if there are many declined leases, and thus the query +processing time may also increase. + +Searching using partial text is currently unsupported. For example, searching by +partial IPv4 address ``192.0.2`` is not accepted by the search box. Partial MAC +address ``01:02:03`` is accepted but will return no results. Specify the complete +MAC address instead, e.g. ``01:02:03:04:05:06``. Searching leases in states other +than ``declined`` is also unsupported. For example, the text ``state:expired-reclaimed`` +is not accepted by the search box. + +The search utility automatically recognizes the specified lease type property and +communicates with the Kea servers to find leases using appropriate commands. Each +search attempt may result in several commands to multiple Kea servers; therefore, +it may take several seconds or more before Stork displays the search results. +If some Kea servers are unavailable or return an error, Stork +shows leases found on the servers which returned a "success" status, and displays a +warning message containing the list of Kea servers that returned an error. + +If the same lease is found on two or more Kea servers, the results list contains +all that lease's occurrences. For example, if there is a pair of servers cooperating +via the High Availability hook library, the servers exchange the lease information, and each of them +maintains a copy of the lease database. In that case, the lease search on these +servers typically returns two occurrences of the same lease. + +To display the detailed lease information, click the expand button (``>``) in the +first column for the selected lease. + +Kea High Availability Status +============================ + +To check the High Availability (HA) status of a machine, go to the ``Services -> Kea Apps`` +menu. On the Kea Apps page, click on a machine name in the list and scroll +down to the High Availability section. This information is +periodically refreshed according to the configured interval of the +Kea status puller (see ``Configuration`` -> ``Settings``). + +Kea HA supports advanced resilience configurations with one central +server (hub) connected to multiple servers providing DHCP service in +different network segments (spokes). This configuration model is described +in the `Hub and Spoke Configuration section in the Kea ARM +`_. +Internally, Kea maintains a separate state machine for each connection between +the hub and a server; we call this state machine a ``relationship``. The +hub has many relationships, and each spoke has a single relationship with the hub. +Stork presents HA status for each relationship separately (e.g., ``Relationship #1``, +``Relationship #2``, etc.). Note that each relationship may be in a different state. +For example: a hub may be in the ``partner-down`` state for ``Relationship #1`` +and in the ``hot-standby`` state for ``Relationship #2``. The hub relationship +states depend on the availability of the respective spoke servers. + +See the `High Availability section in the +Kea ARM +`_ +for details about the roles of the servers within the HA setup. + +To see more information, click on the arrow button to the left of +each HA relationship to see the status details. The following picture shows a typical +High Availability status view for a relationship. + +.. figure:: ./static/kea-ha-status.png + :alt: High Availability status example + + +``This Server`` is the DHCP server (daemon) +whose application status is currently displayed; the ``Partner`` is its +active HA partner belonging to the same relationship. The partner belongs +to a different Kea instance running on a different machine; this machine may or +may not be monitored by Stork. The statuses of both servers are fetched by sending +the `status-get +`_ +command to the Kea server whose details are displayed (``This Server``). +In the load-balancing and hot-standby modes, the server +periodically checks the status of its partner by sending it the +``ha-heartbeat`` command. Therefore, this information is not +always up-to-date; its age depends on the heartbeat command interval +(by default 10 seconds). The status of the partner returned by +Stork includes the age of the displayed status information. + +The Stork status information contains the role, state, and scopes +served by each server. In the typical case, both servers are in +load-balancing state, which means that both are serving DHCP +clients. If the ``partner`` crashes, ``This Server`` transitions to +the ``partner-down`` state , which will be indicated in this view. +If ``This Server`` crashes, it will manifest as a communication +problem between Stork and the server. + +The High Availability view also contains information about the +heartbeat status between the two servers, and information about +failover progress. The failover progress information is only +presented when one of the active servers has been unable to +communicate with the partner via the heartbeat exchange for a +time exceeding the ``max-heartbeat-delay`` threshold. If the +server is configured to monitor the DHCP traffic directed to the +partner, to verify that the partner is not responding to this +traffic before transitioning to the ``partner-down`` state, the +number of ``unacked`` clients (clients which failed to get a lease), +connecting clients (all clients currently trying to get a lease from +the partner), and analyzed packets are displayed. The system +administrator may use this information to diagnose why the failover +transition has not taken place or when such a transition is likely to +happen. + +More about the High Availability status information provided by Kea can +be found in the `Kea ARM +`_. + +Viewing the Kea Log +=================== + +Stork offers a simple log-viewing mechanism to diagnose issues with +monitored applications. + +.. note:: + + This mechanism currently only supports viewing Kea log + files. Monitoring other logging locations such as stdout, stderr, + or syslog is also not supported. + +Kea can be configured to save logs to multiple destinations. Different types +of log messages may be output into different log files: syslog, stdout, +or stderr. The list of log destinations used by the Kea application +is available on the ``Kea Apps`` page: click on a Kea app to view its details, +and then select a Kea daemon by clicking on the appropriate tab, +e.g. ``DHCPv4``, ``DHCPv6``, ``DDNS``, or ``CA``. Then, scroll down to the ``Loggers`` section. + +This section contains a table with a list of configured loggers for +the selected daemon. For each configured logger, the logger's name, +logging severity, and output location are presented. The possible output +locations are: log file, stdout, stderr, or syslog. Stork can +display log output to log files, and shows a link to the associated +file. +Loggers that send output to stdout, stderr, and syslog are also listed, +but Stork is unable to display them. + +Clicking on the selected log file navigates to its log viewer. +By default, the viewer displays the tail of the log file, up to 4000 characters. +Depending on the network latency and the size of the log file, it may take +several seconds or more before the log contents are fetched and displayed. + +The log viewer title bar comprises three buttons. The button with the refresh +icon triggers a log-data fetch without modifying the size of the presented +data. Clicking on the ``+`` button extends the size of the viewed log tail +by 4000 characters and refreshes the data in the log viewer. Conversely, +clicking on the ``-`` button reduces the amount of presented data by +4000 characters. Each time any of these buttons is clicked, the viewer +discards the currently presented data and displays the latest part of the +log file tail. + +Please keep in mind that extending the size of the viewed log tail may +slow down the log viewer and increase network congestion as +the amount of data fetched from the monitored machine grows. + +Viewing the Kea Configuration as a JSON Tree +============================================ + +Kea uses JavaScript Object Notation (JSON) to represent its configuration +in the configuration files and the command channel. Parts of the Kea +configuration held in the `Configuration Backend `_ +are also converted to JSON and returned over the control channel in that +format. The diagnosis of issues with a particular server often begins by +inspecting its configuration. + +In the ``Kea Apps`` view, select the appropriate tab for the daemon +configuration to be inspected, and then click on the ``Raw Configuration`` +button. The displayed tree view comprises the selected daemon's +configuration fetched using the Kea ``config-get`` command. + +.. note:: + + The ``config-get`` command returns the configuration currently in use + by the selected Kea server. It is a combination of the configuration + read from the configuration file and from the config backend, if Kea uses + the backend. Therefore, the configuration tree presented in Stork may + differ (sometimes significantly) from the configuration file contents. + +The nodes with complex data types can be individually expanded and +collapsed. All nodes can also be expanded or collapsed by toggling +the ``Expand`` button. When expanding nodes +with many sub-nodes, they may be paginated to avoid degrading browser +performance. + +Click the ``Refresh`` button to fetch and display the latest configuration. +Click ``Download`` to download the entire configuration into a text file. + +.. note:: + + Some configuration fields may contain sensitive data (e.g. passwords + or tokens). The content of these fields is hidden, and a placeholder is shown. + Configurations downloaded as JSON files by users other than super-admins contain + null values in place of the sensitive data. + +Configuration Review +==================== + +Kea DHCP servers are controlled by numerous configuration parameters, and there is a +risk of misconfiguration or inefficient server operation if those parameters +are misused. Stork can help determine typical problems in a Kea server +configuration, using built-in configuration checkers. + +Stork generates configuration reports for a monitored Kea daemon when it +detects that the daemon's configuration has changed. To view the reports for the daemon, +navigate to the application page and select one of the daemons. The +``Configuration Review Reports`` panel lists issues and proposed configuration +updates generated by the configuration checkers. Each checker focuses on one +particular problem. + +If some reports are considered false alarms, it is possible to +disable some configuration checkers for a selected daemon or globally for all +daemons. Click the ``Checkers`` button to open the list of available checkers and +their current state. Click on the values in the ``State`` column for the respective +checkers until they are in the desired states. Besides enabling and disabling +the checker, it is possible to configure it to use the globally specified +setting (i.e., globally enabled or globally disabled). The global settings +control the checker states for all daemons for which explicit states are not +selected. + +Select ``Configuration -> Review Checkers`` from the menu bar to modify the +global states. Use the checkboxes in the ``State`` column to modify the global +states for the respective checkers. + +The ``Selectors`` listed for each checker indicate the types of daemons whose +configurations they validate: + +- ``each-daemon`` - run for all types of daemons +- ``kea-daemon`` - run for all Kea daemons +- ``kea-ca-daemon`` - run for Kea Control Agents +- ``kea-dhcp-daemon`` - run for DHCPv4 and DHCPv6 daemons +- ``kea-dhcp-v4-daemon`` - run for Kea DHCPv4 daemons +- ``kea-dhcp-v6-daemon`` - run for Kea DHCPv6 daemons +- ``kea-d2-daemon`` - run for Kea D2 daemons +- ``bind9-daemon`` - run for BIND 9 daemons + +The ``Triggers`` indicate the conditions under which the checkers are executed. Currently, +there are three types of triggers: + +- ``manual`` - run on user's request +- ``config change`` - run when daemon configuration change has been detected +- ``host reservations change`` - run when a change in the Kea host reservations database has been detected + +The selectors and triggers are not configurable by users. + +Synchronizing Kea Configurations +================================ + +Stork pullers periodically check Kea configurations against the local copies +stored in the Stork database. These local copies are only updated when Stork +detects any mismatch. This approach works fine in most cases and eliminates +the overhead of unnecessarily updating the local database. However, there are +possible scenarios when a mismatch between the configurations is not detected, +but it is still desirable to fetch and repopulate the configurations from the Kea +servers to Stork. + +There are many internal operations in Stork that may be occurring when a configuration change +is detected (e.g., populating host reservations, log viewer initialization, +configuration reviews, and many others). Resynchronizing the configurations from Kea +triggers all these tasks. The resynchronization may correct some data integrity issues that +sometimes occur due to software bugs, network errors, or any other reason. + +To schedule a configuration synchronization from the Kea servers, navigate to +``Services`` and then ``Kea Apps``, and click on the ``Resynchronize Kea Configs`` button. +The pullers fetch and populate the updated configuration data, but this operation +takes time, depending on the configured puller intervals. Ensure the pullers +are not disabled on the ``Settings`` page; otherwise, the configurations will +never re-synchronize. diff --git a/doc/user/dns.rst b/doc/user/dns.rst new file mode 100644 index 000000000..104711c6c --- /dev/null +++ b/doc/user/dns.rst @@ -0,0 +1,384 @@ +.. _dns: + +*** +DNS +*** + +DNS Servers Integration with Stork +================================== + +Stork can monitor the following DNS servers: + +- `BIND 9 `_ +- `PowerDNS `_ + +Stork agent interacts with these servers using certain APIs. To use these APIs, the +agent must parse DNS servers' configuration files to retrieve the configurations of +these APIs, credentials, etc. It implies certain requirements on the DNS servers' +configurations. These requirements are described in the respective sections below. + +BIND 9 +~~~~~~ + +Detection +--------- + +Stork agent begins detecting the BIND 9 server by parsing the process command line. +If the ``named`` process is started with the ``-c`` parameter, the agent uses the +path specified in the parameter as the configuration file location. If ``named`` was +started without this parameter, the agent will use the config file location specified +in the ``STORK_AGENT_BIND9_CONFIG`` environment variable, if set. + +If the config file is not found using the methods described above, the agent will try +to determine its location by executing and parsing the output of the ``named -V`` command, +which contains the information about the BIND 9 build. Finally, it will fallback to +the typical config file locations in the following order: + +- ``/etc/bind/`` +- ``/etc/opt/isc/isc-bind/`` +- ``/etc/opt/isc/scls/isc-bind/`` +- ``/usr/local/etc/namedb/`` + +If the config file is not found using the methods described above, the agent will report an error, +and BIND 9 will not appear on the list of detected apps. + +.. note:: + The ``STORK_AGENT_BIND9_CONFIG`` environment variable setting has no effect if + the ``named`` process was started with the ``-c`` parameter. The explicit + command line parameter takes precedence over the user setting because the parameter + indicates the config file location that the ``named`` process is actually using. + +Access Point Settings +--------------------- + +Stork agent requires access to the BIND 9 configuration file to retrieve the +information about the control API and statistics endpoints, as well as the +security keys accepted by these APIs. It also retrieves the server's IP address +and security credentials to perform AXFR zone transfers. The agent uses +AXFR to get the zone contents (RRs). + +The following is an example setting of ``controls`` block that the agent will +try to determine the ``rndc`` endpoint and credentials to use: + +.. code-block:: text + + controls { + inet * port 9053 allow { localhost; } keys { "rndc-key"; }; + }; + + +where ``rndc-key`` is the name of the key allowed to authenticate the ``rndc`` +command. The ``keys`` clause is optional. If used, the relevant key must +be specified in the config file. For example: + + +.. code-block:: text + + key "rndc-key" { + algorithm hmac-sha256; + secret "iCQvHPqq43AvFK/xRHaKrUiq4GPaFyBpvt/GwKSvKwM="; + }; + +If no ``port`` is specified in the ``controls`` block the agent will assume the default +port 953. If no ``controls`` block is found the agent will assume the ``rndc`` endpoint is +``127.0.0.1:953``. + +The statistics channel is used by the Stork agent for two purposes. First, +for fetching and exporting DNS server statistics from BIND 9 to +`Prometheus `_. Second, it is used for fetching +a list of configured views and zones. The following is the example statistics +channel setting expected by the agent: + +.. code-block:: text + + statistics-channels { + inet 127.0.0.1 port 8053 allow { 127.0.0.1; }; + }; + +According to these settings, the agent will try to get the statistics from the +`http://127.0.0.1:8053/json/v1` endpoints including: + +- `http://127.0.0.1:8053/json/v1/server` +- `http://127.0.0.1:8053/json/v1/traffic` +- `http://127.0.0.1:8053/json/v1/zones` + +The agent will assume the default port 80 if no port is specified. The ``statistics-channels`` +block is mandatory to enable exporting statistics to `Prometheus `_ +and for the :ref:`zone_viewer`. + +Zone Transfer Settings +---------------------- + +Stork agent uses zone transfer (AXFR) to get the zone contents (RRs) when a +user clicks ``Show Zone`` button in the zone viewer. The agent extracts the +following configuration information from the BIND 9 configuration file to +perform the zone transfer for a selected zone: + +- DNS server address and port using the ``listen-on`` or ``listen-on-v6`` options. +- TSIG key name, algorithm and secret using the ``allow-transfer`` and ``match-clients`` options. + +Using the TSIG key is optional when the desired zone is defined in the default +view (i.e., when the zone is specified globally, rather than in a custom view). +It is mandatory when the desired zone is in a non-default view because the DNS server +determines the view where the zone belongs based on the TSIG key. Without the TSIG +key the request is ambiguous because the zone with the given name may belong to +multiple views. + +.. note:: + + Please refer to the `Understanding views in BIND 9, with examples `_ + article for more details about views in BIND 9. + + +The algorithm by which the Stork agent determines appropriate TSIG key is complex and +requires some explanation. + +The ``allow-transfer`` statement in BIND 9 configuration controls who can perform +zone transfer for a given zone or view. This setting can be specified in the zone scope, +view scope or as a global option. The match list can contain IP addresses, keys, ACLs +or keywords (e.g., ``any``, ``none``). The zone-level setting overrides the view-level +setting, which overrides the global setting. From the Stork agent's perspective the most +important information extracted from the ``allow-transfer`` statements is whether the +zone transfer is allowed (is not ``none``), and if they contain any references to the +TSIG keys to be used in the zone transfer. + +The ``match-clients`` statement can be defined in a view scope. The server uses this +statement to match the DNS clients with a given view. It can contain IP addresses, +keys or ACLs. This statement is another source of information for the Stork agent about +the TSIG keys to be used for the zone transfer. Any keys specified in this statement +will take precedence over the keys specified in the ``allow-transfer`` statement. + +It is important to note that since the Stork agent runs on the same machine as the DNS +server, the source IP addresses used by the agent cannot be used by the DNS server +for matching the AXFR requests with the views. It imposes a requirement on the BIND 9 +configuration to rather use keys as view discriminators in the ``match-clients`` +and/or ``allow-transfer`` statements. For example: + +.. code-block:: text + + key "trusted-key" { + algorithm hmac-sha256; + secret "VO6xA4Tc1PWYaqMuPaf6wfkITb+c9/mkzlEaWJavejU="; + }; + + key "guest-key" { + algorithm hmac-sha256; + secret "6L8DwXFboA7FDQJQP051hjFV/n9B3IR/SwDLX7y5czE="; + }; + + acl trusted { !key guest-key; key trusted-key; localhost; }; + acl guest { !key trusted-key; key guest-key; localhost; }; + + view "trusted" { + match-clients { trusted; }; + zone "bind9.example.com" { + type master; + file "/etc/bind/db.bind9.example.com.trusted"; + }; + }; + + view "guest" { + zone "bind9.example.com" { + type master; + file "/etc/bind/db.bind9.example.com.guest"; + allow-transfer { guest; }; + }; + }; + +This configuration snippet defines two views: ``trusted`` and ``guest``. Both +views contain a zone name. The ``trusted`` view is associated with the ``trusted-key`` +key via ACL ``trusted``. The ``guest`` view is associated with the ``guest-key`` +via the ACL ``guest``, and the ``allow-transfer`` statement, instead of ``match-clients``. +This configuration carries enough information for the Stork agent to perform +successful zone transfer for the ``bind9.example.com`` zone in any of the views. +The agent will pick the correct TSIG key to let the DNS server determine the desired view. + +When the DNS server is not configured to use custom views, the configuration can +be much simpler: + +.. code-block:: text + + zone "bind9.example.com" { + type master; + allow-transfer { any; }; + file "/etc/bind/db.bind9.example.com"; + }; + +This zone is defined globally and uses ``allow-transfer`` statement to allow anybody +to perform zone transfer. It requires no TSIG keys. If the reference to a TSIG key +is attached to the zone via ``allow-transfer`` statement, the agent will use this +key to perform the zone transfer. + +See `match-clients `_ +and `allow-transfer `_ +sections of the BIND 9 reference manual for more details. + + +PowerDNS +~~~~~~~~ + +Detection +--------- + +Stork agent begins detecting the PowerDNS server by parsing the process command line. +If the ``pdns_server`` process is started with the ``--config-dir`` parameter, the agent +uses the path specified in the parameter as the configuration file location. The default +configuration file name is ``pdns.conf``, but the server can be started with the +``--config-name`` parameter described in the `PowerDNS documentation `_. +Stork agent uses the custom file name resulting from using this parameter, if it +is found in the server's command line. + +If ``pdns_server`` was started without the ``--config-dir`` parameter, the agent will use +the config file location specified in the ``STORK_AGENT_POWEDNS_CONFIG`` environment variable, +if set. + +If the config file is not found using the methods described above, the agent will try +to find the config file in the typical locations in the following order: + +- ``/etc/powerdns/`` +- ``/etc/pdns/`` +- ``/usr/local/etc/`` +- ``/opt/homebrew/etc/powerdns/`` + +If the config file is not found using the methods described above, the agent will report an error, +and PowerDNS will not be shown on the list of detected apps. + +.. note:: + The ``STORK_AGENT_POWERDNS_CONFIG`` environment variable setting has no effect if + the ``pdns_server`` process was started with the ``--config-dir`` parameter. The explicit + command line parameter takes precedence over the user setting because the parameter + indicates the config file location that the ``pdns_server`` process is actually using. + + +Access Point Settings +--------------------- + +Stork agent requires access to the PowerDNS configuration file to retrieve the +information about the control API (webserver) endpoint, as well as the +security key accepted by this API. The agent uses the control API to get the +general server information, a list of zones, and zone contents (RRs). + +The webserver must be enabled for the Stork agent to detect monitor the +PowerDNS server. The following is a simple configuration snippet containing +the settings expected by the agent: + +.. code-block:: text + + # The API must be explicitly enabled. + api=yes + api-key=stork + webserver=yes + + # The webserver-address and webserver-port settings are optional. + # If not specified, the agent will use the default values of 127.0.0.1:8081. + webserver-address=0.0.0.0 + webserver-port=8085 + + +Zone Transfer Settings +---------------------- + +Stork agent uses zone transfer (AXFR) to get the zone contents (RRs) when a +user clicks ``Show Zone`` button in the zone viewer. + +.. note:: + + DNS views introduced in the PowerDNS 5.0.0 version are not supported by Stork yet. + For that reason, the agent is not using TSIG keys for the zone transfer. + +The agent merely checks if the ``allow-axfr-ips`` setting allows for the zone +transfer from the local host, and if the ``disable-axfr`` is not set to +``true``. It also extracts the DNS server port from the ``local-port`` setting, +if specified. The following is a simple configuration snippet that explicitly +enables zone transfer by the agent: + +.. code-block:: text + + allow-axfr-ips=127.0.0.1,::1 + disable-axfr=no + local-port=53 + +In fact, all of these settings are optional because they are set to their +default values above. + +.. _zone_viewer: + +Zone Viewer +=========== + +Listing Zones +~~~~~~~~~~~~~ + +Zone viewer lists the zones gathered from all monitored DNS servers and allows +for filtering them and browsing their contents (RRs). The Stork agents local to +the monitored DNS servers are responsible for gathering the list of zones using +APIs provided by these servers, and getting the zone contents using zone transfer. +While getting the list of zones occur automatically once the agent starts, getting +the RRs is not immediate, and is only initiated by the Stork server when the user +clicks the ``Show Zone`` button in the zone viewer. + +In order to list the zones gathered by the agent, navigate to the ``DNS --> Zones``. +The list of zones is initially empty. Stork server does not gather the zones +automatically for performance reasons. To see the zones on the list, click the +``Fetch Zones`` button. The server will contact all connected Stork agents +running on the same machines as the DNS servers to fetch the zones that the +agents had gathered. This operation may take significant amount of time (sometimes +minutes) depending on the number of zones. + +The zones are cached in the Stork server database, so browsing the list of fetched +zones is fast. The zones are not refreshed automatically. To see the updated list of +zones, click the ``Fetch Zones`` button again. + +Any errors occuring during the zone fetch can be inspected by clicking the +``Fetch Status`` button. The status view also includes the following information: + +- **Zone Configs Count**: the number of different zone configurations in the server (if the same zone name appears in multiple views, it is counted multiple times). +- **Distinct Zones**: the number of different zones in the server (if the same zone name appears in multiple views, it is counted only once). +- **Builtin Zones**: the number of distinct builtin zones in the server. Builtin zones are special zones automatically generated by BIND 9. + +The number of builtin zones for each BIND 9 server is around hundred. It is often +convenient to filter out the builtin zones from the list to only browse +those that are configured by the user. Click the ``Toggle builtin zones`` to +exclude or include the builtin zones on the list. + +The listed zone types can be selected using the ``Zone Type`` dropdown. +A ``master`` zone type is an alias for the ``primary`` zone type, and a +``slave`` zone type is an alias for the ``secondary`` zone type. +``master`` and ``slave`` types are not listed in the dropdown. +Selecting ``primary`` or ``secondary`` will include ``master`` and ``slave`` +zones besides ``primary`` or ``secondary`` accordingly. + +``RPZ`` is a special type of zone (response policy zone) which configures +the DNS server to apply a set of rules to the DNS queries. The ``RPZ`` +filtering box provides three options: + +- ``include``: include RPZ along with other zones, +- ``exclude``: exclude RPZ from the list, and only show non-RPZ zones, +- ``only``: return only RPZ. + +The remaining filtering boxes allow for filtering the zones by ``App ID``, +``Serial``, ``Class``, and ``App Type``. + + +Viewing Zone Contents +~~~~~~~~~~~~~~~~~~~~~ + +The details of the selected zone are shown in a tab when the zone name is +clicked on the list. If the selected zone's name is found on multiple DNS +servers/views, the ``DNS Views Associated with the Zone`` has multiple +rows, each row displaying the details for the given DNS server/view, and +the ``Show Zone`` button. + +The ``Show Zone`` button is only enabled if the zone type is ``primary`` or +``secondary`` because zone transfer is only supported for these zone types. + +When the ``Show Zone`` button is clicked, the server contacts appropriate +Stork agent to attempt the zone transfer unless the zone contents have +been already transferred and are cached in the Stork server database. +Caching reduces the burden on the DNS servers and respective agents to +run zone transfer for each ``Show Zone`` button click. However, it implies +that the zone contents may get outdated. To enforce the zone transfer, and +get the latest snapshot of the zone contents, click the ``Refresh from DNS`` +button. Check ``Cached from DNS server on`` timestamp to see the age of the +presented zone contents. + diff --git a/doc/user/index.rst b/doc/user/index.rst index 2265667c5..380b7f462 100644 --- a/doc/user/index.rst +++ b/doc/user/index.rst @@ -23,7 +23,8 @@ along with other Stork resources, can be found on ISC's `Stork project homepage overview install usage - managing-kea + dhcp + dns troubleshooting backend-api demo diff --git a/doc/user/managing-kea.rst b/doc/user/managing-kea.rst deleted file mode 100644 index 6d3218ad4..000000000 --- a/doc/user/managing-kea.rst +++ /dev/null @@ -1,378 +0,0 @@ -************************** -Managing Kea Configuration -************************** - -Host Reservations -================= - -Creating Host Reservations -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Navigate to ``DHCP -> Host Reservations`` to view the list of host reservations. -Clicking the ``New Host`` button opens a tab where a new -host reservation can be specified on one or more Kea servers. These Kea servers must be -configured to use the Host Commands hooks library; only servers with ``host_cmds`` -loaded are available for selection in the ``DHCP Servers`` dropdown. - -Both subnet-level and global host reservations can be created. Setting the -``Global reservation`` option disables subnet selection. Use the ``Subnet`` -dropdown to select a subnet-level reservation. If the desired subnet is -not displayed in the dropdown, the selected DHCP servers may not include this -subnet in their configuration. - -To associate the new host reservation with a DHCP client, select -one of the identifier types supported by Kea; the available identifiers vary -depending on whether the selected servers are running DHCPv4 or DHCPv6. The identifier -can be specified using ``hex`` or ``text`` format. For example, the ``hw-address`` -is typically specified as a string of hexadecimal digits, such as ``ab:76:54:c6:45:31``. -In that case, select the ``hex`` option. Some identifiers, e.g. ``circuit-id``, are -often specified using "printable characters," e.g. ``circuit-no-1``. In that case, -select the ``text`` option. Please refer to -`Host Reservations in DHCPv4 `_ -and `Host Reservations in DHCPv6 `_ -for more details regarding the allowed DHCP identifiers and their formats. - -Next, specify the actual reservations. It is possible -to specify at most one IPv4 address, but multiple IPv6 addresses and delegated prefixes -can be indicated. - -The DHCPv4 ``siaddr``, ``sname``, and ``file`` fields can be statically assigned to -clients using host reservations. The relevant values in Kea and Stork are -``Next Server``, ``Server Hostname``, and ``Boot File Name``. Those values can only -be set for DHCPv4 servers; when editing a DHCPv6 host, those fields are not available. - -It is possible to associate one or more client classes with a host. Kea servers -assign these classes to DHCP packets received from the client that has -the host reservation. Client classes are typically defined in the Kea -configurations, but not always. For example, built-in classes like -``DROP`` have no explicit definitions in configuration files. -Click the ``List`` button to select client classes from the list of -classes explicitly defined in the configurations of the monitored Kea servers. -Select the desired class names and click ``Insert``. If the desired class -name is not on the list, type the class name directly in the -input box and press Enter. Click on the X icon next to the class name -to delete it from the host reservation. - -DHCP options can be added to the host reservation by clicking the ``Add Option`` -button; the list of standard DHCP options is available via the dropdown. -However, if the list is missing a desired option, simply -type the option code in the dropdown. The ``Always Send`` checkbox specifies -whether the option should always be returned to a DHCP client assigned this -host reservation, regardless of whether the client requests this option from -the DHCP server. - -Stork recognizes standard DHCP option formats. After selecting an option -code, the form is adjusted to include option fields suitable for the selected -option. If the option payload comprises an array of option fields, only the -first field (or the first group of the record field) is displayed by default. -Use the ``Add `` button below the option code to add more fields -to the array. - -.. note:: - - Currently, Stork does not verify whether the specified options comply - with the formats specified in the RFCs, nor does it check them against the - runtime option definitions configured in Kea. If the wrong option - format is specified, Stork tries to send the option to Kea for verification, - but Kea rejects the new reservation. The reservation can be submitted - again after correcting the option payload. - -Use the ``Add `` button to add suboptions to a DHCP option. -Stork supports top-level options with a maximum of two levels of suboptions. - -If a host reservation is configured on several DHCP servers, all the -servers typically comprise the same set of parameters (i.e. IP addresses, hostname, -boot fields, client classes, and DHCP options). By default, creating a new -host reservation for multiple servers sends an identical copy of the host -reservation to each. It is possible to specify a different set of boot fields, -client classes, or options for different servers by selecting -``Configure individual server values`` at the top of the form. In this case, -specify the complete sets of boot fields, client classes, and options -for each DHCP server. Leaving them blank for some servers means that these -servers receive no boot fields, classes, or DHCP options with the reservation. - -Updating Host Reservations -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In a selected host reservation's view, click the ``Edit`` button to -edit the host reservation information. The page automatically toggles editing -DHCP options individually for each server (see above) when it detects different -option sets on different servers using the reservation. Besides editing the -host reservation information, it is also possible to deselect some of the -servers (using the DHCP Servers dropdown), which deletes the reservation -from these servers. - -Use the ``Revert Changes`` button to remove all edits and restore -the original host reservation information. Use ``Cancel`` to close the page -without applying any changes. - -Deleting Host Reservations -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To delete a host reservation from all DHCP servers for which it is configured, -click on the reservation in the host reservations list. Click the ``Delete`` -button at the bottom of the page and confirm the reservation deletion. Note that this -operation cannot be undone; the reservation is removed from the DHCP servers' -databases. To restore the reservation, it must be re-created. - -.. note:: - - The ``Delete`` button is unavailable for host reservations configured in the - Kea configuration files, or when the reservations are configured in the host - database but the ``host_cmds`` hook library is not loaded. - -Migrate Host Reservations -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Stork can migrate host reservations from the Kea JSON configuration file into -the Kea host database. This feature is available on the host list page. The -hosts to be migrated are selected using the list filter. The filter may be -configured to select all hosts from a given subnet, Kea server, or by free text -search. The migration process starts when the ``Migrate`` button is clicked and -it is performed in the background. - -The host reservations that reside both in the Kea JSON configuration file and in the -host database and are different from each other (are conflicting) cannot be -migrated. They will be skipped and the migration process will continue with the -remaining host reservations. The user needs to resolve the conflicts manually -to migrate such reservations. - -During the migration process, the Stork server stops pulling the data from Kea -and locks the Kea daemons for modification. The lock is released when the -migration process is finished. -Therefore, the changes in the host reservations cannot be immediately seen in -the host reservations list, because the data is not pulled from Kea. Instead, -the migration progress may be monitored in the "Config Migration" page. - -If any errors occur during the migration, the summary and list of them are -displayed in the "Config Migration" page. In this case, the user should fix -the errors and re-run the migration process. Also, if the server is shut -down or restarted during the migration, the process may be safely -repeated. - -The migration can be interrupted anytime by clicking the ``Cancel`` button. - -Stork migrates the host reservations by sending the command to the Kea. The Kea -must be configured to use the ``host_cmds`` hook library. First, the host -reservations are recreated in the host database, and then they are removed from -the JSON configuration. The host reservations are processed in batches of 100 -reservations. - -The migration process sends the ``config-write`` command at the end of each -batch. It is not recommended to alter the Kea configuration during the -migration process, especially the host reservations should not be modified -or deleted. - -Subnets -======= - -.. _creating-subnets: - -Creating Subnets -~~~~~~~~~~~~~~~~ - -Stork can configure new subnets in Kea instances with the Subnet Commands (``subnet_cmds``) -hook library loaded. Navigate to ``DHCP -> Subnets`` to display the subnets list, and click -the ``New Subnet`` button. The opened form initially contains only an input box where -a subnet prefix must be specified. It can be an IPv4 address (e.g., ``192.0.2.0/24``) or -IPv6 prefix (e.g., ``2001:db8:1::/64``). Click the ``Proceed`` button to expand the -form and enter the remaining subnet configuration information. - -The Stork subnet form allows the user to specify a common subnet configuration that -can be instantly populated to multiple DHCP servers. Configuring the same subnet in -multiple Kea instances is specific to the deployments where service redundancy is -required (e.g. deployments using High Availability or with a shared lease database). -When configuring a new subnet it is possible to select multiple DHCP servers -in the ``Assignments`` panel, and the subnet is populated to these servers. Please -note that the list of servers only contains those matching the subnet prefix -(IPv4 or IPv6). Additionally, only servers running the ``subnet_cmds`` hook library -are listed. - -The new subnet may be assigned to a shared network in the ``Subnet`` panel. The Shared -Network dropdown list may be empty for two reasons: - -- There are no shared networks in the selected Kea instances. -- Some Kea instances selected for the subnet lack a shared-network specification. - -If there are no shared networks, simply create one before creating the subnet. -If the shared-network specification is absent, update the shared network and assign it to all servers -to which the subnet will be assigned. As an example, suppose we want to add a new subnet and assign -it to both ``server 1`` and ``server 2``. If this subnet is currently only on the shared -network that is assigned to ``server 1``, we must first edit the shared network and add its -assignment to ``server 2``. Then we can create a new subnet and assign it to both -``server 1`` and ``server 2``, and the shared networks list should now contain our shared network. -Select this shared network from the list in the subnet form. - -Once a shared network is selected, subnet assignments cannot be changed. To -change an assignment, first unassign the subnet from the shared network by clicking the -X button to the right of the selected shared network name. Once the shared network -has been removed, the subnet assignments can now be changed. - -The subnet usually comes with one or more address pools (both IPv4 and IPv6), and it may -also contain delegated prefix pools (IPv6 only). The DHCP servers assign leases -to the clients from the resources available in these pools. The address pool boundaries -are specified as a pair of addresses (i.e. first and last address). Both addresses -must match the subnet prefix (i.e. must be within this subnet), and the first address must be -lower than or equal to the last address. If the first and last addresses are the same, the -pool contains exactly one address. Empty pools are not allowed. - -In some deployments, multiple DHCP servers can share the same subnets but may -include different pools. In this scenario, administrators can avoid the conflict -whereby two servers offer the same address (from overlapping pools) to different -clients. Stork allows the assignment of a pool to a subset -of the DHCP servers assigned to the subnet. If the pool should be included in -all servers, pick all servers in the pool's ``Assignments`` panel. Note that, in addition to -specifying the pool boundaries and assignments, each expandable pool panel also -allows the specification of some pool-level configuration parameters, -such as ``Client Class`` and ``Pool ID``. It is also possible to specify pool-level -DHCP options. - -Create more pools as needed using the ``Add Pool`` button. Click ``Delete Pool`` -to remove a selected pool from the subnet. - -Delegated prefix pools can be added for IPv6 subnets. The delegated prefix pool -boundaries are specified differently than the address pool boundaries; also, the -delegated prefix pool prefix does not have to match (belong to) the subnet prefix. -The delegated prefix pool comprises an actual prefix (e.g. ``3000::/64``) and -a delegated prefix length (e.g. ``96``). The delegated prefix length must be -greater than or equal to the prefix length; in the examples above, ``96 > 64``. If they are -equal, the delegated prefix pool contains exactly one prefix. - -`RFC 6603 `_ describes the mechanism -to exclude one specific prefix from a delegated prefix set in DHCPv6. -This prefix can be optionally specified as an ``Excluded Prefix`` for a delegated -prefix pool. This prefix must belong to the delegated prefix and its length must be -greater than the delegated prefix length. - -The Kea subnet configuration contains ``DHCP Parameters`` which include different -aspects of lease assignment in that subnet. By default, each DHCP server in the -subnet gets the same values of the DHCP parameters. In some cases, however, an -administrator can choose to specify different values for the same parameter on -different servers. Checking the ``Unlock`` box for specific parameters splits -the form for these parameters, so different values can be specified for different -servers in the input boxes. - -The ``DHCP Options`` panel allows specified DHCP options to be returned to -the clients connected to the subnet. In most cases, these options are common -for different servers assigned to the subnet. However, it is possible to differentiate -some options using a mechanism similar to the one described above for ``DHCP Parameters``. -Click ``Unlock setting DHCP options for individual servers`` and set the respective option -sets for different servers. - -Each DHCP option specification begins with the selection of the option code from the dropdown -list. The input boxes displayed below the option code represent the option fields carried -by the option. Fill in these fields with values appropriate for the option. - -If a DHCP option carries an array of fields, only the input box for the first field -is initially displayed. To add more fields to the array, expand the dropdown list -below the option code selector and select the correct option field type to -be added to the array. The option fields and the options can also be removed from -the form. - -When the subnet form is complete, click the ``Submit`` button to save -the subnet and send it to the Kea servers. The ``Submit`` button is disabled if -the form has any invalid entries. - -Updating Subnets -~~~~~~~~~~~~~~~~ - -To update an existing subnet configuration, click on the subnet in the dashboard -or in the subnets list to display detailed information about the subnet. -Click the ``Edit`` button to open the subnet update form. Note that only subnets -on servers with the ``subnet_cmds`` hook library loaded can -be updated. - -Subnet configuration is described in detail in the :ref:`creating-subnets` section. -Here, we focus on the process of updating a subnet. - -A subnet prefix cannot be modified for an updated subnet. To increase -or decrease a subnet prefix length, simply create a new subnet and delete the -existing one. - -If a shared network field is cleared for the updated subnet, this subnet is -removed from the shared network on the Kea servers. If another shared network -is selected instead, the subnet is first removed from the existing shared -network and then added to the newly selected shared network. - -A pool can be deleted from a subnet; however, it is important to understand the -ramifications. While the pool itself is removed from the configuration instantly, -the leases allocated in this pool are not. Kea maintains these leases in the lease -database and clients continue using these leases, until the leases expire or -the clients attempt to renew them. Lease extensions from the deleted pools are -refused to renewing clients; they will be allocated new leases from -the existing pools. - -Use the ``Revert Changes`` button to remove all edits and restore -the original subnet information. Use ``Cancel`` to close the page -without applying any changes. - -Deleting Subnets -~~~~~~~~~~~~~~~~ - -To delete a subnet from Stork and the Kea instances, navigate to the subnet view -from the dashboard or the subnets list and select the desired subnet. Click the -``Delete`` button and confirm the removal of the subnet from all Kea instances. -Deleting a subnet requires the Kea servers with the subnet to have -the ``subnet_cmds`` hook library loaded. - -Shared Networks -=============== - -Creating Shared Networks -~~~~~~~~~~~~~~~~~~~~~~~~ - -Stork can configure new shared networks in the Kea instances with the ``subnet_cmds`` -hook libraries. The shared networks group subnets with common configuration parameters, -and provide a common address space for the DHCP clients connected to different -subnets. To create a shared network, navigate to the shared networks list (``DHCP -> Shared Networks``) and click -the ``New Shared Network`` button. - -A shared network must be assigned to one or more DHCP servers selected in the ``Assignments`` -panel. All servers must be of the same kind (DHCPv4 or DHCPv6), so after selecting -the first server the list is limited to other servers of the same kind. The shared network -is created in all of the selected Kea servers. - -A shared network name is mandatory. It is an arbitrary value that must be unique among -the servers connected to Stork. - -The ``DHCP Parameters`` and ``DHCP Options`` specified for the shared network are common -for all subnets later added to this shared network. However, these parameters and options -specified at the subnet level override the common shared network-level values. - -Similarly to :ref:`creating-subnets`, it is possible to unlock selected parameters and -options, and to specify different values for different servers holding the shared network -configuration. - -When the form is ready, click the ``Submit`` button to create the shared network in Stork and -the Kea instances. This button is disabled if -the form has any invalid entries. - -Updating Shared Networks -~~~~~~~~~~~~~~~~~~~~~~~~ - -To update an existing shared network configuration, click on the shared network in the dashboard -or in the shared networks list to display detailed information about the shared network. -Click the ``Edit`` button to open the shared-network update form. Note that only shared networks -on servers with the ``subnet_cmds`` hook library loaded can -be updated. - -Removing the shared network from a server (in the ``Assignments`` panel) also removes -the subnets belonging to this shared network from the server. They are added back -when the server is added to the shared network. - -Update the shared network as needed and click ``Submit`` to save the changes in -Stork and in the Kea instances. - -Deleting Shared Networks -~~~~~~~~~~~~~~~~~~~~~~~~ - -To delete a shared network from Stork and the Kea instances, navigate to the shared networks view -from the dashboard or the shared networks list and select the desired shared network. Click the -``Delete`` button and confirm the removal of the shared network from all Kea instances. -Deleting a shared network requires the Kea servers with the shared network to have -the ``subnet_cmds`` hook library loaded. - -Deleting a shared network also deletes all subnets it includes. To -preserve the subnets from the deleted shared network, click on each subnet -belonging to it, edit the subnet, clear the shared network selection in the -``Subnet`` panel, and save the subnet changes before deleting the empty shared network. diff --git a/doc/user/overview.rst b/doc/user/overview.rst index f35b38328..d2baa63be 100644 --- a/doc/user/overview.rst +++ b/doc/user/overview.rst @@ -17,38 +17,111 @@ The goals of the ISC Stork project are: Although Stork currently only offers monitoring, insight, alerts, and configuration for Kea DHCP, we plan to add similar capabilities -for BIND 9 in future versions. +for BIND 9 and other DNS implementations in the future. Please refer to the :ref:`glossary` for specific terms used in this documentation and in the Stork UI. -Architecture -============ +Security Design +=============== -Stork is composed of two components: the Stork server (``stork-server``) -and the Stork agent (``stork-agent``). +Stork has been designed with security in mind. This section describes +the security design and the security features implemented in Stork. -The Stork server is installed on a stand-alone machine. It connects to -any agents, typically running on other machines, and indirectly (via those agents) -interacts with the Kea DHCP and BIND 9 apps. It provides an integrated, -centralized front end for these apps. Only one Stork server is deployed -in a network. +The Stork environment is composed of multiple services: the Stork server, the Stork agent(s), the Kea Control Agent(s), the Kea +DHCP daemon(s), the Kea D2 daemon(s), the BIND 9 daemon(s), the PowerDNS daemon(s), the PostgreSQL database(s), and Prometheus. Each service has its own security +considerations. -The Stork agent is installed along with Kea DHCP and/or BIND 9 and -interacts directly with those apps. There may be many -agents deployed in a network, one per machine. The following figure shows -the connections between Stork components, Kea, and BIND 9. It also shows the different -kinds of databases in a typical deployment. +The following is a diagram of the main Stork components and the services that they might interact with; +a typical Stork deployment would have a much simpler subset of components: -.. figure:: ./static/arch.png +.. figure:: ./static/ecosystem-protocols.drawio.png :align: center - :alt: Connections between Stork components, Kea, and BIND 9 + :alt: Stork security diagram + Connections and protocols between Stork components and services -The presented example includes three physical machines, each running a Stork agent -instance and the Kea and/or BIND 9 applications. The leftmost machine includes a Kea -server connected to a database. Kea natively supports two database systems: -MySQL and PostgreSQL. Kea uses a database to store three types of information: +.. + The above diagram may be edited at https://app.diagrams.net/. + The source file is located in the doc/user/static/ecosystem-protocols.drawio.xml file. + +The Stork server is the central component of the Stork environment. It serves the web UI and REST API over the HTTP +protocol (connections no. 1, 4, and 8 on the diagram). The administrator may secure the Stork server by providing a trusted +SSL/TLS certificate. This is recommended, especially when the Stork server is exposed to a public network. +The Stork server may share some statistics with the Prometheus monitoring system; it is strongly recommended to limit +access to the metrics endpoint to the Prometheus server only. The Stork server has no built-in mechanism to limit the access, but this +may be achieved by using a reverse proxy like NGINX or Apache. See the :ref:`server-setup` section for more details. + +The Stork server requires a PostgreSQL database to store its data; the connection to the database may be established +over the local socket or over the HTTP protocol (connection no. 10 on the diagram). The first option is more secure, +as it does not expose database traffic to the network, but it requires the database to be installed on the same +machine as the Stork server. The second option allows the database to be installed on a different machine, +securing the connection with SSL/TLS is recommended. The Stork server supports mutual TLS authentication with the +database, which should ensure the highest level of security. In any case, Stork server should use a dedicated database +user with the minimum required permissions, and no one else should have access to the database; the database should be +regularly backed up. See the :ref:`securing-the-database-connection` for more details. + +The Stork agent resides on the same machine as the Kea and DNS daemons and is permitted to access their +configuration files and logs and use their APIs. Additionally, it can list the processes running on the machine and read +their details. Therefore, it is recommended to run the Stork agent as a dedicated user with the minimum required +permissions. + +The Stork server communicates with the Stork agents over the GRPC protocol (connection no. 5 on the diagram). Stork +has a built-in solution for securing the communication on this channel using the Transport Layer Security (TLS) +protocol: mutual TLS authentication, which ensures that the server and the agent are who they claim to be. +It is self-managed and does not require any additional configuration. The server acts as a Certificate Authority (CA) +and generates the root certificate and the private key, which are stored in the server's database. The server generates +a certificate and a private key for each agent, during the agent-registration process. The agent uses the certificate and +the private key to authenticate itself to the server; the server does not trust the agent's certificate by default. The +server administrator must approve the agent-registration request in the Stork web UI, by +comparing the token displayed in the UI with the token displayed in the agent's logs. If the tokens match, the +administrator can approve the registration request. It is a one-time operation that protects against +"man-in-the-middle" attacks. + +Alternatively, new Stork agents can be authorized automatically, if an administrator provides agents with the server token. +This deployment mode might be more useful for automated deployments. The server token is a secret available only to the +administrator on the server UI, which may be provided to the agent during the agent registration process. The agents +registered with this token are automatically approved by the server. +Since the server token is a secret and must be protected, we recommend using it only in secure environments. If the +server token is compromised, the administrator can revoke it in the server UI. See the :ref:`secure-server-agent` for more details. + +The Stork agent is responsible for exchanging data between the Stork server and the Kea (connection no. 11 on the +diagram) and DNS (connections no. 7 and 9 on the diagram) daemons. The agent and the daemons are running on the same +machine, so the communication is local; however, it can still be secured. + +The Kea Control Agent (Kea CA) supports Basic Auth to authenticate the clients of its REST API, via the control channel used by the +Stork agent. This solution may be enabled to protect the Kea CA from unauthorized access. If it is enabled, the Stork +agent must be configured with the username and password to authenticate itself to the Kea CA. It is recommended to limit +access to this file only to the ``stork-agent`` user. The Kea CA may be configured to serve the REST API over the +HTTPS protocol; enabling this is strongly recommended if the Basic Auth is configured or if the Kea CA listens on +non-localhost interfaces. Additionally, the Kea CA may be configured to require the client certificate to authenticate +clients. The Stork agent offers partial support for mutual TLS authentication. If it recognizes that the Kea CA requires a +client certificate, the Stork agent attaches its GRPC client certificate (the certificate that was obtained during the agent +registration) to the request. This certificate does not pass client-certificate verification by the Kea CA, which means +that the Kea CA must be configured not to verify the client certificate. + +Stork's connection to BIND 9 utilizes two protocols: RNDC (control channel, connection no. 9 on the diagram) and HTTP ( +statistics channel, connection no. 7 on the diagram). The RNDC protocol may be secured by using RNDC keys; this is +especially recommended if the BIND 9 daemon listens on non-localhost interfaces. The Stork agent retries the RNDC +key from the BIND 9 configuration file; the agent must have the necessary permissions to read this file and use the +``rndc`` and ``named-checkconf`` commands. +The statistics channel is served over the HTTP protocol and may be secured by the SSL/TLS certificate. + +The Stork agent acts as a Prometheus exporter for the Kea and BIND 9 statistics. The Prometheus server scrapes the +metrics from the agent over the HTTP protocol (connection no. 6 on the diagram); this connection is unsecure and does not +support TLS. The metrics channel is expected not to be exposed to the public network. It is recommended to configure any +firewall to limit access to the metrics endpoint only to the Prometheus server. + +The Stork server supports hooks that may be loaded to provide new authentication methods. If these authentication methods +use a dedicated authentication service, we recommend securing the connection to this service with the SSL/TLS +certificate if the service and hook support it. In particular, the LDAP hook may be configured to use the SSL/TLS (LDAPS) +protocol. + +Databases +========= + +Kea natively supports two database systems: MySQL and PostgreSQL. Kea uses a database +to store three types of information: - DHCP leases (this storage is often referred to as a lease database or lease backend), - DHCP host reservations (this storage is referred to as a host database or host backend), @@ -57,17 +130,15 @@ MySQL and PostgreSQL. Kea uses a database to store three types of information: For more information regarding the supported database backends, please consult `the Kea Database Administration section of the Kea ARM `_. -Note that the Stork server does not communicate directly with the Kea databases. +Stork server does not communicate directly with the Kea databases. The lease, host, and configuration information is pulled from the Kea instances by the Kea control channel, which then relays the data to the Stork server. Depending on the configuration, Kea may use all the database backends or only a subset of them, or it may not use any database at all. If it uses the database backends, they may be combined in the same database instance -or they may be separate instances. The rightmost machine on the figure above -is an example of the Kea server running without a database; in this case it -stores allocated DHCP leases in a CSV file (often called a memfile backend). +or they may be separate instances. -The Stork server is connected to its own PostgreSQL database, which has a different +Stork server is connected to its own PostgreSQL database, which has a different schema than a Kea database and stores the information required for the Stork server operation. This database is typically installed on the same physical machine as the Stork server but may also be remote. @@ -87,32 +158,6 @@ also pulls the current configuration from the Kea servers before applying any configuration updates, to minimize the risk of conflicts with any updates applied directly to the Kea servers (outside of Stork). -.. note:: - - The future goal is to make Kea servers fully configurable from Stork, which - already supports configuring the most frequently changing parameters - (e.g., host reservations, subnets, shared networks, and selected global parameters). - However, some configuration capabilities are not yet available via Stork, which means that - administrators may sometimes need to apply configuration updates directly to - Kea servers. These Kea servers are the source of the configuration information in - Stork, so ideally all updates to them would be made via Stork. Even though that - is not yet an option, we highly recommend - applying configuration updates via the Stork interface whenever possible. Stork - provides locking mechanisms to prevent multiple end users from concurrently - modifying the configuration of the same Kea server; direct configuration updates - bypass this mechanism, resulting in a risk of configuration conflicts. - - -Stork uses the ``config-set`` and ``config-write`` Kea commands to save changes related -to global parameters and options, subnets, and shared networks. For this to work, Stork -needs to have write access to the Kea configuration, which is a security decision made -by a Kea administrator. Some deployments may choose to restrict write access; -in such cases, Stork is not able to push configuration changes to Kea. - -The host reservations management mechanism does not modify configurations on -disk; instead, it stores host reservations in the database. Therefore, the note above -does not apply to host management. - Preprocessing the Kea and BIND 9 Statistics for the Prometheus Server ===================================================================== @@ -262,6 +307,32 @@ The following operations are supported: The user can edit the global parameters and DHCP options on Kea servers. +.. note:: + + The future goal is to make Kea servers fully configurable from Stork, which + already supports configuring the most frequently changing parameters + (e.g., host reservations, subnets, shared networks, and selected global parameters). + However, some configuration capabilities are not yet available via Stork, which means that + administrators may sometimes need to apply configuration updates directly to + Kea servers. These Kea servers are the source of the configuration information in + Stork, so ideally all updates to them would be made via Stork. Even though that + is not yet an option, we highly recommend + applying configuration updates via the Stork interface whenever possible. Stork + provides locking mechanisms to prevent multiple end users from concurrently + modifying the configuration of the same Kea server; direct configuration updates + bypass this mechanism, resulting in a risk of configuration conflicts. + + +Stork uses the ``config-set`` and ``config-write`` Kea commands to save changes related +to global parameters and options, subnets, and shared networks. For this to work, Stork +needs to have write access to the Kea configuration, which is a security decision made +by a Kea administrator. Some deployments may choose to restrict write access; +in such cases, Stork is not able to push configuration changes to Kea. + +The host reservations management mechanism does not modify configurations on +disk; instead, it stores host reservations in the database. Therefore, the note above +does not apply to host management. + Reviewing the Kea Configuration =============================== @@ -282,112 +353,19 @@ This feature requires the ``lease_cmds`` hook to be loaded in Kea. The Stork server also displays a list of the leases related to a particular host reservation. -Monitoring the BIND 9 Service -============================= - -The Stork server currently has limited capabilities to monitor the BIND 9 service. -It can display the status of the BIND 9 service, the version of the BIND 9 -daemon, and the details of the configured control and statistics channels. -The UI also displays the RNDC keys, if set, and the basic statistics. - -The BIND 9 instance must be configured with the control channel to enable -monitoring, and the Stork agent must have the necessary permissions -to access the ``named`` daemon configuration and to execute the RNDC commands. - -The BIND 9 statistics channel must be configured to enable the statistics export to Prometheus. -The statistics channel must be configured to enable the statistics export to Prometheus. - -Security Design -=============== - -Stork has been designed with security in mind. The following section describes -the security design and the security features implemented in Stork. - -The Stork environment is composed of multiple services: the Stork server, the Stork agent(s), the Kea Control Agent(s), the Kea -DHCP daemon(s), the Kea D2 daemon(s), the BIND 9 daemon(s), the PostgreSQL database(s), and Prometheus. Each service has its own security -considerations. - -The following is a diagram of all Stork components and the services that they might interact with; -a typical Stork deployment would have a much simpler subset of components: - -.. figure:: ./static/ecosystem-protocols.drawio.png - :align: center - :alt: Stork security diagram - - Connections and protocols between Stork components and services - -.. - The above diagram may be edited at https://app.diagrams.net/. - The source file is located in the doc/user/static/ecosystem-protocols.drawio.xml file. - -The Stork server is the central component of the Stork environment. It serves the web UI and REST API over the HTTP -protocol (connections no. 1, 4, and 8 on the diagram). The administrator may secure the Stork server by providing a trusted -SSL/TLS certificate. This is recommended, especially when the Stork server is exposed to a public network. -The Stork server may share some statistics with the Prometheus monitoring system; it is strongly recommended to limit -access to the metrics endpoint to the Prometheus server only. The Stork server has no built-in mechanism to limit the access, but this -may be achieved by using a reverse proxy like NGINX or Apache. See the :ref:`server-setup` section for more details. - -The Stork server requires a PostgreSQL database to store its data; the connection to the database may be established -over the local socket or over the HTTP protocol (connection no. 10 on the diagram). The first option is more secure, -as it does not expose database traffic to the network, but it requires the database to be installed on the same -machine as the Stork server. The second option allows the database to be installed on a different machine, -securing the connection with SSL/TLS is recommended. The Stork server supports mutual TLS authentication with the -database, which should ensure the highest level of security. In any case, Stork server should use a dedicated database -user with the minimum required permissions, and no one else should have access to the database; the database should be -regularly backed up. See the :ref:`securing-the-database-connection` for more details. - -The Stork agent resides on the same machine as the Kea and BIND 9 daemons and is permitted to access their -configuration files and logs and use their APIs. Additionally, it can list the processes running on the machine and read -their details. Therefore, it is recommended to run the Stork agent as a dedicated user with the minimum required -permissions. - -The Stork server communicates with the Stork agents over the GRPC protocol (connection no. 5 on the diagram). Stork -has a built-in solution for securing the communication on this channel using the Transport Layer Security (TLS) -protocol: mutual TLS authentication, which ensures that the server and the agent are who they claim to be. -It is self-managed and does not require any additional configuration. The server acts as a Certificate Authority (CA) -and generates the root certificate and the private key, which are stored in the server's database. The server generates -a certificate and a private key for each agent, during the agent-registration process. The agent uses the certificate and -the private key to authenticate itself to the server; the server does not trust the agent's certificate by default. The -server administrator must approve the agent-registration request in the Stork web UI, by -comparing the token displayed in the UI with the token displayed in the agent's logs. If the tokens match, the -administrator can approve the registration request. It is a one-time operation that protects against -"man-in-the-middle" attacks. - -Alternatively, new Stork agents can be authorized automatically, if an administrator provides agents with the server token. -This deployment mode might be more useful for automated deployments. The server token is a secret available only to the -administrator on the server UI, which may be provided to the agent during the agent registration process. The agents -registered with this token are automatically approved by the server. -Since the server token is a secret and must be protected, we recommend using it only in secure environments. If the -server token is compromised, the administrator can revoke it in the server UI. See the :ref:`secure-server-agent` for more details. - -The Stork agent is responsible for exchanging data between the Stork server and the Kea (connection no. 11 on the -diagram) and BIND 9 (connections no. 7 and 9 on the diagram) daemons. The agent and the daemons are running on the same -machine, so the communication is local; however, it can still be secured. +Monitoring the DNS Services +=========================== -The Kea Control Agent (Kea CA) supports Basic Auth to authenticate the clients of its REST API, via the control channel used by the -Stork agent. This solution may be enabled to protect the Kea CA from unauthorized access. If it is enabled, the Stork -agent must be configured with the username and password to authenticate itself to the Kea CA. It is recommended to limit -access to this file only to the ``stork-agent`` user. The Kea CA may be configured to serve the REST API over the -HTTPS protocol; enabling this is strongly recommended if the Basic Auth is configured or if the Kea CA listens on -non-localhost interfaces. Additionally, the Kea CA may be configured to require the client certificate to authenticate -clients. The Stork agent offers partial support for mutual TLS authentication. If it recognizes that the Kea CA requires a -client certificate, the Stork agent attaches its GRPC client certificate (the certificate that was obtained during the agent -registration) to the request. This certificate does not pass client-certificate verification by the Kea CA, which means -that the Kea CA must be configured not to verify the client certificate. +Stork is integrated with the BIND 9 and PowerDNS servers. Support for additional +DNS server kinds is planned for future versions. -Stork's connection to BIND 9 utilizes two protocols: RNDC (control channel, connection no. 9 on the diagram) and HTTP ( -statistics channel, connection no. 7 on the diagram). The RNDC protocol may be secured by using RNDC keys; this is -especially recommended if the BIND 9 daemon listens on non-localhost interfaces. The Stork agent retries the RNDC -key from the BIND 9 configuration file; the agent must have the necessary permissions to read this file and use the -``rndc`` and ``named-checkconf`` commands. -The statistics channel is served over the HTTP protocol and may be secured by the SSL/TLS certificate. +Stork can gather and display the list of zones configured on the supported +DNS servers. It can also display the contents of the zones (RRs) for +the primary and secondary zones. -The Stork agent acts as a Prometheus exporter for the Kea and BIND 9 statistics. The Prometheus server scrapes the -metrics from the agent over the HTTP protocol (connection no. 6 on the diagram); this connection is unsecure and does not -support TLS. The metrics channel is expected not to be exposed to the public network. It is recommended to configure any -firewall to limit access to the metrics endpoint only to the Prometheus server. +Stork agent can also work as a Prometheus exporter for the BIND 9 server. +The statistics export for PowerDNS is currently unavailable. -The Stork server supports hooks that may be loaded to provide new authentication methods. If these authentication methods -use a dedicated authentication service, we recommend securing the connection to this service with the SSL/TLS -certificate if the service and hook support it. In particular, the LDAP hook may be configured to use the SSL/TLS (LDAPS) -protocol. +Taking advantage of the DNS integration requires some specific configurations +on the DNS servers. These configurations are described in the respective +sections of the :ref:`dns` chapter. diff --git a/doc/user/usage.rst b/doc/user/usage.rst index 5ecf7618b..989060f7a 100644 --- a/doc/user/usage.rst +++ b/doc/user/usage.rst @@ -4,17 +4,19 @@ Using Stork *********** -This section describes how to use the features available in Stork. To -connect to Stork, use a web browser and connect to port 8080 on the Stork server machine. If +This section describes how to use general features available in Stork. For DHCP-specific features, +see :ref:`dhcp`. For DNS-specific features, see :ref:`dns`. + +To connect to Stork, use a web browser and connect to port 8080 on the Stork server machine. If ``stork-server`` is running on a localhost, it can be reached by navigating to http://localhost:8080. Dashboard ========= -The main Stork page presents a dashboard. It contains a panel with -information about DHCP and a panel with events observed or noticed by -the Stork server. +The main Stork page presents a dashboard. It contains two expandable panels: including +DHCP and DNS data respectively. I also includes an events panel listing the events pertaining +to the monitored servers. The DHCP Panel ~~~~~~~~~~~~~~ @@ -26,6 +28,29 @@ Each section contains three kinds of information: - a list of up to five shared networks with the highest pool utilization - statistics about DHCP +The Service Status section in the DHCP panel lists all monitored DHCP servers. +The information shown includes the hostname, the application version, the app name, +the daemon running on the host, its communication status, the average number of ACKs +sent by the daemon over the previous 15 minutes and 24 hours, its High Availability (HA) +state, whether an HA failure has been detected, and the host's running uptime. +More details about the meaning of these status indicators is included in the :ref:`dhcp` +section. + +The DNS Panel +~~~~~~~~~~~~~ + +The Service Status section in the DNS panel lists all monitored DNS servers. +Similarly, to the DHCP pane, it includes the hostname, the app name, the communication +status with the daemon, and the daemon uptime. It also includes the following indicators +for each DNS daemon: + +- **Zone Fetch Status**: whether or not the zones have been fetched from the server into the Stork server's database. +- **Zone Configs Count**: the number of different zone configurations in the server (if the same zone name appears in multiple views, it is counted multiple times). +- **Distinct Zones**: the number of different zones in the server (if the same zone name appears in multiple views, it is counted only once). +- **Builtin Zones**: the number of distinct builtin zones in the server. Builtin zones are special zones generated by BIND 9. + +More information about these indicators can be found in the :ref:`dns` section. + The Events Panel ~~~~~~~~~~~~~~~~ @@ -36,17 +61,6 @@ or applications, provide a link to a web page containing information about the given object. Users with ``super-admin`` permissions can clear the events (though this leaves behind an event describing their action). -The Service Status Panel -~~~~~~~~~~~~~~~~~~~~~~~~ - -The Service Status Panel displays the current status of all the hosts currently -being monitored by Stork. The information shown includes the hostname, the application -version, the app name, the daemon running on the host, its communication status, the -average number of ACKs sent by the daemon over the previous 15 minutes and 24 hours, -its High Availability (HA) state, whether an HA failure has been detected, and the -host's running uptime. More details about the meaning of these status indicators is -included in the following sections. - Managing Users ============== @@ -264,14 +278,40 @@ application version, application status, and some machine details. The ``Action`` button is also available, to refresh the information about the application. -The application status displays a list of daemons belonging to the +The application status may include a list of daemons belonging to the application. Several daemons may be presented in the application -status columns; typically, they include DHCPv4, DHCPv6, DDNS, and the Kea Control -Agent (CA). +status columns (e.g., DHCPv4, DHCPv6, DDNS, and the Kea Control +Agent (CA) for Kea). The daemons are not listed for the DNS servers +because each DNS server has only one daemon. -Stork uses ``rndc`` to retrieve the application's status. It looks for +The listed Kea daemons are those that Stork finds in the Kea CA +configuration file. A warning is displayed for any daemons from +the CA configuration file that are not running. When the Kea +installation is simply using the default CA configuration file, which +includes configuration of daemons that are never intended to be +launched, it is recommended to remove (or comment out) those +configurations to eliminate unwanted warnings from Stork about +inactive daemons. + +Stork uses ``rndc`` to retrieve the BIND 9 application's status. It looks for the ``controls`` statement in the configuration file, and uses the -first listed control point to monitor the application. +first listed control point to monitor the application. The `statistics-channels` +must be configured to allow fetching BIND 9 statistics (and exporting them to Prometheus), +and fetch a list of zones. + +PowerDNS servers to be monitored by Stork are required to have the +webserver enabled in their configuration file. See the +`PowerDNS documentation `_ +for more details. Stork agent uses the webserver to retrieve the +PowerDNS server's status information, a list of zones. + +Stork's zone viewer allows for browsing the zone contents (RRs) for the +selected zone types. Internally, the zone contents are fetched from the DNS +server using zone transfer (AXFR). For that reason, the servers must be +properly configured to allow zone transfer to the Stork agent. The detailed +requirements for the DNS servers configurations to properly work with the +Stork agent can be found in the :ref:`dns` section. + Furthermore, the Stork agent can be used as a Prometheus exporter if ``named`` is built with ``json-c``, because @@ -281,15 +321,6 @@ the exporter queries the first listed channel. Stork is able to export the most metrics if ``zone-statistics`` is set to ``full`` in the ``named.conf`` configuration. -For Kea, the listed daemons are those that Stork finds in the CA -configuration file. A warning is displayed for any daemons from -the CA configuration file that are not running. When the Kea -installation is simply using the default CA configuration file, which -includes configuration of daemons that are never intended to be -launched, it is recommended to remove (or comment out) those -configurations to eliminate unwanted warnings from Stork about -inactive daemons. - Friendly App Names ~~~~~~~~~~~~~~~~~~ @@ -331,530 +362,6 @@ button is enabled; click this button to submit the new name. The ``Rename`` button is disabled if the name is invalid. In this case, a hint is displayed to explain the issues with the new name. -Subnets and Networks -~~~~~~~~~~~~~~~~~~~~ - -IPv4 and IPv6 Subnets per Kea Application ------------------------------------------- - -One of the primary configuration aspects of any network is the layout -of IP addressing. This is represented in Kea with IPv4 and IPv6 -subnets. Each subnet represents addresses used on a physical -link. Typically, certain parts of each subnet ("pools") are delegated -to the DHCP server to manage. Stork is able to display this -information. - -One way to inspect the subnets and pools within Kea is by looking at -each Kea application to get an overview of the configurations a -specific Kea application is serving. A list of configured subnets on -that specific Kea application is displayed. The following picture -shows a simple view of the Kea DHCPv6 server running with a single -subnet, with three pools configured in it. - -.. figure:: ./static/kea-subnets6.png - :alt: View of subnets assigned to a single Kea application - -IPv4 and IPv6 Subnets in the Whole Network ------------------------------------------- - -It is convenient to see a complete overview of all subnets -configured in the network that are being monitored by Stork. Once at least one -machine with the Kea application running is added to Stork, click on -the ``DHCP`` menu and choose ``Subnets`` to see all available subnets. The -view shows all IPv4 and IPv6 subnets, with the address pools and links -to the applications that are providing them. An example view of all -subnets in the network is presented in the figure below. - -.. figure:: ./static/kea-subnets-list.png - :alt: List of all subnets in the network - -Stork provides filtering capabilities; it is possible to -choose to see IPv4 only, IPv6 only, or both. There is also an -omnisearch box available where users can type a search string. -For strings of four characters or more, the filtering takes place -automatically, while shorter strings require the user to hit -Enter. For example, in the above example it is possible to show only -the first (192.0.2.0/24) subnet by searching for the *0.2* string. One -can also search for specific pools, and easily filter the subnet with -a specific pool, by searching for part of the pool range, -e.g. *3.200*. The input box accepts a text string that can be a part of the -subnet or shared network name. - -Stork displays pool utilization for each subnet, with -the absolute number of addresses allocated and usage percentage. -There are two thresholds: 80% (warning; the pool utilization -bar turns orange) and 90% (critical; the pool utilization bar -turns red). - -Subnet Names ------------- - -Kea allows storing any arbitrary data related to a subnet in the ``user-context`` -field. This field is a JSON object. It may be used to store some metadata about -the subnet, such as the name of the location where the subnet is used, the name -of the department, name of related service or any other information that is -useful for the network administrator. - -Stork displays the subnet's user context on the subnet page. Additionally, the -value of the ``subnet-name`` key is displayed in the subnet list view. This -allows the network administrator to quickly identify the subnet by its name. - -The subnet name can be used to filter the subnets on the subnet list page and -in the global search box. - -IPv4 and IPv6 Networks ----------------------- - -Kea uses the concept of a shared network, which is essentially a stack -of subnets deployed on the same physical link. Stork -retrieves information about shared networks and aggregates it across all -configured Kea servers. The ``Shared Networks`` view allows the -inspection of networks and the subnets that belong in them. Pool -utilization is shown for each subnet. - -Host Reservations -~~~~~~~~~~~~~~~~~ - -Listing Host Reservations -------------------------- - -Kea DHCP servers can be configured to assign static resources or parameters to the -DHCP clients communicating with the servers. Most commonly these resources are the -IP addresses or delegated prefixes; however, Kea also allows assignment of hostnames, -PXE boot parameters, client classes, DHCP options, and other parameters. The mechanism by which -a given set of resources and/or parameters is associated with a given DHCP client -is called "host reservations." - -A host reservation consists of one or more DHCP identifiers used to associate the -reservation with a client, e.g. MAC address, DUID, or client identifier; -and a collection of resources and/or parameters to be returned to the -client if the client's DHCP message is associated with the host reservation by one -of the identifiers. Stork can detect existing host reservations specified both in -the configuration files of the monitored Kea servers and in the host database -backends accessed via the Kea Host Commands hook library. - -All reservations detected by Stork can be listed by selecting the ``DHCP`` -menu option and then selecting ``Host Reservations``. - -The first column in the presented view displays one or more DHCP identifiers -for each host in the format ``hw-address=0a:1b:bd:43:5f:99``, where -``hw-address`` is the identifier type. In this case, the identifier type is -the MAC address of the DHCP client for which the reservation has been specified. -Supported identifier types are described in the following sections of the Kea -Administrator Reference Manual (ARM): -`Host Reservations in DHCPv4 `_ -and `Host Reservations in DHCPv6 `_. - -The next two columns contain the static assignments of the IP addresses and/or -prefixes delegated to the clients. There may be one or more such IP reservations -for each host. - -The ``Hostname`` column contains an optional hostname reservation, i.e., the -hostname assigned to the particular client by the DHCP servers via the -Hostname or Client FQDN option. - -The ``Global/Subnet`` column contains the prefixes of the subnets to which the reserved -IP addresses and prefixes belong. If the reservation is global, i.e., is valid -for all configured subnets of the given server, the word "global" is shown -instead of the subnet prefix. - -Finally, the ``App Name`` column includes one or more links to -Kea applications configured to assign each reservation to the -client. The number of applications is typically greater than one -when Kea servers operate in the High Availability setup. In this case, -each of the HA peers uses the same configuration and may allocate IP -addresses and delegated prefixes to the same set of clients, including -static assignments via host reservations. If HA peers are configured -correctly, the reservations they share will have two links in the -``App Name`` column. Next to each link there is a label indicating -whether the host reservation for the given server has been specified -in its configuration file or a host database (via the Host Commands -hook library). - -The ``Filter Hosts`` input box is located above the ``Hosts`` table. It -allows hosts to be filtered by identifier types, identifier values, IP -reservations, and hostnames, and by globality, i.e., ``is:global`` and ``not:global``. -When filtering by DHCP identifier values, it is not necessary to use -colons between the pairs of hexadecimal digits. For example, the -reservation ``hw-address=0a:1b:bd:43:5f:99`` will be found -whether the filtering text is ``1b:bd:43`` or ``1bbd43``. - -The filtering mechanism also recognizes a set of keywords that can be -used in combination with integer values to search host reservations by -selected properties. For example, type: - - - ``appId:2`` to search the host reservations belonging to the app with ID 2. - - ``subnetId:78`` to search the host reservations in subnet with ID 78. In this - case the ID is the one assigned to the subnet by Stork. - - ``keaSubnetId:123`` to search the host reservations in subnets with ID 123 - assigned in the Kea configurations. - - -Host Reservation Usage Status ------------------------------ - -Clicking on a selected host in the host reservations list opens a new tab -that shows host details. The tab also includes information about -reserved address and delegated prefix usage. Stork needs to query the Kea -servers to gather the lease information for each address and prefix in the -selected reservation; it may take several seconds or longer before this -information is available. The lease information can be refreshed using the -``Leases`` button at the bottom of the tab. - -The usage status is shown next to each IP address and delegated prefix. -Possible statuses and their meanings are listed in the table below. - -.. table:: Possible IP reservation statuses - :widths: 10 90 - - +-----------------+---------------------------------------------------------------+ - | Status | Meaning | - +=================+===============================================================+ - | ``in use`` | There are valid leases assigned to the client. The client | - | | owns the reservation, or the reservation includes the | - | | ``flex-id`` or ``circuit-id`` identifier, making it impossible| - | | to detect conflicts (see note below). | - +-----------------+---------------------------------------------------------------+ - | ``expired`` | At least one of the leases assigned to the client owning | - | | the reservation is expired. | - +-----------------+---------------------------------------------------------------+ - | ``declined`` | The address is declined on at least one of the Kea servers. | - +-----------------+---------------------------------------------------------------+ - | ``in conflict`` | At least one of the leases for the given reservation is | - | | assigned to a client that does not own this reservation. | - +-----------------+---------------------------------------------------------------+ - | ``unused`` | There are no leases for the given reservation. | - +-----------------+---------------------------------------------------------------+ - -View status details by expanding a selected address or delegated prefix row. -Clicking on the selected address or delegated prefix navigates to the leases -search page, where all leases associated with the address or prefix can be -listed. - -.. note:: - - Detecting ``in conflict`` status is currently not supported for host - reservations with the ``flex-id`` or ``circuit-id`` identifiers. If there are - valid leases for such reservations, they are marked ``in use`` regardless - of whether the conflict actually exists. - -Sources of Host Reservations ----------------------------- - -There are two ways to configure Kea servers to use host reservations. First, -the host reservations can be specified within the Kea configuration files; see -`Host Reservations in DHCPv4 `_ -for details. The other way is to use a host database backend, as described in -`Storing Host Reservations in MySQL or PostgreSQL `_. -The second solution requires the given Kea server to be configured to use the -Host Commands hook library (``host_cmds``). This library implements control commands used -to store and fetch the host reservations from the host database to which the Kea -server is connected. If the ``host_cmds`` hook library is not loaded, Stork -only presents the reservations specified within the Kea configuration files. - -Stork periodically fetches the reservations from the host database backends -and updates them in the local database. The default interval at which Stork -refreshes host reservation information is set to 60 seconds. This means that -an update in the host reservation database is not visible in Stork until -up to 60 seconds after it was applied. This interval is configurable in the -Stork interface. - -.. note:: - - The list of host reservations must be manually refreshed by reloading the - browser page to see the most recent updates fetched from the Kea servers. - -Lease Search -~~~~~~~~~~~~ - -Stork can search DHCP leases on monitored Kea servers, which is helpful -for troubleshooting issues with a particular IP address or delegated prefix. -It is also helpful in resolving lease allocation issues for certain DHCP clients. -The search mechanism utilizes Kea control commands to find leases on the monitored -servers. Operators must ensure that any Kea servers on which they intend to search -the leases have the `Lease Commands hook library `_ loaded. Stork cannot search leases on Kea instances without -this library. - -The lease search is available via the ``DHCP -> Lease Search`` menu. Enter one -of the searched lease properties in the search box: - -- IPv4 address, e.g. ``192.0.2.3`` -- IPv6 address or delegated prefix without prefix length, ``2001:db8::1`` -- MAC address, e.g. ``01:02:03:04:05:06`` -- DHCPv4 Client Identifier, e.g. ``01:02:03:04`` -- DHCPv6 DUID, e.g. ``00:02:00:00:00:04:05:06:07`` -- Hostname, e.g. ``myhost.example.org`` - -All identifier types can also be specified using notation with spaces, -e.g. 01 02 03 04 05 06, or notation with hexadecimal digits only, e.g. 010203040506. - -To search all declined leases, type ``state:declined`` in the search box. Be aware that this query may -return a large result if there are many declined leases, and thus the query -processing time may also increase. - -Searching using partial text is currently unsupported. For example, searching by -partial IPv4 address ``192.0.2`` is not accepted by the search box. Partial MAC -address ``01:02:03`` is accepted but will return no results. Specify the complete -MAC address instead, e.g. ``01:02:03:04:05:06``. Searching leases in states other -than ``declined`` is also unsupported. For example, the text ``state:expired-reclaimed`` -is not accepted by the search box. - -The search utility automatically recognizes the specified lease type property and -communicates with the Kea servers to find leases using appropriate commands. Each -search attempt may result in several commands to multiple Kea servers; therefore, -it may take several seconds or more before Stork displays the search results. -If some Kea servers are unavailable or return an error, Stork -shows leases found on the servers which returned a "success" status, and displays a -warning message containing the list of Kea servers that returned an error. - -If the same lease is found on two or more Kea servers, the results list contains -all that lease's occurrences. For example, if there is a pair of servers cooperating -via the High Availability hook library, the servers exchange the lease information, and each of them -maintains a copy of the lease database. In that case, the lease search on these -servers typically returns two occurrences of the same lease. - -To display the detailed lease information, click the expand button (``>``) in the -first column for the selected lease. - -Kea High Availability Status -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To check the High Availability (HA) status of a machine, go to the ``Services -> Kea Apps`` -menu. On the Kea Apps page, click on a machine name in the list and scroll -down to the High Availability section. This information is -periodically refreshed according to the configured interval of the -Kea status puller (see ``Configuration`` -> ``Settings``). - -Kea HA supports advanced resilience configurations with one central -server (hub) connected to multiple servers providing DHCP service in -different network segments (spokes). This configuration model is described -in the `Hub and Spoke Configuration section in the Kea ARM -`_. -Internally, Kea maintains a separate state machine for each connection between -the hub and a server; we call this state machine a ``relationship``. The -hub has many relationships, and each spoke has a single relationship with the hub. -Stork presents HA status for each relationship separately (e.g., ``Relationship #1``, -``Relationship #2``, etc.). Note that each relationship may be in a different state. -For example: a hub may be in the ``partner-down`` state for ``Relationship #1`` -and in the ``hot-standby`` state for ``Relationship #2``. The hub relationship -states depend on the availability of the respective spoke servers. - -See the `High Availability section in the -Kea ARM -`_ -for details about the roles of the servers within the HA setup. - -To see more information, click on the arrow button to the left of -each HA relationship to see the status details. The following picture shows a typical -High Availability status view for a relationship. - -.. figure:: ./static/kea-ha-status.png - :alt: High Availability status example - - -``This Server`` is the DHCP server (daemon) -whose application status is currently displayed; the ``Partner`` is its -active HA partner belonging to the same relationship. The partner belongs -to a different Kea instance running on a different machine; this machine may or -may not be monitored by Stork. The statuses of both servers are fetched by sending -the `status-get -`_ -command to the Kea server whose details are displayed (``This Server``). -In the load-balancing and hot-standby modes, the server -periodically checks the status of its partner by sending it the -``ha-heartbeat`` command. Therefore, this information is not -always up-to-date; its age depends on the heartbeat command interval -(by default 10 seconds). The status of the partner returned by -Stork includes the age of the displayed status information. - -The Stork status information contains the role, state, and scopes -served by each server. In the typical case, both servers are in -load-balancing state, which means that both are serving DHCP -clients. If the ``partner`` crashes, ``This Server`` transitions to -the ``partner-down`` state , which will be indicated in this view. -If ``This Server`` crashes, it will manifest as a communication -problem between Stork and the server. - -The High Availability view also contains information about the -heartbeat status between the two servers, and information about -failover progress. The failover progress information is only -presented when one of the active servers has been unable to -communicate with the partner via the heartbeat exchange for a -time exceeding the ``max-heartbeat-delay`` threshold. If the -server is configured to monitor the DHCP traffic directed to the -partner, to verify that the partner is not responding to this -traffic before transitioning to the ``partner-down`` state, the -number of ``unacked`` clients (clients which failed to get a lease), -connecting clients (all clients currently trying to get a lease from -the partner), and analyzed packets are displayed. The system -administrator may use this information to diagnose why the failover -transition has not taken place or when such a transition is likely to -happen. - -More about the High Availability status information provided by Kea can -be found in the `Kea ARM -`_. - -Viewing the Kea Log -~~~~~~~~~~~~~~~~~~~ - -Stork offers a simple log-viewing mechanism to diagnose issues with -monitored applications. - -.. note:: - - This mechanism currently only supports viewing Kea log - files; viewing BIND 9 logs is not yet supported. Monitoring other - logging locations such as stdout, stderr, or syslog is also not - supported. - -Kea can be configured to save logs to multiple destinations. Different types -of log messages may be output into different log files: syslog, stdout, -or stderr. The list of log destinations used by the Kea application -is available on the ``Kea Apps`` page: click on a Kea app to view its details, -and then select a Kea daemon by clicking on the appropriate tab, -e.g. ``DHCPv4``, ``DHCPv6``, ``DDNS``, or ``CA``. Then, scroll down to the ``Loggers`` section. - -This section contains a table with a list of configured loggers for -the selected daemon. For each configured logger, the logger's name, -logging severity, and output location are presented. The possible output -locations are: log file, stdout, stderr, or syslog. Stork can -display log output to log files, and shows a link to the associated -file. -Loggers that send output to stdout, stderr, and syslog are also listed, -but Stork is unable to display them. - -Clicking on the selected log file navigates to its log viewer. -By default, the viewer displays the tail of the log file, up to 4000 characters. -Depending on the network latency and the size of the log file, it may take -several seconds or more before the log contents are fetched and displayed. - -The log viewer title bar comprises three buttons. The button with the refresh -icon triggers a log-data fetch without modifying the size of the presented -data. Clicking on the ``+`` button extends the size of the viewed log tail -by 4000 characters and refreshes the data in the log viewer. Conversely, -clicking on the ``-`` button reduces the amount of presented data by -4000 characters. Each time any of these buttons is clicked, the viewer -discards the currently presented data and displays the latest part of the -log file tail. - -Please keep in mind that extending the size of the viewed log tail may -slow down the log viewer and increase network congestion as -the amount of data fetched from the monitored machine grows. - -Viewing the Kea Configuration as a JSON Tree -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Kea uses JavaScript Object Notation (JSON) to represent its configuration -in the configuration files and the command channel. Parts of the Kea -configuration held in the `Configuration Backend `_ -are also converted to JSON and returned over the control channel in that -format. The diagnosis of issues with a particular server often begins by -inspecting its configuration. - -In the ``Kea Apps`` view, select the appropriate tab for the daemon -configuration to be inspected, and then click on the ``Raw Configuration`` -button. The displayed tree view comprises the selected daemon's -configuration fetched using the Kea ``config-get`` command. - -.. note:: - - The ``config-get`` command returns the configuration currently in use - by the selected Kea server. It is a combination of the configuration - read from the configuration file and from the config backend, if Kea uses - the backend. Therefore, the configuration tree presented in Stork may - differ (sometimes significantly) from the configuration file contents. - -The nodes with complex data types can be individually expanded and -collapsed. All nodes can also be expanded or collapsed by toggling -the ``Expand`` button. When expanding nodes -with many sub-nodes, they may be paginated to avoid degrading browser -performance. - -Click the ``Refresh`` button to fetch and display the latest configuration. -Click ``Download`` to download the entire configuration into a text file. - -.. note:: - - Some configuration fields may contain sensitive data (e.g. passwords - or tokens). The content of these fields is hidden, and a placeholder is shown. - Configurations downloaded as JSON files by users other than super-admins contain - null values in place of the sensitive data. - -Configuration Review -~~~~~~~~~~~~~~~~~~~~ - -Kea DHCP servers are controlled by numerous configuration parameters, and there is a -risk of misconfiguration or inefficient server operation if those parameters -are misused. Stork can help determine typical problems in a Kea server -configuration, using built-in configuration checkers. - -Stork generates configuration reports for a monitored Kea daemon when it -detects that the daemon's configuration has changed. To view the reports for the daemon, -navigate to the application page and select one of the daemons. The -``Configuration Review Reports`` panel lists issues and proposed configuration -updates generated by the configuration checkers. Each checker focuses on one -particular problem. - -If some reports are considered false alarms, it is possible to -disable some configuration checkers for a selected daemon or globally for all -daemons. Click the ``Checkers`` button to open the list of available checkers and -their current state. Click on the values in the ``State`` column for the respective -checkers until they are in the desired states. Besides enabling and disabling -the checker, it is possible to configure it to use the globally specified -setting (i.e., globally enabled or globally disabled). The global settings -control the checker states for all daemons for which explicit states are not -selected. - -Select ``Configuration -> Review Checkers`` from the menu bar to modify the -global states. Use the checkboxes in the ``State`` column to modify the global -states for the respective checkers. - -The ``Selectors`` listed for each checker indicate the types of daemons whose -configurations they validate: - -- ``each-daemon`` - run for all types of daemons -- ``kea-daemon`` - run for all Kea daemons -- ``kea-ca-daemon`` - run for Kea Control Agents -- ``kea-dhcp-daemon`` - run for DHCPv4 and DHCPv6 daemons -- ``kea-dhcp-v4-daemon`` - run for Kea DHCPv4 daemons -- ``kea-dhcp-v6-daemon`` - run for Kea DHCPv6 daemons -- ``kea-d2-daemon`` - run for Kea D2 daemons -- ``bind9-daemon`` - run for BIND 9 daemons - -The ``Triggers`` indicate the conditions under which the checkers are executed. Currently, -there are three types of triggers: - -- ``manual`` - run on user's request -- ``config change`` - run when daemon configuration change has been detected -- ``host reservations change`` - run when a change in the Kea host reservations database has been detected - -The selectors and triggers are not configurable by users. - -Synchronizing Kea Configurations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Stork pullers periodically check Kea configurations against the local copies -stored in the Stork database. These local copies are only updated when Stork -detects any mismatch. This approach works fine in most cases and eliminates -the overhead of unnecessarily updating the local database. However, there are -possible scenarios when a mismatch between the configurations is not detected, -but it is still desirable to fetch and repopulate the configurations from the Kea -servers to Stork. - -There are many internal operations in Stork that may be occurring when a configuration change -is detected (e.g., populating host reservations, log viewer initialization, -configuration reviews, and many others). Resynchronizing the configurations from Kea -triggers all these tasks. The resynchronization may correct some data integrity issues that -sometimes occur due to software bugs, network errors, or any other reason. - -To schedule a configuration synchronization from the Kea servers, navigate to -``Services`` and then ``Kea Apps``, and click on the ``Resynchronize Kea Configs`` button. -The pullers fetch and populate the updated configuration data, but this operation -takes time, depending on the configured puller intervals. Ensure the pullers -are not disabled on the ``Settings`` page; otherwise, the configurations will -never re-synchronize. - The Events Page =============== From ac83bb5110d5c22b28c037c5cfc004562c97f85c Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Thu, 4 Sep 2025 11:03:16 +0200 Subject: [PATCH 2/2] [#1844] Added ChangeLog for #1844 --- .../1844-organizing-arm-doc-for-dhcp-and-dns.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 changelog_unreleased/1844-organizing-arm-doc-for-dhcp-and-dns.md diff --git a/changelog_unreleased/1844-organizing-arm-doc-for-dhcp-and-dns.md b/changelog_unreleased/1844-organizing-arm-doc-for-dhcp-and-dns.md new file mode 100644 index 000000000..950c48f92 --- /dev/null +++ b/changelog_unreleased/1844-organizing-arm-doc-for-dhcp-and-dns.md @@ -0,0 +1,7 @@ +[doc] marcin + + Restructured Stork ARM. Created new sections to cover DHCP and + DNS-specific topics. Described the process of detecting Kea, + BIND 9 and PowerDNS, and the configuration requirements for the + DNS servers, so they can be monitored by Stork. + (Gitlab #1844)