1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>db_hotbackup</title> 7 <link rel="stylesheet" href="apiReference.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB C++ API Reference" /> 10 <link rel="up" href="utilities.html" title="Appendix 1. Berkeley DB Command Line Utilities" /> 11 <link rel="prev" href="db_dump.html" title="db_dump" /> 12 <link rel="next" href="db_load.html" title="db_load" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">db_hotbackup</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="db_dump.html">Prev</a> </td> 22 <th width="60%" align="center">Appendix 1. 23 Berkeley DB Command Line Utilities 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="db_load.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="db_hotbackup"></a>db_hotbackup</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">db_hotbackup [-cDuVv] [-d data_dir ...] [-h home] 39 [-l log_dir] [-P password] -b backup_dir </pre> 40 <p> 41 The <span class="command"><strong>db_hotbackup</strong></span> utility creates "hot backup" or "hot failover" 42 snapshots of Berkeley DB database environments. 43 </p> 44 <p> 45 The <span class="command"><strong>db_hotbackup</strong></span> utility performs the following steps: 46 </p> 47 <div class="orderedlist"> 48 <ol type="1"> 49 <li> 50 <p> 51 If the <span class="bold"><strong>-c</strong></span> option is specified, 52 checkpoint the source home database environment, and remove any 53 unnecessary log files. 54 </p> 55 </li> 56 <li> 57 <p> 58 If the target directory for the backup does not exist, it is created 59 with mode read-write-execute for the owner. 60 </p> 61 <p> 62 If the target directory for the backup does exist and the <span class="bold"><strong>-u</strong></span> option was specified, all log files in the 63 target directory are removed; if the <span class="bold"><strong>-u</strong></span> option was not specified, all files in the 64 target directory are removed. 65 </p> 66 </li> 67 <li> 68 <p> 69 If the <span class="bold"><strong>-u</strong></span> option was not specified, 70 copy application-specific files found in the database environment home 71 directory, and any directories specified using the <span class="bold"><strong>-d</strong></span> option, into the target directory for the 72 backup. 73 </p> 74 </li> 75 <li> 76 <p> 77 Copy all log files found in the directory specified by the <span class="bold"><strong>-l</strong></span> option (or in the database environment home 78 directory, if no <span class="bold"><strong>-l</strong></span> option was 79 specified), into the target directory for the backup. 80 </p> 81 </li> 82 <li> 83 <p> 84 Perform catastrophic recovery in the target directory for the backup. 85 </p> 86 </li> 87 <li> 88 <p> 89 Remove any unnecessary log files from the target directory for the 90 backup. 91 </p> 92 </li> 93 </ol> 94 </div> 95 <p> 96 The <span class="command"><strong>db_hotbackup</strong></span> utility does not resolve pending transactions that 97 are in the prepared state. Applications that use 98 <a class="xref" href="txnprepare.html" title="DbTxn::prepare()">DbTxn::prepare()</a> must specify 99 <a class="link" href="envopen.html#envopen_DB_RECOVER_FATAL">DB_RECOVER_FATAL</a> 100 when opening the environment, and run 101 <a class="xref" href="txnrecover.html" title="DbEnv::txn_recover()">DbEnv::txn_recover()</a> to 102 resolve any pending transactions, when failing over to the backup. 103 </p> 104 <p> 105 The options are as follows: 106 </p> 107 <div class="itemizedlist"> 108 <ul type="disc"> 109 <li> 110 <p> 111 <span class="bold"><strong>-b</strong></span> 112 </p> 113 <p> 114 Specify the target directory for the backup. 115 </p> 116 </li> 117 <li> 118 <p> 119 <span class="bold"><strong>-c</strong></span> 120 </p> 121 <p> 122 Before performing the backup, checkpoint the source database 123 environment and remove any log files that are no longer required in 124 that environment. <span class="bold"><strong>To avoid making catastrophic 125 recovery impossible, log file removal must be integrated with log file 126 archival.</strong></span> 127 </p> 128 </li> 129 <li> 130 <p> 131 <span class="bold"><strong>-D</strong></span> 132 </p> 133 <p> 134 Use the data and log directories listed in a <a href="../../programmer_reference/env_db_config.html#env_db_config.DB_CONFIG" class="olink">DB_CONFIG</a> 135 configuration file in the source directory. This option has four 136 effects: 137 </p> 138 <div class="itemizedlist"> 139 <ul type="circle"> 140 <li> 141 <p> 142 The specified data and log directories will be created relative to the 143 target directory, with mode read-write-execute owner, if they do not 144 already exist. 145 </p> 146 </li> 147 <li> 148 <p> 149 In step #3 above, all files in any source data directories specified 150 in the <a href="../../programmer_reference/env_db_config.html#env_db_config.DB_CONFIG" class="olink">DB_CONFIG</a> file will 151 be copied to the target data directories. 152 </p> 153 </li> 154 <li> 155 <p> 156 In step #4 above, log files will be copied from any log directory 157 specified in the <a href="../../programmer_reference/env_db_config.html#env_db_config.DB_CONFIG" class="olink">DB_CONFIG</a> file, 158 instead of from the default locations. 159 </p> 160 </li> 161 <li> 162 <p> 163 The <a href="../../programmer_reference/env_db_config.html#env_db_config.DB_CONFIG" class="olink">DB_CONFIG</a> 164 configuration file will be copied from the source directory to the 165 target directory, and subsequently used for configuration if recovery 166 is run in the target directory. 167 </p> 168 </li> 169 </ul> 170 </div> 171 <p> 172 Care should be taken with the <span class="bold"><strong>-D</strong></span> 173 option where data and log directories are named relative to the source 174 directory but are not subdirectories (that is, the name includes the 175 element "..") Specifically, the constructed target directory names 176 must be meaningful and distinct from the source directory names, 177 otherwise running recovery in the target directory might corrupt the 178 source data files. 179 </p> 180 <p> 181 <span class="bold"><strong>It is an error to use absolute pathnames for 182 data or log directories in this mode, as the <a href="../../programmer_reference/env_db_config.html#env_db_config.DB_CONFIG" class="olink">DB_CONFIG</a> 183 configuration file copied into the target directory would then point 184 at the source directories and running recovery would corrupt the 185 source data files.</strong></span> 186 </p> 187 </li> 188 <li> 189 <p> 190 <span class="bold"><strong>-d</strong></span> 191 </p> 192 <p> 193 Specify one or more directories that contain data files to be copied 194 to the target directory. 195 </p> 196 <p> 197 <span class="bold"><strong>As all database files are copied into a single 198 target directory, files named the same, stored in different source 199 directories, would overwrite each other when copied to the target 200 directory.</strong></span> 201 </p> 202 <p> 203 Please note the database environment recovery log references database 204 files as they are named by the application program. <span class="bold"><strong>If the application uses absolute or relative pathnames to 205 name database files, (rather than filenames and the 206 <a class="xref" href="envset_data_dir.html" title="DbEnv::set_data_dir()">DbEnv::set_data_dir()</a> 207 method or the <a href="../../programmer_reference/env_db_config.html#env_db_config.DB_CONFIG" class="olink">DB_CONFIG</a> 208 configuration file to specify filenames), running recovery in the 209 target directory may not properly find the copies of the files or 210 might even find the source files, potentially resulting in 211 corruption.</strong></span> 212 </p> 213 </li> 214 <li> 215 <p> 216 <span class="bold"><strong>-h</strong></span> 217 </p> 218 <p> 219 Specify the source directory for the backup. That is, the database 220 environment home directory. 221 </p> 222 </li> 223 <li> 224 <p> 225 <span class="bold"><strong>-l</strong></span> 226 </p> 227 <p> 228 Specify a source directory that contains log files; if none is 229 specified, the database environment home directory will be searched 230 for log files. 231 </p> 232 </li> 233 <li> 234 <p> 235 <span class="bold"><strong>-P</strong></span> 236 </p> 237 <p> 238 Specify an environment password. Although Berkeley DB utilities 239 overwrite password strings as soon as possible, be aware there may be 240 a window of vulnerability on systems where unprivileged users can see 241 command-line arguments or where utilities are not able to overwrite 242 the memory containing the command-line arguments. 243 </p> 244 </li> 245 <li> 246 <p> 247 <span class="bold"><strong>-u</strong></span> 248 </p> 249 <p> 250 Update a pre-existing hot backup snapshot by copying in new log files. 251 If the <span class="bold"><strong>-u</strong></span> option is specified, no 252 databases will be copied into the target directory. 253 </p> 254 </li> 255 <li> 256 <p> 257 <span class="bold"><strong>-V</strong></span> 258 </p> 259 <p> 260 Write the library version number to the standard output, and exit. 261 </p> 262 </li> 263 <li> 264 <p> 265 <span class="bold"><strong>-v</strong></span> 266 </p> 267 <p> 268 Run in verbose mode, listing operations as they are done. 269 </p> 270 </li> 271 </ul> 272 </div> 273 <p> 274 The <span class="command"><strong>db_hotbackup</strong></span> utility uses a Berkeley DB environment (as described 275 for the <span class="bold"><strong>-h</strong></span> option, the environment 276 variable <span class="bold"><strong>DB_HOME</strong></span>, or because the 277 utility was run in a directory containing a Berkeley DB environment). 278 In order to avoid environment corruption when using a Berkeley DB 279 environment, <span class="command"><strong>db_hotbackup</strong></span> should always be given the chance to detach 280 from the environment and exit gracefully. To cause <span class="command"><strong>db_hotbackup</strong></span> to 281 release all environment resources and exit cleanly, send it an 282 interrupt signal (SIGINT). 283 </p> 284 <p> 285 The <span class="command"><strong>db_hotbackup</strong></span> utility exits 0 on success, and >0 if an error 286 occurs. 287 </p> 288 <div class="sect2" lang="en" xml:lang="en"> 289 <div class="titlepage"> 290 <div> 291 <div> 292 <h3 class="title"><a id="id1718484"></a>Environment Variables</h3> 293 </div> 294 </div> 295 </div> 296 <div class="sect3" lang="en" xml:lang="en"> 297 <div class="titlepage"> 298 <div> 299 <div> 300 <h4 class="title"><a id="id1718538"></a>DB_HOME</h4> 301 </div> 302 </div> 303 </div> 304 <p> 305 If the <span class="bold"><strong>-h</strong></span> option is not specified and 306 the environment variable DB_HOME is set, it is used as the path of the 307 database home, as described in the 308 <a class="xref" href="envopen.html" title="DbEnv::open()">DbEnv::open()</a> method. 309 </p> 310 </div> 311 </div> 312 </div> 313 <div class="navfooter"> 314 <hr /> 315 <table width="100%" summary="Navigation footer"> 316 <tr> 317 <td width="40%" align="left"><a accesskey="p" href="db_dump.html">Prev</a> </td> 318 <td width="20%" align="center"> 319 <a accesskey="u" href="utilities.html">Up</a> 320 </td> 321 <td width="40%" align="right"> <a accesskey="n" href="db_load.html">Next</a></td> 322 </tr> 323 <tr> 324 <td width="40%" align="left" valign="top">db_dump </td> 325 <td width="20%" align="center"> 326 <a accesskey="h" href="index.html">Home</a> 327 </td> 328 <td width="40%" align="right" valign="top"> db_load</td> 329 </tr> 330 </table> 331 </div> 332 </body> 333</html> 334