0.14_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
d49f56a6
TC
177=item server_auth
178
179Set this to non-zero to enable authentication via server
180authentication (usually Basic Authentication.) You should normally
181set this if you set htusers below. Default: 0 (disabled)
182
9168c88c
TC
183=item htusers
184
185This should be the path to a file to be updated with the list of users
186and crypt() versions of their passwords. If this is set then the
187security system will check for a user set by the browser before
188attempting a form based logon. Default: None.
189
331fd099
TC
190=item custom_class
191
192The name of the custom class for your site. This is currently only
193used for article editing customizations. This class should derive
194from BSE::CustomBase. Default: BSE::Custom.
195
b19047a6
TC
196=back
197
198=head2 [mail]
199
35c0719f 200This section controls how BSE sends email.
b19047a6
TC
201
202=over
203
204=item smtp_server
205
206The host or IP address of your mail server. If this is not set
207C<sendmail> will be used instead. If this is set you must also set
208I<helo>.
209
210=item helo
211
212The name that BSE uses to identify itself when sending mail via SMTP.
213Required if I<smtp_server> is set.
214
215=item sendmail
216
217The path to the C<sendmail> binary. Default: /usr/lib/sendmail
218
219=item sendmail_opts
220
221The options supplied to sendmail. Default: -t -oi
222
223You may want to add the -odq option to this if you want mail queued
224rather than sent immediately.
225
61551101
TC
226=back
227
ca9aa2bf 228=head2 [children of I<id>]
721cd24c
TC
229
230Where I<id> is the identifier for an article.
231
232=over
233
234=item template
235
236the name of the default template for children of the given parent
237
238=item template_dirs
239
240a comma-separated list of extra directories under $TMPLDIR to search
241for templates that can be used for children of the given parent article.
242
243=back
244
ca9aa2bf
TC
245=head2 [article I<id>]
246
247Where I<id> is the identifier of an article.
248
249=over
250
251=item template_dirs
252
253A comma-separated list of extra directories under $TMPLDIR to search
254for templates that can be used for children of the given parent
255article.
256
257=item extra_templates
258
259A comma-separated list of extra templates under $TMPLDIR that can be
260used for the given article.
261
262=back
263
caa7299c
TC
264=head2 [level I<level>]
265
266=over
267
268=item template
269
270The default template for this level of article, assuming it hasn't
271been set in the [children of I<article id>] section.
272
273=item template_dirs
274
275A comma-separated list of extra directories under $TMPLDIR to search
276for templates that can be used for articles at the given I<level>.
277
278=back
279
280=head2 [catalogs]
281
282=over
283
284=item template
285
286The default template for catalogs.
287
288=back
289
290=head2 [products]
291
292=over
293
294=item template
295
296The default template for products.
297
d64413ee
TC
298=item extra_templates
299
300A comma separated list of extra templates that can be used for
301products.
302
caa7299c
TC
303=back
304
61551101
TC
305=head2 [messages]
306
307This can be used to control translation of error messages. Each key
308has a prefix identifying the module that uses the error, followed by
309'/' followed by a specific identifier for the message.
310
311Message parameters, expressed as $I<digit>, are replaced with the
312parameters passed to the message. C<$$> is replaced with C<$>.
313
314Each message identifier below is documented with the id, when it
315occurs, the default message, and any parameters.
316
317=over
318
319=item user/needlogon
320
321the user attempted to logon without entering a logon name. Default:
322"Please enter a logon name". No parameters.
323
324=item user/needpass
325
326the user attempted to logon without entering a password. Default:
327"Please enter your password." No parameters.
328
329=item user/baduserpass
330
331the user's logon name or password was not found or did not match.
332Default: "Invalid user or password". No parameters.
333
334=item user/notloggedon
335
336the user attempted to logoff while not logged on. Default: "You
337aren't logged on". No parameters.
338
339=item user/optsoldpass
340
341the user entered a new password on the options page without entering
342their old password. Default: "You need to enter your old password to
343change your password". No parameters.
344
345=back
346
2404a911
TC
347=head2 [downloads]
348
349=over
350
351=item must_be_paid
352
353if non-zero, the order must be marked as paid for before the file can
354be downloaded.
355
356=item must_be_filled
357
358if non-zero the order must be marked as filled before the files can be
359downloaded.
360
4afdbb1b
TC
361=item require_logon
362
363if non-zero the user must be registered/logged on to download I<any>
364file.
365
2404a911
TC
366=back
367
b19047a6
TC
368=head2 [confirmations]
369
370Control over confirmation emails.
371
372=over
373
374=item subject
375
376The subject of email confirmation emails. Default: Subcription
377Confirmation.
378
379=item from
380
381The from field for the email. Default: $SHOP_FROM
382
383=back
384
531fb3bc
TC
385=head2 [subscriptions]
386
387Control over subscription messages.
388
389=over
390
391=item from
392
393The from field for the email. Default: $SHOP_FROM.
394
d09682dd
TC
395=item testname
396
397Default for the "Test Name" field for sending test subscription
398messages.
399
400=item testemail
401
402Default for the "Test Email" field for sending test subscription
403messages.
404
405=item testtextonly
406
407Set to 1 if you want the "Test Text Only" box checked by default for
408sending test subscription messages.
409
410=item testing
411
412Set to 0 to disable display of the test subscription messages portions
413of the subscriptions send form.
414
99b7cef0
TC
415=item text_link_inline
416
417Set to format links as they appear in the text version of emails.
418C<$1> is replaced with the title, C<$2> with the URL and C<$3> with
419the index. C<$$> is replaced with '$'. Default: C<$1 [$3]>
420
421=item text_link_list
422
423Set to format links as they appear at the footer of the body text. If
424this is set to the empty string then no list appears. C<$1>, C<$2>,
425C<$3>, C<$$> are replaced as for I<text_link_inline> and $n is
426replaced with newline. Default: C<[$3] $2>
427
428=item text_link_list_prefix
429
430A line of text produced above the list of URLs if there is one.
431Default: C<----->. $n in this is replaced with newlines.
432
531fb3bc
TC
433=back
434
99b7cef0
TC
435For example, if the configuration is:
436
437 text_link_inline="$1" ($3)
438 text_link_list_prefix=$n$n-------
439 text_link_list=($3) "$1"$n => $2
440
441and the body text is:
442
443 doclink[3]
444 link[http://www.example.com/|Example]
445
446the result will be:
447
448 "The Shop" (1)
449 "Example" (2)
450
451
452 -------
453 (1) "The Shop"
454 => http://www.yoursite.com/shop/index.html
455 (2) "Example"
456 => http://www.example.com/
457
6e3d2da5
TC
458=head2 [search]
459
460=over
461
462=item highlight_partial
463
464If this is true then partial matches will be highlight in search
465result excerpts. Default: True
466
467=back
468
469=head2 [shop]
470
471=over
472
7b81711b
TC
473=item enabled
474
475Used by some templates to check if the shop is enabled. Set this to 1
476to enable the shop, or 0 to disable it.
477
6e3d2da5
TC
478=item register_if_files
479
480If true the customer is required to register before checkout if there
481are any for sale files attached to products in the cart. Default: True
482
483=item require_logon
484
485If true the customer is required to be logged on before checkout,
486whether or not for sale files are attached to products in the cart.
487Default: False.
488
08123550
TC
489=item payment_types
490
491A comma-separated list of acceptable payment types. Default: 0
492
493The possible payment types are:
494
495=over
496
497=item *
498
4990 - the user enters a credit card number, name and expiry date
500
501=item *
502
5031 - the customer will send a cheque
504
505=item *
506
5072 - contact customer for details
508
509=back
510
81f3292d
TC
511Other types can be added by adding entries to the [payment type names]
512and [payment type descs] sections.
513
08123550
TC
514=item address1
515
516=item address2
517
518=item address3
519
520These are used by various shop templates to present an address that a
521cheque payment should be sent to.
522
331fd099
TC
523=item from
524
525From email address for emails sent by the shop. Overides $SHOP_FROM
526in Constants.pm
527
528=item to_name
529
530To name for emailed orders sent by the shop. Overrides $SHOP_TO_NAME
531in Constants.pm
532
533=item to_email
534
535To email for emailed orders sent by the shop. Overrides $SHOP_TO_EMAIL
536in Constants.pm
537
d09682dd
TC
538=item noencrypt
539
540If this is true then orders sent to you by the shop will not be
541encrypted. Enabling this disabled acceptance of credit card orders,
542and the default for C<payment_types> will become C<1> instead or C<0>.
543
544Please realize that other potentially commercially sensitive
545information is being sent in the clear to a central location,
546unencrypted.
547
548=item email_order
549
550If true, then the order is email to to_email, possibly with credit
551card information included. Default: $SHOP_EMAIL_ORDER.
552
d49f56a6
TC
553=item display_I<field>
554
555Used to translate the stored order field name into a presentation name
556suitable for error messages.
557
6e3d2da5
TC
558=back
559
560=head2 [fields]
561
562=over
563
564=item title_size
565
566The maximum length of the article title field. Default: 255. Should
567not be set higher than this unless you change the database schema.
568
569=back
570
ee6577c3
TC
571=head2 [interest]
572
573Controls the interest.pl script.
574
575=over
576
577=item notify
578
579Email address that is notified of the interest. Defaults to $SHOP_FROM.
580
ca9aa2bf 581=back
ee6577c3 582
6e3d2da5
TC
583=head2 [debug]
584
585Used for debugging.
586
587=over
588
589=item logon_cookies
590
591When a user logs on, and the site url is different to the secure url
592BSE attempts to refresh to the other "side" of the site to set the
593same cookie.
594
595BSE does some simple comparisons to attempt to determine whether the
596logon form was triggered on the secure side of the site (possibly from
597the shop) or on the insecure side. Since CGI doesn't necessarily give
598us all the information required, it's possible it will guess wrong.
599
d2730773
TC
600Setting this option to 1 will enable debugging information sent to
601standard error, which will be sent to the error log on Apache. This
602probably isn't useful on IIS.
603
604=item file_unlink
605
606Reports errors to STDERR (hence to the error log on Apache) if there
607is a problem deleting the actual file when an attached file is
608removed.
609
610=item mail_encryption
611
612Reports debugging information to standard error while encrypting your
613mail.
6e3d2da5 614
2d873eb6
TC
615=item cookies
616
617Reports cookies received from the browser and sent to the browser to
618STDERR (hence to the error log on Apache.)
619
ca9aa2bf
TC
620=back
621
622=head2 [uri]
623
624Contains various URIs.
625
626This is underused, so don't rely on it yet.
627
628=over
629
630=item cgi
631
632The URI to the CGI directory. Default: /cgi-bin
633
634=item images
635
636The URI where images are kept. Default: /images
637
638=item shop
639
640=item articles
641
9168c88c 642=back
ca9aa2bf 643
9168c88c 644=head2 [articles]
ca9aa2bf 645
9168c88c
TC
646This will provide translations from symbolic names to article ids.
647
648Currently this is used for converting article ids in the access
649control code, and for looking up the id of the shop.
6e3d2da5 650
0b406a07
TC
651=head2 [printable type]
652
653If the user supplies a template name to printable.pl then you can use
654a different content type by adding an entry to this section. The key
655is the template name, and the value is the full content type.
656
918735d1
TC
657=head2 [search index scores]
658
659This section is used when generating the search index to override the
660default scores for each field in the articles.
661
662The default scores are:
663
664 Field Score
665 ----- -----
666 title 5
667 body 3
668 keyword 4
669
670A special key C<file_description> can be used here to set the score
671for indexing downloadable file descriptions, which aren't indexed by
672default. A good value is probably 2 or 1.
673
674=head2 [article flags]
675
676=head2 [product flags]
677
678=head2 [catalog flags]
679
680Flags that can be set for articles, products and catalogs
681respectively. Note that flags for articles are also visible in
682products and catalogs.
683
684All flag Ids are single letters or digits. Uppercase letters are
685reserved for use by BSE internally, leaving lower-case letters and
686digits for your own use.
687
688Use the id of the flag as the key, and a description of the flag as
689it's value.
690
95989433
TC
691=head2 [article uris]
692
693Each key is an article id, the values are base URIs to store the HTML
694form of those articles and their children under.
695
696=head2 [protect link]
697
698The keys are ids of articles that shouldn't have their link field
699overwritten. The value should be a true value, but is otherwise
700ignored.
701
d09682dd
TC
702=head2 [datadump]
703
704=over
705
706=item to
707
708The recipient for the data dump email sent by datadump.pl. Default:
709$DATA_EMAIL.
710
711=item from
712
713the From for the data dump email sent by datadump.pl. Default:
714$SHOP_FROM.
715
716=back
717
2a295ea9
TC
718=head2 [site users]
719
720Configuration for site users.
721
722=over
723
724=item nopassword
725
726If this is set to true then no passwords are required during
727registration, a confirmation email is sent immediately upon
728registration and that confirmation email contains a link the user can
729use to manage their details.
730
731This option has some security concerns since it can leave links to the
732user's information in the browser history. This option is not
733recommended.
734
735You cannot use this to control access to the shop.
736
737=item require_name1
738
739=item require_name2
740
741=item require_address
742
743=item require_city
744
745=item require_state
746
747=item require_postcode
748
749=item require_telephone
750
751=item require_facsimile
752
753=item require_country
754
755=item require_title
756
757=item require_organization
758
759Set these to true to require the corresponding field during
760registration, and to keep it required after modification. Default:
761false.
762
763If you enable any of these, you should enable C<info_on_register> as
764well, or modify the registration template to include the given fields.
765
766=item display_I<field name>
767
768Controls how the given field is displayed in error messages. If you
769change the field names on the registration and/or options forms you
770should probably change them here too. Default: internal field name
771with the first character converted to upper-case.
772
773=item info_on_register
774
775If this is set then the user info is prompted for during user
776registration. The information still isn't required unless the
777appropriate require_I<field> option is set. Default: false.
778
779=item register_refresh
780
781The default URL to refresh to on completing registration if no r
782parameter is supplied.
783
784=item subscribe_all
785
786If this is set then the subcription checkboxes are all checked on
787registration by default. Default: false.
788
789The user will only receive the subscriptions if they leave them checked
790and follow the link in the confirmation email.
791
792=item subscribe_I<id>
793
794Where I<id> is the number identifying a subscription. If this is set
795then the subscription checkbox for that subscription will be checked
796by default on the registration form. Default: false.
797
798The user will only receive the subscriptions if they leave it checked
799and follow the link in the confirmation email.
800
801You can get the I<id> of a subcription by looking at the Edit link on the
802subscriptions management page, the number after "id=" is the id.
803
9063386f
TC
804=item billing_on_main_opts
805
806If set to zero then user billing options will be managed on a separate
807page. This is controlled by the user/options_base.tmpl template.
808
809=item user_register
810
811If set to zero then users cannot register themselves. Default: true,
812allowing users to register themselves.
813
2a295ea9
TC
814=back
815
81f3292d
TC
816=head2 [payment type names]
817
818This section and [payment type descs] are used to configure new
819paymeny type ids.
820
821The key is the integer representing the payment type. The value is
822the name used in tags for checking the payment type.
823
824You can also add a description (currently unused) to [payment type
825descs].
826
827You should use numbers starting from 10 to avoid conflicts with future
828BSE payment types.
829
830=head2 [payment type descs]
831
832See [payment type names].
833
834=head2 [payment type required]
835
836Set the key given by the payment type id to a value of a
837comma-separated list of fields required for that payment type.
838
61551101
TC
839=head1 AUTHOR
840
841Tony Cook <tony@develop-help.com>
842
843=cut