1<!--$Id: db_hotbackup.so,v 1.10 2007/04/13 15:45:27 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB: db_hotbackup</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td> 13<b>db_hotbackup</b> 14</td> 15</tr></table> 16<hr size=1 noshade> 17<tt> 18<b><pre>db_hotbackup [<b>-cDuVv</b>] [<b>-d data_dir ...</b>] [<b>-h home</b>] [<b>-l log_dir</b>] [<b>-P password</b>] <b>-b</b> backup_dir</pre></b> 19<b>Description</b> 20<a name="2"><!--meow--></a> 21<p>The db_hotbackup utility creates "hot backup" or "hot failover" 22snapshots of Berkeley DB database environments.</p> 23<p>The db_hotbackup utility performs the following steps:</p> 24<ol> 25<p><li>If the <b>-c</b> option is specified, checkpoint the source home 26database environment, and remove any unnecessary log files. 27<p><li>If the target directory for the backup does not exist, it is created 28with mode read-write-execute for the owner. 29<p>If the target directory for the backup does exist and the <b>-u</b> 30option was specified, all log files in the target directory are removed; 31if the <b>-u</b> option was not specified, all files in the target 32directory are removed.</p> 33<p><li>If the <b>-u</b> option was not specified, copy application-specific 34files found in the database environment home directory, and any 35directories specified using the <b>-d</b> option, into the target 36directory for the backup. 37<p><li>Copy all log files found in the directory specified by the <b>-l</b> 38option (or in the database environment home directory, if no <b>-l</b> 39option was specified), into the target directory for the backup. 40<p><li>Perform catastrophic recovery in the target directory for the backup. 41<p><li>Remove any unnecessary log files from the target directory for the 42backup. 43</ol> 44<p>The db_hotbackup utility does not resolve pending transactions that 45are in the prepared state. Applications that use <a href="../api_c/txn_prepare.html">DB_TXN->prepare</a> 46should specify <a href="../api_c/env_open.html#DB_RECOVER_FATAL">DB_RECOVER_FATAL</a> when opening the environment, 47and run <a href="../api_c/txn_recover.html">DB_ENV->txn_recover</a> to resolve any pending transactions, when 48failing over to the backup.</p> 49<p>The options are as follows:</p> 50<br> 51<b>-b</b><ul compact><li>Specify the target directory for the backup.</ul> 52<b>-c</b><ul compact><li>Before performing the backup, checkpoint the source database environment 53and remove any log files that are no longer required in that environment. 54<b>To avoid making catastrophic recovery impossible, log file 55removal must be integrated with log file archival.</b></ul> 56<b>-D</b><ul compact><li>Use the data and log directories listed in a <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration 57file in the source directory. This option has four effects: 58<p><ul type=disc> 59<li>The specified data and log directories will be created relative to the 60target directory, with mode read-write-execute owner, if they do not 61already exist. 62<li>In step #3 above, all files in any source data directories specified in 63the <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> file will be copied to the target data directories. 64<li>In step #4 above, log files will be copied from any log directory specified 65in the <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> file, instead of from the default locations. 66<li>The <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration file will be copied from the source 67directory to the target directory, and subsequently used for configuration 68if recovery is run in the target directory. 69</ul> 70<p>Care should be taken with the <b>-D</b> option where data and log 71directories are named relative to the source directory but are not 72subdirectories (that is, the name includes the element "..") 73Specifically, the constructed target directory names must be meaningful 74and distinct from the source directory names, otherwise running recovery 75in the target directory might corrupt the source data files.</p> 76<p><b>It is an error to use absolute pathnames for data or log directories in 77this mode, as the <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration file copied into the 78target directory would then point at the source directories and running 79recovery would corrupt the source data files.</b></p></ul> 80<b>-d</b><ul compact><li>Specify one or more directories that contain data files to be copied to 81the target directory. 82<p><b>As all database files are copied into a single target directory, files 83named the same, stored in different source directories, would overwrite 84each other when copied to the target directory.</b></p> 85<p>Please note the database environment recovery log references database 86files as they are named by the application program. <b>If the 87application uses absolute or relative pathnames to name database files, 88(rather than filenames and the <a href="../api_c/env_set_data_dir.html">DB_ENV->set_data_dir</a> method or the 89<a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration file to specify filenames), running 90recovery in the target directory may not properly find the copies of 91the files or might even find the source files, potentially resulting in 92corruption.</b></p></ul> 93<b>-h</b><ul compact><li>Specify the target directory for the backup, that is, the database 94environment home directory.</ul> 95<b>-l</b><ul compact><li>Specify a source directory that contains log files; if none is specified, 96the database environment home directory will be searched for log files.</ul> 97<b>-P</b><ul compact><li>Specify an environment password. Although Berkeley DB utilities overwrite 98password strings as soon as possible, be aware there may be a window of 99vulnerability on systems where unprivileged users can see command-line 100arguments or where utilities are not able to overwrite the memory 101containing the command-line arguments.</ul> 102<b>-u</b><ul compact><li>Update a pre-existing hot backup snapshot by copying in new log files. 103If the <b>-u</b> option is specified, no databases will be copied 104into the target directory.</ul> 105<b>-V</b><ul compact><li>Write the library version number to the standard output, and exit.</ul> 106<b>-v</b><ul compact><li>Run in verbose mode, listing operations as they are done.</ul> 107<br> 108<p>The db_hotbackup utility uses a Berkeley DB environment (as described for the 109<b>-h</b> option, the environment variable <b>DB_HOME</b>, or 110because the utility was run in a directory containing a Berkeley DB 111environment). In order to avoid environment corruption when using a 112Berkeley DB environment, db_hotbackup should always be given the chance to 113detach from the environment and exit gracefully. To cause db_hotbackup 114to release all environment resources and exit cleanly, send it an 115interrupt signal (SIGINT).</p> 116<p>The db_hotbackup utility exits 0 on success, and >0 if an error occurs.</p> 117<br><b>Environment Variables</b> 118<br> 119<b>DB_HOME</b><ul compact><li>If the <b>-h</b> option is not specified and the environment variable 120DB_HOME is set, it is used as the path of the database home, as described 121in <a href="../api_c/env_open.html">DB_ENV->open</a>.</ul> 122<br> 123</tt> 124<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 125</body> 126</html> 127