doc/man/ovdb.5

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  31 .\" nothing in troff, for use with C<>.
  32 .tr \(*W-
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "OVDB 5"
 132 .TH OVDB 5 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation"
 133 .SH "NAME"
 134 ovdb \- Overview storage method for INN
 135 .SH "DESCRIPTION"
 136 .IX Header "DESCRIPTION"
 137 Ovdb is a storage method that uses the BerkeleyDB library to store
 138 overview data.  It requires version 2.6.x or later of the BerkeleyDB
 139 library, but has mostly been tested with version 3 and 4.
 140 .PP
 141 Ovdb makes use of the full transaction/logging/locking functionality of
 142 the BerkeleyDB environment.  BerkeleyDB may be downloaded from
 143 <http://www.sleepycat.com> and is needed to build the ovdb backend.
 144 .SH "UPGRADING"
 145 .IX Header "UPGRADING"
 146 This is version 2 of ovdb.  If you have a database created with a previous
 147 version of ovdb (such as the one shipped with \s-1INN\s0 2.3.0) your database
 148 will need to be upgraded using \fIovdb_init\fR\|(8).  See the man page
 149 \&\fIovdb_init\fR\|(8) for upgrade instructions.
 150 .SH "INSTALLATION"
 151 .IX Header "INSTALLATION"
 152 To build ovdb support into \s-1INN\s0, specify the option \f(CW\*(C`\-\-with\-berkeleydb\*(C'\fR
 153 when running the configure script.  By default, configure will search for
 154 a BerkeleyDB tree in several likely locations, and choose the highest
 155 version (based on the name of the directory, e.g., \fIBerkeleyDB.3.0\fR) that
 156 it finds.  There will be a message in the configure output indicating the
 157 chosen pathname.
 158 .PP
 159 You can override this pathname by adding a path to the option, e.g.,
 160 \&\f(CW\*(C`\-\-with\-berkeleydb=/usr/BerkeleyDB.3.1\*(C'\fR.  This directory is expected to
 161 have subdirectories \fIinclude\fR and \fIlib\fR, containing \fIdb.h\fR, and the
 162 library itself, respectively.
 163 .PP
 164 The ovdb database will take up more disk space for a given spool than the
 165 other overview methods.  Plan on needing at least 1.1 \s-1KB\s0 for every article
 166 in your spool (not counting crossposts).  So, if you have 5 million
 167 articles, you'll need at least 5.5 \s-1GB\s0 of disk space for ovdb.  With
 168 BerkeleyDB 2.x, the db files are 'grow only'; the library will not shrink
 169 them, even if data is removed.  So, reserving extra space above the
 170 estimate is a good idea.  Plus, you'll need additional space for
 171 transaction logs: at least 100 \s-1MB\s0.  By default the transaction logs go in
 172 the same directory as the database.  To improve performance, they can be
 173 placed on a different disk \*(-- see the \s-1DB_CONFIG\s0 section.
 174 .SH "CONFIGURATION"
 175 .IX Header "CONFIGURATION"
 176 To enable ovdb, set the \fIovmethod\fR parameter in \fIinn.conf\fR to \f(CW\*(C`ovdb\*(C'\fR.
 177 The ovdb database is stored in the directory specified by the
 178 \&\fIpathoverview\fR paramter in \fIinn.conf\fR.  This is the \*(L"\s-1DB_HOME\s0\*(R" directory.
 179 To start out, this directory should be empty (other than an optional
 180 \&\fI\s-1DB_CONFIG\s0\fR file; see \s-1DB_CONFIG\s0 for details) and \fBinnd\fR (or
 181 \&\fBmakehistory\fR) will create the files as necessary in that directory.
 182 Make sure the directory is owned by the news user.
 183 .PP
 184 Other parameters for configuring ovdb are in the \fIovdb.conf\fR\|(5)
 185 configuration file.  See also the sample \fIovdb.conf\fR.
 186 .IP "cachesize" 4
 187 .IX Item "cachesize"
 188 Size of the memory pool cache, in kilobytes.  The cache will have a
 189 backing store file in the \s-1DB\s0 directory which will be at least as big.  In
 190 general, the bigger the cache, the better.  Use \f(CW\*(C`ovdb_stat \-m\*(C'\fR to see
 191 cache hit percentages.  To make a change of this parameter take effect,
 192 shut down and restart \s-1INN\s0 (be sure to kill all of the nnrpds when shutting
 193 down).  Default is 8000, which is adequate for small to medium sized
 194 servers.  Large servers will probably need at least 20000.
 195 .IP "numdbfiles" 4
 196 .IX Item "numdbfiles"
 197 Overview data is split between this many files.  Currently, \fBinnd\fR will
 198 keep all of the files open, so don't set this too high or \fBinnd\fR may run
 199 out of file descriptors.  \fBnnrpd\fR only opens one at a time, regardless.
 200 May be set to one, or just a few, but only do that if your \s-1OS\s0 supports
 201 large (>2G) files.  Changing this parameter has no effect on an
 202 already-established database.  Default is 32.
 203 .IP "txn_nosync" 4
 204 .IX Item "txn_nosync"
 205 If txn_nosync is set to false, BerkeleyDB flushes the log after every
 206 transaction.  This minimizes the number of transactions that may be lost
 207 in the event of a crash, but results in significantly degraded
 208 performance.  Default is true.
 209 .IP "useshm" 4
 210 .IX Item "useshm"
 211 If useshm is set to true, BerkeleyDB will use shared memory instead of
 212 mmap for its environment regions (cache, lock, etc).  With some platforms,
 213 this may improve performance.  Default is false.  This parameter is
 214 ignored if you have BerkeleyDB 2.x
 215 .IP "shmkey" 4
 216 .IX Item "shmkey"
 217 Sets the shared memory key used by BerkeleyDB when 'useshm' is true.
 218 BerkeleyDB will create several (usually 5) shared memory segments, using
 219 sequentially numbered keys starting with 'shmkey'.  Choose a key that does
 220 not conflict with any existing shared memory segments on your system.
 221 Default is 6400.  This parameter is only used with BerkeleyDB 3.1 or
 222 newer.
 223 .IP "pagesize" 4
 224 .IX Item "pagesize"
 225 Sets the page size for the \s-1DB\s0 files (in bytes).  Must be a power of 2.
 226 Best choices are 4096 or 8192.  The default is 8192.  Changing this
 227 parameter has no effect on an already-established database.
 228 .IP "minkey" 4
 229 .IX Item "minkey"
 230 Sets the minimum number of keys per page.  See the BerkeleyDB
 231 documentation for more info.  Default is based on page size:
 232 .Sp
 233 .Vb 1
 234 \&   default_minkey = MAX(2, pagesize / 2048 \- 1)
 235 .Ve
 236 .Sp
 237 The lowest allowed minkey is 2.  Setting minkey higher than the default is
 238 not recommended, as it will cause the databases to have a lot of overflow
 239 pages.  Changing this parameter has no effect on an already-established
 240 database.
 241 .IP "maxlocks" 4
 242 .IX Item "maxlocks"
 243 Sets the BerkeleyDB \*(L"lk_max\*(R" parameter, which is the maxmium number of
 244 locks that can exist in the database at the same time.  Default is 4000.
 245 .IP "nocompact" 4
 246 .IX Item "nocompact"
 247 The nocompact parameter affects expireover's behavior.  The expireover
 248 function in ovdb can do its job in one of two ways:  by simply deleting
 249 expired records from the database, or by re-writing the overview records
 250 into a different location leaving out the expired records.  The first
 251 method is faster, but it leaves 'holes' that result in space that can not
 252 immediately be reused.  The second method 'compacts' the records by
 253 rewriting them.
 254 .Sp
 255 If this parameter is set to 0, expireover will compact all newsgroups; if
 256 set to 1, expireover will not compact any newsgroups; and if set to a
 257 value greater than one, expireover will only compact groups that have less
 258 than that number of articles.
 259 .Sp
 260 Experience has shown that compacting has minimal effect (other than
 261 making expireover take longer) so the default is now 1.  This parameter
 262 will probably be removed in the future.
 263 .IP "readserver" 4
 264 .IX Item "readserver"
 265 Normally, each nnrpd process directly accesses the BerkeleyDB environment.
 266 The process of attaching to the database (and detaching when finished) is
 267 fairly expensive, and can result in high loads in situations when there
 268 are lots of reader connections of relatively short duration.
 269 .Sp
 270 When the readserver parameter is \*(L"true\*(R", the nnrpds will access overview
 271 via a helper server (\fBovdb_server\fR \*(-- which is started by \fBovdb_init\fR).
 272 This can also result in cleaner shutdowns for the database, improving
 273 stability and avoiding deadlocks and corrupted databases.  If you are
 274 experiencing any instability in ovdb, try setting this parameter to true.
 275 Default is false.
 276 .IP "numrsprocs" 4
 277 .IX Item "numrsprocs"
 278 This parameter is only used when \fIreadserver\fR is true.  It sets the
 279 number of ovdb_server processes.  As each ovdb_server can process only one
 280 transaction at a time, running more servers can improve reader response
 281 times.  Default is 5.
 282 .IP "maxrsconn" 4
 283 .IX Item "maxrsconn"
 284 This parameter is only used when \fIreadserver\fR is true.  It sets a maximum
 285 number of readers that a given ovdb_server process will serve at one time.
 286 This means the maximum number of readers for all of the ovdb_server
 287 processes is (numrsprocs * maxrsconn).  Default is 0, which means an
 288 umlimited number of connections is allowed.
 289 .SH "DB_CONFIG"
 290 .IX Header "DB_CONFIG"
 291 A file called \fI\s-1DB_CONFIG\s0\fR may be placed in the database directory to
 292 customize where the various database files and transaction logs are
 293 written.  By default, all of the files are written in the \*(L"\s-1DB_HOME\s0\*(R"
 294 directory.  One way to improve performance is to put the transaction logs
 295 on a different disk.  To do this, put:
 296 .PP
 297 .Vb 1
 298 \&    DB_LOG_DIR /path/to/logs
 299 .Ve
 300 .PP
 301 in the \fI\s-1DB_CONFIG\s0\fR file.  If the pathname you give starts with a /, it is
 302 treated as an absolute path; otherwise, it is relative to the \*(L"\s-1DB_HOME\s0\*(R"
 303 directory.  Make sure that any directories you specify exist and have
 304 proper ownership/mode before starting \s-1INN\s0, because they won't be created
 305 automatically.  Also, don't change the \s-1DB_CONFIG\s0 file while anything that
 306 uses ovdb is running.
 307 .PP
 308 Another thing that you can do with this file is to split the overview
 309 database across multiple disks.  In the \fI\s-1DB_CONFIG\s0\fR file, you can list
 310 directories that BerkeleyDB will search when it goes to open a database.
 311 .PP
 312 For example, let's say that you have \fIpathoverview\fR set to
 313 \&\fI/mnt/overview\fR and you have four additional file systems created on
 314 \&\fI/mnt/ov?\fR.  You would create a file \*(L"/mnt/overview/DB_CONFIG\*(R" containing
 315 the following lines:
 316 .PP
 317 .Vb 5
 318 \&    set_data_dir /mnt/overview
 319 \&    set_data_dir /mnt/ov1
 320 \&    set_data_dir /mnt/ov2
 321 \&    set_data_dir /mnt/ov3
 322 \&    set_data_dir /mnt/ov4
 323 .Ve
 324 .PP
 325 (For BerkeleyDB 2.x, replace \f(CW\*(C`set_data_dir\*(C'\fR with \f(CW\*(C`DB_DATA_DIR\*(C'\fR.)
 326 .PP
 327 Distribute your ovNNNNN files into the four filesystems.  (say, 8 each).
 328 When called upon to open a database file, the db library will look for it
 329 in each of the specified directories (in order).  If said file is not
 330 found, one will be created in the first of those directories.
 331 .PP
 332 Whenever you change \s-1DB_CONFIG\s0 or move database files around, make sure all
 333 news processes that use the database are shut down first (including
 334 nnrpds).
 335 .PP
 336 The \s-1DB_CONFIG\s0 functionality is part of BerkeleyDB itself, rather than
 337 something provided by ovdb.  See the BerkeleyDB documentation for complete
 338 details for the version of BerkeleyDB that you're running.
 339 .SH "RUNNING"
 340 .IX Header "RUNNING"
 341 When starting the news system, \fBrc.news\fR will invoke \fBovdb_init\fR.
 342 \&\fBovdb_init\fR must be run before using the database.  It performs the
 343 following tasks:
 344 .IP "\(bu" 4
 345 Creates the database environment, if necessary.
 346 .IP "\(bu" 4
 347 If the database is idle, it performs a normal recovery.  The recovery will
 348 remove stale locks, recreate the memory pool cache, and repair any damage
 349 caused by a system crash or improper shutdown.
 350 .IP "\(bu" 4
 351 Starts the \s-1DB\s0 housekeeping processes (\fBovdb_monitor\fR) if they're not
 352 already running.
 353 .PP
 354 And when stopping \s-1INN\s0, \fBrc.news\fR kills the ovdb_monitor processes after
 355 the other \s-1INN\s0 processes have been shut down.
 356 .SH "DIAGNOSTICS"
 357 .IX Header "DIAGNOSTICS"
 358 Problems relating to ovdb are logged to news.err with \*(L"\s-1OVDB\s0\*(R" in the error
 359 message.
 360 .PP
 361 \&\s-1INN\s0 programs that use overview will fail to start up if the ovdb_monitor
 362 processes aren't running.  Be sure to run \fBovdb_init\fR before running
 363 anything that accesses overview.
 364 .PP
 365 Also, \s-1INN\s0 programs that use overview will fail to start up if the user
 366 running them is not the \*(L"news\*(R" user.
 367 .PP
 368 If a program accessing the database crashes, or otherwise exits uncleanly,
 369 it might leave a stale lock in the database.  This lock could cause other
 370 processes to deadlock on that stale lock.  To fix this, shut down all news
 371 processes (using \f(CW\*(C`kill \-9\*(C'\fR if necessary) and then restart.  \fBovdb_init\fR
 372 should perform a recovery operation which will remove the locks and repair
 373 damage caused by killing the deadlocked processes.
 374 .SH "FILES"
 375 .IX Header "FILES"
 376 .IP "inn.conf" 4
 377 .IX Item "inn.conf"
 378 The \fIovmethod\fR and \fIpathoverview\fR parameters are relevant to ovdb.
 379 .IP "ovdb.conf" 4
 380 .IX Item "ovdb.conf"
 381 Optional configuration file for tuning.  See \s-1CONFIGURATION\s0 above.
 382 .IP "\fIpathoverview\fR" 4
 383 .IX Item "pathoverview"
 384 Directory where the database goes.  BerkeleyDB calls it the '\s-1DB_HOME\s0'
 385 directory.
 386 .IP "\fIpathoverview\fR/DB_CONFIG" 4
 387 .IX Item "pathoverview/DB_CONFIG"
 388 Optional file to configure the layout of the database files.
 389 .IP "\fIpathrun\fR/ovdb.sem" 4
 390 .IX Item "pathrun/ovdb.sem"
 391 A file that gets locked by every process that is accessing the database.
 392 This is used by \fBovdb_init\fR to determine whether the database is active
 393 or quiescent.
 394 .IP "\fIpathrun\fR/ovdb_monitor.pid" 4
 395 .IX Item "pathrun/ovdb_monitor.pid"
 396 Contains the process \s-1ID\s0 of \fBovdb_monitor\fR.
 397 .SH "TO DO"
 398 .IX Header "TO DO"
 399 Implement a way to limit how many databases can be open at once (to reduce
 400 file descriptor usage); maybe using something similar to the cache code in
 401 ov3.c
 402 .SH "HISTORY"
 403 .IX Header "HISTORY"
 404 Written by Heath Kehoe <hakehoe@avalon.net> for InterNetNews
 405 .SH "SEE ALSO"
 406 .IX Header "SEE ALSO"
 407 \&\fIinn.conf\fR\|(5), \fIinnd\fR\|(8), \fInnrpd\fR\|(8), \fIovdb_init\fR\|(8), \fIovdb_monitor\fR\|(8),
 408 \&\fIovdb_stat\fR\|(8)
 409 .PP
 410 BerkeleyDB documentation: in the \fIdocs\fR directory of the BerkeleyDB
 411 source distribution, or on the Sleepycat web page:
 412 <http://www.sleepycat.com/>.