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. */
12 /* We have buffers holding path names for database files.
13 PATH_MAX could be used here, but would be wasting memory, as we deal
14 with database files like $spooldirectory/db/<name> */
18 /* Functions for accessing Exim's hints database, which consists of a number of
19 different DBM files. This module does not contain code for reading DBM files
20 for (e.g.) alias expansion. That is all contained within the general search
21 functions. As Exim now has support for several DBM interfaces, all the relevant
22 functions are called as macros.
24 All the data in Exim's database is in the nature of *hints*. Therefore it
25 doesn't matter if it gets destroyed by accident. These functions are not
26 supposed to implement a "safe" database.
28 Keys are passed in as C strings, and the terminating zero *is* used when
29 building the dbm files. This just makes life easier when scanning the files
32 Synchronization is required on the database files, and this is achieved by
33 means of locking on independent lock files. (Earlier attempts to lock on the
34 DBM files themselves were never completely successful.) Since callers may in
35 general want to do more than one read or write while holding the lock, there
36 are separate open and close functions. However, the calling modules should
37 arrange to hold the locks for the bare minimum of time. */
41 /*************************************************
42 * Berkeley DB error callback *
43 *************************************************/
45 /* For Berkeley DB >= 2, we can define a function to be called in case of DB
46 errors. This should help with debugging strange DB problems, e.g. getting "File
47 exists" when you try to open a db file. The API for this function was changed
50 #if defined(USE_DB) && defined(DB_VERSION_STRING)
52 #if DB_VERSION_MAJOR > 4 || (DB_VERSION_MAJOR == 4 && DB_VERSION_MINOR >= 3)
53 dbfn_bdb_error_callback(const DB_ENV *dbenv, const char *pfx, const char *msg)
57 dbfn_bdb_error_callback(const char *pfx, char *msg)
61 log_write(0, LOG_MAIN, "Berkeley DB error: %s", msg);
68 /*************************************************
69 * Open and lock a database file *
70 *************************************************/
72 /* Used for accessing Exim's hints databases.
75 name The single-component name of one of Exim's database files.
76 flags Either O_RDONLY or O_RDWR, indicating the type of open required;
77 O_RDWR implies "create if necessary"
78 dbblock Points to an open_db block to be filled in.
79 lof If TRUE, write to the log for actual open failures (locking failures
81 panic If TRUE, panic on failure to create the db directory
83 Returns: NULL if the open failed, or the locking failed. After locking
84 failures, errno is zero.
86 On success, dbblock is returned. This contains the dbm pointer and
87 the fd of the locked lock file.
89 There are some calls that use O_RDWR|O_CREAT for the flags. Having discovered
90 this in December 2005, I'm not sure if this is correct or not, but for the
91 moment I haven't changed them.
95 dbfn_open(uschar *name, int flags, open_db *dbblock, BOOL lof, BOOL panic)
98 BOOL read_only = flags == O_RDONLY;
101 uschar dirname[PATHLEN], filename[PATHLEN];
103 DEBUG(D_hints_lookup) acl_level++;
105 /* The first thing to do is to open a separate file on which to lock. This
106 ensures that Exim has exclusive use of the database before it even tries to
107 open it. Early versions tried to lock on the open database itself, but that
108 gave rise to mysterious problems from time to time - it was suspected that some
109 DB libraries "do things" on their open() calls which break the interlocking.
110 The lock file is never written to, but we open it for writing so we can get a
111 write lock if required. If it does not exist, we create it. This is done
112 separately so we know when we have done it, because when running as root we
113 need to change the ownership - see the bottom of this function. We also try to
114 make the directory as well, just in case. We won't be doing this many times
115 unnecessarily, because usually the lock file will be there. If the directory
116 exists, there is no error. */
118 snprintf(CS dirname, sizeof(dirname), "%s/db", spool_directory);
119 snprintf(CS filename, sizeof(filename), "%s/%s.lockfile", dirname, name);
121 if ((dbblock->lockfd = Uopen(filename, O_RDWR, EXIMDB_LOCKFILE_MODE)) < 0)
124 (void)directory_make(spool_directory, US"db", EXIMDB_DIRECTORY_MODE, panic);
125 dbblock->lockfd = Uopen(filename, O_RDWR|O_CREAT, EXIMDB_LOCKFILE_MODE);
128 if (dbblock->lockfd < 0)
130 log_write(0, LOG_MAIN, "%s",
131 string_open_failed("database lock file %s", filename));
132 errno = 0; /* Indicates locking failure */
133 DEBUG(D_hints_lookup) acl_level--;
137 /* Now we must get a lock on the opened lock file; do this with a blocking
138 lock that times out. */
140 lock_data.l_type = read_only? F_RDLCK : F_WRLCK;
141 lock_data.l_whence = lock_data.l_start = lock_data.l_len = 0;
143 DEBUG(D_hints_lookup|D_retry|D_route|D_deliver)
144 debug_printf_indent("locking %s\n", filename);
146 sigalrm_seen = FALSE;
147 ALARM(EXIMDB_LOCK_TIMEOUT);
148 rc = fcntl(dbblock->lockfd, F_SETLKW, &lock_data);
151 if (sigalrm_seen) errno = ETIMEDOUT;
154 log_write(0, LOG_MAIN|LOG_PANIC, "Failed to get %s lock for %s: %s",
155 read_only ? "read" : "write", filename,
156 errno == ETIMEDOUT ? "timed out" : strerror(errno));
157 (void)close(dbblock->lockfd);
158 errno = 0; /* Indicates locking failure */
159 DEBUG(D_hints_lookup) acl_level--;
163 DEBUG(D_hints_lookup) debug_printf_indent("locked %s\n", filename);
165 /* At this point we have an opened and locked separate lock file, that is,
166 exclusive access to the database, so we can go ahead and open it. If we are
167 expected to create it, don't do so at first, again so that we can detect
168 whether we need to change its ownership (see comments about the lock file
169 above.) There have been regular reports of crashes while opening hints
170 databases - often this is caused by non-matching db.h and the library. To make
171 it easy to pin this down, there are now debug statements on either side of the
174 snprintf(CS filename, sizeof(filename), "%s/%s", dirname, name);
175 EXIM_DBOPEN(filename, dirname, flags, EXIMDB_MODE, &(dbblock->dbptr));
177 if (!dbblock->dbptr && errno == ENOENT && flags == O_RDWR)
179 DEBUG(D_hints_lookup)
180 debug_printf_indent("%s appears not to exist: trying to create\n", filename);
182 EXIM_DBOPEN(filename, dirname, flags|O_CREAT, EXIMDB_MODE, &(dbblock->dbptr));
187 /* If we are running as root and this is the first access to the database, its
188 files will be owned by root. We want them to be owned by exim. We detect this
189 situation by noting above when we had to create the lock file or the database
190 itself. Because the different dbm libraries use different extensions for their
191 files, I don't know of any easier way of arranging this than scanning the
192 directory for files with the appropriate base name. At least this deals with
193 the lock file at the same time. Also, the directory will typically have only
194 half a dozen files, so the scan will be quick.
196 This code is placed here, before the test for successful opening, because there
197 was a case when a file was created, but the DBM library still returned NULL
198 because of some problem. It also sorts out the lock file if that was created
199 but creation of the database file failed. */
201 if (created && geteuid() == root_uid)
204 uschar path[PATHLEN];
206 int namelen = Ustrlen(name);
208 Ustrcpy(path, filename);
209 lastname = Ustrrchr(path, '/') + 1;
212 if ((dd = exim_opendir(path)))
213 for (struct dirent *ent; ent = readdir(dd); )
214 if (Ustrncmp(ent->d_name, name, namelen) == 0)
217 /* Filenames from readdir() are trusted,
218 so use a taint-nonchecking copy */
219 strcpy(CS lastname, CCS ent->d_name);
220 if (Ustat(path, &statbuf) >= 0 && statbuf.st_uid != exim_uid)
222 DEBUG(D_hints_lookup)
223 debug_printf_indent("ensuring %s is owned by exim\n", path);
224 if (exim_chown(path, exim_uid, exim_gid))
225 DEBUG(D_hints_lookup)
226 debug_printf_indent("failed setting %s to owned by exim\n", path);
233 /* If the open has failed, return NULL, leaving errno set. If lof is TRUE,
234 log the event - also for debugging - but debug only if the file just doesn't
240 if (lof && save_errno != ENOENT)
241 log_write(0, LOG_MAIN, "%s", string_open_failed("DB file %s",
244 DEBUG(D_hints_lookup)
245 debug_printf_indent("%s\n", CS string_open_failed("DB file %s",
247 (void)close(dbblock->lockfd);
249 DEBUG(D_hints_lookup) acl_level--;
253 DEBUG(D_hints_lookup)
254 debug_printf_indent("opened hints database %s: flags=%s\n", filename,
255 flags == O_RDONLY ? "O_RDONLY"
256 : flags == O_RDWR ? "O_RDWR"
257 : flags == (O_RDWR|O_CREAT) ? "O_RDWR|O_CREAT"
260 /* Pass back the block containing the opened database handle and the open fd
269 /*************************************************
270 * Unlock and close a database file *
271 *************************************************/
273 /* Closing a file automatically unlocks it, so after closing the database, just
276 Argument: a pointer to an open database block
281 dbfn_close(open_db *dbblock)
283 EXIM_DBCLOSE(dbblock->dbptr);
284 (void)close(dbblock->lockfd);
285 DEBUG(D_hints_lookup)
286 { debug_printf_indent("closed hints database and lockfile\n"); acl_level--; }
292 /*************************************************
293 * Read from database file *
294 *************************************************/
296 /* Passing back the pointer unchanged is useless, because there is
297 no guarantee of alignment. Since all the records used by Exim need
298 to be properly aligned to pick out the timestamps, etc., we might as
299 well do the copying centrally here.
301 Most calls don't need the length, so there is a macro called dbfn_read which
302 has two arguments; it calls this function adding NULL as the third.
305 dbblock a pointer to an open database block
306 key the key of the record to be read
307 length a pointer to an int into which to return the length, if not NULL
309 Returns: a pointer to the retrieved record, or
310 NULL if the record is not found
314 dbfn_read_with_length(open_db *dbblock, const uschar *key, int *length)
317 EXIM_DATUM key_datum, result_datum;
318 int klen = Ustrlen(key) + 1;
319 uschar * key_copy = store_get(klen, is_tainted(key));
321 memcpy(key_copy, key, klen);
323 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_read: key=%s\n", key);
325 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
326 EXIM_DATUM_INIT(result_datum); /* to be cleared before use. */
327 EXIM_DATUM_DATA(key_datum) = CS key_copy;
328 EXIM_DATUM_SIZE(key_datum) = klen;
330 if (!EXIM_DBGET(dbblock->dbptr, key_datum, result_datum)) return NULL;
332 /* Assume the data store could have been tainted. Properly, we should
333 store the taint status with the data. */
335 yield = store_get(EXIM_DATUM_SIZE(result_datum), TRUE);
336 memcpy(yield, EXIM_DATUM_DATA(result_datum), EXIM_DATUM_SIZE(result_datum));
337 if (length != NULL) *length = EXIM_DATUM_SIZE(result_datum);
339 EXIM_DATUM_FREE(result_datum); /* Some DBM libs require freeing */
344 /* Read a record. If the length is not as expected then delete it, write
345 an error log line, delete the record and return NULL.
346 Use this for fixed-size records (so not retry or wait records).
349 dbblock a pointer to an open database block
350 key the key of the record to be read
351 length the expected record length
353 Returns: a pointer to the retrieved record, or
354 NULL if the record is not found/bad
358 dbfn_read_enforce_length(open_db * dbblock, const uschar * key, size_t length)
361 void * yield = dbfn_read_with_length(dbblock, key, &rlen);
365 if (rlen == length) return yield;
366 log_write(0, LOG_MAIN|LOG_PANIC, "Bad db record size for '%s'", key);
367 dbfn_delete(dbblock, key);
373 /*************************************************
374 * Write to database file *
375 *************************************************/
379 dbblock a pointer to an open database block
380 key the key of the record to be written
381 ptr a pointer to the record to be written
382 length the length of the record to be written
384 Returns: the yield of the underlying dbm or db "write" function. If this
385 is dbm, the value is zero for OK.
389 dbfn_write(open_db *dbblock, const uschar *key, void *ptr, int length)
391 EXIM_DATUM key_datum, value_datum;
392 dbdata_generic *gptr = (dbdata_generic *)ptr;
393 int klen = Ustrlen(key) + 1;
394 uschar * key_copy = store_get(klen, is_tainted(key));
396 memcpy(key_copy, key, klen);
397 gptr->time_stamp = time(NULL);
399 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_write: key=%s\n", key);
401 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
402 EXIM_DATUM_INIT(value_datum); /* to be cleared before use. */
403 EXIM_DATUM_DATA(key_datum) = CS key_copy;
404 EXIM_DATUM_SIZE(key_datum) = klen;
405 EXIM_DATUM_DATA(value_datum) = CS ptr;
406 EXIM_DATUM_SIZE(value_datum) = length;
407 return EXIM_DBPUT(dbblock->dbptr, key_datum, value_datum);
412 /*************************************************
413 * Delete record from database file *
414 *************************************************/
418 dbblock a pointer to an open database block
419 key the key of the record to be deleted
421 Returns: the yield of the underlying dbm or db "delete" function.
425 dbfn_delete(open_db *dbblock, const uschar *key)
427 int klen = Ustrlen(key) + 1;
428 uschar * key_copy = store_get(klen, is_tainted(key));
430 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_delete: key=%s\n", key);
432 memcpy(key_copy, key, klen);
433 EXIM_DATUM key_datum;
434 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require clearing */
435 EXIM_DATUM_DATA(key_datum) = CS key_copy;
436 EXIM_DATUM_SIZE(key_datum) = klen;
437 return EXIM_DBDEL(dbblock->dbptr, key_datum);
442 /*************************************************
443 * Scan the keys of a database file *
444 *************************************************/
448 dbblock a pointer to an open database block
449 start TRUE if starting a new scan
450 FALSE if continuing with the current scan
451 cursor a pointer to a pointer to a cursor anchor, for those dbm libraries
452 that use the notion of a cursor
454 Returns: the next record from the file, or
455 NULL if there are no more
459 dbfn_scan(open_db *dbblock, BOOL start, EXIM_CURSOR **cursor)
461 EXIM_DATUM key_datum, value_datum;
464 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_scan\n");
466 /* Some dbm require an initialization */
468 if (start) EXIM_DBCREATE_CURSOR(dbblock->dbptr, cursor);
470 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
471 EXIM_DATUM_INIT(value_datum); /* to be cleared before use. */
473 yield = (EXIM_DBSCAN(dbblock->dbptr, key_datum, value_datum, start, *cursor))?
474 US EXIM_DATUM_DATA(key_datum) : NULL;
476 /* Some dbm require a termination */
478 if (!yield) EXIM_DBDELETE_CURSOR(*cursor);
484 /*************************************************
485 **************************************************
486 * Stand-alone test program *
487 **************************************************
488 *************************************************/
493 main(int argc, char **cargv)
496 int max_db = sizeof(dbblock)/sizeof(open_db);
500 dbdata_wait *dbwait = NULL;
501 uschar **argv = USS cargv;
503 uschar structbuffer[1024];
507 printf("Usage: test_dbfn directory\n");
508 printf("The subdirectory called \"db\" in the given directory is used for\n");
509 printf("the files used in this test program.\n");
515 spool_directory = argv[1];
516 debug_selector = D_all - D_memory;
518 big_buffer = malloc(big_buffer_size);
520 for (i = 0; i < max_db; i++) dbblock[i].dbptr = NULL;
522 printf("\nExim's db functions tester: interface type is %s\n", EXIM_DBTYPE);
523 printf("DBM library: ");
525 #ifdef DB_VERSION_STRING
526 printf("Berkeley DB: %s\n", DB_VERSION_STRING);
527 #elif defined(BTREEVERSION) && defined(HASHVERSION)
529 printf("probably Berkeley DB version 1.8x (native mode)\n");
531 printf("probably Berkeley DB version 1.8x (compatibility mode)\n");
533 #elif defined(_DBM_RDONLY) || defined(dbm_dirfno)
534 printf("probably ndbm\n");
535 #elif defined(USE_TDB)
536 printf("using tdb\n");
539 printf("probably GDBM (native mode)\n");
541 printf("probably GDBM (compatibility mode)\n");
545 /* Test the functions */
547 printf("\nTest the functions\n> ");
549 while (Ufgets(buffer, 256, stdin) != NULL)
551 int len = Ustrlen(buffer);
555 uschar *cmd = buffer;
556 while (len > 0 && isspace((uschar)buffer[len-1])) len--;
559 if (isdigit((uschar)*cmd))
562 while (isdigit((uschar)*cmd)) cmd++;
563 while (isspace((uschar)*cmd)) cmd++;
566 if (Ustrncmp(cmd, "open", 4) == 0)
571 while (isspace((uschar)*s)) s++;
573 for (i = 0; i < max_db; i++)
574 if (dbblock[i].dbptr == NULL) break;
578 printf("Too many open databases\n> ");
583 odb = dbfn_open(s, O_RDWR, dbblock + i, TRUE, TRUE);
589 printf("opened %d\n", current);
591 /* Other error cases will have written messages */
592 else if (errno == ENOENT)
594 printf("open failed: %s%s\n", strerror(errno),
596 " (or other Berkeley DB error)"
604 else if (Ustrncmp(cmd, "write", 5) == 0)
607 uschar *key = cmd + 5;
612 printf("No current database\n");
616 while (isspace((uschar)*key)) key++;
618 while (*data != 0 && !isspace((uschar)*data)) data++;
620 while (isspace((uschar)*data)) data++;
622 dbwait = (dbdata_wait *)(&structbuffer);
623 Ustrcpy(dbwait->text, data);
627 rc = dbfn_write(dbblock + current, key, dbwait,
628 Ustrlen(data) + sizeof(dbdata_wait));
630 if (rc != 0) printf("Failed: %s\n", strerror(errno));
633 else if (Ustrncmp(cmd, "read", 4) == 0)
635 uschar *key = cmd + 4;
638 printf("No current database\n");
641 while (isspace((uschar)*key)) key++;
644 dbwait = (dbdata_wait *)dbfn_read_with_length(dbblock+ current, key, NULL);
646 printf("%s\n", (dbwait == NULL)? "<not found>" : CS dbwait->text);
649 else if (Ustrncmp(cmd, "delete", 6) == 0)
651 uschar *key = cmd + 6;
654 printf("No current database\n");
657 while (isspace((uschar)*key)) key++;
658 dbfn_delete(dbblock + current, key);
661 else if (Ustrncmp(cmd, "scan", 4) == 0)
664 BOOL startflag = TRUE;
666 uschar keybuffer[256];
669 printf("No current database\n");
673 while ((key = dbfn_scan(dbblock + current, startflag, &cursor)) != NULL)
676 Ustrcpy(keybuffer, key);
677 dbwait = (dbdata_wait *)dbfn_read_with_length(dbblock + current,
679 printf("%s: %s\n", keybuffer, dbwait->text);
682 printf("End of scan\n");
685 else if (Ustrncmp(cmd, "close", 5) == 0)
688 while (isspace((uschar)*s)) s++;
690 if (i >= max_db || dbblock[i].dbptr == NULL) printf("Not open\n"); else
693 dbfn_close(dbblock + i);
695 dbblock[i].dbptr = NULL;
696 if (i == current) current = -1;
700 else if (Ustrncmp(cmd, "file", 4) == 0)
703 while (isspace((uschar)*s)) s++;
705 if (i >= max_db || dbblock[i].dbptr == NULL) printf("Not open\n");
709 else if (Ustrncmp(cmd, "time", 4) == 0)
711 showtime = ~showtime;
712 printf("Timing %s\n", showtime? "on" : "off");
715 else if (Ustrcmp(cmd, "q") == 0 || Ustrncmp(cmd, "quit", 4) == 0) break;
717 else if (Ustrncmp(cmd, "help", 4) == 0)
719 printf("close [<number>] close file [<number>]\n");
720 printf("delete <key> remove record from current file\n");
721 printf("file <number> make file <number> current\n");
722 printf("open <name> open db file\n");
723 printf("q[uit] exit program\n");
724 printf("read <key> read record from current file\n");
725 printf("scan scan current file\n");
726 printf("time time display on/off\n");
727 printf("write <key> <rest-of-line> write record to current file\n");
730 else printf("Eh?\n");
732 if (showtime && stop >= start)
733 printf("start=%d stop=%d difference=%d\n", (int)start, (int)stop,
734 (int)(stop - start));
739 for (i = 0; i < max_db; i++)
741 if (dbblock[i].dbptr != NULL)
743 printf("\nClosing %d", i);
744 dbfn_close(dbblock + i);