1 /*************************************************
2 * Exim - an Internet mail transport agent *
3 *************************************************/
5 /* Copyright (c) University of Cambridge 1995 - 2018 */
6 /* Copyright (c) The Exim Maintainers 2020 */
7 /* See the file NOTICE for conditions of use and distribution. */
13 /* Functions for accessing Exim's hints database, which consists of a number of
14 different DBM files. This module does not contain code for reading DBM files
15 for (e.g.) alias expansion. That is all contained within the general search
16 functions. As Exim now has support for several DBM interfaces, all the relevant
17 functions are called as macros.
19 All the data in Exim's database is in the nature of *hints*. Therefore it
20 doesn't matter if it gets destroyed by accident. These functions are not
21 supposed to implement a "safe" database.
23 Keys are passed in as C strings, and the terminating zero *is* used when
24 building the dbm files. This just makes life easier when scanning the files
27 Synchronization is required on the database files, and this is achieved by
28 means of locking on independent lock files. (Earlier attempts to lock on the
29 DBM files themselves were never completely successful.) Since callers may in
30 general want to do more than one read or write while holding the lock, there
31 are separate open and close functions. However, the calling modules should
32 arrange to hold the locks for the bare minimum of time. */
36 /*************************************************
37 * Berkeley DB error callback *
38 *************************************************/
40 /* For Berkeley DB >= 2, we can define a function to be called in case of DB
41 errors. This should help with debugging strange DB problems, e.g. getting "File
42 exists" when you try to open a db file. The API for this function was changed
45 #if defined(USE_DB) && defined(DB_VERSION_STRING)
47 #if DB_VERSION_MAJOR > 4 || (DB_VERSION_MAJOR == 4 && DB_VERSION_MINOR >= 3)
48 dbfn_bdb_error_callback(const DB_ENV *dbenv, const char *pfx, const char *msg)
52 dbfn_bdb_error_callback(const char *pfx, char *msg)
56 log_write(0, LOG_MAIN, "Berkeley DB error: %s", msg);
61 /*************************************************
62 * Open and lock a database file *
63 *************************************************/
65 /* Used for accessing Exim's hints databases.
68 name The single-component name of one of Exim's database files.
69 flags Either O_RDONLY or O_RDWR, indicating the type of open required;
70 O_RDWR implies "create if necessary"
71 dbblock Points to an open_db block to be filled in.
72 lof If TRUE, write to the log for actual open failures (locking failures
74 panic If TRUE, panic on failure to create the db directory
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, BOOL panic)
91 BOOL read_only = flags == O_RDONLY;
93 uschar dirname[256], filename[256];
95 DEBUG(D_hints_lookup) acl_level++;
97 /* The first thing to do is to open a separate file on which to lock. This
98 ensures that Exim has exclusive use of the database before it even tries to
99 open it. Early versions tried to lock on the open database itself, but that
100 gave rise to mysterious problems from time to time - it was suspected that some
101 DB libraries "do things" on their open() calls which break the interlocking.
102 The lock file is never written to, but we open it for writing so we can get a
103 write lock if required. If it does not exist, we create it. This is done
104 separately so we know when we have done it, because when running as root we
105 need to change the ownership - see the bottom of this function. We also try to
106 make the directory as well, just in case. We won't be doing this many times
107 unnecessarily, because usually the lock file will be there. If the directory
108 exists, there is no error. */
110 snprintf(CS dirname, sizeof(dirname), "%s/db", spool_directory);
111 snprintf(CS filename, sizeof(filename), "%s/%s.lockfile", dirname, name);
113 priv_drop_temp(exim_uid, exim_gid);
114 if ((dbblock->lockfd = Uopen(filename, O_RDWR, EXIMDB_LOCKFILE_MODE)) < 0)
116 (void)directory_make(spool_directory, US"db", EXIMDB_DIRECTORY_MODE, panic);
117 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);
169 priv_drop_temp(exim_uid, exim_gid);
170 EXIM_DBOPEN(filename, dirname, flags, EXIMDB_MODE, &(dbblock->dbptr));
171 if (!dbblock->dbptr && errno == ENOENT && flags == O_RDWR)
173 DEBUG(D_hints_lookup)
174 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 the open has failed, return NULL, leaving errno set. If lof is TRUE,
181 log the event - also for debugging - but debug only if the file just doesn't
186 if (lof && save_errno != ENOENT)
187 log_write(0, LOG_MAIN, "%s", string_open_failed(save_errno, "DB file %s",
190 DEBUG(D_hints_lookup)
191 debug_printf_indent("%s\n", CS string_open_failed(save_errno, "DB file %s",
193 (void)close(dbblock->lockfd);
195 DEBUG(D_hints_lookup) acl_level--;
199 DEBUG(D_hints_lookup)
200 debug_printf_indent("opened hints database %s: flags=%s\n", filename,
201 flags == O_RDONLY ? "O_RDONLY"
202 : flags == O_RDWR ? "O_RDWR"
203 : flags == (O_RDWR|O_CREAT) ? "O_RDWR|O_CREAT"
206 /* Pass back the block containing the opened database handle and the open fd
215 /*************************************************
216 * Unlock and close a database file *
217 *************************************************/
219 /* Closing a file automatically unlocks it, so after closing the database, just
222 Argument: a pointer to an open database block
227 dbfn_close(open_db *dbblock)
229 EXIM_DBCLOSE(dbblock->dbptr);
230 (void)close(dbblock->lockfd);
231 DEBUG(D_hints_lookup)
232 { debug_printf_indent("closed hints database and lockfile\n"); acl_level--; }
238 /*************************************************
239 * Read from database file *
240 *************************************************/
242 /* Passing back the pointer unchanged is useless, because there is
243 no guarantee of alignment. Since all the records used by Exim need
244 to be properly aligned to pick out the timestamps, etc., we might as
245 well do the copying centrally here.
247 Most calls don't need the length, so there is a macro called dbfn_read which
248 has two arguments; it calls this function adding NULL as the third.
251 dbblock a pointer to an open database block
252 key the key of the record to be read
253 length a pointer to an int into which to return the length, if not NULL
255 Returns: a pointer to the retrieved record, or
256 NULL if the record is not found
260 dbfn_read_with_length(open_db *dbblock, const uschar *key, int *length)
263 EXIM_DATUM key_datum, result_datum;
264 int klen = Ustrlen(key) + 1;
265 uschar * key_copy = store_get(klen, is_tainted(key));
267 memcpy(key_copy, key, klen);
269 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_read: key=%s\n", key);
271 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
272 EXIM_DATUM_INIT(result_datum); /* to be cleared before use. */
273 EXIM_DATUM_DATA(key_datum) = CS key_copy;
274 EXIM_DATUM_SIZE(key_datum) = klen;
276 if (!EXIM_DBGET(dbblock->dbptr, key_datum, result_datum)) return NULL;
278 /* Assume the data store could have been tainted. Properly, we should
279 store the taint status with the data. */
281 yield = store_get(EXIM_DATUM_SIZE(result_datum), TRUE);
282 memcpy(yield, EXIM_DATUM_DATA(result_datum), EXIM_DATUM_SIZE(result_datum));
283 if (length != NULL) *length = EXIM_DATUM_SIZE(result_datum);
285 EXIM_DATUM_FREE(result_datum); /* Some DBM libs require freeing */
291 /*************************************************
292 * Write to database file *
293 *************************************************/
297 dbblock a pointer to an open database block
298 key the key of the record to be written
299 ptr a pointer to the record to be written
300 length the length of the record to be written
302 Returns: the yield of the underlying dbm or db "write" function. If this
303 is dbm, the value is zero for OK.
307 dbfn_write(open_db *dbblock, const uschar *key, void *ptr, int length)
309 EXIM_DATUM key_datum, value_datum;
310 dbdata_generic *gptr = (dbdata_generic *)ptr;
311 int klen = Ustrlen(key) + 1;
312 uschar * key_copy = store_get(klen, is_tainted(key));
314 memcpy(key_copy, key, klen);
315 gptr->time_stamp = time(NULL);
317 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_write: key=%s\n", key);
319 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
320 EXIM_DATUM_INIT(value_datum); /* to be cleared before use. */
321 EXIM_DATUM_DATA(key_datum) = CS key_copy;
322 EXIM_DATUM_SIZE(key_datum) = klen;
323 EXIM_DATUM_DATA(value_datum) = CS ptr;
324 EXIM_DATUM_SIZE(value_datum) = length;
325 return EXIM_DBPUT(dbblock->dbptr, key_datum, value_datum);
330 /*************************************************
331 * Delete record from database file *
332 *************************************************/
336 dbblock a pointer to an open database block
337 key the key of the record to be deleted
339 Returns: the yield of the underlying dbm or db "delete" function.
343 dbfn_delete(open_db *dbblock, const uschar *key)
345 int klen = Ustrlen(key) + 1;
346 uschar * key_copy = store_get(klen, is_tainted(key));
348 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_delete: key=%s\n", key);
350 memcpy(key_copy, key, klen);
351 EXIM_DATUM key_datum;
352 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require clearing */
353 EXIM_DATUM_DATA(key_datum) = CS key_copy;
354 EXIM_DATUM_SIZE(key_datum) = klen;
355 return EXIM_DBDEL(dbblock->dbptr, key_datum);
360 /*************************************************
361 * Scan the keys of a database file *
362 *************************************************/
366 dbblock a pointer to an open database block
367 start TRUE if starting a new scan
368 FALSE if continuing with the current scan
369 cursor a pointer to a pointer to a cursor anchor, for those dbm libraries
370 that use the notion of a cursor
372 Returns: the next record from the file, or
373 NULL if there are no more
377 dbfn_scan(open_db *dbblock, BOOL start, EXIM_CURSOR **cursor)
379 EXIM_DATUM key_datum, value_datum;
381 value_datum = value_datum; /* dummy; not all db libraries use this */
383 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_scan\n");
385 /* Some dbm require an initialization */
387 if (start) EXIM_DBCREATE_CURSOR(dbblock->dbptr, cursor);
389 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
390 EXIM_DATUM_INIT(value_datum); /* to be cleared before use. */
392 yield = (EXIM_DBSCAN(dbblock->dbptr, key_datum, value_datum, start, *cursor))?
393 US EXIM_DATUM_DATA(key_datum) : NULL;
395 /* Some dbm require a termination */
397 if (!yield) EXIM_DBDELETE_CURSOR(*cursor);
403 /*************************************************
404 **************************************************
405 * Stand-alone test program *
406 **************************************************
407 *************************************************/
412 main(int argc, char **cargv)
415 int max_db = sizeof(dbblock)/sizeof(open_db);
419 dbdata_wait *dbwait = NULL;
420 uschar **argv = USS cargv;
422 uschar structbuffer[1024];
426 printf("Usage: test_dbfn directory\n");
427 printf("The subdirectory called \"db\" in the given directory is used for\n");
428 printf("the files used in this test program.\n");
434 spool_directory = argv[1];
435 debug_selector = D_all - D_memory;
437 big_buffer = malloc(big_buffer_size);
439 for (i = 0; i < max_db; i++) dbblock[i].dbptr = NULL;
441 printf("\nExim's db functions tester: interface type is %s\n", EXIM_DBTYPE);
442 printf("DBM library: ");
444 #ifdef DB_VERSION_STRING
445 printf("Berkeley DB: %s\n", DB_VERSION_STRING);
446 #elif defined(BTREEVERSION) && defined(HASHVERSION)
448 printf("probably Berkeley DB version 1.8x (native mode)\n");
450 printf("probably Berkeley DB version 1.8x (compatibility mode)\n");
452 #elif defined(_DBM_RDONLY) || defined(dbm_dirfno)
453 printf("probably ndbm\n");
454 #elif defined(USE_TDB)
455 printf("using tdb\n");
458 printf("probably GDBM (native mode)\n");
460 printf("probably GDBM (compatibility mode)\n");
464 /* Test the functions */
466 printf("\nTest the functions\n> ");
468 while (Ufgets(buffer, 256, stdin) != NULL)
470 int len = Ustrlen(buffer);
474 uschar *cmd = buffer;
475 while (len > 0 && isspace((uschar)buffer[len-1])) len--;
478 if (isdigit((uschar)*cmd))
481 while (isdigit((uschar)*cmd)) cmd++;
482 while (isspace((uschar)*cmd)) cmd++;
485 if (Ustrncmp(cmd, "open", 4) == 0)
490 while (isspace((uschar)*s)) s++;
492 for (i = 0; i < max_db; i++)
493 if (dbblock[i].dbptr == NULL) break;
497 printf("Too many open databases\n> ");
502 odb = dbfn_open(s, O_RDWR, dbblock + i, TRUE, TRUE);
508 printf("opened %d\n", current);
510 /* Other error cases will have written messages */
511 else if (errno == ENOENT)
513 printf("open failed: %s%s\n", strerror(errno),
515 " (or other Berkeley DB error)"
523 else if (Ustrncmp(cmd, "write", 5) == 0)
526 uschar *key = cmd + 5;
531 printf("No current database\n");
535 while (isspace((uschar)*key)) key++;
537 while (*data != 0 && !isspace((uschar)*data)) data++;
539 while (isspace((uschar)*data)) data++;
541 dbwait = (dbdata_wait *)(&structbuffer);
542 Ustrcpy(dbwait->text, data);
546 rc = dbfn_write(dbblock + current, key, dbwait,
547 Ustrlen(data) + sizeof(dbdata_wait));
549 if (rc != 0) printf("Failed: %s\n", strerror(errno));
552 else if (Ustrncmp(cmd, "read", 4) == 0)
554 uschar *key = cmd + 4;
557 printf("No current database\n");
560 while (isspace((uschar)*key)) key++;
563 dbwait = (dbdata_wait *)dbfn_read_with_length(dbblock+ current, key, NULL);
565 printf("%s\n", (dbwait == NULL)? "<not found>" : CS dbwait->text);
568 else if (Ustrncmp(cmd, "delete", 6) == 0)
570 uschar *key = cmd + 6;
573 printf("No current database\n");
576 while (isspace((uschar)*key)) key++;
577 dbfn_delete(dbblock + current, key);
580 else if (Ustrncmp(cmd, "scan", 4) == 0)
583 BOOL startflag = TRUE;
585 uschar keybuffer[256];
588 printf("No current database\n");
592 while ((key = dbfn_scan(dbblock + current, startflag, &cursor)) != NULL)
595 Ustrcpy(keybuffer, key);
596 dbwait = (dbdata_wait *)dbfn_read_with_length(dbblock + current,
598 printf("%s: %s\n", keybuffer, dbwait->text);
601 printf("End of scan\n");
604 else if (Ustrncmp(cmd, "close", 5) == 0)
607 while (isspace((uschar)*s)) s++;
609 if (i >= max_db || dbblock[i].dbptr == NULL) printf("Not open\n"); else
612 dbfn_close(dbblock + i);
614 dbblock[i].dbptr = NULL;
615 if (i == current) current = -1;
619 else if (Ustrncmp(cmd, "file", 4) == 0)
622 while (isspace((uschar)*s)) s++;
624 if (i >= max_db || dbblock[i].dbptr == NULL) printf("Not open\n");
628 else if (Ustrncmp(cmd, "time", 4) == 0)
630 showtime = ~showtime;
631 printf("Timing %s\n", showtime? "on" : "off");
634 else if (Ustrcmp(cmd, "q") == 0 || Ustrncmp(cmd, "quit", 4) == 0) break;
636 else if (Ustrncmp(cmd, "help", 4) == 0)
638 printf("close [<number>] close file [<number>]\n");
639 printf("delete <key> remove record from current file\n");
640 printf("file <number> make file <number> current\n");
641 printf("open <name> open db file\n");
642 printf("q[uit] exit program\n");
643 printf("read <key> read record from current file\n");
644 printf("scan scan current file\n");
645 printf("time time display on/off\n");
646 printf("write <key> <rest-of-line> write record to current file\n");
649 else printf("Eh?\n");
651 if (showtime && stop >= start)
652 printf("start=%d stop=%d difference=%d\n", (int)start, (int)stop,
653 (int)(stop - start));
658 for (i = 0; i < max_db; i++)
660 if (dbblock[i].dbptr != NULL)
662 printf("\nClosing %d", i);
663 dbfn_close(dbblock + i);