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