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 104 <tt class="methodname">DB_ENV->open()</tt> 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 127 <tt class="methodname">DB_ENV->open()</tt> 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 146 <tt class="methodname">DB_ENV->open()</tt> 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 168 <tt class="methodname">DB_ENV->open()</tt> 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 <tt class="methodname">DB_ENV->open()</tt> 287 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 <span><tt class="methodname">DB_ENV->open()</tt>, </span> 299 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 <tt class="methodname">DB_ENV->open()</tt> 307 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 <tt class="methodname">DB_ENV->set_data_dir()</tt> 430 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 <tt class="methodname">DB_ENV->set_data_dir()</tt> 457 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 <tt class="methodname">DB_ENV->set_lg_dir()</tt> 471 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 <tt class="methodname">DB_ENV->set_lg_dir()</tt> 497 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 <span>DB</span> 539 540 541 <span>structure.</span> 542 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_errcall()</tt> 553 554 </p> 555 <p> 556 Defines the function that is called when an error message is 557 issued by DB. The error prefix and message are passed to 558 this callback. It is up to the application to display this 559 information correctly. 560 </p> 561 </li> 562 <li> 563 <p> 564 <tt class="methodname">set_errfile()</tt> 565 </p> 566 <p> 567 Sets the C library <tt class="literal">FILE *</tt> to be used for 568 displaying error messages issued by the DB library. 569 </p> 570 </li> 571 <li> 572 <p> 573 <tt class="methodname">set_errpfx()</tt> 574 575 </p> 576 <p> 577 Sets the prefix used to for any error messages issued by the 578 DB library. 579 </p> 580 </li> 581 <li> 582 <p> 583 <tt class="methodname">err()</tt> 584 </p> 585 <p> 586 Issues an error message based upon a DB error code a message text that you supply. 587 The error message is sent to the 588 callback function as defined by <tt class="methodname">set_errcall()</tt>. 589 If that method has not been used, then the error message is sent to the 590 file defined by 591 <span><tt class="methodname">set_errfile()</tt>.</span> 592 593 If none of these methods have been used, then the error message is sent to 594 standard error. 595 </p> 596 <p> 597 The error message consists of the prefix string 598 (as defined by <tt class="methodname">set_errprefix()</tt>), 599 an optional <tt class="literal">printf</tt>-style formatted message, 600 the DB error message associated with the supplied error code, 601 and a trailing newline. 602 </p> 603 </li> 604 <li> 605 <p> 606 <tt class="methodname">errx()</tt> 607 </p> 608 <p> 609 Behaves identically to <tt class="methodname">err()</tt> except 610 that you do not provide the DB error code and so 611 the DB message text is not displayed. 612 </p> 613 </li> 614 </ul> 615 </div> 616 <p> 617 In addition, you can use the <tt class="function">db_strerror()</tt> 618 function to directly return the error string that corresponds to a 619 particular error number. For more information on the 620 <tt class="function">db_strerror()</tt> function, see the <tt class="literal">Error Returns</tt> 621 section of the <i class="citetitle">Getting Started with Berkeley DB</i> guide. 622 </p> 623 </div> 624 <div class="sect2" lang="en" xml:lang="en"> 625 <div class="titlepage"> 626 <div> 627 <div> 628 <h3 class="title"><a id="sharedmemory"></a>Shared Memory Regions</h3> 629 </div> 630 </div> 631 <div></div> 632 </div> 633 <p> 634 The subsystems that you enable for an environment (in our case, 635 transaction, logging, locking, and the memory pool) 636 are described by one or more regions. The regions contain all of the 637 state information that needs to be shared among threads and/or 638 processes using the environment. 639 </p> 640 <p> 641 Regions may be backed by the file system, by heap memory, or by 642 system shared memory. 643 </p> 644 <div class="sect3" lang="en" xml:lang="en"> 645 <div class="titlepage"> 646 <div> 647 <div> 648 <h4 class="title"><a id="filebackedregions"></a>Regions Backed by Files</h4> 649 </div> 650 </div> 651 <div></div> 652 </div> 653 <p> 654 By default, shared memory regions are created as files in the environment's 655 home directory (<span class="emphasis"><em>not</em></span> the environment's data 656 directory). If it is available, the POSIX <tt class="literal">mmap</tt> 657 interface is used to map these files into your application's 658 address space. If <tt class="literal">mmap</tt> 659 is not available, then the UNIX <tt class="literal">shmget</tt> interfaces 660 are used instead (again, if they are available). 661 </p> 662 <p> 663 In this default case, the region files are named 664 <tt class="literal">__db.###</tt> 665 (for example, <tt class="literal">__db.001</tt>, <tt class="literal">__db.002</tt>, 666 and so on). 667 </p> 668 </div> 669 <div class="sect3" lang="en" xml:lang="en"> 670 <div class="titlepage"> 671 <div> 672 <div> 673 <h4 class="title"><a id="heapbackedregions"></a>Regions Backed by Heap Memory</h4> 674 </div> 675 </div> 676 <div></div> 677 </div> 678 <p> 679 If heap memory is used to back your shared memory regions, 680 the environment may only be 681 accessed by a single process, although that process may be 682 multi-threaded. In this case, the regions are managed only in 683 memory, and they are not written to the filesystem. You 684 indicate that heap memory is to be used for the region files by 685 specifying 686 <span> 687 <tt class="literal">DB_PRIVATE</tt> to the 688 <tt class="methodname">DB_ENV->open()</tt> 689 690 method. 691 </span> 692 693 694 695 </p> 696 <p> 697 (For an example of an entirely in-memory transactional 698 application, see 699 <span> 700 <a href="inmem_txnexample_c.html">In-Memory Transaction Example</a>.) 701 </span> 702 703 704 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="systembackedregions"></a>Regions Backed by System Memory</h4> 712 </div> 713 </div> 714 <div></div> 715 </div> 716 <p> 717 Finally, you can cause system memory to be used for your 718 regions instead of memory-mapped files. You do this by providing 719 <span> 720 <tt class="literal">DB_SYSTEM_MEM</tt> to the 721 <tt class="methodname">DB_ENV->open()</tt> 722 723 method. 724 </span> 725 726 727 </p> 728 <p> 729 When region files are backed by system memory, DB creates a 730 single file in the environment's home directory. This file 731 contains information necessary to identify the system shared 732 memory in use by the environment. By creating this file, DB 733 enables multiple processes to share the environment. 734 </p> 735 <p> 736 The system memory that is used is architecture-dependent. For 737 example, on systems supporting X/Open-style shared memory 738 interfaces, such as UNIX systems, the <tt class="literal">shmget(2)</tt> 739 and related System V IPC interfaces are used. 740 741 <span> 742 743 Additionally, VxWorks systems use system memory. In these cases, 744 an initial segment ID must be specified by the application to 745 ensure that applications do not overwrite each other's 746 environments, so that the number of segments created does not 747 grow without bounds. See the 748 749 <tt class="methodname">DB_ENV->set_shm_key()</tt> 750 751 752 method for more information. 753 </span> 754 </p> 755 <p> 756 On Windows platforms, the use of system memory for the region files 757 is problematic because the operating system uses reference counting 758 to clean up shared objects in the paging file automatically. In 759 addition, the default access permissions for shared objects are 760 different from files, which may cause problems when an environment 761 is accessed by multiple processes running as different users. See 762 <a href="" target="_top">Windows notes</a> 763 or more information. 764 </p> 765 </div> 766 </div> 767 <div class="sect2" lang="en" xml:lang="en"> 768 <div class="titlepage"> 769 <div> 770 <div> 771 <h3 class="title"><a id="security"></a>Security Considerations</h3> 772 </div> 773 </div> 774 <div></div> 775 </div> 776 <p> 777 When using environments, there are some security considerations to 778 keep in mind: 779 </p> 780 <div class="itemizedlist"> 781 <ul type="disc"> 782 <li> 783 <p> 784 Database environment permissions 785 </p> 786 <p> 787 The directory used for the environment 788 should have its permissions set to ensure that files in the 789 environment are not accessible to users without appropriate 790 permissions. Applications that add to the user's permissions 791 (for example, UNIX <tt class="literal">setuid</tt> or 792 <tt class="literal">setgid</tt> applications), must be 793 carefully checked to not permit illegal use of those 794 permissions such as general file access in the environment 795 directory. 796 </p> 797 </li> 798 <li> 799 <p> 800 Environment variables 801 </p> 802 <p> 803 Setting 804 805 <span> 806 the <tt class="literal">DB_USE_ENVIRON</tt> or 807 <tt class="literal">DB_USE_ENVIRON_ROOT</tt> flags 808 </span> 809 810 811 so that environment variables can be used during file naming 812 can be dangerous. Setting those flags in DB 813 applications with additional permissions (for example, UNIX 814 <tt class="literal">setuid</tt> or <tt class="literal">setgid</tt> 815 applications) could potentially allow users 816 to read and write databases to which they would not normally 817 have access. 818 </p> 819 <p> 820 For example, suppose you write a DB application 821 that runs <tt class="literal">setuid</tt>. This means that 822 when the application runs, it does so under a 823 userid different than that of the application's caller. 824 This is especially problematic if the application is 825 granting stronger privileges to a user than the user 826 might ordinarily have. 827 </p> 828 <p> 829 Now, if 830 <span> 831 the <tt class="literal">DB_USE_ENVIRON</tt> or 832 <tt class="literal">DB_USE_ENVIRON_ROOT</tt> flags 833 are set for the environment, 834 </span> 835 836 837 838 then the environment that the application is 839 using is modifiable using the 840 <tt class="literal">DB_HOME</tt> environment variable. In 841 this scenario, if the uid used by the application has 842 sufficiently broad privileges, then the application's caller 843 can read and/or write databases owned by another user 844 simply by setting his 845 <tt class="literal">DB_HOME</tt> environment variable to the 846 environment used by that other user. 847 </p> 848 <p> 849 Note that this scenario need not be malicious; the 850 wrong environment could be used by the application 851 simply by inadvertently specifying the wrong path to 852 <tt class="literal">DB_HOME</tt>. 853 </p> 854 <p> 855 As always, you should use <tt class="literal">setuid</tt> 856 sparingly, if at all. But if you do use 857 <tt class="literal">setuid</tt>, then you should refrain from 858 specifying 859 <span> 860 the <tt class="literal">DB_USE_ENVIRON</tt> or 861 <tt class="literal">DB_USE_ENVIRON_ROOT</tt> flags 862 </span> 863 864 for the environment open. And, of course, if you must 865 use <tt class="literal">setuid</tt>, then make sure you use 866 the weakest uid possible – preferably one that is 867 used only by the application itself. 868 </p> 869 </li> 870 <li> 871 <p> 872 File permissions 873 </p> 874 <p> 875 By default, DB always creates database and log files readable and 876 writable by the owner and the group (that is, 877 <tt class="literal">S_IRUSR</tt>, 878 <tt class="literal">S_IWUSR</tt>, <tt class="literal">S_IRGRP</tt> and 879 <tt class="literal">S_IWGRP</tt>; or octal mode 0660 on historic 880 UNIX systems). The group ownership of created files is based 881 on the system and directory defaults, and is not further 882 specified by DB. 883 </p> 884 </li> 885 <li> 886 <p> 887 Temporary backing files 888 </p> 889 <p> 890 If an unnamed database is created and the cache is too small 891 to hold the database in memory, Berkeley DB will create a 892 temporary physical file to enable it to page the database to 893 disk as needed. In this case, environment variables such as 894 <tt class="literal">TMPDIR</tt> may be used to specify the 895 location of that temporary file. Although temporary backing 896 files are created readable and writable by the owner only 897 (<tt class="literal">S_IRUSR</tt> and <tt class="literal">S_IWUSR</tt>, 898 or octal mode 0600 on historic UNIX systems), some 899 filesystems may not sufficiently protect temporary files 900 created in random directories from improper access. To be 901 absolutely safe, applications storing sensitive data in 902 unnamed databases should use the 903 <tt class="methodname">DB_ENV->set_tmp_dir()</tt> 904 905 906 method to specify a temporary directory with known permissions. 907 </p> 908 </li> 909 </ul> 910 </div> 911 </div> 912 </div> 913 </div> 914 <div class="navfooter"> 915 <hr /> 916 <table width="100%" summary="Navigation footer"> 917 <tr> 918 <td width="40%" align="left"><a accesskey="p" href="perftune-intro.html">Prev</a> </td> 919 <td width="20%" align="center"> 920 <a accesskey="u" href="index.html">Up</a> 921 </td> 922 <td width="40%" align="right"> <a accesskey="n" href="envopen.html">Next</a></td> 923 </tr> 924 <tr> 925 <td width="40%" align="left" valign="top">Performance Tuning </td> 926 <td width="20%" align="center"> 927 <a accesskey="h" href="index.html">Home</a> 928 </td> 929 <td width="40%" align="right" valign="top"> Opening a Transactional Environment and 930 Database 931 932 933 </td> 934 </tr> 935 </table> 936 </div> 937 </body> 938</html> 939