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 =back
 164
 165 =head2 [mail]
 166
 167 This section controls how BSE sends email.
 168
 169 =over
 170
 171 =item smtp_server
 172
 173 The host or IP address of your mail server.  If this is not set
 174 C<sendmail> will be used instead.  If this is set you must also set
 175 I<helo>.
 176
 177 =item helo
 178
 179 The name that BSE uses to identify itself when sending mail via SMTP.
 180 Required if I<smtp_server> is set.
 181
 182 =item sendmail
 183
 184 The path to the C<sendmail> binary.  Default: /usr/lib/sendmail
 185
 186 =item sendmail_opts
 187
 188 The options supplied to sendmail.  Default: -t -oi
 189
 190 You may want to add the -odq option to this if you want mail queued
 191 rather than sent immediately.
 192
 193 =back
 194
 195 =head2 [children of I<id>]
 196
 197 Where I<id> is the identifier for an article.
 198
 199 =over
 200
 201 =item template
 202
 203 the name of the default template for children of the given parent
 204
 205 =item template_dirs
 206
 207 a comma-separated list of extra directories under $TMPLDIR to search
 208 for templates that can be used for children of the given parent article.
 209
 210 =back
 211
 212 =head2 [article I<id>]
 213
 214 Where I<id> is the identifier of an article.
 215
 216 =over
 217
 218 =item template_dirs
 219
 220 A comma-separated list of extra directories under $TMPLDIR to search
 221 for templates that can be used for children of the given parent
 222 article.
 223
 224 =item extra_templates
 225
 226 A comma-separated list of extra templates under $TMPLDIR that can be
 227 used for the given article.
 228
 229 =back
 230
 231 =head2 [level I<level>]
 232
 233 =over
 234
 235 =item template
 236
 237 The default template for this level of article, assuming it hasn't
 238 been set in the [children of I<article id>] section.
 239
 240 =item template_dirs
 241
 242 A comma-separated list of extra directories under $TMPLDIR to search
 243 for templates that can be used for articles at the given I<level>.
 244
 245 =back
 246
 247 =head2 [catalogs]
 248
 249 =over
 250
 251 =item template
 252
 253 The default template for catalogs.
 254
 255 =back
 256
 257 =head2 [products]
 258
 259 =over
 260
 261 =item template
 262
 263 The default template for products.
 264
 265 =back
 266
 267 =head2 [messages]
 268
 269 This can be used to control translation of error messages.  Each key
 270 has a prefix identifying the module that uses the error, followed by
 271 '/' followed by a specific identifier for the message.
 272
 273 Message parameters, expressed as $I<digit>, are replaced with the
 274 parameters passed to the message.  C<$$> is replaced with C<$>.
 275
 276 Each message identifier below is documented with the id, when it
 277 occurs, the default message, and any parameters.
 278
 279 =over
 280
 281 =item user/needlogon
 282
 283 the user attempted to logon without entering a logon name.  Default:
 284 "Please enter a logon name".  No parameters.
 285
 286 =item user/needpass
 287
 288 the user attempted to logon without entering a password.  Default:
 289 "Please enter your password."  No parameters.
 290
 291 =item user/baduserpass
 292
 293 the user's logon name or password was not found or did not match.
 294 Default: "Invalid user or password".  No parameters.
 295
 296 =item user/notloggedon
 297
 298 the user attempted to logoff while not logged on.  Default: "You
 299 aren't logged on".  No parameters.
 300
 301 =item user/optsoldpass
 302
 303 the user entered a new password on the options page without entering
 304 their old password.  Default: "You need to enter your old password to
 305 change your password".  No parameters.
 306
 307 =back
 308
 309 =head2 [downloads]
 310
 311 =over
 312
 313 =item must_be_paid
 314
 315 if non-zero, the order must be marked as paid for before the file can
 316 be downloaded.
 317
 318 =item must_be_filled
 319
 320 if non-zero the order must be marked as filled before the files can be
 321 downloaded.
 322
 323 =item require_logon
 324
 325 if non-zero the user must be registered/logged on to download I<any>
 326 file.
 327
 328 =back
 329
 330 =head2 [confirmations]
 331
 332 Control over confirmation emails.
 333
 334 =over
 335
 336 =item subject
 337
 338 The subject of email confirmation emails.  Default: Subcription
 339 Confirmation.
 340
 341 =item from
 342
 343 The from field for the email.  Default: $SHOP_FROM
 344
 345 =back
 346
 347 =head2 [subscriptions]
 348
 349 Control over subscription messages.
 350
 351 =over
 352
 353 =item from
 354
 355 The from field for the email.  Default: $SHOP_FROM.
 356
 357 =back
 358
 359 =head2 [search]
 360
 361 =over
 362
 363 =item highlight_partial
 364
 365 If this is true then partial matches will be highlight in search
 366 result excerpts.  Default: True
 367
 368 =back
 369
 370 =head2 [shop]
 371
 372 =over
 373
 374 =item register_if_files
 375
 376 If true the customer is required to register before checkout if there
 377 are any for sale files attached to products in the cart.  Default: True
 378
 379 =item require_logon
 380
 381 If true the customer is required to be logged on before checkout,
 382 whether or not for sale files are attached to products in the cart.
 383 Default: False.
 384
 385 =back
 386
 387 =head2 [fields]
 388
 389 =over
 390
 391 =item title_size
 392
 393 The maximum length of the article title field.  Default: 255.  Should
 394 not be set higher than this unless you change the database schema.
 395
 396 =back
 397
 398 =head2 [interest]
 399
 400 Controls the interest.pl script.
 401
 402 =over
 403
 404 =item notify
 405
 406 Email address that is notified of the interest.  Defaults to $SHOP_FROM.
 407
 408 =back
 409
 410 =head2 [debug]
 411
 412 Used for debugging.
 413
 414 =over
 415
 416 =item logon_cookies
 417
 418 When a user logs on, and the site url is different to the secure url
 419 BSE attempts to refresh to the other "side" of the site to set the
 420 same cookie.
 421
 422 BSE does some simple comparisons to attempt to determine whether the
 423 logon form was triggered on the secure side of the site (possibly from
 424 the shop) or on the insecure side.  Since CGI doesn't necessarily give
 425 us all the information required, it's possible it will guess wrong.
 426
 427 Setting this option to 1 will enable debugging information sent to
 428 standard error, which will be sent to the error log on Apache.  This
 429 probably isn't useful on IIS.
 430
 431 =item file_unlink
 432
 433 Reports errors to STDERR (hence to the error log on Apache) if there
 434 is a problem deleting the actual file when an attached file is
 435 removed.
 436
 437 =item mail_encryption
 438
 439 Reports debugging information to standard error while encrypting your
 440 mail.
 441
 442 =back
 443
 444 =head2 [uri]
 445
 446 Contains various URIs.
 447
 448 This is underused, so don't rely on it yet.
 449
 450 =over
 451
 452 =item cgi
 453
 454 The URI to the CGI directory.  Default: /cgi-bin
 455
 456 =item images
 457
 458 The URI where images are kept.  Default: /images
 459
 460 =item shop
 461
 462 =item articles
 463
 464
 465
 466 =back
 467
 468 =head1 AUTHOR
 469
 470 Tony Cook <tony@develop-help.com>
 471
 472 =cut