1 /*************************************************
2 * Exim - an Internet mail transport agent *
3 *************************************************/
5 /* Copyright (c) University of Cambridge 1995 - 2018 */
6 /* See the file NOTICE for conditions of use and distribution. */
12 /* Functions for accessing Exim's hints database, which consists of a number of
13 different DBM files. This module does not contain code for reading DBM files
14 for (e.g.) alias expansion. That is all contained within the general search
15 functions. As Exim now has support for several DBM interfaces, all the relevant
16 functions are called as macros.
18 All the data in Exim's database is in the nature of *hints*. Therefore it
19 doesn't matter if it gets destroyed by accident. These functions are not
20 supposed to implement a "safe" database.
22 Keys are passed in as C strings, and the terminating zero *is* used when
23 building the dbm files. This just makes life easier when scanning the files
26 Synchronization is required on the database files, and this is achieved by
27 means of locking on independent lock files. (Earlier attempts to lock on the
28 DBM files themselves were never completely successful.) Since callers may in
29 general want to do more than one read or write while holding the lock, there
30 are separate open and close functions. However, the calling modules should
31 arrange to hold the locks for the bare minimum of time. */
35 /*************************************************
36 * Berkeley DB error callback *
37 *************************************************/
39 /* For Berkeley DB >= 2, we can define a function to be called in case of DB
40 errors. This should help with debugging strange DB problems, e.g. getting "File
41 exists" when you try to open a db file. The API for this function was changed
44 #if defined(USE_DB) && defined(DB_VERSION_STRING)
46 #if DB_VERSION_MAJOR > 4 || (DB_VERSION_MAJOR == 4 && DB_VERSION_MINOR >= 3)
47 dbfn_bdb_error_callback(const DB_ENV *dbenv, const char *pfx, const char *msg)
51 dbfn_bdb_error_callback(const char *pfx, char *msg)
55 log_write(0, LOG_MAIN, "Berkeley DB error: %s", msg);
62 /*************************************************
63 * Open and lock a database file *
64 *************************************************/
66 /* Used for accessing Exim's hints databases.
69 name The single-component name of one of Exim's database files.
70 flags Either O_RDONLY or O_RDWR, indicating the type of open required;
71 O_RDWR implies "create if necessary"
72 dbblock Points to an open_db block to be filled in.
73 lof If TRUE, write to the log for actual open failures (locking failures
76 Returns: NULL if the open failed, or the locking failed. After locking
77 failures, errno is zero.
79 On success, dbblock is returned. This contains the dbm pointer and
80 the fd of the locked lock file.
82 There are some calls that use O_RDWR|O_CREAT for the flags. Having discovered
83 this in December 2005, I'm not sure if this is correct or not, but for the
84 moment I haven't changed them.
88 dbfn_open(uschar *name, int flags, open_db *dbblock, BOOL lof)
91 BOOL read_only = flags == O_RDONLY;
94 uschar dirname[256], filename[256];
96 DEBUG(D_hints_lookup) acl_level++;
98 /* The first thing to do is to open a separate file on which to lock. This
99 ensures that Exim has exclusive use of the database before it even tries to
100 open it. Early versions tried to lock on the open database itself, but that
101 gave rise to mysterious problems from time to time - it was suspected that some
102 DB libraries "do things" on their open() calls which break the interlocking.
103 The lock file is never written to, but we open it for writing so we can get a
104 write lock if required. If it does not exist, we create it. This is done
105 separately so we know when we have done it, because when running as root we
106 need to change the ownership - see the bottom of this function. We also try to
107 make the directory as well, just in case. We won't be doing this many times
108 unnecessarily, because usually the lock file will be there. If the directory
109 exists, there is no error. */
111 snprintf(CS dirname, sizeof(dirname), "%s/db", spool_directory);
112 snprintf(CS filename, sizeof(filename), "%s/%s.lockfile", dirname, name);
114 if ((dbblock->lockfd = Uopen(filename, O_RDWR, EXIMDB_LOCKFILE_MODE)) < 0)
117 (void)directory_make(spool_directory, US"db", EXIMDB_DIRECTORY_MODE, TRUE);
118 dbblock->lockfd = Uopen(filename, O_RDWR|O_CREAT, EXIMDB_LOCKFILE_MODE);
121 if (dbblock->lockfd < 0)
123 log_write(0, LOG_MAIN, "%s",
124 string_open_failed(errno, "database lock file %s", filename));
125 errno = 0; /* Indicates locking failure */
126 DEBUG(D_hints_lookup) acl_level--;
130 /* Now we must get a lock on the opened lock file; do this with a blocking
131 lock that times out. */
133 lock_data.l_type = read_only? F_RDLCK : F_WRLCK;
134 lock_data.l_whence = lock_data.l_start = lock_data.l_len = 0;
136 DEBUG(D_hints_lookup|D_retry|D_route|D_deliver)
137 debug_printf_indent("locking %s\n", filename);
139 sigalrm_seen = FALSE;
140 alarm(EXIMDB_LOCK_TIMEOUT);
141 rc = fcntl(dbblock->lockfd, F_SETLKW, &lock_data);
144 if (sigalrm_seen) errno = ETIMEDOUT;
147 log_write(0, LOG_MAIN|LOG_PANIC, "Failed to get %s lock for %s: %s",
148 read_only ? "read" : "write", filename,
149 errno == ETIMEDOUT ? "timed out" : strerror(errno));
150 (void)close(dbblock->lockfd);
151 errno = 0; /* Indicates locking failure */
152 DEBUG(D_hints_lookup) acl_level--;
156 DEBUG(D_hints_lookup) debug_printf_indent("locked %s\n", filename);
158 /* At this point we have an opened and locked separate lock file, that is,
159 exclusive access to the database, so we can go ahead and open it. If we are
160 expected to create it, don't do so at first, again so that we can detect
161 whether we need to change its ownership (see comments about the lock file
162 above.) There have been regular reports of crashes while opening hints
163 databases - often this is caused by non-matching db.h and the library. To make
164 it easy to pin this down, there are now debug statements on either side of the
167 snprintf(CS filename, sizeof(filename), "%s/%s", dirname, name);
168 EXIM_DBOPEN(filename, dirname, flags, EXIMDB_MODE, &(dbblock->dbptr));
170 if (!dbblock->dbptr && errno == ENOENT && flags == O_RDWR)
172 DEBUG(D_hints_lookup)
173 debug_printf_indent("%s appears not to exist: trying to create\n", filename);
175 EXIM_DBOPEN(filename, dirname, flags|O_CREAT, EXIMDB_MODE, &(dbblock->dbptr));
180 /* If we are running as root and this is the first access to the database, its
181 files will be owned by root. We want them to be owned by exim. We detect this
182 situation by noting above when we had to create the lock file or the database
183 itself. Because the different dbm libraries use different extensions for their
184 files, I don't know of any easier way of arranging this than scanning the
185 directory for files with the appropriate base name. At least this deals with
186 the lock file at the same time. Also, the directory will typically have only
187 half a dozen files, so the scan will be quick.
189 This code is placed here, before the test for successful opening, because there
190 was a case when a file was created, but the DBM library still returned NULL
191 because of some problem. It also sorts out the lock file if that was created
192 but creation of the database file failed. */
194 if (created && geteuid() == root_uid)
198 uschar *lastname = Ustrrchr(filename, '/') + 1;
199 int namelen = Ustrlen(name);
202 dd = opendir(CS filename);
204 while ((ent = readdir(dd)))
205 if (Ustrncmp(ent->d_name, name, namelen) == 0)
208 Ustrcpy(lastname, ent->d_name);
209 if (Ustat(filename, &statbuf) >= 0 && statbuf.st_uid != exim_uid)
211 DEBUG(D_hints_lookup) debug_printf_indent("ensuring %s is owned by exim\n", filename);
212 if (Uchown(filename, exim_uid, exim_gid))
213 DEBUG(D_hints_lookup) debug_printf_indent("failed setting %s to owned by exim\n", filename);
220 /* If the open has failed, return NULL, leaving errno set. If lof is TRUE,
221 log the event - also for debugging - but debug only if the file just doesn't
226 if (lof && save_errno != ENOENT)
227 log_write(0, LOG_MAIN, "%s", string_open_failed(save_errno, "DB file %s",
230 DEBUG(D_hints_lookup)
231 debug_printf_indent("%s\n", CS string_open_failed(save_errno, "DB file %s",
233 (void)close(dbblock->lockfd);
235 DEBUG(D_hints_lookup) acl_level--;
239 DEBUG(D_hints_lookup)
240 debug_printf_indent("opened hints database %s: flags=%s\n", filename,
241 flags == O_RDONLY ? "O_RDONLY"
242 : flags == O_RDWR ? "O_RDWR"
243 : flags == (O_RDWR|O_CREAT) ? "O_RDWR|O_CREAT"
246 /* Pass back the block containing the opened database handle and the open fd
255 /*************************************************
256 * Unlock and close a database file *
257 *************************************************/
259 /* Closing a file automatically unlocks it, so after closing the database, just
262 Argument: a pointer to an open database block
267 dbfn_close(open_db *dbblock)
269 EXIM_DBCLOSE(dbblock->dbptr);
270 (void)close(dbblock->lockfd);
271 DEBUG(D_hints_lookup)
272 { debug_printf_indent("closed hints database and lockfile\n"); acl_level--; }
278 /*************************************************
279 * Read from database file *
280 *************************************************/
282 /* Passing back the pointer unchanged is useless, because there is
283 no guarantee of alignment. Since all the records used by Exim need
284 to be properly aligned to pick out the timestamps, etc., we might as
285 well do the copying centrally here.
287 Most calls don't need the length, so there is a macro called dbfn_read which
288 has two arguments; it calls this function adding NULL as the third.
291 dbblock a pointer to an open database block
292 key the key of the record to be read
293 length a pointer to an int into which to return the length, if not NULL
295 Returns: a pointer to the retrieved record, or
296 NULL if the record is not found
300 dbfn_read_with_length(open_db *dbblock, const uschar *key, int *length)
303 EXIM_DATUM key_datum, result_datum;
304 int klen = Ustrlen(key) + 1;
305 uschar * key_copy = store_get(klen);
307 memcpy(key_copy, key, klen);
309 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_read: key=%s\n", key);
311 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
312 EXIM_DATUM_INIT(result_datum); /* to be cleared before use. */
313 EXIM_DATUM_DATA(key_datum) = CS key_copy;
314 EXIM_DATUM_SIZE(key_datum) = klen;
316 if (!EXIM_DBGET(dbblock->dbptr, key_datum, result_datum)) return NULL;
318 yield = store_get(EXIM_DATUM_SIZE(result_datum));
319 memcpy(yield, EXIM_DATUM_DATA(result_datum), EXIM_DATUM_SIZE(result_datum));
320 if (length != NULL) *length = EXIM_DATUM_SIZE(result_datum);
322 EXIM_DATUM_FREE(result_datum); /* Some DBM libs require freeing */
328 /*************************************************
329 * Write to database file *
330 *************************************************/
334 dbblock a pointer to an open database block
335 key the key of the record to be written
336 ptr a pointer to the record to be written
337 length the length of the record to be written
339 Returns: the yield of the underlying dbm or db "write" function. If this
340 is dbm, the value is zero for OK.
344 dbfn_write(open_db *dbblock, const uschar *key, void *ptr, int length)
346 EXIM_DATUM key_datum, value_datum;
347 dbdata_generic *gptr = (dbdata_generic *)ptr;
348 int klen = Ustrlen(key) + 1;
349 uschar * key_copy = store_get(klen);
351 memcpy(key_copy, key, klen);
352 gptr->time_stamp = time(NULL);
354 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_write: key=%s\n", key);
356 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
357 EXIM_DATUM_INIT(value_datum); /* to be cleared before use. */
358 EXIM_DATUM_DATA(key_datum) = CS key_copy;
359 EXIM_DATUM_SIZE(key_datum) = klen;
360 EXIM_DATUM_DATA(value_datum) = CS ptr;
361 EXIM_DATUM_SIZE(value_datum) = length;
362 return EXIM_DBPUT(dbblock->dbptr, key_datum, value_datum);
367 /*************************************************
368 * Delete record from database file *
369 *************************************************/
373 dbblock a pointer to an open database block
374 key the key of the record to be deleted
376 Returns: the yield of the underlying dbm or db "delete" function.
380 dbfn_delete(open_db *dbblock, const uschar *key)
382 int klen = Ustrlen(key) + 1;
383 uschar * key_copy = store_get(klen);
385 memcpy(key_copy, key, klen);
386 EXIM_DATUM key_datum;
387 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require clearing */
388 EXIM_DATUM_DATA(key_datum) = CS key_copy;
389 EXIM_DATUM_SIZE(key_datum) = klen;
390 return EXIM_DBDEL(dbblock->dbptr, key_datum);
395 /*************************************************
396 * Scan the keys of a database file *
397 *************************************************/
401 dbblock a pointer to an open database block
402 start TRUE if starting a new scan
403 FALSE if continuing with the current scan
404 cursor a pointer to a pointer to a cursor anchor, for those dbm libraries
405 that use the notion of a cursor
407 Returns: the next record from the file, or
408 NULL if there are no more
412 dbfn_scan(open_db *dbblock, BOOL start, EXIM_CURSOR **cursor)
414 EXIM_DATUM key_datum, value_datum;
416 value_datum = value_datum; /* dummy; not all db libraries use this */
418 /* Some dbm require an initialization */
420 if (start) EXIM_DBCREATE_CURSOR(dbblock->dbptr, cursor);
422 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
423 EXIM_DATUM_INIT(value_datum); /* to be cleared before use. */
425 yield = (EXIM_DBSCAN(dbblock->dbptr, key_datum, value_datum, start, *cursor))?
426 US EXIM_DATUM_DATA(key_datum) : NULL;
428 /* Some dbm require a termination */
430 if (!yield) EXIM_DBDELETE_CURSOR(*cursor);
436 /*************************************************
437 **************************************************
438 * Stand-alone test program *
439 **************************************************
440 *************************************************/
445 main(int argc, char **cargv)
448 int max_db = sizeof(dbblock)/sizeof(open_db);
452 dbdata_wait *dbwait = NULL;
453 uschar **argv = USS cargv;
455 uschar structbuffer[1024];
459 printf("Usage: test_dbfn directory\n");
460 printf("The subdirectory called \"db\" in the given directory is used for\n");
461 printf("the files used in this test program.\n");
467 spool_directory = argv[1];
468 debug_selector = D_all - D_memory;
470 big_buffer = malloc(big_buffer_size);
472 for (i = 0; i < max_db; i++) dbblock[i].dbptr = NULL;
474 printf("\nExim's db functions tester: interface type is %s\n", EXIM_DBTYPE);
475 printf("DBM library: ");
477 #ifdef DB_VERSION_STRING
478 printf("Berkeley DB: %s\n", DB_VERSION_STRING);
479 #elif defined(BTREEVERSION) && defined(HASHVERSION)
481 printf("probably Berkeley DB version 1.8x (native mode)\n");
483 printf("probably Berkeley DB version 1.8x (compatibility mode)\n");
485 #elif defined(_DBM_RDONLY) || defined(dbm_dirfno)
486 printf("probably ndbm\n");
487 #elif defined(USE_TDB)
488 printf("using tdb\n");
491 printf("probably GDBM (native mode)\n");
493 printf("probably GDBM (compatibility mode)\n");
497 /* Test the functions */
499 printf("\nTest the functions\n> ");
501 while (Ufgets(buffer, 256, stdin) != NULL)
503 int len = Ustrlen(buffer);
507 uschar *cmd = buffer;
508 while (len > 0 && isspace((uschar)buffer[len-1])) len--;
511 if (isdigit((uschar)*cmd))
514 while (isdigit((uschar)*cmd)) cmd++;
515 while (isspace((uschar)*cmd)) cmd++;
518 if (Ustrncmp(cmd, "open", 4) == 0)
523 while (isspace((uschar)*s)) s++;
525 for (i = 0; i < max_db; i++)
526 if (dbblock[i].dbptr == NULL) break;
530 printf("Too many open databases\n> ");
535 odb = dbfn_open(s, O_RDWR, dbblock + i, TRUE);
541 printf("opened %d\n", current);
543 /* Other error cases will have written messages */
544 else if (errno == ENOENT)
546 printf("open failed: %s%s\n", strerror(errno),
548 " (or other Berkeley DB error)"
556 else if (Ustrncmp(cmd, "write", 5) == 0)
559 uschar *key = cmd + 5;
564 printf("No current database\n");
568 while (isspace((uschar)*key)) key++;
570 while (*data != 0 && !isspace((uschar)*data)) data++;
572 while (isspace((uschar)*data)) data++;
574 dbwait = (dbdata_wait *)(&structbuffer);
575 Ustrcpy(dbwait->text, data);
579 rc = dbfn_write(dbblock + current, key, dbwait,
580 Ustrlen(data) + sizeof(dbdata_wait));
582 if (rc != 0) printf("Failed: %s\n", strerror(errno));
585 else if (Ustrncmp(cmd, "read", 4) == 0)
587 uschar *key = cmd + 4;
590 printf("No current database\n");
593 while (isspace((uschar)*key)) key++;
596 dbwait = (dbdata_wait *)dbfn_read_with_length(dbblock+ current, key, NULL);
598 printf("%s\n", (dbwait == NULL)? "<not found>" : CS dbwait->text);
601 else if (Ustrncmp(cmd, "delete", 6) == 0)
603 uschar *key = cmd + 6;
606 printf("No current database\n");
609 while (isspace((uschar)*key)) key++;
610 dbfn_delete(dbblock + current, key);
613 else if (Ustrncmp(cmd, "scan", 4) == 0)
616 BOOL startflag = TRUE;
618 uschar keybuffer[256];
621 printf("No current database\n");
625 while ((key = dbfn_scan(dbblock + current, startflag, &cursor)) != NULL)
628 Ustrcpy(keybuffer, key);
629 dbwait = (dbdata_wait *)dbfn_read_with_length(dbblock + current,
631 printf("%s: %s\n", keybuffer, dbwait->text);
634 printf("End of scan\n");
637 else if (Ustrncmp(cmd, "close", 5) == 0)
640 while (isspace((uschar)*s)) s++;
642 if (i >= max_db || dbblock[i].dbptr == NULL) printf("Not open\n"); else
645 dbfn_close(dbblock + i);
647 dbblock[i].dbptr = NULL;
648 if (i == current) current = -1;
652 else if (Ustrncmp(cmd, "file", 4) == 0)
655 while (isspace((uschar)*s)) s++;
657 if (i >= max_db || dbblock[i].dbptr == NULL) printf("Not open\n");
661 else if (Ustrncmp(cmd, "time", 4) == 0)
663 showtime = ~showtime;
664 printf("Timing %s\n", showtime? "on" : "off");
667 else if (Ustrcmp(cmd, "q") == 0 || Ustrncmp(cmd, "quit", 4) == 0) break;
669 else if (Ustrncmp(cmd, "help", 4) == 0)
671 printf("close [<number>] close file [<number>]\n");
672 printf("delete <key> remove record from current file\n");
673 printf("file <number> make file <number> current\n");
674 printf("open <name> open db file\n");
675 printf("q[uit] exit program\n");
676 printf("read <key> read record from current file\n");
677 printf("scan scan current file\n");
678 printf("time time display on/off\n");
679 printf("write <key> <rest-of-line> write record to current file\n");
682 else printf("Eh?\n");
684 if (showtime && stop >= start)
685 printf("start=%d stop=%d difference=%d\n", (int)start, (int)stop,
686 (int)(stop - start));
691 for (i = 0; i < max_db; i++)
693 if (dbblock[i].dbptr != NULL)
695 printf("\nClosing %d", i);
696 dbfn_close(dbblock + i);