1DB_HOTBACKUP(1) BerkeleyDB Utilities DB_HOTBACKUP(1)
2
6 db_hotbackup - Create "hot backup" or "hot failover" snapshots
7
9 db_hotbackup [-cDEguVv] [-d data_dir ...] [-h home] [-l log_dir] [-P
10 password] -b backup_dir
11
13 The db_hotbackup utility creates "hot backup" or "hot failover" snap‐
14 shots of Berkeley DB database environments.
15 The db_hotbackup utility performs the following steps:
17 1. Sets the DB_HOTBACKUP_IN_PROGRESS flag in the home database
19 environment.
20 2. If the -c option is specified, checkpoint the source home
22 database environment, and remove any unnecessary log files.
23 3. If the target directory for the backup does not exist, it is
25 created with mode read-write-execute for the owner.
26 If the target directory for the backup does exist and the -u
28 option was specified, all log files in the target directory
29 are removed; if the -u option was not specified, all files in
30 the target directory are removed.
31 4. If the -u option was not specified, copy application-specific
33 files found in the database environment home directory, or
34 any directory specified using the -d option, into the target
35 directory for the backup.
36 5. Copy all log files found in the directory specified by the -l
38 option (or in the database environment home directory, if no
39 -l option was specified), into the target directory for the
40 backup.
41 6. Perform catastrophic recovery on the hot backup.
43 7. Remove any unnecessary log files from the hot backup.
45 8. Reset the DB_HOTBACKUP_IN_PROGRESS flag in the environment.
47 The db_hotbackup utility does not resolve pending transactions that are
49 in the prepared state. Applications that use DB_TXN->prepare should
50 specify DB_RECOVER_FATAL when opening the environment, and run
51 DB_ENV->txn_recover to resolve any pending transactions, when failing
52 over to the hot backup.
53
55 -b backup_dir
56 Specify the target directory for the backup.
57 -c Before performing the snapshot, checkpoint the source database
59 environment and remove any log files that are no longer required
60 in that environment. To avoid making catastrophic failure
61 impossible, log file removal must be integrated with log file
62 archival.
63 Care should be taken with the -c option, where the db_hotbackup
65 MUST be run by the same user that owns the database. If db_hot‐
66 backup is run by a user different to the owner of the database,
67 a new log file owned by this user might be created, making it
68 impossible to use the database for its owner.
69 -D Use the data and log directories listed in a DB_CONFIG configu‐
71 ration file in the source directory. This option has four
72 effects:
73 1. The specified data and log directories will be created rela‐
75 tive to the target directory, with mode read-write-execute
76 owner, if they do not already exist.
77 2. In step #3 above, all files in any source data directories
79 specified in the DB_CONFIG file will be copied to the target
80 data directories.
81 3. In step #4 above, log files will be copied from any log
83 directory specified in the DB_CONFIG file, instead of from
84 the default locations.
85 4. The DB_CONFIG configuration file will be copied from the
87 source directory to the target directory, and subsequently
88 used for configuration if recovery is run in the target
89 directory.
90 Care should be taken with the -D option where data and log
92 directories are named relative to the source directory but are
93 not subdirectories (that is, the name includes the element "..")
94 Specifically, the constructed target directory names must be
95 meaningful and distinct from the source directory names, other‐
96 wise running recovery in the target directory might corrupt the
97 source data files.
98 It is an error to use absolute pathnames for data or log direc‐
100 tories in this mode, as the DB_CONFIG configuration file copied
101 into the target directory would then point at the source direc‐
102 tories and running recovery would corrupt the source data files.
103 -d data_dir
105 Specify one or more source directories that contain databases;
106 if none is specified, the database environment home directory
107 will be searched for database files. As database files are
108 copied into a single backup directory, files named the same,
109 stored in different source directories, could overwrite each
110 other when copied into the backup directory.
111 -F Directly copy from the filesystem. This option can CORRUPT the
113 backup if used while the environment is active and the operating
114 system does not support atomic file system reads. This option
115 is known to be safe only on UNIX systems, not Linux or Windows
116 systems.
117 -h home
119 Specify the source directory for the backup, that is, the data‐
120 base environment home directory.
121 -l log_dir
123 Specify a source directory that contains log files; if none is
124 specified, the database environment home directory will be
125 searched for log files.
126 -P password
128 Specify an environment password. Although Berkeley DB utilities
129 overwrite password strings as soon as possible, be aware there
130 may be a window of vulnerability on systems where unprivileged
131 users can see command-line arguments or where utilities are not
132 able to overwrite the memory containing the command-line argu‐
133 ments.
134 -u Update a pre-existing hot backup snapshot by copying in new log
136 files. If the -u option is specified, no databases will be
137 copied into the target directory.
138 -V Write the library version number to the standard output, and
140 exit.
141 -v Run in verbose mode, listing operations as they are done.
143 -D Use the data directories listed in the DB_CONFIG configuration
145 file in the source directory. This option has three effects:
146 First, if they do not already exist, the specified data directo‐
147 ries will be created relative to the target directory (with mode
148 read-write-execute owner). Second, all files in the source data
149 directories will be copied to the target data directories. If
150 the DB_CONFIG file specifies one or more absolute pathnames,
151 files in those source directories will be copied to the top-
152 level target directory. Third, the DB_CONFIG configuration file
153 will be copied from the +source directory to the target direc‐
154 tory, and subsequently used for configuration if recovery is run
155 in the target directory.
156 Care should be taken with the -D option and data directories which are
158 named relative to the source directory but are not subdirectories (that
159 is, the name includes the element "..") Specifically, the constructed
160 target directory names must be meaningful and distinct from the source
161 directory names, otherwise running recovery in the target directory
162 might corrupt the source data files.
163 It is an error to use absolute pathnames for data directories or the
165 log directory in this mode, as the DB_CONFIG configuration file copied
166 into the target directory would then point at the source directories
167 and running recovery would corrupt the source data files.
168 The db_hotbackup utility uses a Berkeley DB environment (as described
170 for the -h option, the environment variable DB_HOME, or because the
171 utility was run in a directory containing a Berkeley DB environment).
172 In order to avoid environment corruption when using a Berkeley DB envi‐
173 ronment, db_hotbackup should always be given the chance to detach from
174 the environment and exit gracefully. To cause db_hotbackup to release
175 all environment resources and exit cleanly, send it an interrupt signal
176 (SIGINT).
177
179 The db_hotbackup utility exits 0 on success, and >0 if an error occurs.
180
182 DB_HOME
183 If the -h option is not specified and the environment variable
184 DB_HOME is set, it is used as the path of the database home, as
185 described in DB_ENV->open.
186
188 db_archive(1) db_checkpoint(1) db_deadlock(1) db_dump(1) db_log_ver‐
189 ify(1) db_load(1) db_printlog(1) db_recover(1) db_replicate(1)
190 db_stat(1) db_tuner(1) db_upgrade(1) db_verify(1)
191BerkeleyDB 5.3.21 06 December 2016 DB_HOTBACKUP(1)