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);
63 /*************************************************
64 * Open and lock a database file *
65 *************************************************/
67 /* Used for accessing Exim's hints databases.
70 name The single-component name of one of Exim's database files.
71 flags Either O_RDONLY or O_RDWR, indicating the type of open required;
72 O_RDWR implies "create if necessary"
73 dbblock Points to an open_db block to be filled in.
74 lof If TRUE, write to the log for actual open failures (locking failures
76 panic If TRUE, panic on failure to create the db directory
78 Returns: NULL if the open failed, or the locking failed. After locking
79 failures, errno is zero.
81 On success, dbblock is returned. This contains the dbm pointer and
82 the fd of the locked lock file.
84 There are some calls that use O_RDWR|O_CREAT for the flags. Having discovered
85 this in December 2005, I'm not sure if this is correct or not, but for the
86 moment I haven't changed them.
90 dbfn_open(uschar *name, int flags, open_db *dbblock, BOOL lof, BOOL panic)
93 BOOL read_only = flags == O_RDONLY;
96 uschar dirname[256], filename[256];
98 DEBUG(D_hints_lookup) acl_level++;
100 /* The first thing to do is to open a separate file on which to lock. This
101 ensures that Exim has exclusive use of the database before it even tries to
102 open it. Early versions tried to lock on the open database itself, but that
103 gave rise to mysterious problems from time to time - it was suspected that some
104 DB libraries "do things" on their open() calls which break the interlocking.
105 The lock file is never written to, but we open it for writing so we can get a
106 write lock if required. If it does not exist, we create it. This is done
107 separately so we know when we have done it, because when running as root we
108 need to change the ownership - see the bottom of this function. We also try to
109 make the directory as well, just in case. We won't be doing this many times
110 unnecessarily, because usually the lock file will be there. If the directory
111 exists, there is no error. */
113 snprintf(CS dirname, sizeof(dirname), "%s/db", spool_directory);
114 snprintf(CS filename, sizeof(filename), "%s/%s.lockfile", dirname, name);
116 if ((dbblock->lockfd = Uopen(filename, O_RDWR, EXIMDB_LOCKFILE_MODE)) < 0)
119 (void)directory_make(spool_directory, US"db", EXIMDB_DIRECTORY_MODE, panic);
120 dbblock->lockfd = Uopen(filename, O_RDWR|O_CREAT, EXIMDB_LOCKFILE_MODE);
123 if (dbblock->lockfd < 0)
125 log_write(0, LOG_MAIN, "%s",
126 string_open_failed("database lock file %s", filename));
127 errno = 0; /* Indicates locking failure */
128 DEBUG(D_hints_lookup) acl_level--;
132 /* Now we must get a lock on the opened lock file; do this with a blocking
133 lock that times out. */
135 lock_data.l_type = read_only? F_RDLCK : F_WRLCK;
136 lock_data.l_whence = lock_data.l_start = lock_data.l_len = 0;
138 DEBUG(D_hints_lookup|D_retry|D_route|D_deliver)
139 debug_printf_indent("locking %s\n", filename);
141 sigalrm_seen = FALSE;
142 ALARM(EXIMDB_LOCK_TIMEOUT);
143 rc = fcntl(dbblock->lockfd, F_SETLKW, &lock_data);
146 if (sigalrm_seen) errno = ETIMEDOUT;
149 log_write(0, LOG_MAIN|LOG_PANIC, "Failed to get %s lock for %s: %s",
150 read_only ? "read" : "write", filename,
151 errno == ETIMEDOUT ? "timed out" : strerror(errno));
152 (void)close(dbblock->lockfd);
153 errno = 0; /* Indicates locking failure */
154 DEBUG(D_hints_lookup) acl_level--;
158 DEBUG(D_hints_lookup) debug_printf_indent("locked %s\n", filename);
160 /* At this point we have an opened and locked separate lock file, that is,
161 exclusive access to the database, so we can go ahead and open it. If we are
162 expected to create it, don't do so at first, again so that we can detect
163 whether we need to change its ownership (see comments about the lock file
164 above.) There have been regular reports of crashes while opening hints
165 databases - often this is caused by non-matching db.h and the library. To make
166 it easy to pin this down, there are now debug statements on either side of the
169 snprintf(CS filename, sizeof(filename), "%s/%s", dirname, name);
170 EXIM_DBOPEN(filename, dirname, flags, EXIMDB_MODE, &(dbblock->dbptr));
172 if (!dbblock->dbptr && errno == ENOENT && flags == O_RDWR)
174 DEBUG(D_hints_lookup)
175 debug_printf_indent("%s appears not to exist: trying to create\n", filename);
177 EXIM_DBOPEN(filename, dirname, flags|O_CREAT, EXIMDB_MODE, &(dbblock->dbptr));
182 /* If we are running as root and this is the first access to the database, its
183 files will be owned by root. We want them to be owned by exim. We detect this
184 situation by noting above when we had to create the lock file or the database
185 itself. Because the different dbm libraries use different extensions for their
186 files, I don't know of any easier way of arranging this than scanning the
187 directory for files with the appropriate base name. At least this deals with
188 the lock file at the same time. Also, the directory will typically have only
189 half a dozen files, so the scan will be quick.
191 This code is placed here, before the test for successful opening, because there
192 was a case when a file was created, but the DBM library still returned NULL
193 because of some problem. It also sorts out the lock file if that was created
194 but creation of the database file failed. */
196 if (created && geteuid() == root_uid)
199 uschar *lastname = Ustrrchr(filename, '/') + 1;
200 int namelen = Ustrlen(name);
204 if ((dd = exim_opendir(filename)))
205 for (struct dirent *ent; ent = readdir(dd); )
206 if (Ustrncmp(ent->d_name, name, namelen) == 0)
209 /* Filenames from readdir() are trusted,
210 so use a taint-nonchecking copy */
211 strcpy(CS lastname, CCS ent->d_name);
212 if (Ustat(filename, &statbuf) >= 0 && statbuf.st_uid != exim_uid)
214 DEBUG(D_hints_lookup)
215 debug_printf_indent("ensuring %s is owned by exim\n", filename);
216 if (exim_chown(filename, exim_uid, exim_gid))
217 DEBUG(D_hints_lookup)
218 debug_printf_indent("failed setting %s to owned by exim\n", filename);
225 /* If the open has failed, return NULL, leaving errno set. If lof is TRUE,
226 log the event - also for debugging - but debug only if the file just doesn't
232 if (lof && save_errno != ENOENT)
233 log_write(0, LOG_MAIN, "%s", string_open_failed("DB file %s",
236 DEBUG(D_hints_lookup)
237 debug_printf_indent("%s\n", CS string_open_failed("DB file %s",
239 (void)close(dbblock->lockfd);
241 DEBUG(D_hints_lookup) acl_level--;
245 DEBUG(D_hints_lookup)
246 debug_printf_indent("opened hints database %s: flags=%s\n", filename,
247 flags == O_RDONLY ? "O_RDONLY"
248 : flags == O_RDWR ? "O_RDWR"
249 : flags == (O_RDWR|O_CREAT) ? "O_RDWR|O_CREAT"
252 /* Pass back the block containing the opened database handle and the open fd
261 /*************************************************
262 * Unlock and close a database file *
263 *************************************************/
265 /* Closing a file automatically unlocks it, so after closing the database, just
268 Argument: a pointer to an open database block
273 dbfn_close(open_db *dbblock)
275 EXIM_DBCLOSE(dbblock->dbptr);
276 (void)close(dbblock->lockfd);
277 DEBUG(D_hints_lookup)
278 { debug_printf_indent("closed hints database and lockfile\n"); acl_level--; }
284 /*************************************************
285 * Read from database file *
286 *************************************************/
288 /* Passing back the pointer unchanged is useless, because there is
289 no guarantee of alignment. Since all the records used by Exim need
290 to be properly aligned to pick out the timestamps, etc., we might as
291 well do the copying centrally here.
293 Most calls don't need the length, so there is a macro called dbfn_read which
294 has two arguments; it calls this function adding NULL as the third.
297 dbblock a pointer to an open database block
298 key the key of the record to be read
299 length a pointer to an int into which to return the length, if not NULL
301 Returns: a pointer to the retrieved record, or
302 NULL if the record is not found
306 dbfn_read_with_length(open_db *dbblock, const uschar *key, int *length)
309 EXIM_DATUM key_datum, result_datum;
310 int klen = Ustrlen(key) + 1;
311 uschar * key_copy = store_get(klen, is_tainted(key));
313 memcpy(key_copy, key, klen);
315 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_read: key=%s\n", key);
317 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
318 EXIM_DATUM_INIT(result_datum); /* to be cleared before use. */
319 EXIM_DATUM_DATA(key_datum) = CS key_copy;
320 EXIM_DATUM_SIZE(key_datum) = klen;
322 if (!EXIM_DBGET(dbblock->dbptr, key_datum, result_datum)) return NULL;
324 /* Assume the data store could have been tainted. Properly, we should
325 store the taint status with the data. */
327 yield = store_get(EXIM_DATUM_SIZE(result_datum), TRUE);
328 memcpy(yield, EXIM_DATUM_DATA(result_datum), EXIM_DATUM_SIZE(result_datum));
329 if (length != NULL) *length = EXIM_DATUM_SIZE(result_datum);
331 EXIM_DATUM_FREE(result_datum); /* Some DBM libs require freeing */
336 /* Read a record. If the length is not as expected then delete it, write
337 an error log line and return NULL.
338 Use this for fixed-size records (so not retry or wait records).
341 dbblock a pointer to an open database block
342 key the key of the record to be read
343 length the expected record length
345 Returns: a pointer to the retrieved record, or
346 NULL if the record is not found/bad
350 dbfn_read_enforce_length(open_db * dbblock, const uschar * key, size_t length)
353 void * yield = dbfn_read_with_length(dbblock, key, &rlen);
357 if (rlen == length) return yield;
358 log_write(0, LOG_MAIN|LOG_PANIC, "Bad db record size for '%s'", key);
359 dbfn_delete(dbblock, key);
365 /*************************************************
366 * Write to database file *
367 *************************************************/
371 dbblock a pointer to an open database block
372 key the key of the record to be written
373 ptr a pointer to the record to be written
374 length the length of the record to be written
376 Returns: the yield of the underlying dbm or db "write" function. If this
377 is dbm, the value is zero for OK.
381 dbfn_write(open_db *dbblock, const uschar *key, void *ptr, int length)
383 EXIM_DATUM key_datum, value_datum;
384 dbdata_generic *gptr = (dbdata_generic *)ptr;
385 int klen = Ustrlen(key) + 1;
386 uschar * key_copy = store_get(klen, is_tainted(key));
388 memcpy(key_copy, key, klen);
389 gptr->time_stamp = time(NULL);
391 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_write: key=%s\n", key);
393 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
394 EXIM_DATUM_INIT(value_datum); /* to be cleared before use. */
395 EXIM_DATUM_DATA(key_datum) = CS key_copy;
396 EXIM_DATUM_SIZE(key_datum) = klen;
397 EXIM_DATUM_DATA(value_datum) = CS ptr;
398 EXIM_DATUM_SIZE(value_datum) = length;
399 return EXIM_DBPUT(dbblock->dbptr, key_datum, value_datum);
404 /*************************************************
405 * Delete record from database file *
406 *************************************************/
410 dbblock a pointer to an open database block
411 key the key of the record to be deleted
413 Returns: the yield of the underlying dbm or db "delete" function.
417 dbfn_delete(open_db *dbblock, const uschar *key)
419 int klen = Ustrlen(key) + 1;
420 uschar * key_copy = store_get(klen, is_tainted(key));
422 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_delete: key=%s\n", key);
424 memcpy(key_copy, key, klen);
425 EXIM_DATUM key_datum;
426 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require clearing */
427 EXIM_DATUM_DATA(key_datum) = CS key_copy;
428 EXIM_DATUM_SIZE(key_datum) = klen;
429 return EXIM_DBDEL(dbblock->dbptr, key_datum);
434 /*************************************************
435 * Scan the keys of a database file *
436 *************************************************/
440 dbblock a pointer to an open database block
441 start TRUE if starting a new scan
442 FALSE if continuing with the current scan
443 cursor a pointer to a pointer to a cursor anchor, for those dbm libraries
444 that use the notion of a cursor
446 Returns: the next record from the file, or
447 NULL if there are no more
451 dbfn_scan(open_db *dbblock, BOOL start, EXIM_CURSOR **cursor)
453 EXIM_DATUM key_datum, value_datum;
456 DEBUG(D_hints_lookup) debug_printf_indent("dbfn_scan\n");
458 /* Some dbm require an initialization */
460 if (start) EXIM_DBCREATE_CURSOR(dbblock->dbptr, cursor);
462 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
463 EXIM_DATUM_INIT(value_datum); /* to be cleared before use. */
465 yield = (EXIM_DBSCAN(dbblock->dbptr, key_datum, value_datum, start, *cursor))?
466 US EXIM_DATUM_DATA(key_datum) : NULL;
468 /* Some dbm require a termination */
470 if (!yield) EXIM_DBDELETE_CURSOR(*cursor);
476 /*************************************************
477 **************************************************
478 * Stand-alone test program *
479 **************************************************
480 *************************************************/
485 main(int argc, char **cargv)
488 int max_db = sizeof(dbblock)/sizeof(open_db);
492 dbdata_wait *dbwait = NULL;
493 uschar **argv = USS cargv;
495 uschar structbuffer[1024];
499 printf("Usage: test_dbfn directory\n");
500 printf("The subdirectory called \"db\" in the given directory is used for\n");
501 printf("the files used in this test program.\n");
507 spool_directory = argv[1];
508 debug_selector = D_all - D_memory;
510 big_buffer = malloc(big_buffer_size);
512 for (i = 0; i < max_db; i++) dbblock[i].dbptr = NULL;
514 printf("\nExim's db functions tester: interface type is %s\n", EXIM_DBTYPE);
515 printf("DBM library: ");
517 #ifdef DB_VERSION_STRING
518 printf("Berkeley DB: %s\n", DB_VERSION_STRING);
519 #elif defined(BTREEVERSION) && defined(HASHVERSION)
521 printf("probably Berkeley DB version 1.8x (native mode)\n");
523 printf("probably Berkeley DB version 1.8x (compatibility mode)\n");
525 #elif defined(_DBM_RDONLY) || defined(dbm_dirfno)
526 printf("probably ndbm\n");
527 #elif defined(USE_TDB)
528 printf("using tdb\n");
531 printf("probably GDBM (native mode)\n");
533 printf("probably GDBM (compatibility mode)\n");
537 /* Test the functions */
539 printf("\nTest the functions\n> ");
541 while (Ufgets(buffer, 256, stdin) != NULL)
543 int len = Ustrlen(buffer);
547 uschar *cmd = buffer;
548 while (len > 0 && isspace((uschar)buffer[len-1])) len--;
551 if (isdigit((uschar)*cmd))
554 while (isdigit((uschar)*cmd)) cmd++;
555 while (isspace((uschar)*cmd)) cmd++;
558 if (Ustrncmp(cmd, "open", 4) == 0)
563 while (isspace((uschar)*s)) s++;
565 for (i = 0; i < max_db; i++)
566 if (dbblock[i].dbptr == NULL) break;
570 printf("Too many open databases\n> ");
575 odb = dbfn_open(s, O_RDWR, dbblock + i, TRUE, TRUE);
581 printf("opened %d\n", current);
583 /* Other error cases will have written messages */
584 else if (errno == ENOENT)
586 printf("open failed: %s%s\n", strerror(errno),
588 " (or other Berkeley DB error)"
596 else if (Ustrncmp(cmd, "write", 5) == 0)
599 uschar *key = cmd + 5;
604 printf("No current database\n");
608 while (isspace((uschar)*key)) key++;
610 while (*data != 0 && !isspace((uschar)*data)) data++;
612 while (isspace((uschar)*data)) data++;
614 dbwait = (dbdata_wait *)(&structbuffer);
615 Ustrcpy(dbwait->text, data);
619 rc = dbfn_write(dbblock + current, key, dbwait,
620 Ustrlen(data) + sizeof(dbdata_wait));
622 if (rc != 0) printf("Failed: %s\n", strerror(errno));
625 else if (Ustrncmp(cmd, "read", 4) == 0)
627 uschar *key = cmd + 4;
630 printf("No current database\n");
633 while (isspace((uschar)*key)) key++;
636 dbwait = (dbdata_wait *)dbfn_read_with_length(dbblock+ current, key, NULL);
638 printf("%s\n", (dbwait == NULL)? "<not found>" : CS dbwait->text);
641 else if (Ustrncmp(cmd, "delete", 6) == 0)
643 uschar *key = cmd + 6;
646 printf("No current database\n");
649 while (isspace((uschar)*key)) key++;
650 dbfn_delete(dbblock + current, key);
653 else if (Ustrncmp(cmd, "scan", 4) == 0)
656 BOOL startflag = TRUE;
658 uschar keybuffer[256];
661 printf("No current database\n");
665 while ((key = dbfn_scan(dbblock + current, startflag, &cursor)) != NULL)
668 Ustrcpy(keybuffer, key);
669 dbwait = (dbdata_wait *)dbfn_read_with_length(dbblock + current,
671 printf("%s: %s\n", keybuffer, dbwait->text);
674 printf("End of scan\n");
677 else if (Ustrncmp(cmd, "close", 5) == 0)
680 while (isspace((uschar)*s)) s++;
682 if (i >= max_db || dbblock[i].dbptr == NULL) printf("Not open\n"); else
685 dbfn_close(dbblock + i);
687 dbblock[i].dbptr = NULL;
688 if (i == current) current = -1;
692 else if (Ustrncmp(cmd, "file", 4) == 0)
695 while (isspace((uschar)*s)) s++;
697 if (i >= max_db || dbblock[i].dbptr == NULL) printf("Not open\n");
701 else if (Ustrncmp(cmd, "time", 4) == 0)
703 showtime = ~showtime;
704 printf("Timing %s\n", showtime? "on" : "off");
707 else if (Ustrcmp(cmd, "q") == 0 || Ustrncmp(cmd, "quit", 4) == 0) break;
709 else if (Ustrncmp(cmd, "help", 4) == 0)
711 printf("close [<number>] close file [<number>]\n");
712 printf("delete <key> remove record from current file\n");
713 printf("file <number> make file <number> current\n");
714 printf("open <name> open db file\n");
715 printf("q[uit] exit program\n");
716 printf("read <key> read record from current file\n");
717 printf("scan scan current file\n");
718 printf("time time display on/off\n");
719 printf("write <key> <rest-of-line> write record to current file\n");
722 else printf("Eh?\n");
724 if (showtime && stop >= start)
725 printf("start=%d stop=%d difference=%d\n", (int)start, (int)stop,
726 (int)(stop - start));
731 for (i = 0; i < max_db; i++)
733 if (dbblock[i].dbptr != NULL)
735 printf("\nClosing %d", i);
736 dbfn_close(dbblock + i);