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 Store or 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 74 <span>Store or Database</span> 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 <span> 98 You do this by using the 99 <code class="methodname">EnvironmentConfig.setTransactional()</code> 100 method. 101 </span> 102 103 104 105 <span> 106 Note that initializing the transactional subsystem implies that 107 the logging subsystem is also initialized. Also, note that 108 if you do not initialize transactions when you first create 109 your environment, then you cannot use transactions for that 110 environment after that. This is because DB 111 allocates certain structures needed for transactional 112 locking that are not available if the environment is 113 created without transactional support. 114 </span> 115 </p> 116 </li> 117 <li> 118 <p> 119 Initialize the in-memory cache by 120 121 122 <span> 123 passing <code class="literal">true</code> to the 124 <code class="methodname">EnvironmentConfig.setInitializeCache()</code> 125 method. 126 </span> 127 </p> 128 </li> 129 <li> 130 <p> 131 Initialize the locking subsystem. This is what provides locking for concurrent applications. It also is used 132 to perform deadlock detection. See <a class="xref" href="txnconcurrency.html" title="Chapter 4. Concurrency">Concurrency</a> 133 for more information. 134 </p> 135 <p> 136 You initialize the locking subsystem by 137 138 139 <span> 140 passing <code class="literal">true</code> to the 141 <code class="methodname">EnvironmentConfig.setInitializeLocking()</code> 142 method. 143 </span> 144 </p> 145 </li> 146 <li> 147 <p> 148 If you are using the DPL, transaction-enable your stores. 149 You do this by using the 150 <code class="methodname">StoreConfig.setTransactional() method.</code> 151 </p> 152 </li> 153 <li> 154 <p> 155 <span> 156 Transaction-enable your databases. 157 </span> 158 <span> 159 If you are using the base API, transaction-enable your databases. 160 </span> 161 You do this by 162 <span> 163 using the 164 <code class="methodname">DatabaseConfig.setTransactional()</code> 165 method, and then opening the database from within a transaction. 166 </span> 167 168 169 170 171 <span> 172 Note that the common practice is for auto commit to be used to 173 transaction-protect the database open. To use auto-commit, you 174 must still enable transactions as described here, but you do 175 not have to explicitly use a transaction when you open your 176 database. An example of this is given in the next section. 177 </span> 178 </p> 179 </li> 180 </ul> 181 </div> 182 <div class="sect1" lang="en" xml:lang="en"> 183 <div class="titlepage"> 184 <div> 185 <div> 186 <h2 class="title" style="clear: both"><a id="environments"></a>Environments</h2> 187 </div> 188 </div> 189 </div> 190 <div class="toc"> 191 <dl> 192 <dt> 193 <span class="sect2"> 194 <a href="enabletxn.html#filenaming">File Naming</a> 195 </span> 196 </dt> 197 <dt> 198 <span class="sect2"> 199 <a href="enabletxn.html#errorsupport">Error Support</a> 200 </span> 201 </dt> 202 <dt> 203 <span class="sect2"> 204 <a href="enabletxn.html#sharedmemory">Shared Memory Regions</a> 205 </span> 206 </dt> 207 <dt> 208 <span class="sect2"> 209 <a href="enabletxn.html#security">Security Considerations</a> 210 </span> 211 </dt> 212 </dl> 213 </div> 214 <p> 215 For simple DB applications, environments are optional. However, in 216 order to transaction protect your database operations, you must use an 217 environment. 218 </p> 219 <p> 220 An <span class="emphasis"><em>environment</em></span>, represents an 221 encapsulation of one or more databases and any associated log and 222 region files. They are used to support multi-threaded 223 and multi-process applications by allowing different threads of 224 control to share the in-memory cache, the locking tables, the 225 logging subsystem, and the file namespace. By sharing these things, 226 your concurrent application is more efficient than if each thread 227 of control had to manage these resources on its own. 228 </p> 229 <p> 230 By default all DB databases are backed by files on disk. In 231 addition to these files, transactional DB applications create 232 logs that are also by default stored on disk (they can optionally 233 be backed using shared memory). Finally, transactional 234 DB applications also create and use shared-memory regions that 235 are also typically backed by the filesystem. But like databases and 236 logs, the regions can be maintained strictly in-memory if your 237 application requires it. For an example of an application that 238 manages all environment files in-memory, see 239 240 <span><a class="xref" href="inmem_txnexample_java.html" title="Base API In-Memory Transaction Example">Base API In-Memory Transaction Example</a>.</span> 241 242 243 </p> 244 <div class="sect2" lang="en" xml:lang="en"> 245 <div class="titlepage"> 246 <div> 247 <div> 248 <h3 class="title"><a id="filenaming"></a>File Naming</h3> 249 </div> 250 </div> 251 </div> 252 <p> 253 In order to operate, your DB application must be able to 254 locate its database files, log files, and region files. If these 255 are stored in the filesystem, then you must tell DB where 256 they are located (a number of mechanisms exist that allow you to 257 identify the location of these files – see below). Otherwise, 258 by default they are located in the current working directory. 259 </p> 260 <div class="sect3" lang="en" xml:lang="en"> 261 <div class="titlepage"> 262 <div> 263 <div> 264 <h4 class="title"><a id="envhome"></a>Specifying the Environment Home Directory</h4> 265 </div> 266 </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 288 <code class="methodname">Environment()</code> 289 290 <span>constructor,</span> 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 300 <span><code class="methodname">Environment()</code>, </span> 301 then the directory identified by the <code class="literal">DB_HOME</code> environment variable 302 is used <span class="emphasis"><em>if</em></span> you specify 303 304 305 <span> 306 <code class="literal">true</code> to either the 307 <code class="methodname">EnvironmentConfig.setUseEnvironment()</code> 308 or 309 <code class="methodname">EnvironmentConfig.setUseEnvironmentRoot()</code> 310 method. Both methods allow you to identify the 311 path to the environment's home directory 312 using <code class="literal">DB_HOME</code>. However, 313 <code class="methodname">EnvironmentConfig.setUseEnvironmentRoot()</code> 314 is honored only if the process is run with root or administrative privileges. 315 </span> 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> 329 <p> 330 By default, all DB files are created relative to the environment 331 home directory. For example, suppose your environment home is in 332 <code class="literal">/export/myAppHome</code>. Also suppose you name your database 333 <span><code class="literal">data/myDatabase.db</code>.</span> 334 335 Then in this case, the database is placed in: 336 <span><code class="literal">/export/myAppHome/data/myDatabase.db</code>.</span> 337 338 </p> 339 <p> 340 That said, DB always defers to absolute pathnames. 341 This means that if you provide an absolute filename when you 342 name your database, then that file is <span class="emphasis"><em>not</em></span> 343 placed relative to the environment home directory. Instead, it 344 is placed in the exact location that you specified for the 345 filename. 346 </p> 347 <p> 348 On UNIX systems, an absolute pathname is a name that begins with a 349 forward slash ('/'). On Windows systems, an absolute pathname is a 350 name that begins with one of the following: 351 </p> 352 <div class="itemizedlist"> 353 <ul type="disc"> 354 <li> 355 <p> 356 A backslash ('\'). 357 </p> 358 </li> 359 <li> 360 <p> 361 Any alphabetic letter, followed by a colon (':'), followed 362 by a backslash ('\'). 363 </p> 364 </li> 365 </ul> 366 </div> 367 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 368 <h3 class="title">Note</h3> 369 <p> 370 Try not to use absolute path names for your environment's 371 files. Under certain recovery scenarios, absolute path 372 names can render your environment unrecoverable. This 373 occurs if you are attempting to recover your environment on 374 a system that does not support the absolute path name that 375 you used. 376 </p> 377 </div> 378 </div> 379 <div class="sect3" lang="en" xml:lang="en"> 380 <div class="titlepage"> 381 <div> 382 <div> 383 <h4 class="title"><a id="splittingdata"></a>Identifying Specific File Locations</h4> 384 </div> 385 </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 431 <code class="methodname">EnvironmentConfig.addDataDir()</code> 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 440 <p> 441 This method modifies the directory 442 used for database files created and managed by 443 a single environment handle; it does not 444 configure the entire environment. 445 446 </p> 447 448 <p> 449 You can also set a default data location that is used by 450 the entire environment by using the 451 <code class="literal">set_data_dir</code> parameter 452 in the environment's <code class="literal">DB_CONFIG</code> file. 453 Note that the <code class="literal">set_data_dir</code> 454 parameter overrides any value set by the 455 456 457 <code class="methodname">EnvironmentConfig.addDataDir()</code> 458 method. 459 </p> 460 </td> 461 </tr> 462 <tr> 463 <td>Log files</td> 464 <td> 465 <p> 466 You can cause log files to be created 467 in a directory other than the environment home 468 directory by using the 469 470 471 <code class="methodname">EnvironmentConfig.LogDirectory()</code> 472 method. The directory identified 473 here must exist. If a relative path is 474 provided, then the directory location is 475 resolved relative to the environment's home 476 directory. 477 </p> 478 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 485 </p> 486 487 <p> 488 You can also set a default log file location that is used by 489 the entire environment by using the 490 <code class="literal">set_lg_dir</code> parameter 491 in the environment's <code class="literal">DB_CONFIG</code> file. 492 Note that the <code class="literal">set_lg_dir</code> 493 parameter overrides any value set by the 494 495 496 <code class="methodname">EnvironmentConfig.LogDirectory()</code> 497 method. 498 </p> 499 </td> 500 </tr> 501 <tr> 502 <td>Region files</td> 503 <td> 504 If backed by the filesystem, region 505 files are always placed in the environment home 506 directory. 507 </td> 508 </tr> 509 </tbody> 510 </table> 511 </div> 512 <p> 513 Note that the <code class="literal">DB_CONFIG</code> must reside in the 514 environment home directory. Parameters are specified in it one 515 parameter to a line. Each parameter is followed by a space, 516 which is followed by the parameter value. For example: 517 </p> 518 <pre class="programlisting"> set_data_dir /export1/db/env_data_files </pre> 519 </div> 520 </div> 521 <div class="sect2" lang="en" xml:lang="en"> 522 <div class="titlepage"> 523 <div> 524 <div> 525 <h3 class="title"><a id="errorsupport"></a>Error Support</h3> 526 </div> 527 </div> 528 </div> 529 <p> 530 To simplify error handling and to aid in application debugging, environments offer several useful 531 methods. 532 533 <span>Note that many of these 534 methods are identical to the error handling methods available for the 535 536 537 <span>DatabaseConfig</span> 538 539 <span>class.</span> 540 541 </span> 542 543 They are: 544 </p> 545 <div class="itemizedlist"> 546 <ul type="disc"> 547 <li> 548 <p> 549 550 <code class="methodname">EnvironmentConfig.setErrorStream()</code> 551 </p> 552 <p> 553 Sets the 554 555 <span>Java <code class="classname">OutputStream</code></span> 556 to be used for displaying error messages issued by the DB library. 557 </p> 558 </li> 559 <li> 560 <p> 561 562 <code class="methodname">EnvironmentConfig.setErrorHandler()</code> 563 </p> 564 <p> 565 Defines the message handler that is called when an error message is 566 issued by DB. The error prefix and message are passed to 567 this callback. It is up to the application to display this 568 information correctly. 569 </p> 570 <p> 571 Note that the message handler must be an implementation of the 572 <code class="classname">com.sleepycat.db.ErrorHandler</code> 573 interface. 574 </p> 575 <p> 576 This is the recommended way to get error messages from 577 DB. 578 </p> 579 </li> 580 <li> 581 <p> 582 583 <code class="methodname">EnvironmentConfig.setErrorPrefix()</code> 584 </p> 585 <p> 586 Sets the prefix used to for any error messages issued by the 587 DB library. 588 </p> 589 </li> 590 </ul> 591 </div> 592 </div> 593 <div class="sect2" lang="en" xml:lang="en"> 594 <div class="titlepage"> 595 <div> 596 <div> 597 <h3 class="title"><a id="sharedmemory"></a>Shared Memory Regions</h3> 598 </div> 599 </div> 600 </div> 601 <p> 602 The subsystems that you enable for an environment (in our case, 603 transaction, logging, locking, and the memory pool) 604 are described by one or more regions. The regions contain all of the 605 state information that needs to be shared among threads and/or 606 processes using the environment. 607 </p> 608 <p> 609 Regions may be backed by the file system, by heap memory, or by 610 system shared memory. 611 </p> 612 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 613 <h3 class="title">Note</h3> 614 <p> 615 When DB dynamically obtains memory, it uses memory outside of the JVM. Normally the amount of memory 616 that DB obtains is trivial, a few bytes here and there, so you might not notice it. However, if 617 heap or system memory is used to back your region files, then this can represent a significant amount of 618 memory being used by DB above and beyond the memory required by the JVM process. As a result, the 619 JVM process may appear to be using more memory than you told the process it could use. 620 </p> 621 </div> 622 <div class="sect3" lang="en" xml:lang="en"> 623 <div class="titlepage"> 624 <div> 625 <div> 626 <h4 class="title"><a id="filebackedregions"></a>Regions Backed by Files</h4> 627 </div> 628 </div> 629 </div> 630 <p> 631 By default, shared memory regions are created as files in the environment's 632 home directory (<span class="emphasis"><em>not</em></span> the environment's data 633 directory). If it is available, the POSIX <code class="literal">mmap</code> 634 interface is used to map these files into your application's 635 address space. If <code class="literal">mmap</code> 636 is not available, then the UNIX <code class="literal">shmget</code> interfaces 637 are used instead (again, if they are available). 638 </p> 639 <p> 640 In this default case, the region files are named 641 <code class="literal">__db.###</code> 642 (for example, <code class="literal">__db.001</code>, <code class="literal">__db.002</code>, 643 and so on). 644 </p> 645 </div> 646 <div class="sect3" lang="en" xml:lang="en"> 647 <div class="titlepage"> 648 <div> 649 <div> 650 <h4 class="title"><a id="heapbackedregions"></a>Regions Backed by Heap Memory</h4> 651 </div> 652 </div> 653 </div> 654 <p> 655 If heap memory is used to back your shared memory regions, 656 the environment may only be 657 accessed by a single process, although that process may be 658 multi-threaded. In this case, the regions are managed only in 659 memory, and they are not written to the filesystem. You 660 indicate that heap memory is to be used for the region files by 661 specifying 662 663 664 <span> 665 <code class="literal">true</code> to the 666 <code class="methodname">EnvironmentConfig.setPrivate()</code> 667 method. 668 </span> 669 670 </p> 671 <p> 672 (For an example of an entirely in-memory transactional 673 application, see 674 675 <span> 676 <a class="xref" href="inmem_txnexample_java.html" title="Base API In-Memory Transaction Example">Base API In-Memory Transaction Example</a>.) 677 </span> 678 679 680 </p> 681 </div> 682 <div class="sect3" lang="en" xml:lang="en"> 683 <div class="titlepage"> 684 <div> 685 <div> 686 <h4 class="title"><a id="systembackedregions"></a>Regions Backed by System Memory</h4> 687 </div> 688 </div> 689 </div> 690 <p> 691 Finally, you can cause system memory to be used for your 692 regions instead of memory-mapped files. You do this by providing 693 694 695 <span> 696 <code class="literal">true</code> to the 697 <code class="methodname">EnvironmentConfig.setSystemMemory()</code> 698 method. 699 </span> 700 </p> 701 <p> 702 When region files are backed by system memory, DB creates a 703 single file in the environment's home directory. This file 704 contains information necessary to identify the system shared 705 memory in use by the environment. By creating this file, DB 706 enables multiple processes to share the environment. 707 </p> 708 <p> 709 The system memory that is used is architecture-dependent. For 710 example, on systems supporting X/Open-style shared memory 711 interfaces, such as UNIX systems, the <code class="literal">shmget(2)</code> 712 and related System V IPC interfaces are used. 713 714 <span> 715 716 Additionally, VxWorks systems use system memory. In these cases, 717 an initial segment ID must be specified by the application to 718 ensure that applications do not overwrite each other's 719 environments, so that the number of segments created does not 720 grow without bounds. See the 721 722 723 724 <code class="methodname">EnvironmentConfig.setSegmentId()</code> 725 method for more information. 726 </span> 727 </p> 728 <p> 729 On Windows platforms, the use of system memory for the region files 730 is problematic because the operating system uses reference counting 731 to clean up shared objects in the paging file automatically. In 732 addition, the default access permissions for shared objects are 733 different from files, which may cause problems when an environment 734 is accessed by multiple processes running as different users. See 735 <a class="ulink" href="" target="_top">Windows notes</a> 736 or more information. 737 </p> 738 </div> 739 </div> 740 <div class="sect2" lang="en" xml:lang="en"> 741 <div class="titlepage"> 742 <div> 743 <div> 744 <h3 class="title"><a id="security"></a>Security Considerations</h3> 745 </div> 746 </div> 747 </div> 748 <p> 749 When using environments, there are some security considerations to 750 keep in mind: 751 </p> 752 <div class="itemizedlist"> 753 <ul type="disc"> 754 <li> 755 <p> 756 Database environment permissions 757 </p> 758 <p> 759 The directory used for the environment 760 should have its permissions set to ensure that files in the 761 environment are not accessible to users without appropriate 762 permissions. Applications that add to the user's permissions 763 (for example, UNIX <code class="literal">setuid</code> or 764 <code class="literal">setgid</code> applications), must be 765 carefully checked to not permit illegal use of those 766 permissions such as general file access in the environment 767 directory. 768 </p> 769 </li> 770 <li> 771 <p> 772 Environment variables 773 </p> 774 <p> 775 Setting 776 777 778 <span> 779 <code class="literal">true</code> for <code class="methodname">EnvironmentConfig.setUseEnvironment()</code> 780 or 781 <code class="methodname">EnvironmentConfig.setUseEnvironmentRoot()</code> 782 </span> 783 784 so that environment variables can be used during file naming 785 can be dangerous. Setting those flags in DB 786 applications with additional permissions (for example, UNIX 787 <code class="literal">setuid</code> or <code class="literal">setgid</code> 788 applications) could potentially allow users 789 to read and write databases to which they would not normally 790 have access. 791 </p> 792 <p> 793 For example, suppose you write a DB application 794 that runs <code class="literal">setuid</code>. This means that 795 when the application runs, it does so under a 796 userid different than that of the application's caller. 797 This is especially problematic if the application is 798 granting stronger privileges to a user than the user 799 might ordinarily have. 800 </p> 801 <p> 802 Now, if 803 804 <span> 805 <code class="literal">true</code> is specified 806 for <code class="methodname">EnvironmentConfig.setUseEnvironment()</code> 807 or 808 <code class="methodname">EnvironmentConfig.setUseEnvironmentRoot()</code>, 809 </span> 810 811 812 then the environment that the application is 813 using is modifiable using the 814 <code class="literal">DB_HOME</code> environment variable. In 815 this scenario, if the uid used by the application has 816 sufficiently broad privileges, then the application's caller 817 can read and/or write databases owned by another user 818 simply by setting his 819 <code class="literal">DB_HOME</code> environment variable to the 820 environment used by that other user. 821 </p> 822 <p> 823 Note that this scenario need not be malicious; the 824 wrong environment could be used by the application 825 simply by inadvertently specifying the wrong path to 826 <code class="literal">DB_HOME</code>. 827 </p> 828 <p> 829 As always, you should use <code class="literal">setuid</code> 830 sparingly, if at all. But if you do use 831 <code class="literal">setuid</code>, then you should refrain from 832 specifying 833 834 <span> 835 <code class="literal">true</code> for <code class="methodname">EnvironmentConfig.setUseEnvironment()</code> 836 or 837 <code class="methodname">EnvironmentConfig.setUseEnvironmentRoot()</code> 838 </span> 839 for the environment open. And, of course, if you must 840 use <code class="literal">setuid</code>, then make sure you use 841 the weakest uid possible – preferably one that is 842 used only by the application itself. 843 </p> 844 </li> 845 <li> 846 <p> 847 File permissions 848 </p> 849 <p> 850 By default, DB always creates database and log files readable and 851 writable by the owner and the group (that is, 852 <code class="literal">S_IRUSR</code>, 853 <code class="literal">S_IWUSR</code>, <code class="literal">S_IRGRP</code> and 854 <code class="literal">S_IWGRP</code>; or octal mode 0660 on historic 855 UNIX systems). The group ownership of created files is based 856 on the system and directory defaults, and is not further 857 specified by DB. 858 </p> 859 </li> 860 <li> 861 <p> 862 Temporary backing files 863 </p> 864 <p> 865 If an unnamed database is created and the cache is too small 866 to hold the database in memory, Berkeley DB will create a 867 temporary physical file to enable it to page the database to 868 disk as needed. In this case, environment variables such as 869 <code class="literal">TMPDIR</code> may be used to specify the 870 location of that temporary file. Although temporary backing 871 files are created readable and writable by the owner only 872 (<code class="literal">S_IRUSR</code> and <code class="literal">S_IWUSR</code>, 873 or octal mode 0600 on historic UNIX systems), some 874 filesystems may not sufficiently protect temporary files 875 created in random directories from improper access. To be 876 absolutely safe, applications storing sensitive data in 877 unnamed databases should use the 878 879 880 <code class="methodname">EnvironmentConfig.setTemporaryDirectory()</code> 881 method to specify a temporary directory with known permissions. 882 </p> 883 </li> 884 </ul> 885 </div> 886 </div> 887 </div> 888 </div> 889 <div class="navfooter"> 890 <hr /> 891 <table width="100%" summary="Navigation footer"> 892 <tr> 893 <td width="40%" align="left"><a accesskey="p" href="perftune-intro.html">Prev</a> </td> 894 <td width="20%" align="center"> </td> 895 <td width="40%" align="right"> <a accesskey="n" href="envopen.html">Next</a></td> 896 </tr> 897 <tr> 898 <td width="40%" align="left" valign="top">Performance Tuning </td> 899 <td width="20%" align="center"> 900 <a accesskey="h" href="index.html">Home</a> 901 </td> 902 <td width="40%" align="right" valign="top"> Opening a Transactional Environment and 903 904 <span>Store or Database</span> 905 906 </td> 907 </tr> 908 </table> 909 </div> 910 </body> 911</html> 912