site/docs/config.pod

   1 =head1 NAME
   2
   3 config.pod - documents BSE configuration file options
   4
   5 =head1 DESCRIPTION
   6
   7 BSE historically used Constants.pm to keep most configuration
   8 information.  The plan is to make sure any new configuration is kept
   9 in bse.cfg, and to slowly move most configuration information into
  10 bse.cfg.
  11
  12 Keeping configuration information in Constants.pm makes it difficult
  13 to perform upgrades and makes it impossible to use tools such as
  14 mod_perl, at least if you want more than one site on the machine.
  15
  16 =head1 CONFIGURATION ENTRIES
  17
  18 =head2 [paths]
  19
  20 Contains various file system paths.
  21
  22 =over
  23
  24 =item downloads
  25
  26 This is where the files uploads with the file wizard are stored.  It
  27 must be writable by the web server user.
  28
  29 =item admin_templates
  30
  31 Directory containing administrative templates.  Note: this is not
  32 completely implemented for now, so assume the default.  Default: admin
  33 directory under $TMPLDIR.
  34
  35 =item templates
  36
  37 Directory base for most templates.  Note: this is not completely
  38 implemented for now, so assume the default.  Default: $TMPLDIR.
  39
  40 =item images
  41
  42 Where uploaded images are stored.  This is not yet completely
  43 implemented.  Default: $IMAGEDIR.
  44
  45 =back
  46
  47 =head2 [extensions]
  48
  49 This section is used by the file wizard to map uploaded file
  50 extensions to MIME content types.  This can be used to extend
  51 BSE::FileEditor's internal extension map.  It cannot override that
  52 map.
  53
  54 The key for each entry is the extension, without the leading '.'.
  55
  56 eg.
  57
  58   xls = application/msexcel
  59
  60 =head2 [templates]
  61
  62 Used for translating symbolic template names into full names under the
  63 template directory.
  64
  65 In each case the default is the name with a C<.tmpl> extension.
  66
  67 =over
  68
  69 =item user/logon
  70
  71 user logon page
  72
  73 =item user/register
  74
  75 user registration page
  76
  77 =back
  78
  79 =head2 [admin templates]
  80
  81 Used for translating the names of administration templates into filenames.
  82
  83 In each case the default is the name with a C<.tmpl> extension.
  84
  85 =over
  86
  87 =item filelist
  88
  89 article file wizard
  90
  91 =item catalog
  92
  93 Catalog editor page.  Default admin/edit_catalog.tmpl
  94
  95 =item 1
  96
  97 =item 2
  98
  99 =item 3
 100
 101 =item 4
 102
 103 =item 5
 104
 105 Article edit pages.  Default admin/edit_<number>.tmpl
 106
 107 =item steps
 108
 109 Step child/parent management page.  Default admin/edit_steps.tmpl
 110
 111 =back
 112
 113 =head2 [html]
 114
 115 Minor html items.
 116
 117 =over
 118
 119 =item charset
 120
 121 The value of the charset keyword when outputting HTML from a script.
 122 Set to the empty string to suppress the charset keyword.  Default:
 123 iso-8859-1.
 124
 125 =back
 126
 127 =head2 [basic]
 128
 129 =over
 130
 131 =item cookie_lifetime
 132
 133 The expiry time for cookies.  This should be in the form supported by
 134 CGI.pm for the -expires parameter.  Typically you want a plus ('+'), a
 135 number, and a time character (s - seconds, m - minutes, h - hours, d -
 136 days, M - months).  Default: +3h
 137
 138 =item minpassword
 139
 140 Minimum password length in characters.  Default: 4.
 141
 142 =item randomdata
 143
 144 Device to read random data from.  This device should not block when it
 145 runs out of entropy.
 146
 147 =item sign
 148
 149 If this is true then the encrypted messages containing the customer's
 150 credit card number are sent to the shop owner signed.  To avoid
 151 keeping a passphrase and signing key on the server you can set this to
 152 false (0).  This has the effect that anyone could send you an unsigned
 153 message encrypted with your public key, though this may not be a
 154 security threat.  Default: True.
 155
 156 =item link_titles
 157
 158 If this is true then the links to your articles within BSE will be
 159 followed by a / and then by a simplified version of the article title.
 160 The aim is to include at least some title information in the URL
 161 without modifying the name of the HTML file.  Default: False.
 162
 163 =item access_control
 164
 165 If this is true then the user/group/permissions database is used to
 166 control access to the system.  Default: False.
 167
 168 =item htusers
 169
 170 This should be the path to a file to be updated with the list of users
 171 and crypt() versions of their passwords.  If this is set then the
 172 security system will check for a user set by the browser before
 173 attempting a form based logon.  Default: None.
 174
 175 =back
 176
 177 =head2 [mail]
 178
 179 This section controls how BSE sends email.
 180
 181 =over
 182
 183 =item smtp_server
 184
 185 The host or IP address of your mail server.  If this is not set
 186 C<sendmail> will be used instead.  If this is set you must also set
 187 I<helo>.
 188
 189 =item helo
 190
 191 The name that BSE uses to identify itself when sending mail via SMTP.
 192 Required if I<smtp_server> is set.
 193
 194 =item sendmail
 195
 196 The path to the C<sendmail> binary.  Default: /usr/lib/sendmail
 197
 198 =item sendmail_opts
 199
 200 The options supplied to sendmail.  Default: -t -oi
 201
 202 You may want to add the -odq option to this if you want mail queued
 203 rather than sent immediately.
 204
 205 =back
 206
 207 =head2 [children of I<id>]
 208
 209 Where I<id> is the identifier for an article.
 210
 211 =over
 212
 213 =item template
 214
 215 the name of the default template for children of the given parent
 216
 217 =item template_dirs
 218
 219 a comma-separated list of extra directories under $TMPLDIR to search
 220 for templates that can be used for children of the given parent article.
 221
 222 =back
 223
 224 =head2 [article I<id>]
 225
 226 Where I<id> is the identifier of an article.
 227
 228 =over
 229
 230 =item template_dirs
 231
 232 A comma-separated list of extra directories under $TMPLDIR to search
 233 for templates that can be used for children of the given parent
 234 article.
 235
 236 =item extra_templates
 237
 238 A comma-separated list of extra templates under $TMPLDIR that can be
 239 used for the given article.
 240
 241 =back
 242
 243 =head2 [level I<level>]
 244
 245 =over
 246
 247 =item template
 248
 249 The default template for this level of article, assuming it hasn't
 250 been set in the [children of I<article id>] section.
 251
 252 =item template_dirs
 253
 254 A comma-separated list of extra directories under $TMPLDIR to search
 255 for templates that can be used for articles at the given I<level>.
 256
 257 =back
 258
 259 =head2 [catalogs]
 260
 261 =over
 262
 263 =item template
 264
 265 The default template for catalogs.
 266
 267 =back
 268
 269 =head2 [products]
 270
 271 =over
 272
 273 =item template
 274
 275 The default template for products.
 276
 277 =back
 278
 279 =head2 [messages]
 280
 281 This can be used to control translation of error messages.  Each key
 282 has a prefix identifying the module that uses the error, followed by
 283 '/' followed by a specific identifier for the message.
 284
 285 Message parameters, expressed as $I<digit>, are replaced with the
 286 parameters passed to the message.  C<$$> is replaced with C<$>.
 287
 288 Each message identifier below is documented with the id, when it
 289 occurs, the default message, and any parameters.
 290
 291 =over
 292
 293 =item user/needlogon
 294
 295 the user attempted to logon without entering a logon name.  Default:
 296 "Please enter a logon name".  No parameters.
 297
 298 =item user/needpass
 299
 300 the user attempted to logon without entering a password.  Default:
 301 "Please enter your password."  No parameters.
 302
 303 =item user/baduserpass
 304
 305 the user's logon name or password was not found or did not match.
 306 Default: "Invalid user or password".  No parameters.
 307
 308 =item user/notloggedon
 309
 310 the user attempted to logoff while not logged on.  Default: "You
 311 aren't logged on".  No parameters.
 312
 313 =item user/optsoldpass
 314
 315 the user entered a new password on the options page without entering
 316 their old password.  Default: "You need to enter your old password to
 317 change your password".  No parameters.
 318
 319 =back
 320
 321 =head2 [downloads]
 322
 323 =over
 324
 325 =item must_be_paid
 326
 327 if non-zero, the order must be marked as paid for before the file can
 328 be downloaded.
 329
 330 =item must_be_filled
 331
 332 if non-zero the order must be marked as filled before the files can be
 333 downloaded.
 334
 335 =item require_logon
 336
 337 if non-zero the user must be registered/logged on to download I<any>
 338 file.
 339
 340 =back
 341
 342 =head2 [confirmations]
 343
 344 Control over confirmation emails.
 345
 346 =over
 347
 348 =item subject
 349
 350 The subject of email confirmation emails.  Default: Subcription
 351 Confirmation.
 352
 353 =item from
 354
 355 The from field for the email.  Default: $SHOP_FROM
 356
 357 =back
 358
 359 =head2 [subscriptions]
 360
 361 Control over subscription messages.
 362
 363 =over
 364
 365 =item from
 366
 367 The from field for the email.  Default: $SHOP_FROM.
 368
 369 =back
 370
 371 =head2 [search]
 372
 373 =over
 374
 375 =item highlight_partial
 376
 377 If this is true then partial matches will be highlight in search
 378 result excerpts.  Default: True
 379
 380 =back
 381
 382 =head2 [shop]
 383
 384 =over
 385
 386 =item register_if_files
 387
 388 If true the customer is required to register before checkout if there
 389 are any for sale files attached to products in the cart.  Default: True
 390
 391 =item require_logon
 392
 393 If true the customer is required to be logged on before checkout,
 394 whether or not for sale files are attached to products in the cart.
 395 Default: False.
 396
 397 =item payment_types
 398
 399 A comma-separated list of acceptable payment types.  Default: 0
 400
 401 The possible payment types are:
 402
 403 =over
 404
 405 =item *
 406
 407 0 - the user enters a credit card number, name and expiry date
 408
 409 =item *
 410
 411 1 - the customer will send a cheque
 412
 413 =item *
 414
 415 2 - contact customer for details
 416
 417 =back
 418
 419 =item address1
 420
 421 =item address2
 422
 423 =item address3
 424
 425 These are used by various shop templates to present an address that a
 426 cheque payment should be sent to.
 427
 428 =back
 429
 430 =head2 [fields]
 431
 432 =over
 433
 434 =item title_size
 435
 436 The maximum length of the article title field.  Default: 255.  Should
 437 not be set higher than this unless you change the database schema.
 438
 439 =back
 440
 441 =head2 [interest]
 442
 443 Controls the interest.pl script.
 444
 445 =over
 446
 447 =item notify
 448
 449 Email address that is notified of the interest.  Defaults to $SHOP_FROM.
 450
 451 =back
 452
 453 =head2 [debug]
 454
 455 Used for debugging.
 456
 457 =over
 458
 459 =item logon_cookies
 460
 461 When a user logs on, and the site url is different to the secure url
 462 BSE attempts to refresh to the other "side" of the site to set the
 463 same cookie.
 464
 465 BSE does some simple comparisons to attempt to determine whether the
 466 logon form was triggered on the secure side of the site (possibly from
 467 the shop) or on the insecure side.  Since CGI doesn't necessarily give
 468 us all the information required, it's possible it will guess wrong.
 469
 470 Setting this option to 1 will enable debugging information sent to
 471 standard error, which will be sent to the error log on Apache.  This
 472 probably isn't useful on IIS.
 473
 474 =item file_unlink
 475
 476 Reports errors to STDERR (hence to the error log on Apache) if there
 477 is a problem deleting the actual file when an attached file is
 478 removed.
 479
 480 =item mail_encryption
 481
 482 Reports debugging information to standard error while encrypting your
 483 mail.
 484
 485 =back
 486
 487 =head2 [uri]
 488
 489 Contains various URIs.
 490
 491 This is underused, so don't rely on it yet.
 492
 493 =over
 494
 495 =item cgi
 496
 497 The URI to the CGI directory.  Default: /cgi-bin
 498
 499 =item images
 500
 501 The URI where images are kept.  Default: /images
 502
 503 =item shop
 504
 505 =item articles
 506
 507 =back
 508
 509 =head2 [articles]
 510
 511 This will provide translations from symbolic names to article ids.
 512
 513 Currently this is used for converting article ids in the access
 514 control code, and for looking up the id of the shop.
 515
 516 =head1 AUTHOR
 517
 518 Tony Cook <tony@develop-help.com>
 519
 520 =cut