0.14 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
d09682dd
TC
384=item testname
385
386Default for the "Test Name" field for sending test subscription
387messages.
388
389=item testemail
390
391Default for the "Test Email" field for sending test subscription
392messages.
393
394=item testtextonly
395
396Set to 1 if you want the "Test Text Only" box checked by default for
397sending test subscription messages.
398
399=item testing
400
401Set to 0 to disable display of the test subscription messages portions
402of the subscriptions send form.
403
531fb3bc
TC
404=back
405
6e3d2da5
TC
406=head2 [search]
407
408=over
409
410=item highlight_partial
411
412If this is true then partial matches will be highlight in search
413result excerpts. Default: True
414
415=back
416
417=head2 [shop]
418
419=over
420
7b81711b
TC
421=item enabled
422
423Used by some templates to check if the shop is enabled. Set this to 1
424to enable the shop, or 0 to disable it.
425
6e3d2da5
TC
426=item register_if_files
427
428If true the customer is required to register before checkout if there
429are any for sale files attached to products in the cart. Default: True
430
431=item require_logon
432
433If true the customer is required to be logged on before checkout,
434whether or not for sale files are attached to products in the cart.
435Default: False.
436
08123550
TC
437=item payment_types
438
439A comma-separated list of acceptable payment types. Default: 0
440
441The possible payment types are:
442
443=over
444
445=item *
446
4470 - the user enters a credit card number, name and expiry date
448
449=item *
450
4511 - the customer will send a cheque
452
453=item *
454
4552 - contact customer for details
456
457=back
458
459=item address1
460
461=item address2
462
463=item address3
464
465These are used by various shop templates to present an address that a
466cheque payment should be sent to.
467
331fd099
TC
468=item from
469
470From email address for emails sent by the shop. Overides $SHOP_FROM
471in Constants.pm
472
473=item to_name
474
475To name for emailed orders sent by the shop. Overrides $SHOP_TO_NAME
476in Constants.pm
477
478=item to_email
479
480To email for emailed orders sent by the shop. Overrides $SHOP_TO_EMAIL
481in Constants.pm
482
d09682dd
TC
483=item noencrypt
484
485If this is true then orders sent to you by the shop will not be
486encrypted. Enabling this disabled acceptance of credit card orders,
487and the default for C<payment_types> will become C<1> instead or C<0>.
488
489Please realize that other potentially commercially sensitive
490information is being sent in the clear to a central location,
491unencrypted.
492
493=item email_order
494
495If true, then the order is email to to_email, possibly with credit
496card information included. Default: $SHOP_EMAIL_ORDER.
497
6e3d2da5
TC
498=back
499
500=head2 [fields]
501
502=over
503
504=item title_size
505
506The maximum length of the article title field. Default: 255. Should
507not be set higher than this unless you change the database schema.
508
509=back
510
ee6577c3
TC
511=head2 [interest]
512
513Controls the interest.pl script.
514
515=over
516
517=item notify
518
519Email address that is notified of the interest. Defaults to $SHOP_FROM.
520
ca9aa2bf 521=back
ee6577c3 522
6e3d2da5
TC
523=head2 [debug]
524
525Used for debugging.
526
527=over
528
529=item logon_cookies
530
531When a user logs on, and the site url is different to the secure url
532BSE attempts to refresh to the other "side" of the site to set the
533same cookie.
534
535BSE does some simple comparisons to attempt to determine whether the
536logon form was triggered on the secure side of the site (possibly from
537the shop) or on the insecure side. Since CGI doesn't necessarily give
538us all the information required, it's possible it will guess wrong.
539
d2730773
TC
540Setting this option to 1 will enable debugging information sent to
541standard error, which will be sent to the error log on Apache. This
542probably isn't useful on IIS.
543
544=item file_unlink
545
546Reports errors to STDERR (hence to the error log on Apache) if there
547is a problem deleting the actual file when an attached file is
548removed.
549
550=item mail_encryption
551
552Reports debugging information to standard error while encrypting your
553mail.
6e3d2da5 554
ca9aa2bf
TC
555=back
556
557=head2 [uri]
558
559Contains various URIs.
560
561This is underused, so don't rely on it yet.
562
563=over
564
565=item cgi
566
567The URI to the CGI directory. Default: /cgi-bin
568
569=item images
570
571The URI where images are kept. Default: /images
572
573=item shop
574
575=item articles
576
9168c88c 577=back
ca9aa2bf 578
9168c88c 579=head2 [articles]
ca9aa2bf 580
9168c88c
TC
581This will provide translations from symbolic names to article ids.
582
583Currently this is used for converting article ids in the access
584control code, and for looking up the id of the shop.
6e3d2da5 585
0b406a07
TC
586=head2 [printable type]
587
588If the user supplies a template name to printable.pl then you can use
589a different content type by adding an entry to this section. The key
590is the template name, and the value is the full content type.
591
918735d1
TC
592=head2 [search index scores]
593
594This section is used when generating the search index to override the
595default scores for each field in the articles.
596
597The default scores are:
598
599 Field Score
600 ----- -----
601 title 5
602 body 3
603 keyword 4
604
605A special key C<file_description> can be used here to set the score
606for indexing downloadable file descriptions, which aren't indexed by
607default. A good value is probably 2 or 1.
608
609=head2 [article flags]
610
611=head2 [product flags]
612
613=head2 [catalog flags]
614
615Flags that can be set for articles, products and catalogs
616respectively. Note that flags for articles are also visible in
617products and catalogs.
618
619All flag Ids are single letters or digits. Uppercase letters are
620reserved for use by BSE internally, leaving lower-case letters and
621digits for your own use.
622
623Use the id of the flag as the key, and a description of the flag as
624it's value.
625
95989433
TC
626=head2 [article uris]
627
628Each key is an article id, the values are base URIs to store the HTML
629form of those articles and their children under.
630
631=head2 [protect link]
632
633The keys are ids of articles that shouldn't have their link field
634overwritten. The value should be a true value, but is otherwise
635ignored.
636
d09682dd
TC
637=head2 [datadump]
638
639=over
640
641=item to
642
643The recipient for the data dump email sent by datadump.pl. Default:
644$DATA_EMAIL.
645
646=item from
647
648the From for the data dump email sent by datadump.pl. Default:
649$SHOP_FROM.
650
651=back
652
61551101
TC
653=head1 AUTHOR
654
655Tony Cook <tony@develop-help.com>
656
657=cut