dlz.h revision 170223
1/* 2 * Portions Copyright (C) 2005 Internet Systems Consortium, Inc. ("ISC") 3 * Portions Copyright (C) 1999-2001 Internet Software Consortium. 4 * 5 * Permission to use, copy, modify, and distribute this software for any 6 * purpose with or without fee is hereby granted, provided that the above 7 * copyright notice and this permission notice appear in all copies. 8 * 9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15 * PERFORMANCE OF THIS SOFTWARE. 16 */ 17 18/* 19 * Copyright (C) 2002 Stichting NLnet, Netherlands, stichting@nlnet.nl. 20 * 21 * Permission to use, copy, modify, and distribute this software for any 22 * purpose with or without fee is hereby granted, provided that the 23 * above copyright notice and this permission notice appear in all 24 * copies. 25 * 26 * THE SOFTWARE IS PROVIDED "AS IS" AND STICHTING NLNET 27 * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL 28 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL 29 * STICHTING NLNET BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR 30 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS 31 * OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 32 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE 33 * USE OR PERFORMANCE OF THIS SOFTWARE. 34 * 35 * The development of Dynamically Loadable Zones (DLZ) for Bind 9 was 36 * conceived and contributed by Rob Butler. 37 * 38 * Permission to use, copy, modify, and distribute this software for any 39 * purpose with or without fee is hereby granted, provided that the 40 * above copyright notice and this permission notice appear in all 41 * copies. 42 * 43 * THE SOFTWARE IS PROVIDED "AS IS" AND ROB BUTLER 44 * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL 45 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL 46 * ROB BUTLER BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR 47 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS 48 * OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 49 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE 50 * USE OR PERFORMANCE OF THIS SOFTWARE. 51 */ 52 53/* $Id: dlz.h,v 1.2.2.2 2005/09/06 03:47:18 marka Exp $ */ 54 55/*! \file */ 56 57#ifndef DLZ_H 58#define DLZ_H 1 59 60/***** 61 ***** Module Info 62 *****/ 63 64/* 65 * DLZ Interface 66 * 67 * The DLZ interface allows zones to be looked up using a driver instead of 68 * Bind's default in memory zone table. 69 * 70 * 71 * Reliability: 72 * No anticipated impact. 73 * 74 * Resources: 75 * 76 * Security: 77 * No anticipated impact. 78 * 79 * Standards: 80 * None. 81 */ 82 83/***** 84 ***** Imports 85 *****/ 86 87#include <dns/name.h> 88#include <dns/types.h> 89#include <dns/view.h> 90 91#include <isc/lang.h> 92 93ISC_LANG_BEGINDECLS 94 95/*** 96 *** Types 97 ***/ 98 99#define DNS_DLZ_MAGIC ISC_MAGIC('D','L','Z','D') 100#define DNS_DLZ_VALID(dlz) ISC_MAGIC_VALID(dlz, DNS_DLZ_MAGIC) 101 102typedef isc_result_t 103(*dns_dlzallowzonexfr_t)(void *driverarg, void *dbdata, isc_mem_t *mctx, 104 dns_rdataclass_t rdclass, dns_name_t *name, 105 isc_sockaddr_t *clientaddr, 106 dns_db_t **dbp); 107 108/*%< 109 * Method prototype. Drivers implementing the DLZ interface MUST 110 * supply an allow zone transfer method. This method is called when 111 * the DNS server is performing a zone transfer query. The driver's 112 * method should return ISC_R_SUCCESS and a database pointer to the 113 * name server if the zone is supported by the database, and zone 114 * transfer is allowed. Otherwise it will return ISC_R_NOTFOUND if 115 * the zone is not supported by the database, or ISC_R_NOPERM if zone 116 * transfers are not allowed. If an error occurs it should return a 117 * result code indicating the type of error. 118 */ 119 120typedef isc_result_t 121(*dns_dlzcreate_t)(isc_mem_t *mctx, const char *dlzname, unsigned int argc, 122 char *argv[], void *driverarg, void **dbdata); 123 124/*%< 125 * Method prototype. Drivers implementing the DLZ interface MUST 126 * supply a create method. This method is called when the DNS server 127 * is starting up and creating drivers for use later. 128 */ 129 130typedef void 131(*dns_dlzdestroy_t)(void *driverarg, void **dbdata); 132 133/*%< 134 * Method prototype. Drivers implementing the DLZ interface MUST 135 * supply a destroy method. This method is called when the DNS server 136 * is shuting down and no longer needs the driver. 137 */ 138 139typedef isc_result_t 140(*dns_dlzfindzone_t)(void *driverarg, void *dbdata, isc_mem_t *mctx, 141 dns_rdataclass_t rdclass, dns_name_t *name, 142 dns_db_t **dbp); 143 144/*%< 145 146 * Method prototype. Drivers implementing the DLZ interface MUST 147 * supply a find zone method. This method is called when the DNS 148 * server is performing a query. The find zone method will be called 149 * with the longest possible name first, and continue to be called 150 * with successively shorter domain names, until any of the following 151 * occur: 152 * 153 * \li 1) a match is found, and the function returns (ISC_R_SUCCESS) 154 * 155 * \li 2) a problem occurs, and the functions returns anything other 156 * than (ISC_R_NOTFOUND) 157 * \li 3) we run out of domain name labels. I.E. we have tried the 158 * shortest domain name 159 * \li 4) the number of labels in the domain name is less than 160 * min_lables for dns_dlzfindzone 161 * 162 * The driver's find zone method should return ISC_R_SUCCESS and a 163 * database pointer to the name server if the zone is supported by the 164 * database. Otherwise it will return ISC_R_NOTFOUND, and a null 165 * pointer if the zone is not supported. If an error occurs it should 166 * return a result code indicating the type of error. 167 */ 168 169/*% the methods supplied by a DLZ driver */ 170typedef struct dns_dlzmethods { 171 dns_dlzcreate_t create; 172 dns_dlzdestroy_t destroy; 173 dns_dlzfindzone_t findzone; 174 dns_dlzallowzonexfr_t allowzonexfr; 175} dns_dlzmethods_t; 176 177/*% information about a DLZ driver */ 178struct dns_dlzimplementation { 179 const char *name; 180 const dns_dlzmethods_t *methods; 181 isc_mem_t *mctx; 182 void *driverarg; 183 ISC_LINK(dns_dlzimplementation_t) link; 184}; 185 186/*% an instance of a DLZ driver */ 187struct dns_dlzdb { 188 unsigned int magic; 189 isc_mem_t *mctx; 190 dns_dlzimplementation_t *implementation; 191 void *dbdata; 192}; 193 194 195/*** 196 *** Method declarations 197 ***/ 198 199isc_result_t 200dns_dlzallowzonexfr(dns_view_t *view, dns_name_t *name, 201 isc_sockaddr_t *clientaddr, dns_db_t **dbp); 202 203/*%< 204 * This method is called when the DNS server is performing a zone 205 * transfer query. It will call the DLZ driver's allow zone tranfer 206 * method. 207 */ 208 209isc_result_t 210dns_dlzcreate(isc_mem_t *mctx, const char *dlzname, 211 const char *drivername, unsigned int argc, 212 char *argv[], dns_dlzdb_t **dbp); 213 214/*%< 215 * This method is called when the DNS server is starting up and 216 * creating drivers for use later. It will search the DLZ driver list 217 * for 'drivername' and return a DLZ driver via dbp if a match is 218 * found. If the DLZ driver supplies a create method, this function 219 * will call it. 220 */ 221 222void 223dns_dlzdestroy(dns_dlzdb_t **dbp); 224 225/*%< 226 * This method is called when the DNS server is shuting down and no 227 * longer needs the driver. If the DLZ driver supplies a destroy 228 * methods, this function will call it. 229 */ 230 231isc_result_t 232dns_dlzfindzone(dns_view_t *view, dns_name_t *name, 233 unsigned int minlabels, dns_db_t **dbp); 234 235/*%< 236 * This method is called when the DNS server is performing a query. 237 * It will call the DLZ driver's find zone method. 238 */ 239 240isc_result_t 241dns_dlzregister(const char *drivername, const dns_dlzmethods_t *methods, 242 void *driverarg, isc_mem_t *mctx, 243 dns_dlzimplementation_t **dlzimp); 244 245/*%< 246 * Register a dynamically loadable zones (DLZ) driver for the database 247 * type 'drivername', implemented by the functions in '*methods'. 248 * 249 * dlzimp must point to a NULL dlz_implementation_t pointer. That is, 250 * dlzimp != NULL && *dlzimp == NULL. It will be assigned a value that 251 * will later be used to identify the driver when deregistering it. 252 */ 253 254isc_result_t 255dns_dlzstrtoargv(isc_mem_t *mctx, char *s, unsigned int *argcp, char ***argvp); 256 257/*%< 258 * This method is called when the name server is starting up to parse 259 * the DLZ driver command line from named.conf. Basically it splits 260 * up a string into and argc / argv. The primary difference of this 261 * method is items between braces { } are considered only 1 word. for 262 * example the command line "this is { one grouped phrase } and this 263 * isn't" would be parsed into: 264 * 265 * \li argv[0]: "this" 266 * \li argv[1]: "is" 267 * \li argv{2]: " one grouped phrase " 268 * \li argv[3]: "and" 269 * \li argv[4]: "this" 270 * \li argv{5}: "isn't" 271 * 272 * braces should NOT be nested, more than one grouping in the command 273 * line is allowed. Notice, argv[2] has an extra space at the 274 * beginning and end. Extra spaces are not stripped between a 275 * grouping. You can do so in your driver if needed, or be sure not 276 * to put extra spaces before / after the braces. 277 */ 278 279void 280dns_dlzunregister(dns_dlzimplementation_t **dlzimp); 281 282/*%< 283 * Removes the dlz driver from the list of registered dlz drivers. 284 * There must be no active dlz drivers of this type when this function 285 * is called. 286 */ 287 288ISC_LANG_ENDDECLS 289 290#endif /* DLZ_H */ 291