1 /*************************************************
2 * Exim - an Internet mail transport agent *
3 *************************************************/
5 /* Copyright (c) The Exim Maintainers 2020 - 2024 */
6 /* Copyright (c) University of Cambridge 1995 - 2018 */
7 /* See the file NOTICE for conditions of use and distribution. */
8 /* SPDX-License-Identifier: GPL-2.0-or-later */
13 /* We have buffers holding path names for database files.
14 PATH_MAX could be used here, but would be wasting memory, as we deal
15 with database files like $spooldirectory/db/<name> */
19 /* Functions for accessing Exim's hints database, which consists of a number of
20 different DBM files. This module does not contain code for reading DBM files
21 for (e.g.) alias expansion. That is all contained within the general search
22 functions. As Exim now has support for several DBM interfaces, all the relevant
23 functions are called as inlinable functions from an included file.
25 All the data in Exim's database is in the nature of *hints*. Therefore it
26 doesn't matter if it gets destroyed by accident. These functions are not
27 supposed to implement a "safe" database.
29 Keys are passed in as C strings, and the terminating zero *is* used when
30 building the dbm files. This just makes life easier when scanning the files
33 Synchronization is required on the database files, and this is achieved by
34 means of locking on independent lock files. (Earlier attempts to lock on the
35 DBM files themselves were never completely successful.) Since callers may in
36 general want to do more than one read or write while holding the lock, there
37 are separate open and close functions. However, the calling modules should
38 arrange to hold the locks for the bare minimum of time.
41 exim_lockfile_needed facilities predicate
42 dbfn_open takes lockfile or opens transaction
43 dbfn_open_multi only if transactions supported;
44 no lock or transaction taken
45 dbfn_close release lockfile or transaction
47 dbfn_transaction_start only if transactions supported
48 dbfn_transaction_commit
50 dbfn_read_enforce_length
53 dbfn_scan unused; ifdeffout out
56 ACL ratelimit & seen conditions
57 delivery retry handling
58 delivery serialization
59 TLS session resumption
66 /*************************************************
67 * Open and lock a database file *
68 *************************************************/
70 /* Ensure the directory for the DB is present */
73 db_dir_make(BOOL panic)
75 (void) directory_make(spool_directory, US"db", EXIMDB_DIRECTORY_MODE, panic);
79 /* Lock a file to protect the DB. Return TRUE for success */
82 lockfile_take(open_db * dbblock, const uschar * filename, BOOL rdonly, BOOL panic)
85 int rc, * fdp = &dbblock->lockfd;
87 priv_drop_temp(exim_uid, exim_gid);
88 if ((*fdp = Uopen(filename, O_RDWR, EXIMDB_LOCKFILE_MODE)) < 0)
91 *fdp = Uopen(filename, O_RDWR|O_CREAT, EXIMDB_LOCKFILE_MODE);
97 log_write(0, LOG_MAIN, "%s",
98 string_open_failed("database lock file %s", filename));
99 errno = 0; /* Indicates locking failure */
103 /* Now we must get a lock on the opened lock file; do this with a blocking
104 lock that times out. */
106 lock_data.l_type = rdonly ? F_RDLCK : F_WRLCK;
107 lock_data.l_whence = lock_data.l_start = lock_data.l_len = 0;
109 DEBUG(D_hints_lookup|D_retry|D_route|D_deliver)
110 debug_printf_indent("locking %s\n", filename);
112 sigalrm_seen = FALSE;
113 ALARM(EXIMDB_LOCK_TIMEOUT);
114 rc = fcntl(*fdp, F_SETLKW, &lock_data);
117 if (sigalrm_seen) errno = ETIMEDOUT;
120 log_write(0, LOG_MAIN|LOG_PANIC, "Failed to get %s lock for %s: %s",
121 rdonly ? "read" : "write", filename,
122 errno == ETIMEDOUT ? "timed out" : strerror(errno));
123 (void)close(*fdp); *fdp = -1;
124 errno = 0; /* Indicates locking failure */
128 DEBUG(D_hints_lookup) debug_printf_indent("locked %s\n", filename);
132 /* Used for accessing Exim's hints databases.
135 name The single-component name of one of Exim's database files.
136 flags Either O_RDONLY or O_RDWR, indicating the type of open required;
138 dbblock Points to an open_db block to be filled in.
139 lof If TRUE, write to the log for actual open failures (locking failures
141 panic If TRUE, panic on failure to create the db directory
143 Returns: NULL if the open failed, or the locking failed. After locking
144 failures, errno is zero.
146 On success, dbblock is returned. This contains the dbm pointer and
147 the fd of the locked lock file.
151 dbfn_open(const uschar * name, int flags, open_db * dbblock,
152 BOOL lof, BOOL panic)
154 int rc, save_errno, dlen, flen;
156 uschar dirname[PATHLEN], filename[PATHLEN];
158 DEBUG(D_hints_lookup) acl_level++;
160 /* The first thing to do is to open a separate file on which to lock. This
161 ensures that Exim has exclusive use of the database before it even tries to
162 open it. Early versions tried to lock on the open database itself, but that
163 gave rise to mysterious problems from time to time - it was suspected that some
164 DB libraries "do things" on their open() calls which break the interlocking.
165 The lock file is never written to, but we open it for writing so we can get a
166 write lock if required. If it does not exist, we create it. This is done
167 separately so we know when we have done it, because when running as root we
168 need to change the ownership - see the bottom of this function. We also try to
169 make the directory as well, just in case. We won't be doing this many times
170 unnecessarily, because usually the lock file will be there. If the directory
171 exists, there is no error. */
173 dlen = snprintf(CS dirname, sizeof(dirname), "%s/db", spool_directory);
175 dbblock->readonly = (flags & O_ACCMODE) == O_RDONLY;
176 dbblock->lockfd = -1;
177 if (!exim_lockfile_needed())
181 flen = Ustrlen(name);
182 snprintf(CS filename, sizeof(filename), "%.*s/%.*s.lockfile",
183 (int)sizeof(filename) - dlen - flen - 11, dirname,
185 if (!lockfile_take(dbblock, filename, flags == O_RDONLY, panic))
187 DEBUG(D_hints_lookup) acl_level--;
192 /* At this point we have an opened and locked separate lock file, that is,
193 exclusive access to the database, so we can go ahead and open it. If we are
194 expected to create it, don't do so at first, again so that we can detect
195 whether we need to change its ownership (see comments about the lock file
196 above.) There have been regular reports of crashes while opening hints
197 databases - often this is caused by non-matching db.h and the library. To make
198 it easy to pin this down, there are now debug statements on either side of the
201 snprintf(CS filename, sizeof(filename), "%.*s/%s", dlen, dirname, name);
203 priv_drop_temp(exim_uid, exim_gid);
204 dbblock->dbptr = dbblock->readonly && !exim_lockfile_needed()
205 ? exim_dbopen_multi(filename, dirname, flags & O_ACCMODE, EXIMDB_MODE)
206 : exim_dbopen(filename, dirname, flags & O_ACCMODE, EXIMDB_MODE);
208 if (!dbblock->dbptr && errno == ENOENT && flags & O_CREAT)
210 DEBUG(D_hints_lookup)
211 debug_printf_indent("%s appears not to exist: trying to create\n", filename);
212 dbblock->dbptr = exim_dbopen(filename, dirname, flags, EXIMDB_MODE);
217 /* If the open has failed, return NULL, leaving errno set. If lof is TRUE,
218 log the event - also for debugging - but debug only if the file just doesn't
224 if (lof && save_errno != ENOENT)
225 log_write(0, LOG_MAIN, "%s", string_open_failed("DB file %s",
228 DEBUG(D_hints_lookup)
229 debug_printf_indent("%s\n", CS string_open_failed("DB file %s",
231 (void)close(dbblock->lockfd);
232 dbblock->lockfd = -1;
236 /* Pass back the block containing the opened database handle and the open fd
239 DEBUG(D_hints_lookup) acl_level--;
245 /* Only for transaction-capable DB types. Open without locking or
246 starting a transaction. "lof" and "panic" always true; read/write mode.
250 dbfn_open_multi(const uschar * name, int flags, open_db * dbblock)
252 int rc, save_errno, dlen;
254 uschar dirname[PATHLEN], filename[PATHLEN];
256 DEBUG(D_hints_lookup) acl_level++;
258 dbblock->lockfd = -1;
261 dlen = snprintf(CS dirname, sizeof(dirname), "%s/db", spool_directory);
262 snprintf(CS filename, sizeof(filename), "%.*s/%s", dlen, dirname, name);
264 priv_drop_temp(exim_uid, exim_gid);
265 dbblock->dbptr = exim_dbopen_multi(filename, dirname, flags & O_ACCMODE, EXIMDB_MODE);
266 if (!dbblock->dbptr && errno == ENOENT && flags & O_CREAT)
268 DEBUG(D_hints_lookup)
269 debug_printf_indent("%s appears not to exist: trying to create\n", filename);
270 dbblock->dbptr = exim_dbopen_multi(filename, dirname, flags, EXIMDB_MODE);
275 /* If the open has failed, return NULL, leaving errno set. If lof is TRUE,
276 log the event - also for debugging - but debug only if the file just doesn't
282 if (save_errno != ENOENT)
283 log_write(0, LOG_MAIN, "%s", string_open_failed("DB file %s",
286 DEBUG(D_hints_lookup)
287 debug_printf_indent("%s\n", CS string_open_failed("DB file %s",
292 /* Pass back the block containing the opened database handle */
293 DEBUG(D_hints_lookup) acl_level--;
299 dbfn_transaction_start(open_db * dbp)
301 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_transaction_start\n");
302 if (!dbp->readonly) return exim_dbtransaction_start(dbp->dbptr);
305 dbfn_transaction_commit(open_db * dbp)
307 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_transaction_commit\n");
308 if (!dbp->readonly) exim_dbtransaction_commit(dbp->dbptr);
313 /*************************************************
314 * Unlock and close a database file *
315 *************************************************/
317 /* Closing a file automatically unlocks it, so after closing the database, just
318 close the lock file if there was one.
320 Argument: a pointer to an open database block
325 dbfn_close(open_db * dbp)
327 int * fdp = &dbp->lockfd;
329 if (dbp->readonly && !exim_lockfile_needed())
330 exim_dbclose_multi(dbp->dbptr);
332 exim_dbclose(dbp->dbptr);
334 if (*fdp >= 0) (void)close(*fdp);
335 DEBUG(D_hints_lookup)
336 debug_printf_indent("closed hints database%s\n",
337 *fdp < 0 ? "" : " and lockfile");
343 dbfn_close_multi(open_db * dbp)
345 exim_dbclose_multi(dbp->dbptr);
346 DEBUG(D_hints_lookup)
347 debug_printf_indent("closed hints database\n");
353 /*************************************************
354 * Read from database file *
355 *************************************************/
357 /* Passing back the pointer unchanged is useless, because there is
358 no guarantee of alignment. Since all the records used by Exim need
359 to be properly aligned to pick out the timestamps, etc., we might as
360 well do the copying centrally here.
362 Most calls don't need the length, so there is a macro called dbfn_read which
363 has two arguments; it calls this function adding NULL as the third.
366 dbblock a pointer to an open database block
367 key the key of the record to be read
368 length a pointer to an int into which to return the length, if not NULL
370 Returns: a pointer to the retrieved record, or
371 NULL if the record is not found
375 dbfn_read_with_length(open_db * dbblock, const uschar * key, int * length)
378 EXIM_DATUM key_datum, result_datum;
379 int klen = Ustrlen(key) + 1;
380 uschar * key_copy = store_get(klen, key);
383 memcpy(key_copy, key, klen);
385 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_read: key=%s\n", key);
387 exim_datum_init(&key_datum); /* Some DBM libraries require the datum */
388 exim_datum_init(&result_datum); /* to be cleared before use. */
389 exim_datum_data_set(&key_datum, key_copy);
390 exim_datum_size_set(&key_datum, klen);
392 if (!exim_dbget(dbblock->dbptr, &key_datum, &result_datum))
394 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_read: null return\n");
398 /* Assume the data store could have been tainted. Properly, we should
399 store the taint status with the data. */
401 dlen = exim_datum_size_get(&result_datum);
402 yield = store_get(dlen, GET_TAINTED);
403 memcpy(yield, exim_datum_data_get(&result_datum), dlen);
404 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_read: size %u return\n", dlen);
405 if (length) *length = dlen;
407 exim_datum_free(&result_datum); /* Some DBM libs require freeing */
412 /* Read a record. If the length is not as expected then delete it, write
413 an error log line, delete the record and return NULL.
414 Use this for fixed-size records (so not retry or wait records).
417 dbblock a pointer to an open database block
418 key the key of the record to be read
419 length the expected record length
421 Returns: a pointer to the retrieved record, or
422 NULL if the record is not found/bad
426 dbfn_read_enforce_length(open_db * dbblock, const uschar * key, size_t length)
429 void * yield = dbfn_read_with_length(dbblock, key, &rlen);
433 if (rlen == length) return yield;
434 log_write(0, LOG_MAIN|LOG_PANIC, "Bad db record size for '%s'", key);
435 dbfn_delete(dbblock, key);
441 /*************************************************
442 * Write to database file *
443 *************************************************/
447 dbblock a pointer to an open database block
448 key the key of the record to be written
449 ptr a pointer to the record to be written
450 length the length of the record to be written
452 Returns: the yield of the underlying dbm or db "write" function. If this
453 is dbm, the value is zero for OK.
457 dbfn_write(open_db *dbblock, const uschar *key, void *ptr, int length)
459 EXIM_DATUM key_datum, value_datum;
460 dbdata_generic *gptr = (dbdata_generic *)ptr;
461 int klen = Ustrlen(key) + 1;
462 uschar * key_copy = store_get(klen, key);
464 memcpy(key_copy, key, klen);
465 gptr->time_stamp = time(NULL);
467 DEBUG(D_hints_lookup)
468 debug_printf_indent("dbfn_write: key=%s datalen %d\n", key, length);
470 exim_datum_init(&key_datum); /* Some DBM libraries require the datum */
471 exim_datum_init(&value_datum); /* to be cleared before use. */
472 exim_datum_data_set(&key_datum, key_copy);
473 exim_datum_size_set(&key_datum, klen);
474 exim_datum_data_set(&value_datum, ptr);
475 exim_datum_size_set(&value_datum, length);
476 return exim_dbput(dbblock->dbptr, &key_datum, &value_datum);
481 /*************************************************
482 * Delete record from database file *
483 *************************************************/
487 dbblock a pointer to an open database block
488 key the key of the record to be deleted
490 Returns: the yield of the underlying dbm or db "delete" function.
494 dbfn_delete(open_db *dbblock, const uschar *key)
496 int klen = Ustrlen(key) + 1;
497 uschar * key_copy = store_get(klen, key);
498 EXIM_DATUM key_datum;
500 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_delete: key=%s\n", key);
502 memcpy(key_copy, key, klen);
503 exim_datum_init(&key_datum); /* Some DBM libraries require clearing */
504 exim_datum_data_set(&key_datum, key_copy);
505 exim_datum_size_set(&key_datum, klen);
506 return exim_dbdel(dbblock->dbptr, &key_datum);
512 /* XXX This appears to be unused. There's a separate implementation
513 in dbutils.c for dumpdb and fixdb, using the same underlying support.
516 /*************************************************
517 * Scan the keys of a database file *
518 *************************************************/
522 dbblock a pointer to an open database block
523 start TRUE if starting a new scan
524 FALSE if continuing with the current scan
525 cursor a pointer to a pointer to a cursor anchor, for those dbm libraries
526 that use the notion of a cursor
528 Returns: the next record from the file, or
529 NULL if there are no more
533 dbfn_scan(open_db *dbblock, BOOL start, EXIM_CURSOR **cursor)
535 EXIM_DATUM key_datum, value_datum;
538 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_scan\n");
540 /* Some dbm require an initialization */
542 if (start) *cursor = exim_dbcreate_cursor(dbblock->dbptr);
544 exim_datum_init(&key_datum); /* Some DBM libraries require the datum */
545 exim_datum_init(&value_datum); /* to be cleared before use. */
547 yield = exim_dbscan(dbblock->dbptr, &key_datum, &value_datum, start, *cursor)
548 ? US exim_datum_data_get(&key_datum) : NULL;
550 /* Some dbm require a termination */
552 if (!yield) exim_dbdelete_cursor(*cursor);
559 /*************************************************
560 **************************************************
561 * Stand-alone test program *
562 **************************************************
563 *************************************************/
568 main(int argc, char **cargv)
571 int max_db = sizeof(dbblock)/sizeof(open_db);
575 dbdata_wait *dbwait = NULL;
576 uschar **argv = USS cargv;
578 uschar structbuffer[1024];
582 printf("Usage: test_dbfn directory\n");
583 printf("The subdirectory called \"db\" in the given directory is used for\n");
584 printf("the files used in this test program.\n");
590 spool_directory = argv[1];
591 debug_selector = D_all - D_memory;
593 big_buffer = malloc(big_buffer_size);
595 for (i = 0; i < max_db; i++) dbblock[i].dbptr = NULL;
597 printf("\nExim's db functions tester: interface type is %s\n", EXIM_DBTYPE);
598 printf("DBM library: ");
600 #ifdef DB_VERSION_STRING
601 printf("Berkeley DB: %s\n", DB_VERSION_STRING);
602 #elif defined(BTREEVERSION) && defined(HASHVERSION)
604 printf("probably Berkeley DB version 1.8x (native mode)\n");
606 printf("probably Berkeley DB version 1.8x (compatibility mode)\n");
608 #elif defined(_DBM_RDONLY) || defined(dbm_dirfno)
609 printf("probably ndbm\n");
610 #elif defined(USE_TDB)
611 printf("using tdb\n");
614 printf("probably GDBM (native mode)\n");
616 printf("probably GDBM (compatibility mode)\n");
620 /* Test the functions */
622 printf("\nTest the functions\n> ");
624 while (Ufgets(buffer, 256, stdin) != NULL)
626 int len = Ustrlen(buffer);
630 uschar *cmd = buffer;
631 while (len > 0 && isspace((uschar)buffer[len-1])) len--;
634 if (isdigit((uschar)*cmd))
637 while (isdigit((uschar)*cmd)) cmd++;
638 Uskip_whitespace(&cmd);
641 if (Ustrncmp(cmd, "open", 4) == 0)
646 Uskip_whitespace(&s);
648 for (i = 0; i < max_db; i++)
649 if (dbblock[i].dbptr == NULL) break;
653 printf("Too many open databases\n> ");
658 odb = dbfn_open(s, O_RDWR|O_CREAT, dbblock + i, TRUE, TRUE);
664 printf("opened %d\n", current);
666 /* Other error cases will have written messages */
667 else if (errno == ENOENT)
669 printf("open failed: %s%s\n", strerror(errno),
671 " (or other Berkeley DB error)"
679 else if (Ustrncmp(cmd, "write", 5) == 0)
682 uschar * key = cmd + 5, * data;
686 printf("No current database\n");
690 Uskip_whitespace(&key);
692 Uskip_nonwhite(&data);
694 Uskip_whitespace(&data);
696 dbwait = (dbdata_wait *)(&structbuffer);
697 Ustrcpy(dbwait->text, data);
701 rc = dbfn_write(dbblock + current, key, dbwait,
702 Ustrlen(data) + sizeof(dbdata_wait));
704 if (rc != 0) printf("Failed: %s\n", strerror(errno));
707 else if (Ustrncmp(cmd, "read", 4) == 0)
709 uschar * key = cmd + 4;
712 printf("No current database\n");
715 Uskip_whitespace(&key);
718 dbwait = (dbdata_wait *)dbfn_read_with_length(dbblock+ current, key, NULL);
720 printf("%s\n", (dbwait == NULL)? "<not found>" : CS dbwait->text);
723 else if (Ustrncmp(cmd, "delete", 6) == 0)
725 uschar * key = cmd + 6;
728 printf("No current database\n");
731 Uskip_whitespace(&key);
732 dbfn_delete(dbblock + current, key);
735 else if (Ustrncmp(cmd, "scan", 4) == 0)
738 BOOL startflag = TRUE;
740 uschar keybuffer[256];
743 printf("No current database\n");
747 while ((key = dbfn_scan(dbblock + current, startflag, &cursor)) != NULL)
750 Ustrcpy(keybuffer, key);
751 dbwait = (dbdata_wait *)dbfn_read_with_length(dbblock + current,
753 printf("%s: %s\n", keybuffer, dbwait->text);
756 printf("End of scan\n");
759 else if (Ustrncmp(cmd, "close", 5) == 0)
761 uschar * s = cmd + 5;
762 Uskip_whitespace(&s);
764 if (i >= max_db || dbblock[i].dbptr == NULL) printf("Not open\n"); else
767 dbfn_close(dbblock + i);
769 dbblock[i].dbptr = NULL;
770 if (i == current) current = -1;
774 else if (Ustrncmp(cmd, "file", 4) == 0)
776 uschar * s = cmd + 4;
777 Uskip_whitespace(&s);
779 if (i >= max_db || dbblock[i].dbptr == NULL) printf("Not open\n");
783 else if (Ustrncmp(cmd, "time", 4) == 0)
785 showtime = ~showtime;
786 printf("Timing %s\n", showtime? "on" : "off");
789 else if (Ustrcmp(cmd, "q") == 0 || Ustrncmp(cmd, "quit", 4) == 0) break;
791 else if (Ustrncmp(cmd, "help", 4) == 0)
793 printf("close [<number>] close file [<number>]\n");
794 printf("delete <key> remove record from current file\n");
795 printf("file <number> make file <number> current\n");
796 printf("open <name> open db file\n");
797 printf("q[uit] exit program\n");
798 printf("read <key> read record from current file\n");
799 printf("scan scan current file\n");
800 printf("time time display on/off\n");
801 printf("write <key> <rest-of-line> write record to current file\n");
804 else printf("Eh?\n");
806 if (showtime && stop >= start)
807 printf("start=%d stop=%d difference=%d\n", (int)start, (int)stop,
808 (int)(stop - start));
813 for (i = 0; i < max_db; i++)
815 if (dbblock[i].dbptr != NULL)
817 printf("\nClosing %d", i);
818 dbfn_close(dbblock + i);