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