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