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