From: Shawn Routhier Date: Mon, 1 Aug 2016 05:21:56 +0000 (-0700) Subject: [trac4511] Add description of the legal log hooks configuration and use X-Git-Tag: trac4551_base~10 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8fd967a483297c313945c5162863e14b98a0a331;p=thirdparty%2Fkea.git [trac4511] Add description of the legal log hooks configuration and use --- diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml index 94ac3d72ba..104d3108a3 100644 --- a/doc/guide/hooks.xml +++ b/doc/guide/hooks.xml @@ -138,4 +138,211 @@ hooks libraries. + +
+ Available Hooks Libraries + + As described above the hooks functionality provides a way to customize + a Kea server without modifying the core code. ISC has chosen to take + advantage of this feature to provide functions that may not be useful + to all users. To this end ISC has created some hooks libraries which + are discussed in the following sections. + + + + Some of these libraries will be available with the base code while + others will only be available via a support contract. + +
+ Legal Log Hooks + + This section describes the legal log hooks library. This library + povides hooks that record a detailed log of lease assignments + and renewals into a set of log files. Currently this library + is only available to customers with a support contract. + + + In many legal jurisdictions companies, especially ISPs, must record + information about the addresses they have leased to DHCP clients. + This library is designed to help with that requirement. If the + information that it records is sufficient it may be used directly. + If your jurisdiction requires that you save a different set of + information you may use it as a template or example and create your + own custom logging hooks. + +
+ Log File Naming + + The names for the log files have the following form: + + +path/base-name.CCYYMMDD.txt + + + The "path" and "base-name" are supplied in the + configuration as described below see + . The next part of the name is + the date the log file was started, with four digits for year, two digits + for month and two digits for day. The file is rotated on a daily basis. + + + When running Kea servers for both DHCPv4 and DHCPv6 the log names must + be distinct. See the examples in . + +
+
+ DHCPv4 Log Entries + + For DHCPv4 the library creates entries based on DHCPREQUEST messages + and corresponding DHCPv4 leases intercepted by lease4_select + (for new leases) and lease4_renew (for renewed leases) hooks. + + + An entry is a single string with no embedded end-of-line markers + and has the following sections: + +address duration device-id {client-info} {relay-info} + + + + Where: + + + address - the leased IPv4 address given out and whether it was + assigned or renewed. + + + duration - the lease lifetime expressed in days (if present), + hours, minutes and seconds. A lease lifetime of 0xFFFFFFFF will be + denoted with the text "infinite duration". + + + device-id - the client's hardware address shown as numerical type + and hex digit string. + + + client-info - the DHCP client id option (61) if present, shown as + a hex string. + + + relay-info - for relayed packets the giaddr and the RAI circuit id + and remote id options (option 82 sub options 1 and 2) if present. + The circuit id and remote id are presented as hex strings + + + + + For instance (line breaks added for readability, they would not + be present in the log file). + +Address: 192.2.1.100 has been renewed for 1 hrs 52 min 15 secs to a device with +hardware address: hwtype=1 08:00:2b:02:3f:4e, client-id: 17:34:e2:ff:09:92:54 +connected via relay at address: 192.2.16.33, identified by circuit-id: +68:6f:77:64:79 and remote-id: 87:f6:79:77:ef + + +
+
+ DHCPv6 Log Entries + + For DHCPv6 the library creates entries based on lease management + actions intercepted by the lease6_select (for new leases), lease6_renew + (for renewed leases) and lease6_rebind (for rebound leases). + + + An entry is a single string with no embedded end-of-line markers + and has the following sections: + +address duration device-id {relay-info}* + + + + Where: + + + address - the leased IPv6 address or prefix given out and whether + it was assigned or renewed. + + + duration - the lease lifetime expressed in days (if present), + hours, minutes and seconds. A lease lifetime of 0xFFFFFFFF will be + denoted with the text "infinite duration". + + + device-id - the client's DUID and hardware address (if present). + + + relay-info - for relayed packets the content of relay agent + messages, remote id and subscriber id options (x and xx) if present. + + + + + For instance (line breaks added for readability, they would not + be present in the log file). + +Address:2001:db8:1:: has been assigned for 0 hrs 11 mins 53 secs to a device with +DUID: 17:34:e2:ff:09:92:54 and hardware address: hwtype=1 08:00:2b:02:3f:4e +(from Raw Socket) connected via relay at address: fe80::abcd for client on +link address: 3001::1, hop count: 1, identified by remote-id: +01:02:03:04:0a:0b:0c:0d:0e:0f and subscriber-id: 1a:2b:3c:4d:5e:6f + + +
+ +
+