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>Chapter 2. Enabling Transactions</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Getting Started with Berkeley DB Transaction Processing" /> 10 <link rel="up" href="index.html" title="Getting Started with Berkeley DB Transaction Processing" /> 11 <link rel="prev" href="perftune-intro.html" title="Performance Tuning" /> 12 <link rel="next" href="envopen.html" title="Opening a Transactional Environment and Database" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Chapter 2. Enabling Transactions</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="perftune-intro.html">Prev</a> </td> 22 <th width="60%" align="center"> </th> 23 <td width="20%" align="right"> <a accesskey="n" href="envopen.html">Next</a></td> 24 </tr> 25 </table> 26 <hr /> 27 </div> 28 <div class="chapter" lang="en" xml:lang="en"> 29 <div class="titlepage"> 30 <div> 31 <div> 32 <h2 class="title"><a id="enabletxn"></a>Chapter 2. Enabling Transactions</h2> 33 </div> 34 </div> 35 </div> 36 <div class="toc"> 37 <p> 38 <b>Table of Contents</b> 39 </p> 40 <dl> 41 <dt> 42 <span class="sect1"> 43 <a href="enabletxn.html#environments">Environments</a> 44 </span> 45 </dt> 46 <dd> 47 <dl> 48 <dt> 49 <span class="sect2"> 50 <a href="enabletxn.html#filenaming">File Naming</a> 51 </span> 52 </dt> 53 <dt> 54 <span class="sect2"> 55 <a href="enabletxn.html#errorsupport">Error Support</a> 56 </span> 57 </dt> 58 <dt> 59 <span class="sect2"> 60 <a href="enabletxn.html#sharedmemory">Shared Memory Regions</a> 61 </span> 62 </dt> 63 <dt> 64 <span class="sect2"> 65 <a href="enabletxn.html#security">Security Considerations</a> 66 </span> 67 </dt> 68 </dl> 69 </dd> 70 <dt> 71 <span class="sect1"> 72 <a href="envopen.html">Opening a Transactional Environment and 73 <span>Database</span> 74 75 76 </a> 77 </span> 78 </dt> 79 </dl> 80 </div> 81 <p> 82 In order to use transactions with your application, you must turn them 83 on. To do this you must: 84 </p> 85 <div class="itemizedlist"> 86 <ul type="disc"> 87 <li> 88 <p> 89 Use an 90 environment (see <a class="xref" href="enabletxn.html#environments" title="Environments">Environments</a> for details). 91 </p> 92 </li> 93 <li> 94 <p> 95 Turn on transactions for your environment. 96 97 98 99 <span> 100 You do this by providing the <code class="literal">DB_INIT_TXN</code> 101 flag to the 102 <code class="methodname">DbEnv::open()</code> 103 104 method. 105 </span> 106 107 <span> 108 Note that initializing the transactional subsystem implies that 109 the logging subsystem is also initialized. Also, note that 110 if you do not initialize transactions when you first create 111 your environment, then you cannot use transactions for that 112 environment after that. This is because DB 113 allocates certain structures needed for transactional 114 locking that are not available if the environment is 115 created without transactional support. 116 </span> 117 </p> 118 </li> 119 <li> 120 <p> 121 Initialize the in-memory cache by 122 <span> 123 passing the <code class="literal">DB_INIT_MPOOL</code> 124 flag to the 125 <code class="methodname">DbEnv::open()</code> 126 127 method. 128 </span> 129 130 131 </p> 132 </li> 133 <li> 134 <p> 135 Initialize the locking subsystem. This is what provides locking for concurrent applications. It also is used 136 to perform deadlock detection. See <a class="xref" href="txnconcurrency.html" title="Chapter 4. Concurrency">Concurrency</a> 137 for more information. 138 </p> 139 <p> 140 You initialize the locking subsystem by 141 <span> 142 passing the <code class="literal">DB_INIT_LOCK</code> 143 flag to the 144 <code class="methodname">DbEnv::open()</code> 145 146 method. 147 </span> 148 149 150 </p> 151 </li> 152 <li> 153 <p> 154 Initialize the logging subsystem. While this is enabled by 155 default for transactional applications, we suggest that 156 you explicitly initialize it anyway for the purposes of code readability. The logging 157 subsystem is what provides your transactional application its durability guarantee, and it is required for 158 recoverability purposes. See <a class="xref" href="filemanagement.html" title="Chapter 5. Managing DB Files">Managing DB Files</a> 159 for more information. 160 </p> 161 <p> 162 You initialize the logging subsystem by 163 <span> 164 passing the <code class="literal">DB_INIT_LOG</code> 165 flag to the 166 <code class="methodname">DbEnv::open()</code> 167 168 method. 169 </span> 170 171 172 </p> 173 </li> 174 <li> 175 <p> 176 <span> 177 Transaction-enable your databases. 178 </span> 179 <span> 180 If you are using the base API, transaction-enable your databases. 181 </span> 182 You do this by 183 184 185 <span> 186 encapsulating the database open in a transaction. 187 </span> 188 189 190 <span> 191 Note that the common practice is for auto commit to be used to 192 transaction-protect the database open. To use auto-commit, you 193 must still enable transactions as described here, but you do 194 not have to explicitly use a transaction when you open your 195 database. An example of this is given in the next section. 196 </span> 197 </p> 198 </li> 199 </ul> 200 </div> 201 <div class="sect1" lang="en" xml:lang="en"> 202 <div class="titlepage"> 203 <div> 204 <div> 205 <h2 class="title" style="clear: both"><a id="environments"></a>Environments</h2> 206 </div> 207 </div> 208 </div> 209 <div class="toc"> 210 <dl> 211 <dt> 212 <span class="sect2"> 213 <a href="enabletxn.html#filenaming">File Naming</a> 214 </span> 215 </dt> 216 <dt> 217 <span class="sect2"> 218 <a href="enabletxn.html#errorsupport">Error Support</a> 219 </span> 220 </dt> 221 <dt> 222 <span class="sect2"> 223 <a href="enabletxn.html#sharedmemory">Shared Memory Regions</a> 224 </span> 225 </dt> 226 <dt> 227 <span class="sect2"> 228 <a href="enabletxn.html#security">Security Considerations</a> 229 </span> 230 </dt> 231 </dl> 232 </div> 233 <p> 234 For simple DB applications, environments are optional. However, in 235 order to transaction protect your database operations, you must use an 236 environment. 237 </p> 238 <p> 239 An <span class="emphasis"><em>environment</em></span>, represents an 240 encapsulation of one or more databases and any associated log and 241 region files. They are used to support multi-threaded 242 and multi-process applications by allowing different threads of 243 control to share the in-memory cache, the locking tables, the 244 logging subsystem, and the file namespace. By sharing these things, 245 your concurrent application is more efficient than if each thread 246 of control had to manage these resources on its own. 247 </p> 248 <p> 249 By default all DB databases are backed by files on disk. In 250 addition to these files, transactional DB applications create 251 logs that are also by default stored on disk (they can optionally 252 be backed using shared memory). Finally, transactional 253 DB applications also create and use shared-memory regions that 254 are also typically backed by the filesystem. But like databases and 255 logs, the regions can be maintained strictly in-memory if your 256 application requires it. For an example of an application that 257 manages all environment files in-memory, see 258 <span><a class="xref" href="inmem_txnexample_c.html" title="In-Memory Transaction Example">In-Memory Transaction Example</a>.</span> 259 260 261 262 </p> 263 <div class="sect2" lang="en" xml:lang="en"> 264 <div class="titlepage"> 265 <div> 266 <div> 267 <h3 class="title"><a id="filenaming"></a>File Naming</h3> 268 </div> 269 </div> 270 </div> 271 <p> 272 In order to operate, your DB application must be able to 273 locate its database files, log files, and region files. If these 274 are stored in the filesystem, then you must tell DB where 275 they are located (a number of mechanisms exist that allow you to 276 identify the location of these files – see below). Otherwise, 277 by default they are located in the current working directory. 278 </p> 279 <div class="sect3" lang="en" xml:lang="en"> 280 <div class="titlepage"> 281 <div> 282 <div> 283 <h4 class="title"><a id="envhome"></a>Specifying the Environment Home Directory</h4> 284 </div> 285 </div> 286 </div> 287 <p> 288 The environment home directory is used to determine where 289 DB files are located. Its location 290 is identified using one of the following mechanisms, in the 291 following order of priority: 292 </p> 293 <div class="itemizedlist"> 294 <ul type="disc"> 295 <li> 296 <p> 297 If no information is given as to where to put the 298 environment home, then the current working 299 directory is used. 300 </p> 301 </li> 302 <li> 303 <p> 304 If a home directory is specified on the 305 306 <code class="methodname">DbEnv::open()</code> 307 308 <span>method,</span> 309 310 then that location is always used for the environment 311 home. 312 </p> 313 </li> 314 <li> 315 <p> 316 If a home directory is not supplied to 317 318 <span><code class="methodname">DbEnv::open()</code>, </span> 319 320 then the directory identified by the <code class="literal">DB_HOME</code> environment variable 321 is used <span class="emphasis"><em>if</em></span> you specify 322 <span> 323 either the <code class="literal">DB_USE_ENVIRON</code> or 324 <code class="literal">DB_USE_ENVIRON_ROOT</code> flags to the 325 326 <code class="methodname">DbEnv::open()</code> 327 method. Both flags allow you to identify the 328 path to the environment's home directory 329 using the <code class="literal">DB_HOME</code> environment variable. However, 330 <code class="literal">DB_USE_ENVIRON_ROOT</code> is honored only if the 331 process is run with root or administrative privileges. 332 </span> 333 334 335 </p> 336 </li> 337 </ul> 338 </div> 339 </div> 340 <div class="sect3" lang="en" xml:lang="en"> 341 <div class="titlepage"> 342 <div> 343 <div> 344 <h4 class="title"><a id="filelocation"></a>Specifying File Locations</h4> 345 </div> 346 </div> 347 </div> 348 <p> 349 By default, all DB files are created relative to the environment 350 home directory. For example, suppose your environment home is in 351 <code class="literal">/export/myAppHome</code>. Also suppose you name your database 352 <span><code class="literal">data/myDatabase.db</code>.</span> 353 354 Then in this case, the database is placed in: 355 <span><code class="literal">/export/myAppHome/data/myDatabase.db</code>.</span> 356 357 </p> 358 <p> 359 That said, DB always defers to absolute pathnames. 360 This means that if you provide an absolute filename when you 361 name your database, then that file is <span class="emphasis"><em>not</em></span> 362 placed relative to the environment home directory. Instead, it 363 is placed in the exact location that you specified for the 364 filename. 365 </p> 366 <p> 367 On UNIX systems, an absolute pathname is a name that begins with a 368 forward slash ('/'). On Windows systems, an absolute pathname is a 369 name that begins with one of the following: 370 </p> 371 <div class="itemizedlist"> 372 <ul type="disc"> 373 <li> 374 <p> 375 A backslash ('\'). 376 </p> 377 </li> 378 <li> 379 <p> 380 Any alphabetic letter, followed by a colon (':'), followed 381 by a backslash ('\'). 382 </p> 383 </li> 384 </ul> 385 </div> 386 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 387 <h3 class="title">Note</h3> 388 <p> 389 Try not to use absolute path names for your environment's 390 files. Under certain recovery scenarios, absolute path 391 names can render your environment unrecoverable. This 392 occurs if you are attempting to recover your environment on 393 a system that does not support the absolute path name that 394 you used. 395 </p> 396 </div> 397 </div> 398 <div class="sect3" lang="en" xml:lang="en"> 399 <div class="titlepage"> 400 <div> 401 <div> 402 <h4 class="title"><a id="splittingdata"></a>Identifying Specific File Locations</h4> 403 </div> 404 </div> 405 </div> 406 <p> 407 As described in the previous sections, DB will place all its 408 files in or relative to the environment home directory. 409 You can also cause a 410 specific database file to be placed in a particular location by 411 using an absolute path name for its name. In this 412 situation, the environment's home directory is not 413 considered when naming the file. 414 </p> 415 <p> 416 It is frequently desirable to place database, log, and region files on separate 417 disk drives. By spreading I/O across multiple drives, you 418 can increase parallelism and improve throughput. 419 Additionally, by placing log files and database files on 420 separate drives, you improve your application's 421 reliability by providing your application with a greater 422 chance of surviving a disk failure. 423 </p> 424 <p> 425 You can cause DB's files to be placed in specific 426 locations using the following mechanisms: 427 </p> 428 <div class="informaltable"> 429 <table border="1" width="80%"> 430 <colgroup> 431 <col /> 432 <col /> 433 </colgroup> 434 <thead> 435 <tr> 436 <th>File Type</th> 437 <th>To Override</th> 438 </tr> 439 </thead> 440 <tbody> 441 <tr> 442 <td>database files</td> 443 <td> 444 <p> 445 You can cause database files to be created 446 in a directory other than the 447 environment home by using the 448 449 <code class="methodname">DbEnv::set_data_dir()</code> 450 451 method. 452 The directory identified 453 here must exist. If a relative path is 454 provided, then the directory location is 455 resolved relative to the environment's home 456 directory. 457 </p> 458 459 <p> 460 This method modifies the directory 461 used for database files created and managed by 462 a single environment handle; it does not 463 configure the entire environment. 464 <span>This 465 method may not be called after the 466 environment has been opened. 467 </span> 468 </p> 469 470 <p> 471 You can also set a default data location that is used by 472 the entire environment by using the 473 <code class="literal">set_data_dir</code> parameter 474 in the environment's <code class="literal">DB_CONFIG</code> file. 475 Note that the <code class="literal">set_data_dir</code> 476 parameter overrides any value set by the 477 478 <code class="methodname">DbEnv::set_data_dir()</code> 479 480 method. 481 </p> 482 </td> 483 </tr> 484 <tr> 485 <td>Log files</td> 486 <td> 487 <p> 488 You can cause log files to be created 489 in a directory other than the environment home 490 directory by using the 491 492 <code class="methodname">DbEnv::set_lg_dir()</code> 493 494 method. The directory identified 495 here must exist. If a relative path is 496 provided, then the directory location is 497 resolved relative to the environment's home 498 directory. 499 </p> 500 501 <p> 502 This method modifies the directory 503 used for database files created and managed by 504 a single environment handle; it does not 505 configure the entire environment. 506 <span>This 507 method may not be called after the 508 environment has been opened. 509 </span> 510 </p> 511 512 <p> 513 You can also set a default log file location that is used by 514 the entire environment by using the 515 <code class="literal">set_lg_dir</code> parameter 516 in the environment's <code class="literal">DB_CONFIG</code> file. 517 Note that the <code class="literal">set_lg_dir</code> 518 parameter overrides any value set by the 519 520 <code class="methodname">DbEnv::set_lg_dir()</code> 521 522 method. 523 </p> 524 </td> 525 </tr> 526 <tr> 527 <td>Region files</td> 528 <td> 529 If backed by the filesystem, region 530 files are always placed in the environment home 531 directory. 532 </td> 533 </tr> 534 </tbody> 535 </table> 536 </div> 537 <p> 538 Note that the <code class="literal">DB_CONFIG</code> must reside in the 539 environment home directory. Parameters are specified in it one 540 parameter to a line. Each parameter is followed by a space, 541 which is followed by the parameter value. For example: 542 </p> 543 <pre class="programlisting"> set_data_dir /export1/db/env_data_files </pre> 544 </div> 545 </div> 546 <div class="sect2" lang="en" xml:lang="en"> 547 <div class="titlepage"> 548 <div> 549 <div> 550 <h3 class="title"><a id="errorsupport"></a>Error Support</h3> 551 </div> 552 </div> 553 </div> 554 <p> 555 To simplify error handling and to aid in application debugging, environments offer several useful 556 methods. 557 558 <span>Note that many of these 559 methods are identical to the error handling methods available for the 560 561 <span>Db</span> 562 563 564 <span>class.</span> 565 566 </span> 567 568 They are: 569 </p> 570 <div class="itemizedlist"> 571 <ul type="disc"> 572 <li> 573 <p> 574 <code class="methodname">set_error_stream()</code> 575 576 </p> 577 <p> 578 Sets the 579 <span>C++ <code class="classname">ostream</code></span> 580 581 to be used for displaying error messages issued by the DB library. 582 </p> 583 </li> 584 <li> 585 <p> 586 <code class="methodname">set_errcall()</code> 587 588 </p> 589 <p> 590 Defines the function that is called when an error message is 591 issued by DB. The error prefix and message are passed to 592 this callback. It is up to the application to display this 593 information correctly. 594 </p> 595 <p> 596 This is the recommended way to get error messages from 597 DB. 598 </p> 599 </li> 600 <li> 601 <p> 602 <code class="methodname">set_errfile()</code> 603 </p> 604 <p> 605 Sets the C library <code class="literal">FILE *</code> to be used for 606 displaying error messages issued by the DB library. 607 </p> 608 </li> 609 <li> 610 <p> 611 <code class="methodname">set_errpfx()</code> 612 613 </p> 614 <p> 615 Sets the prefix used to for any error messages issued by the 616 DB library. 617 </p> 618 </li> 619 <li> 620 <p> 621 <code class="methodname">err()</code> 622 </p> 623 <p> 624 Issues an error message based upon a DB error code a message text that you supply. 625 The error message is sent to the 626 callback function as defined by <code class="methodname">set_errcall()</code>. 627 If that method has not been used, then the error message is sent to the 628 file defined by 629 630 <span> 631 <code class="methodname">set_errfile()</code> or <code class="methodname">set_error_stream()</code>. 632 </span> 633 If none of these methods have been used, then the error message is sent to 634 standard error. 635 </p> 636 <p> 637 The error message consists of the prefix string 638 (as defined by <code class="methodname">set_errprefix()</code>), 639 an optional <code class="literal">printf</code>-style formatted message, 640 the DB error message associated with the supplied error code, 641 and a trailing newline. 642 </p> 643 </li> 644 <li> 645 <p> 646 <code class="methodname">errx()</code> 647 </p> 648 <p> 649 Behaves identically to <code class="methodname">err()</code> except 650 that you do not provide the DB error code and so 651 the DB message text is not displayed. 652 </p> 653 </li> 654 </ul> 655 </div> 656 <p> 657 In addition, you can use the <code class="function">db_strerror()</code> 658 function to directly return the error string that corresponds to a 659 particular error number. For more information on the 660 <code class="function">db_strerror()</code> function, see the <code class="literal">Error Returns</code> 661 section of the <em class="citetitle">Getting Started with Berkeley DB</em> guide. 662 </p> 663 </div> 664 <div class="sect2" lang="en" xml:lang="en"> 665 <div class="titlepage"> 666 <div> 667 <div> 668 <h3 class="title"><a id="sharedmemory"></a>Shared Memory Regions</h3> 669 </div> 670 </div> 671 </div> 672 <p> 673 The subsystems that you enable for an environment (in our case, 674 transaction, logging, locking, and the memory pool) 675 are described by one or more regions. The regions contain all of the 676 state information that needs to be shared among threads and/or 677 processes using the environment. 678 </p> 679 <p> 680 Regions may be backed by the file system, by heap memory, or by 681 system shared memory. 682 </p> 683 <div class="sect3" lang="en" xml:lang="en"> 684 <div class="titlepage"> 685 <div> 686 <div> 687 <h4 class="title"><a id="filebackedregions"></a>Regions Backed by Files</h4> 688 </div> 689 </div> 690 </div> 691 <p> 692 By default, shared memory regions are created as files in the environment's 693 home directory (<span class="emphasis"><em>not</em></span> the environment's data 694 directory). If it is available, the POSIX <code class="literal">mmap</code> 695 interface is used to map these files into your application's 696 address space. If <code class="literal">mmap</code> 697 is not available, then the UNIX <code class="literal">shmget</code> interfaces 698 are used instead (again, if they are available). 699 </p> 700 <p> 701 In this default case, the region files are named 702 <code class="literal">__db.###</code> 703 (for example, <code class="literal">__db.001</code>, <code class="literal">__db.002</code>, 704 and so on). 705 </p> 706 </div> 707 <div class="sect3" lang="en" xml:lang="en"> 708 <div class="titlepage"> 709 <div> 710 <div> 711 <h4 class="title"><a id="heapbackedregions"></a>Regions Backed by Heap Memory</h4> 712 </div> 713 </div> 714 </div> 715 <p> 716 If heap memory is used to back your shared memory regions, 717 the environment may only be 718 accessed by a single process, although that process may be 719 multi-threaded. In this case, the regions are managed only in 720 memory, and they are not written to the filesystem. You 721 indicate that heap memory is to be used for the region files by 722 specifying 723 <span> 724 <code class="literal">DB_PRIVATE</code> to the 725 726 <code class="methodname">DbEnv::open()</code> 727 method. 728 </span> 729 730 731 732 </p> 733 <p> 734 (For an example of an entirely in-memory transactional 735 application, see 736 <span> 737 <a class="xref" href="inmem_txnexample_c.html" title="In-Memory Transaction Example">In-Memory Transaction Example</a>.) 738 </span> 739 740 741 742 </p> 743 </div> 744 <div class="sect3" lang="en" xml:lang="en"> 745 <div class="titlepage"> 746 <div> 747 <div> 748 <h4 class="title"><a id="systembackedregions"></a>Regions Backed by System Memory</h4> 749 </div> 750 </div> 751 </div> 752 <p> 753 Finally, you can cause system memory to be used for your 754 regions instead of memory-mapped files. You do this by providing 755 <span> 756 <code class="literal">DB_SYSTEM_MEM</code> to the 757 758 <code class="methodname">DbEnv::open()</code> 759 method. 760 </span> 761 762 763 </p> 764 <p> 765 When region files are backed by system memory, DB creates a 766 single file in the environment's home directory. This file 767 contains information necessary to identify the system shared 768 memory in use by the environment. By creating this file, DB 769 enables multiple processes to share the environment. 770 </p> 771 <p> 772 The system memory that is used is architecture-dependent. For 773 example, on systems supporting X/Open-style shared memory 774 interfaces, such as UNIX systems, the <code class="literal">shmget(2)</code> 775 and related System V IPC interfaces are used. 776 777 <span> 778 779 Additionally, VxWorks systems use system memory. In these cases, 780 an initial segment ID must be specified by the application to 781 ensure that applications do not overwrite each other's 782 environments, so that the number of segments created does not 783 grow without bounds. See the 784 785 786 <code class="methodname">DbEnv::set_shm_key()</code> 787 788 method for more information. 789 </span> 790 </p> 791 <p> 792 On Windows platforms, the use of system memory for the region files 793 is problematic because the operating system uses reference counting 794 to clean up shared objects in the paging file automatically. In 795 addition, the default access permissions for shared objects are 796 different from files, which may cause problems when an environment 797 is accessed by multiple processes running as different users. See 798 <a class="ulink" href="" target="_top">Windows notes</a> 799 or more information. 800 </p> 801 </div> 802 </div> 803 <div class="sect2" lang="en" xml:lang="en"> 804 <div class="titlepage"> 805 <div> 806 <div> 807 <h3 class="title"><a id="security"></a>Security Considerations</h3> 808 </div> 809 </div> 810 </div> 811 <p> 812 When using environments, there are some security considerations to 813 keep in mind: 814 </p> 815 <div class="itemizedlist"> 816 <ul type="disc"> 817 <li> 818 <p> 819 Database environment permissions 820 </p> 821 <p> 822 The directory used for the environment 823 should have its permissions set to ensure that files in the 824 environment are not accessible to users without appropriate 825 permissions. Applications that add to the user's permissions 826 (for example, UNIX <code class="literal">setuid</code> or 827 <code class="literal">setgid</code> applications), must be 828 carefully checked to not permit illegal use of those 829 permissions such as general file access in the environment 830 directory. 831 </p> 832 </li> 833 <li> 834 <p> 835 Environment variables 836 </p> 837 <p> 838 Setting 839 840 <span> 841 the <code class="literal">DB_USE_ENVIRON</code> or 842 <code class="literal">DB_USE_ENVIRON_ROOT</code> flags 843 </span> 844 845 846 so that environment variables can be used during file naming 847 can be dangerous. Setting those flags in DB 848 applications with additional permissions (for example, UNIX 849 <code class="literal">setuid</code> or <code class="literal">setgid</code> 850 applications) could potentially allow users 851 to read and write databases to which they would not normally 852 have access. 853 </p> 854 <p> 855 For example, suppose you write a DB application 856 that runs <code class="literal">setuid</code>. This means that 857 when the application runs, it does so under a 858 userid different than that of the application's caller. 859 This is especially problematic if the application is 860 granting stronger privileges to a user than the user 861 might ordinarily have. 862 </p> 863 <p> 864 Now, if 865 <span> 866 the <code class="literal">DB_USE_ENVIRON</code> or 867 <code class="literal">DB_USE_ENVIRON_ROOT</code> flags 868 are set for the environment, 869 </span> 870 871 872 873 then the environment that the application is 874 using is modifiable using the 875 <code class="literal">DB_HOME</code> environment variable. In 876 this scenario, if the uid used by the application has 877 sufficiently broad privileges, then the application's caller 878 can read and/or write databases owned by another user 879 simply by setting his 880 <code class="literal">DB_HOME</code> environment variable to the 881 environment used by that other user. 882 </p> 883 <p> 884 Note that this scenario need not be malicious; the 885 wrong environment could be used by the application 886 simply by inadvertently specifying the wrong path to 887 <code class="literal">DB_HOME</code>. 888 </p> 889 <p> 890 As always, you should use <code class="literal">setuid</code> 891 sparingly, if at all. But if you do use 892 <code class="literal">setuid</code>, then you should refrain from 893 specifying 894 <span> 895 the <code class="literal">DB_USE_ENVIRON</code> or 896 <code class="literal">DB_USE_ENVIRON_ROOT</code> flags 897 </span> 898 899 for the environment open. And, of course, if you must 900 use <code class="literal">setuid</code>, then make sure you use 901 the weakest uid possible – preferably one that is 902 used only by the application itself. 903 </p> 904 </li> 905 <li> 906 <p> 907 File permissions 908 </p> 909 <p> 910 By default, DB always creates database and log files readable and 911 writable by the owner and the group (that is, 912 <code class="literal">S_IRUSR</code>, 913 <code class="literal">S_IWUSR</code>, <code class="literal">S_IRGRP</code> and 914 <code class="literal">S_IWGRP</code>; or octal mode 0660 on historic 915 UNIX systems). The group ownership of created files is based 916 on the system and directory defaults, and is not further 917 specified by DB. 918 </p> 919 </li> 920 <li> 921 <p> 922 Temporary backing files 923 </p> 924 <p> 925 If an unnamed database is created and the cache is too small 926 to hold the database in memory, Berkeley DB will create a 927 temporary physical file to enable it to page the database to 928 disk as needed. In this case, environment variables such as 929 <code class="literal">TMPDIR</code> may be used to specify the 930 location of that temporary file. Although temporary backing 931 files are created readable and writable by the owner only 932 (<code class="literal">S_IRUSR</code> and <code class="literal">S_IWUSR</code>, 933 or octal mode 0600 on historic UNIX systems), some 934 filesystems may not sufficiently protect temporary files 935 created in random directories from improper access. To be 936 absolutely safe, applications storing sensitive data in 937 unnamed databases should use the 938 939 <code class="methodname">DbEnv::set_tmp_dir()</code> 940 941 method to specify a temporary directory with known permissions. 942 </p> 943 </li> 944 </ul> 945 </div> 946 </div> 947 </div> 948 </div> 949 <div class="navfooter"> 950 <hr /> 951 <table width="100%" summary="Navigation footer"> 952 <tr> 953 <td width="40%" align="left"><a accesskey="p" href="perftune-intro.html">Prev</a> </td> 954 <td width="20%" align="center"> </td> 955 <td width="40%" align="right"> <a accesskey="n" href="envopen.html">Next</a></td> 956 </tr> 957 <tr> 958 <td width="40%" align="left" valign="top">Performance Tuning </td> 959 <td width="20%" align="center"> 960 <a accesskey="h" href="index.html">Home</a> 961 </td> 962 <td width="40%" align="right" valign="top"> Opening a Transactional Environment and 963 <span>Database</span> 964 965 966 </td> 967 </tr> 968 </table> 969 </div> 970 </body> 971</html> 972