1.. _hooks-host-cache: 2 3host_cache: Caching Host Reservations 4===================================== 5 6Some database backends, such as RADIUS, are considered slow and may take 7a long time to respond. Since Kea in general is synchronous, backend 8performance directly affects DHCP performance. To minimize the 9impact and improve performance, the Host Cache library provides a way to 10cache information from the database locally. This includes negative 11caching, i.e. the ability to remember that there is no client 12information in the database. 13 14.. note:: 15 16 This library may only be loaded by the ``kea-dhcp4`` or 17 ``kea-dhcp6`` process. 18 19In principle, this hooks library can be used with any backend that may 20introduce performance degradation (MySQL, PostgreSQL, Cassandra, or 21RADIUS). Host Cache must be loaded for the RADIUS accounting mechanism 22to work. 23 24The Host Cache hooks library is currently very simple. It takes only one 25optional parameter ("maximum"), which defines the maximum number of hosts 26to be cached. If not specified, the default value of 0 is used, which 27means there is no limit. This hooks library can be loaded the same way as 28any other hooks library; for example, this configuration could be used: 29 30:: 31 32 "Dhcp4": { 33 34 # Your regular DHCPv4 configuration parameters here. 35 36 "hooks-libraries": [ 37 { 38 "library": "/usr/local/lib/kea/hooks/libdhc_host_cache.so", 39 "parameters": { 40 41 # Tells Kea to never cache more than 1000 hosts. 42 "maximum": 1000 43 44 } 45 } ] 46 47Once loaded, the Host Cache hooks library provides a number of new 48commands which can be used either over the control channel (see 49:ref:`ctrl-channel-client`) or the RESTful API (see 50:ref:`agent-overview`). An example RESTful API client is described in 51:ref:`shell-overview`. The following sections describe the commands 52available. 53 54.. _command-cache-flush: 55 56The cache-flush Command 57~~~~~~~~~~~~~~~~~~~~~~~ 58 59This command allows removal of a specified number of cached host 60entries. It takes one parameter, which defines the number of hosts to be 61removed. An example usage looks as follows: 62 63:: 64 65 { 66 "command": "cache-flush", 67 "arguments": 1000 68 } 69 70This command will remove 1000 hosts. To delete all cached 71hosts, please use cache-clear instead. The hosts are stored in FIFO 72(first-in, first-out) order, so the oldest entries are always removed. 73 74.. _command-cache-clear: 75 76The cache-clear Command 77~~~~~~~~~~~~~~~~~~~~~~~ 78 79This command allows removal of all cached host entries. An example usage 80looks as follows: 81 82:: 83 84 { 85 "command": "cache-clear" 86 } 87 88This command will remove all hosts. To delete only a certain 89number of cached hosts, please use cache-flush instead. 90 91.. _command-cache-size: 92 93The cache-size Command 94~~~~~~~~~~~~~~~~~~~~~~ 95 96This command returns the number of host entries. An example usage looks 97as follows: 98 99:: 100 101 { 102 "command": "cache-size" 103 } 104 105.. _command-cache-write: 106 107The cache-write Command 108~~~~~~~~~~~~~~~~~~~~~~~ 109 110In general, the cache content is considered a runtime state and the 111server can be shut down or restarted as usual; the cache will then be 112repopulated after restart. However, there are some cases when it is 113useful to store the contents of the cache. One such case is RADIUS, 114where the cached hosts also retain additional cached RADIUS attributes; 115there is no easy way to obtain this information again, because renewing 116clients send their packet to the DHCP server directly. Another use case 117is when an administrator wants to restart the server and, for performance reasons, 118wants it to start with a hot (populated) cache. 119 120This command allows writing the contents of the in-memory cache to a 121file on disk. It takes one parameter, which defines the filename. An 122example usage looks as follows: 123 124:: 125 126 { 127 "command": "cache-write", 128 "arguments": "/tmp/kea-host-cache.json" 129 } 130 131This causes the contents to be stored in the /tmp/kea-host-cache.json 132file. That file can then be loaded with the cache-load command or 133processed by any other tool that is able to understand JSON format. 134 135.. _command-cache-load: 136 137The cache-load Command 138~~~~~~~~~~~~~~~~~~~~~~ 139 140See the previous section for a discussion of use cases where it may be 141useful to write and load contents of the host cache to disk. 142 143This command allows the contents of a file on disk to be loaded into an 144in-memory cache. It takes one parameter, which defines the filename. An 145example usage looks as follows: 146 147:: 148 149 { 150 "command": "cache-load", 151 "arguments": "/tmp/kea-host-cache.json" 152 } 153 154This command will store the contents to the /tmp/kea-host-cache.json 155file. That file can then be loaded with the cache-load command or 156processed by any other tool that is able to understand JSON format. 157 158.. _command-cache-get: 159 160The cache-get Command 161~~~~~~~~~~~~~~~~~~~~~ 162 163This command is similar to cache-write, but instead of writing the cache 164contents to disk, it returns the contents to whoever sent the command. 165 166This command allows the contents of a file on disk to be loaded into an 167in-memory cache. It takes one parameter, which defines the filename. An 168example usage looks as follows: 169 170:: 171 172 { 173 "command": "cache-get" 174 } 175 176This command will return all the cached hosts. Note that the response 177may be large. 178 179.. _command-cache-get-by-id: 180 181The cache-get-by-id Command 182~~~~~~~~~~~~~~~~~~~~~~~~~~~ 183 184This command is similar to cache-get, but instead of returning the whole 185content it returns only the entries matching the given identifier. 186 187It takes one parameter, which defines the identifier of wanted cached 188host reservations. An example usage looks as follows: 189 190:: 191 192 { 193 "command": "cache-get-by-id", 194 "arguments": { 195 "hw-address": "01:02:03:04:05:06" 196 } 197 } 198 199This command will return all the cached hosts with the given hardware 200address. 201 202.. _command-cache-insert: 203 204The cache-insert Command 205~~~~~~~~~~~~~~~~~~~~~~~~ 206 207This command may be used to manually insert a host into the cache; there 208are very few use cases when this command might be useful. This command 209expects its arguments to follow the usual syntax for specifying host 210reservations (see :ref:`host-reservation-v4` or 211:ref:`host-reservation-v6`), with one difference: the subnet-id 212value must be specified explicitly. 213 214An example command that will insert an IPv4 host into the host cache 215looks as follows: 216 217:: 218 219 { 220 "command": "cache-insert", 221 "arguments": { 222 "hw-address": "01:02:03:04:05:06", 223 "subnet-id4": 4, 224 "subnet-id6": 0, 225 "ip-address": "192.0.2.100", 226 "hostname": "somehost.example.org", 227 "client-classes4": [ ], 228 "client-classes6": [ ], 229 "option-data4": [ ], 230 "option-data6": [ ], 231 "next-server": "192.0.0.2", 232 "server-hostname": "server-hostname.example.org", 233 "boot-file-name": "bootfile.efi", 234 "host-id": 0 235 } 236 } 237 238An example command that will insert an IPv6 host into the host cache 239looks as follows: 240 241:: 242 243 { 244 "command": "cache-insert", 245 "arguments": { 246 "hw-address": "01:02:03:04:05:06", 247 "subnet-id4": 0, 248 "subnet-id6": 6, 249 "ip-addresses": [ "2001:db8::cafe:babe" ], 250 "prefixes": [ "2001:db8:dead:beef::/64" ], 251 "hostname": "", 252 "client-classes4": [ ], 253 "client-classes6": [ ], 254 "option-data4": [ ], 255 "option-data6": [ ], 256 "next-server": "0.0.0.0", 257 "server-hostname": "", 258 "boot-file-name": "", 259 "host-id": 0 260 } 261 } 262 263.. _command-cache-remove: 264 265The cache-remove Command 266~~~~~~~~~~~~~~~~~~~~~~~~ 267 268Sometimes it is useful to remove a single entry from the host cache. A 269good use case is a situation where the device is up, Kea has already 270provided configuration, and the host entry is in cache. As a result of 271administrative action (e.g. the customer hasn't paid their bills or has 272perhaps been upgraded to better service), the information in the backend 273(e.g. MySQL or RADIUS) is being updated. However, since the cache is in use, 274Kea does not notice the change as the cached values are used. The 275cache-remove command can solve this problem by removing a cached entry 276after administrative changes. 277 278The cache-remove command works similarly to the reservation-get command. 279It allows querying by two parameters: either subnet-id4 or subnet-id6; 280or ip-address (may be an IPv4 or IPv6 address), hw-address (specifies 281hardware/MAC address), duid, circuit-id, client-id, or flex-id. 282 283An example command to remove an IPv4 host with reserved address 284192.0.2.1 from a subnet with a subnet-id 123 looks as follows: 285 286:: 287 288 { 289 "command": "cache-remove", 290 "arguments": { 291 "ip-address": "192.0.2.1", 292 "subnet-id": 123 293 } 294 } 295 296Another example that removes an IPv6 host identifier by DUID and 297specific subnet-id is: 298 299:: 300 301 { 302 "command": "cache-remove", 303 "arguments": { 304 "duid": "00:01:ab:cd:f0:a1:c2:d3:e4", 305 "subnet-id": 123 306 } 307 } 308