6c0011fc0d09b9144b5833d9c3f33682c57881cd
[bse.git] / 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 F<bse.cfg> is read as a utf-8 encoded file.
17
18 =head1 CONFIGURATION ENTRIES
19
20 =head2 [site]
21
22 Contains URL configuration for the site.
23
24 =over
25
26 =item url
27
28 The normal URL for the non-secure parts of the site.
29
30 =item secureurl
31
32 The secure URL for the shop, products and other portions of the site
33 that should use SSL.  This isn't checked to make sure it is https.
34
35 =item name
36
37 Used as the site "name" in a few places.
38
39 =item adminurl
40
41 If set, this is used as the base URL for accessing the administrative
42 functions of your site.
43
44 =item secureadmin
45
46 Ignored if C<adminurl> is set.
47
48 If this is true then C<secureurl> is used as the base URL for
49 accessing the administrative functions of your site, otherwise C<url>
50 is used as the base URL.  Default: false (C<url>'s value is used)
51
52 =item forward_from
53
54 Configure the IP address of one or more front-end proxies.  This can
55 be a regular expression except that C<.> is translated to C<\.> and
56 C<*> is tranlated to C<.*> to give more glob() like matching.
57
58 If the reqesting host matches then admin site URL matching is done
59 against HTTP_X_FORWARDED_SERVER instead of SERVER_NAME.
60
61 Default: no front-end server configured.
62
63 =item secret
64
65 A secret used (currently) for hashing cookie values passed between the
66 secure and non-secure parts of the site.  This must be set.  A
67 suitable value can be created with:
68
69   openssl rand -base64 32
70
71 =back
72
73 =head2 [paths]
74
75 Contains various file system paths.
76
77 =over
78
79 =item downloads
80
81 This is where the files uploads with the file wizard are stored.  It
82 must be writable by the web server user.
83
84 =item admin_templates
85
86 Directory containing administrative templates.  Note: this is not
87 completely implemented for now, so assume the default.  Default: admin
88 directory under $TMPLDIR.
89
90 =item templates
91
92 Directory base for most templates.  This can contain references like
93 $(section/key) to other configuration entries.  Split on the systems
94 PATH separators (run: perl -V:path_sep)
95
96 =item local_templates
97
98 Local Directory base for templates.  This is searched before the
99 templates directory.  This can contain references like $(section/key)
100 to other configuration entries.  Split on the system's PATH separator.
101
102 =item public_html
103
104 Web server document root.  Static pages are generated under this
105 directory.  Default: $CONTENTBASE.
106
107 =item images
108
109 Where uploaded images are stored.  This is not yet completely
110 implemented.  Default: $IMAGEDIR.
111
112 =item libraries
113
114 Local search path for BSE::Custom, or the class configured by
115 C<custom_class> in [basic].
116
117 =item scalecache
118
119 The directory where cached versions of scaled thumbnails are stored.
120 Defaults to I<[paths].images>F</scaled>.  This must be in the document tree.  If
121 you set this you should also set I<[uri].scalecache>.
122
123 =item siteuser_images
124
125 Where uploaded siteuser images are stored.  This must be set in the
126 config file.  The default bse.cfg include an entry to use the current
127 values of [paths].downloads
128
129 =item dynamic_cache
130
131 Pregenerated dynamic article pages are stored here.  This must be
132 defined if you site contains any dynamicly generated pages.
133
134 =item public_files
135
136 The directory to store public BSE::TB::File content in (currently used
137 for application specific files.)
138
139 =back
140
141 =head2 [extensions]
142
143 This section is used by the file wizard to map uploaded file
144 extensions to MIME content types.  This can be used to extend
145 BSE::FileEditor's internal extension map.  It cannot override that
146 map.
147
148 The key for each entry is the extension, without the leading '.'.
149
150 eg.
151
152   xls = application/msexcel
153
154 =head2 [templates]
155
156 Used for translating symbolic template names into full names under the
157 template directory.
158
159 In each case the default is the name with a C<.tmpl> extension.
160
161 =over
162
163 =item user/logon
164
165 user logon page
166
167 =item user/register
168
169 user registration page
170
171 =back
172
173 =head2 [admin templates]
174
175 Used for translating the names of administration templates into filenames.
176
177 In each case the default is the name with a C<.tmpl> extension.
178
179 =over
180
181 =item filelist
182
183 article file wizard
184
185 =item catalog
186
187 Catalog editor page.  Default admin/edit_catalog.tmpl
188
189 =item Z<>1
190
191 =item Z<>2
192
193 =item Z<>3
194
195 =item Z<>4
196
197 =item Z<>5
198
199 Article edit pages.  Default admin/edit_<number>.tmpl
200
201 =item steps
202
203 Step child/parent management page.  Default admin/edit_steps.tmpl
204
205 =back
206
207 =head2 [html]
208
209 Minor html items.
210
211 =over
212
213 =item charset
214
215 The value of the charset keyword when outputting HTML from a script.
216 Set to the empty string to suppress the charset keyword.  Default:
217 iso-8859-1.
218
219 =item redirect_links
220
221 If this is a non-zero number, then all but mailto links are redirected
222 to C<nuser.pl/redirect> so you can display a diclaimer.  If this
223 contained alphabetics it's treated as a comma separated list of url
224 schemes that should be handled via C<nuser.pl/redirect>.  If 0 or not
225 present, no redirection is done.
226
227 The redirect URL includes a hash of the url, title and the redirect
228 salt to prevent using this mechanism by external sites for cookie
229 stealing attacks.
230
231 =item redirect_salt
232
233 The salt used in generating the has for redirect_links.  Default: an
234 empty string.
235
236 =item validate
237
238 If non-zero then any HTML output is validated with HTML::Tidy.
239 Validation errors and warnings are sent to the audit log.  See [html
240 tidy].
241
242 =item tagformat
243
244 The default tag formatting to use for C<< <:= ... :> >> tags.
245 Default: C<html>.
246
247 =item formatter_image_class
248
249 The default class to use for image[...]  tags in body text.  Default:
250 C<bse_image_inline>.
251
252 =back
253
254 =head2 [basic]
255
256 =over
257
258 =item access_control
259
260 If this is true then the user/group/permissions database is used to
261 control access to the system.  Default: False.
262
263 =item access_filter_parents
264
265 If this is true, then the drop-down lists of possible parents on the
266 newsletter edit pages are filtered for access control.
267 Default: False.
268
269 =item access_filter_steps
270
271 If this is true, then the drop-down lists of possible stepparents and
272 stepchildren on the article edit pages are filtered for access control.
273 Default: False.
274
275 =item alias_prefix
276
277 The prefix applied to articles that use a linkAlias url.  This should
278 start with a /.
279
280 =item alias_recursive
281
282 If this is non-zero then the link is formed by the C<alias_prefix>,
283 followed by slash (C</>) separated aliases from the ancestors starting
284 from the section, followed by the C<alias_suffix>.  You may need to
285 change your redirect handling if you enable this.  Default: Off.
286
287 =item alias_suffix
288
289 If this is non-zero then the title is cleaned up (all but
290 alphanumerics removed) and appended to the alias URL generated.
291
292 =item all_dynamic
293
294 If true then all articles are treated as dynamic.  Default: false.
295
296 =item auto_images
297
298 By default, if the author doesn't use any image tags, BSE will insert
299 any unnamed article images into the body text of an article.  You can
300 disable this on a per-article basis in the image tool, or disable it
301 globally by setting C<auto_images> to 0.
302
303 An alternative is to set C<imagePos> in C<[article defaults]> to
304 C<xx> which will default articles to not auto-inserting images.
305
306 =item cache_templates
307
308 If true, BSE will cache compiled templates using the configured BSE
309 cache, if any.  Depending on the configured cache this may slow things
310 down.  Default: disabled.
311
312 =item cache_templates_locally
313
314 If true, BSE will cache compiled templates in memory.  This may
315 significantly improve performance but may increase memory use.
316 Default: disabled.
317
318 =item cache_thumbnails
319
320 If set to zero the results of the thumbimage/gthumbimage body/template
321 tags will not be cached.  Default: 1 (caching is enabled).
322
323 =item cookie_domain
324
325 This overrides the domain value set for cookies.  This is useful if
326 you allow the site to run under both example.com and www.example.com,
327 if you set cookie_domain to example.com then a user visiting
328 www.example.com will still have their cookies when they visit
329 example.com.
330
331 =item cookie_lifetime
332
333 The expiry time for cookies.  This should be in the form supported by
334 CGI.pm for the -expires parameter.  Typically you want a plus ('+'), a
335 number, and a time character (s - seconds, m - minutes, h - hours, d -
336 days, M - months).  Set to an empty string for session cookies.
337 Default: +3h
338
339 =item cookie_name
340
341 This overrides the cookie name used to store the session id.  Default:
342 sessionid.  This is useful when you have 2 sites under the same
343 top-level domain, and helps disambiguate the cookie returned by the
344 browser.
345
346 =item custom_class
347
348 The name of the custom class for your site.  This is currently only
349 used for article editing customizations.  This class should derive
350 from BSE::CustomBase.  Default: BSE::Custom.
351
352 =item default_popupimage
353
354 This is the default popup image class for the popimage[] and
355 gpopimage[] tags.  Default: popup.
356
357 =item dynamic_access_filter
358
359 If set to 0, dynamic article iterators will no access control filter
360 their results.  Default: 1.
361
362 =item error_not_defined
363
364 If non-zero, during dynamic page generation, inserts a message
365 explaining which variable is not set, instead of just leaving the tag
366 unreplaced.  Default: 1.
367
368 =item http_only_session
369
370 If this is non-zero, the default, the session cookie sent to the
371 browser has the C<HttpOnly> attribute set.  This can prevent session
372 cookie hijacking.  Default: 1.
373
374 =item htusers
375
376 This should be the path to a file to be updated with the list of users
377 and crypt() versions of their passwords.  If this is set then the
378 security system will check for a user set by the browser before
379 attempting a form based logon.  Default: None.
380
381 =item index_file
382
383 The name of the file to generate for static articles when the link is
384 terminated by "/".  Default: C<index.html>.
385
386 =item jit_dynamic_pregen
387
388 If this is true, then pre-generation for dynamic pages will be delayed
389 until the page is displayed to a user.  Default: off.
390
391 =item link_titles
392
393 If this is true then the links to your articles within BSE will be
394 followed by a / and then by a simplified version of the article title.
395 The aim is to include at least some title information in the URL
396 without modifying the name of the HTML file.  Default: False.
397
398 =item make_userid_cookie
399
400 If this is non-zero, the default, then when the site member logs in, a
401 javascript visible cookie, C<userid> will be set that contains the
402 login name of the user.  BSE's back-end doesn't use this cookie, its
403 only use is for Javascript to enable/disable user interface elements.
404 Default: 1.
405
406 =item minpassword
407
408 Previously the minimum length of site user passwords in characters.
409 You must now set C<length> in C<[siteuser passwords]>.
410
411 =item no_cache_dynamic
412
413 If non-zero, the default, dynamic responses will include a
414 C<Cache-Control: no-cache> header.  This can be overridden for
415 articles via , article flags, C<[template >
416 I<templatename>C<].no_cache_dynamic> and [article].no_cache_dynamic.
417 Default: 1.
418
419 =item preload_template
420
421 Preload the named template, searching the template search part.  Any
422 text that would normally be produced by the preloaded template is
423 ignored.  This can be useful for common definitions and variables for
424 use in many templates.  Default: none.
425
426 =item randomdata
427
428 Device to read random data from.  This device should not block when it
429 runs out of entropy.
430
431 =item redir_to_alias
432
433 If true then page.pl will 301 redirect (Moved Permanently) requests
434 for an article by its id to the generated link if the article has a
435 link alias.  Default: false.  Must only be used with use_alias true.
436
437 =item secure_session
438
439 If this is non-zero then the session cookie sent to the browser has
440 the C<Secure> attribute set.  This means that the cookie will only be
441 visible over https.  This is only useful when the only URL the site is
442 visited over is a https URL.  Default: 0.
443
444 =item server_auth
445
446 Set this to non-zero to enable authentication via server
447 authentication (usually Basic Authentication.)  You should normally
448 set this if you set htusers below.  Default: 0 (disabled)
449
450 =item sign
451
452 If this is true then the encrypted messages containing the customer's
453 credit card number are sent to the shop owner signed.  To avoid
454 keeping a passphrase and signing key on the server you can set this to
455 false (0).  This has the effect that anyone could send you an unsigned
456 message encrypted with your public key, though this may not be a
457 security threat.  Default: True.
458
459 =item staticajax
460
461 If true, the ifAjax and ajax tags will be active for static pages.
462
463 =item static_thumbnails
464
465 If true and cache_thumbnails is true then thumbnails for the thumbnail
466 cache will be generated when a static page is regenerated, and the
467 link from the page will link to the image in the cache rather than to
468 C<thumb.pl>.  Default: 1 (static thumbnails enabled).
469
470 =item track_uploads
471
472 If this is non-zero, and a cache is configured (see [cache]), file
473 uploads are tracked in entries in the cache.
474
475 The fileprogress.pl script can be called by Ajax to display file
476 upload progress information to the user.  The upload state is updated
477 a maximum of once a second.
478
479 =item use_alias
480
481 If this is non-zero then an article with linkAlias set will use an
482 alias url instead of the "real" url.  You will need to configure a
483 RewriteRule or ErrorDocument to page.pl to direct the user to the
484 correct URL.  Default: 1.
485
486 =item warn_obsolete
487
488 Some obsolete tags will warn to stderr if this is non-zero.  Default:
489 don't warn.
490
491 =back
492
493 =head2 [mail]
494
495 This section controls how BSE sends email.
496
497 =over
498
499 =item smtp_server
500
501 The host or IP address of your mail server.  If this is not set
502 C<sendmail> will be used instead.  If this is set you must also set
503 I<helo>.
504
505 =item helo
506
507 The name that BSE uses to identify itself when sending mail via SMTP.
508 Required if I<smtp_server> is set.
509
510 =item sendmail
511
512 The path to the C<sendmail> binary.  Default: /usr/lib/sendmail
513
514 =item sendmail_opts
515
516 The options supplied to sendmail.  Default: -t -oi
517
518 You may want to add the -odq option to this if you want mail queued
519 rather than sent immediately.
520
521 =item set_errors_to_from
522
523 If true, we add an Errors-To header set to the same as the From
524 header.  Default: true.
525
526 =item html_system_email
527
528 If non-zero then emails sent via the compose mail system that aren't
529 being sent to a member record, will be sent as HTML, if the HTML
530 template is available.
531
532 =item inline_css
533
534 If this is C<style> (the default) then use CSS::Inliner to attempt to
535 inline CSS in mail if the text "<style" is found in the generated
536 HTML.
537
538 If this is C<force> then we always attempt to inline CSS.
539
540 If this is any other value then don't inline CSS.
541
542 =item inline_css_flags
543
544 A comma separated list of flags to supply to CSS::Inliner->new().
545 Reasonable flags are C<strip_attrs> to strip C<id> and C<class>
546 attributes, and C<leave_style> to leave the HTML style block in place.
547
548 Default: no flags.
549
550 =item inline_css_report
551
552 If this is true and CSS inlining fails, log an error to the audit
553 log. This is intended for use in debugging and should be disabled in
554 production.  Default: false (disabled)
555
556 =back
557
558 =head2 [children of I<id>]
559
560 Where I<id> is the identifier for an article.
561
562 =over
563
564 =item template
565
566 the name of the default template for children of the given parent
567
568 =item template_dirs
569
570 a comma-separated list of extra directories under $TMPLDIR to search
571 for templates that can be used for children of the given parent article.
572
573 =back
574
575 =head2 [article I<id>]
576
577 Where I<id> is the identifier of an article.
578
579 =over
580
581 =item template_dirs
582
583 A comma-separated list of extra directories under $TMPLDIR to search
584 for templates that can be used for children of the given parent
585 article.
586
587 =item extra_templates
588
589 A comma-separated list of extra templates under $TMPLDIR that can be
590 used for the given article.
591
592 =back
593
594 =head2 [level I<level>]
595
596 =over
597
598 =item template
599
600 The default template for this level of article, assuming it hasn't
601 been set in the [children of I<article id>] section.
602
603 =item template_dirs
604
605 A comma-separated list of extra directories under $TMPLDIR to search
606 for templates that can be used for articles at the given I<level>.
607
608 =back
609
610 =head2 [catalogs]
611
612 =over
613
614 =item template
615
616 The default template for catalogs.
617
618 =back
619
620 =head2 [products]
621
622 =over
623
624 =item template
625
626 The default template for products.
627
628 =item extra_templates
629
630 A comma separated list of extra templates that can be used for
631 products.
632
633 =back
634
635 =head2 [messages]
636
637 This can be used to control translation of error messages.  Each key
638 has a prefix identifying the module that uses the error, followed by
639 '/' followed by a specific identifier for the message.
640
641 Message parameters, expressed as $I<digit>, are replaced with the
642 parameters passed to the message.  C<$$> is replaced with C<$>.
643
644 Each message identifier below is documented with the id, when it
645 occurs, the default message, and any parameters.
646
647 =over
648
649 =item user/needlogon
650
651 the user attempted to logon without entering a logon name.  Default:
652 "Please enter a logon name".  No parameters.
653
654 =item user/needpass
655
656 the user attempted to logon without entering a password.  Default:
657 "Please enter your password."  No parameters.
658
659 =item user/baduserpass
660
661 the user's logon name or password was not found or did not match.
662 Default: "Invalid user or password".  No parameters.
663
664 =item user/notloggedon
665
666 the user attempted to logoff while not logged on.  Default: "You
667 aren't logged on".  No parameters.
668
669 =item user/optsoldpass
670
671 the user entered a new password on the options page without entering
672 their old password.  Default: "You need to enter your old password to
673 change your password".  No parameters.
674
675 =item shop/logonrequired
676
677 Displayed if the user attempts to checkout when [shop].require_logon
678 is true.
679
680 =back
681
682 =head2 [downloads]
683
684 =over
685
686 =item must_be_paid
687
688 if non-zero, the order must be marked as paid for before the file can
689 be downloaded.
690
691 =item must_be_filled
692
693 if non-zero the order must be marked as filled before the files can be
694 downloaded.
695
696 =item require_logon
697
698 if non-zero the user must be registered/logged on to download I<any>
699 file.
700
701 =item log_downufile
702
703 if non-zero, downloads of userfiles will be logged.  Default: 0
704
705 =item log_downufile_maxage
706
707 the maximum age of entries in the user file download log, in days.
708 Default: 30.
709
710 =back
711
712 =head2 [confirmations]
713
714 Control over confirmation emails.
715
716 =over
717
718 =item subject
719
720 The subject of email confirmation emails.  Default: Subcription
721 Confirmation.
722
723 =item from
724
725 The from field for the email.  Default: $SHOP_FROM
726
727 =back
728
729 =head2 [subscriptions]
730
731 Control over subscription messages.
732
733 =over
734
735 =item from
736
737 The from field for the email.  Default: $SHOP_FROM.
738
739 =item testname
740
741 Default for the "Test Name" field for sending test subscription
742 messages.
743
744 =item testemail
745
746 Default for the "Test Email" field for sending test subscription
747 messages.
748
749 =item testtextonly
750
751 Set to 1 if you want the "Test Text Only" box checked by default for
752 sending test subscription messages.
753
754 =item testing
755
756 Set to 0 to disable display of the test subscription messages portions
757 of the subscriptions send form.
758
759 =item text_link_inline
760
761 Set to format links as they appear in the text version of emails.
762 C<$1> is replaced with the title, C<$2> with the URL and C<$3> with
763 the index. C<$$> is replaced with '$'. Default: C<$1 [$3]>
764
765 =item text_link_list
766
767 Set to format links as they appear at the footer of the body text.  If
768 this is set to the empty string then no list appears. C<$1>, C<$2>,
769 C<$3>, C<$$> are replaced as for I<text_link_inline> and $n is
770 replaced with newline.  Default: C<[$3] $2>
771
772 =item text_link_list_prefix
773
774 A line of text produced above the list of URLs if there is one.
775 Default: C<----->. $n in this is replaced with newlines.
776
777 =back
778
779 For example, if the configuration is:
780
781   text_link_inline="$1" ($3)
782   text_link_list_prefix=$n$n-------
783   text_link_list=($3) "$1"$n  => $2
784
785 and the body text is:
786
787   doclink[3]
788   link[http://www.example.com/|Example]
789
790 the result will be:
791
792   "The Shop" (1)
793   "Example" (2)
794   
795   
796   -------
797   (1) "The Shop"
798     => http://www.yoursite.com/shop/index.html
799   (2) "Example"
800     => http://www.example.com/
801
802 =head2 [search]
803
804 =over
805
806 =item highlight_partial
807
808 If this is true then partial matches will be highlight in search
809 result excerpts.  Default: True
810
811 =item keep_inaccessible
812
813 If this is true then resulting articles that can't be accessed by the
814 user are listed in the search results.  Default: false.
815
816 =item wordre
817
818 The default regular expression used to match words in text during
819 indexing.  Default: \w+
820
821 =item wordre_I<fieldname>
822
823 The field specific word match regular expression for the built-in
824 search indexer.  Default: the value of C<wordre>.
825
826 =item indexer
827
828 Module used to build the search index.  Default: BSE::Index::BSE.
829
830 =item index_priority
831
832 For C<BSE::Index::BSE>, the optimization priority.  The default of
833 C<speed> builds the index in memory and is very fast, but can consume
834 a lot of memory.  Otherwise, set this to C<memory> to reduce memory
835 usage.
836
837 C<memory> priority index building requires that the C<DBM::Deep>
838 module be installed.
839
840 =item level
841
842 Articles with a higher level than this are indexed as their ancestor.
843 Default: C<$SEARCH_LEVEL> which defaults to 5.
844
845 =item case_sensitive
846
847 Level of case-sensitivity in the search engine.  This can be one of:
848
849 =over
850
851 =item *
852
853 C<none> - no case-sensitive searches
854
855 =item *
856
857 C<context> - case-sensitive if there are any upper-case characters in
858 the search string, case-insensitive otherwise.
859
860 =item *
861
862 C<controlled> - case-sensitive via a query parameter.  This is
863 currently not supported by the built-in search engie.
864
865 =back
866
867 Renegerate your search indexes after changing this value.  Default:
868 context.
869
870 =back
871
872 =head2 [search highlight]
873
874 Sets the prefix and suffix used for highlighting matches for different
875 fields.
876
877 These are used by the highlight_result, excerpt, pageTitle, author,
878 keywords and matchFile tags.
879
880 Each field has a prefix and suffix entry.  The key is
881 I<fieldname>_prefix or I<fieldname>_suffix.  For file fields this is
882 file_I<fieldname>_prefix and file_I<fieldname>_suffix.
883
884 The default prefix is <b>.  The default suffix is </b>.
885
886 For example you can do:
887
888   [search highlight]
889   body_prefix=<span class="searchfound">
890   body_suffix=</span>
891   
892 The default prefix and suffix can also be redefined:
893
894   [search highlight]
895   prefix=<mark>
896   suffix=</mark>
897
898 =head2 [shop]
899
900 =over
901
902 =item enabled
903
904 Used by some templates to check if the shop is enabled.  Set this to 1
905 to enable the shop, or 0 to disable it.
906
907 =item secureurl_articles
908
909 If this is false then shop articles will not use the secureurl as their 
910 baseurl.  Default: True
911
912 =item register_if_files
913
914 If true the customer is required to register before checkout if there
915 are any for sale files attached to products in the cart.  Default: True
916
917 =item require_logon
918
919 If true the customer is required to be logged on before checkout,
920 whether or not for sale files are attached to products in the cart.
921 Default: False.
922
923 =item payment_types
924
925 A comma-separated list of acceptable payment types.  Default: 0
926
927 The possible payment types are:
928
929 =over
930
931 =item *
932
933 0 - the user enters a credit card number, name and expiry date
934
935 =item *
936
937 1 - the customer will send a cheque
938
939 =item *
940
941 2 - contact customer for details
942
943 =item *
944
945 4 - paypal - see L<paypal.pod>
946
947 =back
948
949 Other types can be added by adding entries to the [payment type names]
950 and [payment type descs] sections.
951
952 =item address1
953
954 =item address2
955
956 =item address3
957
958 These are used by various shop templates to present an address that a
959 cheque payment should be sent to.
960
961 =item from
962
963 From email address for emails sent by the shop.  Overides $SHOP_FROM
964 in Constants.pm
965
966 =item to_name
967
968 To name for emailed orders sent by the shop.  Overrides $SHOP_TO_NAME
969 in Constants.pm
970
971 =item to_email
972
973 To email for emailed orders sent by the shop.  Overrides $SHOP_TO_EMAIL
974 in Constants.pm
975
976 =item bcc_email
977
978 BCC email address for order confirmation emails sent to the customer.
979 Default: No bcc.
980
981 =item noencrypt
982
983 If this is true then orders sent to you by the shop will not be
984 encrypted.  Enabling this disabled acceptance of credit card orders,
985 and the default for C<payment_types> will become C<1> instead or C<0>.
986
987 Please realize that other potentially commercially sensitive
988 information is being sent in the clear to a central location,
989 unencrypted.
990
991 =item email_order
992
993 If true, then the order is email to to_email, possibly with credit
994 card information included.  Default: $SHOP_EMAIL_ORDER.
995
996 =item display_I<field>
997
998 Used to translate the stored order field name into a presentation name
999 suitable for error messages.
1000
1001 =item cardprocessor
1002
1003 The name of a class to load to process credit card transactions online.
1004
1005 Currently this can be either DevHelp::Payments::Test or
1006 DevHelp::Payments::Inpho.
1007
1008 =item crypt_module
1009
1010 Name of the encryption module to use.  Default: $SHOP_CRYPTO.
1011
1012 =item crypt_signing_id
1013
1014 Id of the key to sign the order email with.  If this is non-empty then
1015 the email is signed even if [basic].sign is false.  Default:
1016 $SHOP_SIGNING_ID.
1017
1018 =item crypt_gpg
1019
1020 Path to the GnuPG program.  Default: $SHOP_GPG
1021
1022 =item crypt_passphrase
1023
1024 Passphrase of the key used to sign the email.  Default:
1025 $SHOP_PASSPHRASE.
1026
1027 =item show_card_type
1028
1029 If true, request the card type when requesting credit card
1030 information.  Default: False.
1031
1032 =item cart_entry_limit
1033
1034 Maximum number of entries in the cart.  This limits the number of
1035 distinct products (with options) in the cart, not the total
1036 quantities.  Default: Unlimited.
1037
1038 =item currency_code
1039
1040 The shop currency as a 3-letter currency code.  Default: AUD.
1041 Currencies other than "AUD" aren't supported by most of the system.
1042
1043 =item country_code
1044
1045 Set to non-zero if you're using country codes in the order country
1046 field.  If this is set then the delivCountry is supplied as is to
1047 various parts of the system, otherwise it is translated from a country
1048 name to a country code.  Default: 0.
1049
1050 =item require_fields
1051
1052 A comma separated list of extra fields to require during checkout.
1053 This is in addition to the usual fields required during checkout.
1054 Default: none.
1055
1056 =item require_delivery
1057
1058 If true, and the C<need_delivery> CGI parameter is true, treat the
1059 following delivery fields as required during checkout: delivFirstName,
1060 delivLastName, delivStreet, delivSuburb, delivPostCode and delivCountry.
1061 Default: true.
1062
1063 =item require_delivery_fields
1064
1065 If C<require_delivery> is true, and the C<need_delivery> CGI parameter
1066 is true, add the comma separated fields listed here to the required
1067 checkout fields list.  Default: none.
1068
1069 =back
1070
1071 =head2 [shipping]
1072
1073 =over
1074
1075 =item couriers
1076
1077 A space-separated list of modules under Courier::, e.g. "Fastway::Road
1078 AustraliaPost::Air". These will be made available as shipping methods
1079 on the checkout page.
1080
1081 =item quoted
1082
1083 If true then a default "Quote shipping charges later" shipping method
1084 will be added to the shipping methods list.
1085
1086 =item sourcepostcode
1087
1088 The post code from which products are shipped.
1089
1090 =item fastwayfranchisee
1091
1092 The name of the Fastway franchisee used to ship products from the
1093 sourcepostcode.
1094
1095 =item fastwayfranchiseecode
1096
1097 The Fastway franchisee code for the customer, if any.
1098
1099 =back
1100
1101 =head2 [Shop Order Validation]
1102
1103 This section can contain extra order validation information, including
1104 specifying required fields, display names and extra validation rules.
1105
1106 =head2 [fields]
1107
1108 =over
1109
1110 =item title_size
1111
1112 The maximum length of the article title field.  Default: 255.  Should
1113 not be set higher than this unless you change the database schema.
1114
1115 =back
1116
1117 =head2 [interest]
1118
1119 Controls the interest.pl script.
1120
1121 =over
1122
1123 =item notify
1124
1125 Email address that is notified of the interest.  Defaults to $SHOP_FROM.
1126
1127 =back
1128
1129 =head2 [debug]
1130
1131 Used for debugging.
1132
1133 =over
1134
1135 =item logon_cookies
1136
1137 When a user logs on, and the site url is different to the secure url
1138 BSE attempts to refresh to the other "side" of the site to set the
1139 same cookie.
1140
1141 BSE does some simple comparisons to attempt to determine whether the
1142 logon form was triggered on the secure side of the site (possibly from
1143 the shop) or on the insecure side.  Since CGI doesn't necessarily give
1144 us all the information required, it's possible it will guess wrong.
1145
1146 Setting this option to 1 will enable debugging information sent to
1147 standard error, which will be sent to the error log on Apache.  This
1148 probably isn't useful on IIS.
1149
1150 =item file_unlink
1151
1152 Reports errors to STDERR (hence to the error log on Apache) if there
1153 is a problem deleting the actual file when an attached file is
1154 removed.
1155
1156 =item mail_encryption
1157
1158 Reports debugging information to standard error while encrypting your
1159 mail.
1160
1161 =item cookies
1162
1163 Reports cookies received from the browser and sent to the browser to
1164 STDERR (hence to the error log on Apache.)
1165
1166 =item dump_session
1167
1168 If nonzero the session hash is dumped to STDERR after it is retrived
1169 from the database.
1170
1171 =item subscription_expiry
1172
1173 If non-zero then subscription expiry date calculations are dumped to
1174 STDERR.
1175
1176 =item jit_dynamic_regen
1177
1178 If non-zero then information about jit_dynamic_regen is sent to
1179 STDERR.
1180
1181 =item ifUserCan
1182
1183 If non-zero then the ifUserCan tag will output some trace information
1184 to STDERR.
1185
1186 =item trace_noimpl
1187
1188 Enables some trace messages from tags that return an ENOIMPL
1189 exception.  This can be useful for tracking down why a tag isn't being
1190 replaced.  This will produce a lot of output during page regeneration.
1191
1192 =back
1193
1194 =head2 [uri]
1195
1196 Contains various URIs.
1197
1198 This is underused, so don't rely on it yet.
1199
1200 =over
1201
1202 =item articles
1203
1204 =item cgi
1205
1206 The URI to the CGI directory.  Default: /cgi-bin
1207
1208 =item dist_images
1209
1210 The URI where images included with BSE can be found.
1211
1212 This includes images such as F<trans_pixel.gif> and C<admin/error.gif>.
1213
1214 Default: C</images>
1215
1216 =item images
1217
1218 The URI where managed images are kept which should correspond to
1219 C<images> in C<[paths]>.
1220
1221 Default: C</images> (from C<$Constants::IMAGES_URI>)
1222
1223 =item scalecache
1224
1225 The URL to the directory represented by scalecache.  Defaults to
1226 I<[uri].images>F</scaled>.
1227
1228 =item public_files
1229
1230 The URL to the directory configured as I<[paths].public_files>.
1231
1232 =item shop
1233
1234 =back
1235
1236 =head2 [articles]
1237
1238 This will provide translations from symbolic names to article ids.
1239
1240 Currently this is used for converting article ids in the access
1241 control code, and for looking up the id of the shop.
1242
1243 =head2 [printable type]
1244
1245 If the user supplies a template name to printable.pl then you can use
1246 a different content type by adding an entry to this section.  The key
1247 is the template name, and the value is the full content type.
1248
1249 =head2 [search index scores]
1250
1251 This section is used when generating the search index to override the
1252 default scores for each field in the articles.
1253
1254 The default scores are:
1255
1256   Field           Score  Notes
1257   -----           -----  -----
1258   title             5
1259   body              3
1260   keyword           4
1261   pageTitle         5
1262   author            4
1263   summary           0
1264   description       0    Products only
1265   product_code      0    Products only
1266   file_displayName  2    displayName for files
1267   file_description  2    description for files
1268   file_notes        1    notes for files
1269
1270 =head2 [article flags]
1271
1272 =head2 [product flags]
1273
1274 =head2 [catalog flags]
1275
1276 Flags that can be set for articles, products and catalogs
1277 respectively.  Note that flags for articles are also visible in
1278 products and catalogs.
1279
1280 All flag Ids are single letters or digits.  Uppercase letters are
1281 reserved for use by BSE internally, leaving lower-case letters and
1282 digits for your own use.
1283
1284 Use the id of the flag as the key, and a description of the flag as
1285 it's value.
1286
1287 =head2 [article uris]
1288
1289 Each key is an article id, the values are base URIs to store the HTML
1290 form of those articles and their children under.
1291
1292 =head2 [protect link]
1293
1294 The keys are ids of articles that shouldn't have their link field
1295 overwritten.  The value should be a true value, but is otherwise
1296 ignored.
1297
1298 =head2 [datadump]
1299
1300 =over
1301
1302 =item to
1303
1304 The recipient for the data dump email sent by datadump.pl. Default:
1305 $DATA_EMAIL.
1306
1307 =item from
1308
1309 the From for the data dump email sent by datadump.pl.  Default:
1310 $SHOP_FROM.
1311
1312 =back
1313
1314 =head2 [site users]
1315
1316 Configuration for site users.
1317
1318 =over
1319
1320 =item nopassword
1321
1322 If this is set to true then no passwords are required during
1323 registration, a confirmation email is sent immediately upon
1324 registration and that confirmation email contains a link the user can
1325 use to manage their details.
1326
1327 This option has some security concerns since it can leave links to the
1328 user's information in the browser history.  This option is not
1329 recommended.
1330
1331 You cannot use this to control access to the shop.
1332
1333 =item require_name1
1334
1335 =item require_name2
1336
1337 =item require_street
1338
1339 =item require_suburb
1340
1341 =item require_state
1342
1343 =item require_postcode
1344
1345 =item require_telephone
1346
1347 =item require_facsimile
1348
1349 =item require_country
1350
1351 =item require_title
1352
1353 =item require_organization
1354
1355 Set these to true to require the corresponding field during
1356 registration, and to keep it required after modification.  Default:
1357 false.
1358
1359 If you enable any of these, you should enable C<info_on_register> as
1360 well, or modify the registration template to include the given fields.
1361
1362 =item display_I<field name>
1363
1364 Controls how the given field is displayed in error messages.  If you
1365 change the field names on the registration and/or options forms you
1366 should probably change them here too.  Default: internal field name
1367 with the first character converted to upper-case.
1368
1369 =item info_on_register
1370
1371 If this is set then the user info is prompted for during user
1372 registration.  The information still isn't required unless the
1373 appropriate require_I<field> option is set.  Default: false.
1374
1375 =item register_refresh
1376
1377 The default URL to refresh to on completing registration if no r
1378 parameter is supplied.
1379
1380 =item subscribe_all
1381
1382 If this is set then the subcription checkboxes are all checked on
1383 registration by default.  Default: false.
1384
1385 The user will only receive the subscriptions if they leave them checked
1386 and follow the link in the confirmation email.
1387
1388 =item subscribe_I<id>
1389
1390 Where I<id> is the number identifying a subscription.  If this is set
1391 then the subscription checkbox for that subscription will be checked
1392 by default on the registration form.  Default: false.
1393
1394 The user will only receive the subscriptions if they leave it checked
1395 and follow the link in the confirmation email.
1396
1397 You can get the I<id> of a subcription by looking at the Edit link on the
1398 subscriptions management page, the number after "id=" is the id.
1399
1400 =item billing_on_main_opts
1401
1402 If set to zero then user billing options will be managed on a separate
1403 page.  This is controlled by the user/options_base.tmpl template.
1404
1405 =item user_register
1406
1407 If set to zero then users cannot register themselves.  Default: true,
1408 allowing users to register themselves.
1409
1410 =item notify_register
1411
1412 If true then an email is sent when a new user registers on your site.
1413 The email address sent to is the first set of [site
1414 users].notify_register_email, [shop].from or $SHOP_FROM from
1415 Constants.pm
1416
1417 No email is sent if a new user is created from the administration user
1418 interface.
1419
1420 See also: notify_register_email, notify_register_subject.
1421
1422 =item notify_register_email
1423
1424 The email to sent the registration notification too.  See
1425 notify_register above.
1426
1427 =item notify_register_subject
1428
1429 The subject of the notification email sent when a new user registers.
1430 Any {I<field>} is replaced with the given field from the registered
1431 user.  See notify_register above.
1432
1433 Default: New user {userId} registered
1434
1435 =item notify_register_customer
1436
1437 If non-zero then email id C<notify_register_customer> will be sent to
1438 new user on registration.  By default this uses template
1439 user/email_register, subject "Thank you for registering" which can be
1440 overridden in [email notify_register_customer] or via the
1441 C<set_subject> tag.
1442
1443 =item notify_register_customer_admin
1444
1445 If non-zero then the behaviour described for
1446 C<notify_register_customer> will take place when a new member is added
1447 by an administrator.  Defaults to the value of
1448 C<notify_register_customer>.
1449
1450 =back
1451
1452 =head2 [payment type names]
1453
1454 This section and [payment type descs] are used to configure new
1455 paymeny type ids.
1456
1457 The key is the integer representing the payment type.  The value is
1458 the name used in tags for checking the payment type.
1459
1460 You can also add a description (currently unused) to [payment type
1461 descs].
1462
1463 You should use numbers starting from 10 to avoid conflicts with future
1464 BSE payment types.
1465
1466 =head2 [payment type descs]
1467
1468 See [payment type names].
1469
1470 =head2 [payment type required]
1471
1472 Set the key given by the payment type id to a value of a
1473 comma-separated list of fields required for that payment type.
1474
1475 =head2 [help style I<style-name>]
1476
1477 This type of configuration section is used to set values for a style
1478 of help icon.  Only the C<template> and C<prefix> values are used
1479 directly by the code, the others are used by the default helpicon
1480 templates.
1481
1482 =over
1483
1484 =item prefix
1485
1486 The URI to the help files for this style.  Default: /help/ in style
1487 "user", /admin/help/ in style "admin".
1488
1489 =item template
1490
1491 The template used to produce the icon.  Default: helpicon in style
1492 user, admin/helpicon in style "admin".
1493
1494 =item icon
1495
1496 URI to the help icon image.   Default: /images/admin/help.gif
1497
1498 =item iconwidth
1499
1500 The width of the help icon image.  Default: 16
1501
1502 =item iconheight
1503
1504 The height of the help icon image.  Default: 16
1505
1506 =back
1507
1508 If you just want to change the help icon image for user help icons you
1509 might do:
1510
1511   [help style user]
1512   icon=/images/help.gif
1513
1514 =head2 [affiliate]
1515
1516 =over
1517
1518 =item allowed_referer
1519
1520 A semi-colon (;) separated list of referer domains that are allowed to
1521 link to the C<a_set> target of L<affiliate.pl>.
1522
1523 If the user's browser supplies a referer header then it will be
1524 checked against this list.
1525
1526 =item require_referer
1527
1528 If this is set then the C<a_set> target of L<affiliate.pl> will
1529 require that the user's browser supply a Referer header.
1530
1531 =item default_refresh
1532
1533 If no C<r> parameter is supplied to the C<a_set> target of
1534 L<affiliate.pl> then this is used as the default refresh.
1535
1536 Default: the site base url.
1537
1538 =item subscription_required
1539
1540 This is either the numeric or text of a subscription for which the
1541 affiliate must have an active subscription.
1542
1543 =item flag_required
1544
1545 A single letter flag which the site administrator must set for the
1546 affiliate page to be displayed for the given member.
1547
1548 =item set_cookie
1549
1550 If this is set then affiliate.pl will set the named cookie to the
1551 affiliate id.
1552
1553 =item other_cookies
1554
1555 This is a comma-separated list of other cookies that should be set by
1556 the a_set target.  The values for the cookies should be passed to the
1557 a_set target.  For example with:
1558
1559   [affiliate]
1560   other_cookies=alpha,beta
1561
1562 if the url:
1563
1564   http://your.site.com/cgi-bin/affiliate.pl?a_set=1&id=someid&alpha=1&beta=2&gamme=3
1565
1566 is accessed, then the cookie alpha is set to "1", beta is set to "2".
1567 The cookie gamma will not be set since it's not listed.
1568
1569 =item linkbaseurl
1570
1571 Used as the link base URL for the afflink.tmpl side bar template when
1572 an affiliate id is set.  Default: example.com
1573
1574 =item linkbasedesc
1575
1576 Used at the text of the link for the afflink.tmpl side bar template
1577 when an affiliate id is set.  Default: Your Site.
1578
1579 =item linkdefurl
1580
1581 Used as the link URL for the afflink.tmpl side bar template when an
1582 affiliate id is not set.  Default: example.com
1583
1584 =item linkdefdesc
1585
1586 Used as the text of the link for the afflink.tmpl side bar template
1587 when an affiliate id is not set.  Default: Our site
1588
1589 =back
1590
1591 =head2 [BSE Siteuser Images]
1592
1593 Each key is the id of a member image, with a corresponding [BSE
1594 Siteuser Image I<image_id>] section.  The values are ignored.
1595
1596 =head2 [BSE Siteuser Image I<image_id>]
1597
1598 Provides information about a single member image "template".
1599
1600 =over
1601
1602 =item description
1603
1604 Short description on the image, like "Logo".  Used in error messages.
1605
1606 =item help
1607
1608 Longer description of the image.  Accessible with the member_image tag.
1609
1610 =item minwidth
1611
1612 =item minheight
1613
1614 =item maxwidth
1615
1616 =item maxheight
1617
1618 The minimum and maximum dimensions of the image.
1619
1620 =item widthsmallerror
1621
1622 =item heightsmallerror
1623
1624 =item widthlargeerror
1625
1626 =item heightlargeerror
1627
1628 Error messages displayed in the when the image is outside the
1629 configured dimensions.
1630
1631 =item largeerror
1632
1633 =item smallerror
1634
1635 Default error messages for the above.
1636
1637 =item maxspace
1638
1639 Maximum storage the image can use in bytes.  Default: 1000000.
1640
1641 =item spaceerror
1642
1643 Error message displayed if the image uses too much storage.
1644
1645 =back
1646
1647 =head2 [editor]
1648
1649 Various editor settings.
1650
1651 =over
1652
1653 =item allow_thumb
1654
1655 If this is non-zero the system will attempt to load the configured
1656 thumbnail class, and put thumbnail images on the image manager page
1657 rather than full-size images.  Default: off
1658
1659 =item thumbs_class
1660
1661 The name of a perl class that implement's BSE's thumbnail API.  At
1662 this point the only class that implements that is BSE::Thumb::Imager,
1663 supplied with BSE.  Default: None
1664
1665 =item default_thumbnail
1666
1667 URI to the default thumbnail image.  This is presented when the
1668 runtime production of a thumbnail image fails.
1669
1670 =item default_thumbnail_width
1671
1672 =item default_thumbnail_height
1673
1674 Dimensions of the default thumbnail image.
1675
1676 =item default_thumbnail_alt
1677
1678 Alt text for the default thumbnail image.
1679
1680 =item check_modified
1681
1682 If this is true then BSE will check the value of the lastModified
1683 parameter passed against the value in the article.  If these don't
1684 match the article isn't saved and is redisplayed with an error
1685 message.  This provides simple protection against one user saving
1686 changes over those made by another.
1687
1688 =back
1689
1690 =head2 [thumbnails]
1691
1692 =over
1693
1694 =item max_width
1695
1696 =item max_height
1697
1698 =item max_pixels
1699
1700 Default values for the thumbimage tag.
1701
1702 =back
1703
1704 =head2 [includes]
1705
1706 Each value is used as the relative or absolute name of a file or
1707 directory to load more configuration data from.
1708
1709 The keywords must remain unique.
1710
1711 Only the [includes] section from bse.cfg itself is used to locate more
1712 configuration data.
1713
1714 If the value references a directory, all files with an extension of
1715 C<.cfg> are read for configuration data.
1716
1717 The order the files are read (which later files overriding older
1718 files) is:
1719
1720 =over
1721
1722 =item 1.
1723
1724 bse.cfg is read
1725
1726 =item 2.
1727
1728 the entries in [includes] are sorted alphabetically (or rather
1729 asciily), so an entry with key "A" is read before one with key "B",
1730 one with key "01" is read before "02", but key "10" would be read
1731 I<before> key "2".
1732
1733 =item 3.
1734
1735 if an entry is a file then that is read and the values merged.
1736
1737 =item 4.
1738
1739 if an entry is a directory, then that is scanned and the files found
1740 read alphabetically as above.
1741
1742 =back
1743
1744 =head2 [error_img]
1745
1746 This is used to configure the error icon displayed next to fields that
1747 fail validation.
1748
1749 =over
1750
1751 =item image
1752
1753 URI to the image file.
1754
1755 =item width
1756
1757 =item height
1758
1759 The width and height of the error icon image.
1760
1761 =back
1762
1763 =head2 [site user flags]
1764
1765 Flags that can be set for site users.
1766
1767 All flag Ids are single letters or digits.  Uppercase letters are
1768 reserved for use by BSE internally, leaving lower-case letters and
1769 digits for your own use.
1770
1771 Use the id of the flag as the key, and a description of the flag as
1772 it's value.
1773
1774 =head2 [article defaults]
1775
1776 =head2 [catalog defaults]
1777
1778 =head2 [product defaults]
1779
1780 These sections contain defaults values for the corresponding article
1781 types.
1782
1783 Each key is the name of a column for the article type.
1784
1785 If an entry is not found in [catalog defaults] then [article defaults]
1786 is also checked.
1787
1788 If an entry is not found in [product defaults] then [article defaults]
1789 is also checked.
1790
1791 These sections are checked B<after> the C<[children of >I<id>C<]> and
1792 C<[level >I<level>C<]> sections.
1793
1794 These defaults are used when creating an article where no value is
1795 supplied, they can also be accessed via the <:default I<name>:> tag.
1796
1797 =head2 [newsletter filters]
1798
1799 Contains C<criteria>I<index> entries starting from C<criteria1>, then
1800 C<criteria2>, etc.
1801
1802 Each entry consists of a filter class name, followed by a ; followed
1803 by data passed to that filter.
1804
1805   ; user the original SQL based filter, configured from 
1806   ; section [foo]
1807   criteria1=BSE::NLFilter::SQL;foo
1808
1809 See the documentation for each filter to configure the filters.
1810
1811 =head2 [Query Groups]
1812
1813 The key of each entry is the numeric identifier of a query group, the
1814 values are the name of the query group.  For example:
1815
1816   [query groups]
1817   1=some name
1818
1819   [query group some name]
1820   sql=select id from bse_siteusers where id = ? and name1 like '%some%'
1821
1822 Each entry also has a corresponding [Query Group I<name>] section.
1823
1824 =head2 [query group I<name>]
1825
1826 This section corresponds to an entry in [Query Groups].
1827
1828 =over
1829
1830 =item sql
1831
1832 This is an SQL statement.  One placeholder is required and is passed
1833 the siteuser id (primary key) of the user to be checked.  If this
1834 query returns I<any> rows then the user is considered part of the
1835 group.
1836
1837 =back
1838
1839 =head2 [template types]
1840
1841 Each key is a template name, the value is the content type to be used
1842 when displaying the template dynamically.
1843
1844 =head2 [template descriptions]
1845
1846 Each key is a template name, the value is a description used in the
1847 template dropdown for that template.
1848
1849 =head2 [body class]
1850
1851 This section defines CSS class names for BSE's body text link tags.
1852 The key is the tag name, the value is the CSS class to be used.
1853
1854 By default the class used is the same as the name of the tag, but you
1855 can switch this off by adding an entry setting the class to the empty
1856 string, for example:
1857
1858   ; no class attribute for any of the links
1859   [body class]
1860   link=
1861   poplink=
1862   doclink=
1863   popdoclink=
1864
1865 You can set p here too to set the class for paragraphs generated as
1866 body text.  By default no class is set.
1867
1868 =head2 [popimage]
1869
1870 Controls the behaviour of the window displayed by the popimage[] body
1871 text tag.  If the Javascript for this has been customized then this
1872 may not apply.
1873
1874 =over
1875
1876 =item extrawidth
1877
1878 =item extraheight
1879
1880 Extra width and height for the window beyond the size of the image.
1881 Default: no extra width or height.
1882
1883 =item popmiddle
1884
1885 If set to non-zero popimage[] will attempt to centre the popup within
1886 the current window.  Default: 0.
1887
1888 =back
1889
1890 =head2 [inpho]
1891
1892 This is used to configure the DevHelp::Payments::Inpho module.
1893
1894 =over
1895
1896 =item test
1897
1898 If this is set then the test parameters are used instead of the
1899 product values.
1900
1901 =item url
1902
1903 The URL to process requests through.  
1904
1905 Default: https://extranet.inpho.com.au/cc_ssl/process
1906
1907 =item user
1908
1909 Inpho supplied user name.
1910
1911 =item password
1912
1913 Inpho supplied password.
1914
1915 =item test_url
1916
1917 The URL to process test requests through.
1918
1919 =item test_user
1920
1921 The user to supply to test requests.
1922
1923 =item test_password
1924
1925 The password to supply to test requests.
1926
1927 =back
1928
1929 =head2 [custom]
1930
1931 This section controls whether some custom class methods are called:
1932
1933 =over
1934
1935 =item saveopts
1936
1937 If this is non-zero then siteuser_saveopts is called.
1938
1939 =back
1940
1941 =head2 [levelI<level> menus]
1942
1943 Where I<level> is the article level at which the defined menu options will be available.
1944 Configure each menu value and description as I<key> and I<value>.
1945
1946 =over
1947
1948 For example:
1949
1950   [level1 menus]
1951   0=Default
1952   1=Sidebar
1953   2=Footer
1954
1955 To create a menus using such values, use the "allkids_of" iterator "filter" option.
1956
1957 For example:
1958
1959   <:iterator begin allkids_of -1 filter: [menu] == 2 :>
1960
1961 =back
1962
1963 =head2 [title alias]
1964
1965 Enable the "titleAlias" article field and set which level it will be available.
1966
1967 =over
1968
1969 =item levelI<level>
1970
1971 Where I<level> is the article "level" for which the "titleAlias" field should be enabled.  To enable
1972 set the value to non-zero.
1973
1974 For example:
1975
1976   [title alias]
1977   level1=1
1978
1979 The "titleAlias" can be used as an alternate "short" title for the given article, especially useful
1980 for space critical iterated menus.  A template conditional can be used to display the "titleAlias" 
1981 in place of the article "title" when appropriate.
1982
1983 =back
1984
1985 =head2 [thumb geometries]
1986
1987 Each key represents a geometry identifier for use by the thumbimage[],
1988 gthumbimage[] body text tags and the <:thumbimage ...:>, <:gthumbimage
1989 ...:>, <:dthumbimage ...:> template tags.
1990
1991 The key is the geometry identifier, the value is the geometry string
1992 as follows.
1993
1994 The geometry string consists of:
1995
1996 =over
1997
1998 =item *
1999
2000 dimensions
2001
2002 =item *
2003
2004 crop flag - if present
2005
2006 =item *
2007
2008 optional fill
2009
2010 =back
2011
2012 The dimensions can be in any of the following forms:
2013
2014 =over
2015
2016 =item *
2017
2018 <width>x<height> - the desired maximum width and height. eg 200x150
2019
2020 =item *
2021
2022 <width>x - the desired width, with the height calculated
2023 proportionally based on the source image size
2024
2025 =item *
2026
2027 x<height> - the designed height, with the width calculated
2028 proportionally based on the source image size.
2029
2030 =item *
2031
2032 <size> - the desired maximum size in both directions. so "200" is
2033 equivalent to "200x200"
2034
2035 =back
2036
2037 The crop flag is a single letter "c", if present then the image should
2038 be scaled so the smaller dimension matches the requested size, and the
2039 longer dimension will be cropped to fit.
2040
2041 The fill if present is: fill(color) where color is a color recognized
2042 by the underlying graphics implementation.  This should be at least
2043 hex web colors without the #, eg fill(FF0000) will fill with red.
2044
2045 =head2 [thumb classes]
2046
2047 Each key represents a geometry identifier for use by the thumbimage[],
2048 gthumbimage[] body text tags and the <:thumbimage ...:>, <:gthumbimage
2049 ...:>, <:dthumbimage ...:> template tags.
2050
2051 The value is used as the class for the generated img tag.
2052
2053 =head2 [targets]
2054
2055 Each value represents a handler or script name for the <:dyntarget
2056 I<script> I<target> ...:> tag.
2057
2058 Each key has a TARGET version and a no-TARGET version, with the key
2059 suffixed with C<_n>.
2060
2061 The default C<nuser> target is C</cgi-bin/nuser.pl/user/TARGET>.  The
2062 default no-target C<nuser> is C</cgi-bin/nuser.pl/user>.
2063
2064 For other targets the default is
2065 C</cgi-bin/>I<script>C<.pl?a_TARGET=1> and
2066 C</cgi-bin/>I<script>C<.pl>.
2067
2068 The string C<TARGET> is replaced with the target specified in the
2069 dyntarget tag.
2070
2071 This, along with dyntarget is intended to allow a more "Web 2.0" type
2072 of access to BSE.  eg. you might set:
2073
2074   [targets]
2075   shop=/xshop/TARGET
2076   shop_x=/xshop/
2077
2078 and have a rewrite rule:
2079
2080   RewriteRule ^/xshop/(.*)$ /cgi-bin/nuser.pl/shop/$1 [PT]
2081
2082 =head2 [popimage class I<classname>]
2083
2084 This defines the settings for a class of images generated by the
2085 popimage[] and gpopimage[] body text markup tags.  For example, the
2086 settings for C<popimage[imageid|foo]> can be found in section
2087 C<[popimage class foo]>.
2088
2089 =over
2090
2091 =item html
2092
2093 The html generated for this class.  Tags of the form
2094 C<{>I<identifier>C<}> are replaced, where I<identifier> can be
2095 C<inline_> or C<outline_> followed by an image field name, for example
2096 C<inline_src> is the URL to the inline image.
2097
2098 Default: <a href="{outline_src}" rel="lightbox[id]" target="_blank"><img src="{inline_src}" alt="{inline_alt}" width="{inline_width}" height="{inline_height}" border="0" /></a>
2099
2100 The default may be tuned as needed.
2101
2102 =item inline
2103
2104 The inline image geometry.  Default: editor (the value used for
2105 thumbnails on the admin side)
2106
2107 =item outline
2108
2109 The outline image geometry.  If no value is supplied then the original
2110 image values are used.
2111
2112 =back
2113
2114 =head2 [mail resources]
2115
2116 Each key is the identifier of a file that can be attached to
2117 BSE::ComposeMail emails.  The value is comma separated filename,
2118 content type, inline status.
2119
2120 The files are searched for through the template search mechanism, so
2121 the filename can be relative to either the master or local templates
2122 directories.
2123
2124 If the content type is not supplied, if the filename end in gif, png
2125 or jpg the appropriate content type is used, otherwise
2126 application/octet-stream.
2127
2128 If the inline status is not supplied then images are considered
2129 inline, and other files arent.
2130
2131 =head2 [shop registration]
2132
2133 Each key represents a message id from attempts to checkout.  Except
2134 the all key which covers all cases.
2135
2136 If the C<all> key or the message id key is non-zero then the checkout
2137 page will redirect to registration instead of login if the cart or
2138 configuration requires that the user be logged in.
2139
2140 =head2 [template I<template-name>]
2141
2142 Settings for articles based on a particular template.
2143
2144 =over
2145
2146 =item no_cache_dynamic
2147
2148 Controls whether a cache-control: no-cache header will be produced.
2149 Can be overridden with the A and B article flags.  If not set the
2150 value of [article].no_cache_dynamic is used.
2151
2152 =back
2153
2154 =head2 [article]
2155
2156 Global settings for articles.
2157
2158 =over
2159
2160 =item no_cache_dynamic
2161
2162 Controls whether a cache-control: no-cache header will be produced.
2163 Can be overridden with the A and B article flags or [template
2164 I<template-name>].no_cache_dynamic.  If not set the value of
2165 [basic].no_cache_dynamic is used.
2166
2167 =back
2168
2169 =head2 [recaptcha]
2170
2171 For the <:recaptcha:> tag currently only used for fmail.pl.
2172
2173 =over
2174
2175 =item api_public_key
2176
2177 =item api_private_key
2178
2179 The public and private key you receive when you register with reCAPTCHA.
2180
2181 =item error_I<error_code>
2182
2183 Replace the error message for the given I<error_code> where
2184 I<error_code> is the reCAPTCHA error code
2185 (eg. "incorrect-captcha-sol") with dash replaced by underscore.
2186
2187 eg.
2188
2189   error_incorrect_captch_sol=VERY BAD INPUT
2190
2191 =back
2192
2193 =head2 [global file metadata]
2194
2195 Each key represents an item of metadata for files attached to
2196 articles.
2197
2198 The values are ignored.
2199
2200 For each key, extra information is defined in the [file metadata
2201 I<name>] section.
2202
2203 =head2 [file metadata I<name>]
2204
2205 Definition for the file metadata item I<name>.
2206
2207 =over
2208
2209 =item *
2210
2211 title - descriptive name of the metadata.  Defaults to I<name>.
2212
2213 =item *
2214
2215 rules - validation rules, separated by ;.  Custom rules can be defined
2216 in [file metadata validation].
2217
2218 =item *
2219
2220 ro - if non-zero the metadata cannot be modified directly by the admin
2221 (applications can still generate it). Default: writable.
2222
2223 =item *
2224
2225 type - the data type of the metadata, any of string, text, enum,
2226 integer, real, image.  If this is enum values must be defined and
2227 labels should be.  Default: string.
2228
2229 The types are:
2230
2231 =over
2232
2233 =item *
2234
2235 string - single line of text
2236
2237 =item *
2238
2239 text - one or more lines of text
2240
2241 =item *
2242
2243 integer - whole number
2244
2245 =item *
2246
2247 real - number with decimal points
2248
2249 =item *
2250
2251 enum - select from a list of possible values.
2252
2253 =item *
2254
2255 image - image file.
2256
2257 =back
2258
2259 =item *
2260
2261 values - semi-colon separated list of values for this metadata.
2262
2263 =item *
2264
2265 labels - semi-colon separated list of labels for the values
2266
2267 =item *
2268
2269 help - help html to display for the metadata
2270
2271 =item *
2272
2273 data_name - (images only) the key to use to store the image data.
2274 Default: I<name>_data.
2275
2276 =item *
2277
2278 width_name - (images only) the key to use to store the image width.
2279 Default: I<name>_width.
2280
2281 =item *
2282
2283 height_name - (images only) the key to use to store the image height.
2284 Default: I<name>_height.
2285
2286 =item *
2287
2288 cond - a perl expression indicating whether the metadata should be
2289 prompted for, for this file.  $file is the file object.  Default: 1.
2290
2291 =item *
2292
2293 unit - text displayed after the entry box for the metadata.  Default:
2294 empty.  Useful for including a unit ("pixels") or format help
2295 ("hh:mm").
2296
2297 =back
2298
2299 =head2 [session cleanup]
2300
2301 Controls the processing of the bse_session_clean.pl script.
2302
2303 =over
2304
2305 =item *
2306
2307 days - the minimum age in days of sessions to be removed.  Default: 30.
2308
2309 =item *
2310
2311 per - the number of records to remove per SQL delete request.
2312 Default: 1000.
2313
2314 =item *
2315
2316 count - the number of SQL delete requests to perform, maximum.
2317 Default: 1000.
2318
2319 =item *
2320
2321 optimize - whether to perform a table optimization after deleting
2322 records.  Default: 1 (set to 0 to skip optimization)
2323
2324 =back
2325
2326 =head2 [nightly work]
2327
2328 Controls the bse_nightly.pl script.
2329
2330 =over
2331
2332 =item *
2333
2334 jobs - a comma separated list of BSE background processes to run when
2335 bse_nightly.pl is run.  Default: bse_session_clean
2336
2337 =item *
2338
2339 I<other keys> - each key is a sort key, and the value is a single
2340 background task name.  This allows add-ons to setup extra tasks
2341 without overwriting each other.  The sugessted key format is:
2342
2343   99 - two digit priority - 00 is executed first, 99 last
2344   package-name - name of package the task is for
2345   unique - extra text to make the key unique, if necessary
2346
2347 =back
2348
2349 =head2 [cache]
2350
2351 Parameters controlling where cached information - eg. file upload
2352 progress is stored.
2353
2354 =over
2355
2356 =item *
2357
2358 class - the BSE::Cache compatible cache class.  See the documentation
2359 of BSE::Cache::Cache, BSE::Cache::CHI or BSE::Cache::Memcached.
2360
2361 =back
2362
2363 =head2 [db]
2364
2365 Database connection parameters.  These override the settings in
2366 Constants.pm which are deprecated.
2367
2368 =over
2369
2370 =item *
2371
2372 dsn - the DBI dsn used to connect to the database. Default:
2373 $Constants::DSN.
2374
2375 =item *
2376
2377 user - the logon to the database.  Default: $Constants::UN
2378
2379 =item *
2380
2381 password - the password for the user.  Default: $Constants::PW.
2382
2383 =item *
2384
2385 dbopts - a perl expression that should evaluate to a hash reference.
2386 Default: $Constants::DBOPTs, or an empty hashref.
2387
2388 =item *
2389
2390 class - the database wrapper class to use.  Default: BSE::DB::Mysql.
2391 No other values are currently supported.
2392
2393 =back
2394
2395 =head2 [extra a_config]
2396
2397 Defines extra configuration to be returned from the BSE system
2398 configuration.
2399
2400 Each key is the keyword in the returned JSON object.  If the key
2401 already exists it is not overwritten.
2402
2403 Each value is the name of a section in the BSE configuration.  The
2404 strings "{level}", "{generator}", "{parentid}", "{template}" are
2405 replaced with their values from the article that config is being
2406 requested for.
2407
2408 So:
2409
2410   [extra a_config]
2411   menu=level{level} menu
2412
2413   [level1 menu]
2414   alpha=One
2415   beta=Two
2416
2417 will include:
2418
2419   menu: { alpha: "One", beta: "Two" }
2420
2421 in the returned configuration
2422
2423 =head2 [cookie names]
2424
2425 This section maps BSE's default cookie names to alternate names.  This
2426 can be useful if you have two BSE sites under the same domain and need
2427 to ensure they use different cookies.
2428
2429 eg.
2430
2431   [cookie names]
2432   userid=altuserid
2433
2434 =head2 [siteuser updates]
2435
2436 Each key identifies an update specification for userupdate.pl, the
2437 value is a description of the specification.
2438
2439 See L<< [siteuser update I<specid>] >> for the rest of the import
2440 specification.
2441
2442
2443 =head2 [siteuser update I<specid>]
2444
2445 Currently contains only a single key:
2446
2447 =over
2448
2449 =item *
2450
2451 fields - a semi-colon separated list of fields to import.  Must
2452 contain one of C<id> or C<userId> which is used as a key to identify
2453 the user to update.  An C<x> entry is a field to ignore.  Some fields,
2454 such as C<confirmed> may not appear in this list.
2455
2456 =back
2457
2458 =head2 [paypal]
2459
2460 Configuration for BSE's PayPal integration.
2461
2462 It shouldn't be necessary to change any of the URLs.
2463
2464 =over
2465
2466 =item *
2467
2468 test - if true, then the PayPal sandbox is used, and the configuration
2469 entries starting in C<test_> are used.  If false, PayPal is live, and
2470 configuration entries starting in C<live_> are used.  Default: 1.
2471
2472 =item *
2473
2474 test_api_username, test_api_password, test_api_signature - API
2475 credentials for test mode.  Required in test mode.
2476
2477 =item *
2478
2479 live_api_username, live_api_password, live_api_signature - API
2480 credentials for live mode.  Required for live mode.
2481
2482 =item *
2483
2484 test_ws_url - URL to make NVP requests through in test mode.  Default:
2485 https://api-3t.sandbox.paypal.com/nvp
2486
2487 =item *
2488
2489 test_refresh_url - PayPal URL to refresh to in test mode.  Default:
2490 https://www.sandbox.paypal.com/webscr
2491
2492 =item *
2493
2494 live_ws_url - URL to make NVP requests through in live mode.  Default:
2495 https://api-3t.paypal.com/nvp
2496
2497 =item *
2498
2499 live_refresh_url - PayPal URL to refresh to in live mode.  Default:
2500 https://www.paypal.com/cgibin/webscr
2501
2502 =back
2503
2504 =head2 [paypal custom]
2505
2506 Extra parameters supplied to the SetExpressCheckout API.  See the
2507 Express Checkout Advanced Features Guide (from PayPal) for details.
2508
2509 Some settings that may be useful:
2510
2511 =over
2512
2513 =item *
2514
2515 PAGESTYLE - the style of payment page to use from those listed in your
2516 account profile.
2517
2518 =item *
2519
2520 HDRIMG - https URL to an image to use in the payment page header.
2521
2522 =item *
2523
2524 HDRBACKCOLOR - a 6 hex digit color to use as the background of the
2525 payment page header.
2526
2527 =item *
2528
2529 HDRBORDERCOLOR - a 6 hex digit color to use as the border of the
2530 payment page header.
2531
2532 =back
2533
2534 =head2 [audit log]
2535
2536 =over
2537
2538 =item *
2539
2540 mail - if non-zero any emails sent through BSE::ComposeMail are logged
2541 in the audit log.  Default: 0.
2542
2543 =item *
2544
2545 mail_max_dump - if non-zero this is the size limit of the dump stored
2546 in the audit log when [audit log].mail is enabled.  Default: 50000.
2547
2548 =back
2549
2550 =head2 [audit log I<facility>]
2551
2552 Most commonly C<[audit log bse]>.  Controls whether given events or
2553 families of events are logged.
2554
2555 The key is one of:
2556
2557 =over
2558
2559 =item I<component>
2560
2561 =item I<component>C<:>I<module>
2562
2563 =item I<component>C<:>I<module>C<:>I<function>
2564
2565 =back
2566
2567 with the longer keys overriding the shorter keys, and defaulting to
2568 all actions being logged.
2569
2570 =head2 [mail audit log]
2571
2572 This enables sent when an event is logged in the audit log.  Warning:
2573 for common events this will result in large amounts of email.
2574
2575 =over
2576
2577 =item *
2578
2579 to - the email address to send the email to
2580
2581 =item *
2582
2583 emerg, alert, crit, error, warning, notice, info, debug - if present
2584 and true then events at these levels result in an email.  If the value
2585 contains an C<@> then the value is used as the recipient address.
2586
2587 =item *
2588
2589 I<facility>-I<component>
2590
2591 =item *
2592
2593 I<facility>-I<component>-I<module>
2594
2595 =item *
2596
2597 I<facility>-I<component>-I<module>-I<function>
2598
2599 Controls sending an email for specific events or families of events.
2600 If the value is true, send an email for that event.  If the value
2601 contains an C<@> then the value is used as the recipient address.
2602
2603 =back
2604
2605 with the longer keys overriding the shorter keys, and defaulting to
2606 all actions being logged.
2607
2608 =head2 [html tidy]
2609
2610 Contains options to pass to HTML::Tidy.  Anything not listed below is
2611 passed directly to HTML::Tidy->new.
2612
2613 =over
2614
2615 =item *
2616
2617 ignore_types - types of message to ignore separated by commas, any,
2618 all or none of info, warning, error.
2619
2620 =item *
2621
2622 ignore_text_I<key> - messages to ignore, I<key> is not used, just the
2623 value.
2624
2625
2626 =back
2627
2628 =head2 [email I<token>]
2629
2630 Controls emails sent via F<cgi-bin/admin/sendemail.pl>.
2631
2632 =over
2633
2634 =item *
2635
2636 template - plain text template
2637
2638 =item *
2639
2640 html_template - HTML template (defaults to the value of I<template>
2641 followed by C<_html>
2642
2643 =item *
2644
2645 subject - subject of the email, can be overridden with the
2646 C<set_subject> tag.
2647
2648 =item *
2649
2650 from - from email address, defaults to the shop from address
2651
2652 =item *
2653
2654 from_name - from name
2655
2656 =item *
2657
2658 allow_html - controls whether HTML is allowed.  By default this is
2659 based on the user's settings.
2660
2661 =back
2662
2663 =head2 [lost password]
2664
2665 =over
2666
2667 =item *
2668
2669 daily_limit - the number of recovery attempts permitted per day.
2670 Default: 3.
2671
2672 =item *
2673
2674 age_limit - the id included in the email is valid for this many days.
2675 Default: 7.
2676
2677 =back
2678
2679 =head2 [link replacement]
2680
2681 For formatted text, this is a list of URL prefixes to replace.
2682
2683 The key is a sort key, replacements are checked in alphabetical order.
2684
2685 The value is the original prefix, followed by ";", followed by the
2686 replacement.
2687
2688 Replacement is performed case-insenitively.  Regexp metacharacters
2689
2690 =head2 [article categories]
2691
2692 =over
2693
2694 =item *
2695
2696 ids - a comma separated list of category ids.  There are (currently)
2697 no restrictions on the contents of these ids, but alphanumerics are
2698 recommended to simplify templates.
2699
2700 =item *
2701
2702 I<id> - a description for a particular category id.  Overridden by the
2703 C<name> key in C<< [article category I<id>] >>.  Default: ucfirst of
2704 the id.
2705
2706 =back
2707
2708 =head2 [article category I<id>]
2709
2710 =over
2711
2712 =item *
2713
2714 name - name of the article category.
2715
2716 =back
2717
2718 Other keys may be used as desired, eg. to make it simpler to configure
2719 article behaviour based on the category.
2720
2721 =head2 [article menu]
2722
2723 This section can be used to add new menu items to the menu displayed
2724 on article edit pages.
2725
2726 The keys are used for sorting only.
2727
2728 The value is comma-separated:
2729
2730 =over
2731
2732 =item *
2733
2734 target script name
2735
2736 =item *
2737
2738 target identifier, to be set to 1 on making a request to the script.
2739
2740 =item *
2741
2742 the label for the item in the menu.
2743
2744 =back
2745
2746 eg.
2747
2748   sample,a_foo,Sample Item
2749
2750 will generate a link like:
2751
2752   <a href="/cgi-bin/admin/sample.pl?id=10&amp;a_foo=1">Sample Item</a>
2753
2754 where 10 is the id of the article being edited.
2755
2756 Keys with a prefix of C<bse_> are reserved for BSE internal use.
2757
2758 =head2 [undeletable articles]
2759
2760 Keys are the ids of articles that may not be deleted.
2761
2762 This applies if the value of the entry is a true perl value.
2763
2764   [undeletable articles]
2765   1=home page
2766   2=more home page
2767   ; article 3 is deletable
2768   3=
2769
2770 =head2 [dummy shipping methods]
2771
2772 Configures extra shipping methods only selectable from the order
2773 detail page.
2774
2775 Entries are sorted by value.
2776
2777 If the value contains a comma the text up to the comma is removed and
2778 the remains used as the label, otherwise the key is used as the label.
2779
2780 =head2 [article custom fields]
2781
2782 =head2 [product custom fields]
2783
2784 =head2 [catalog custom fields]
2785
2786 These can be used to define article, product and catalog custom fields
2787 respectively, in a similar manner to L<formmail>.
2788
2789 The field names are predefined, C<customDate1>, C<customDate2>,
2790 C<customInt1>, C<customInt2>, C<customInt3>, C<customInt4>,
2791 C<customStr1> and C<customStr2>, but are only active if a description
2792 is defined for the field:
2793
2794   [article custom fields]
2795   customInt1_description=Stock Level
2796
2797 =head2 [siteuser passwords]
2798
2799 Rules for validating (not verifying) site user passwords.  Possible
2800 keys are:
2801
2802 =over
2803
2804 =item *
2805
2806 C<length> - the minimum length of passwords.  This replaces
2807 C<minpassword> in C<[basic]>.
2808
2809 =item *
2810
2811 C<entropy> - the minimum password entropy as measured by
2812 L<Data::Password::Entropy>.
2813
2814 =item *
2815
2816 C<symbols> - if non-zero, the password must contain non-alphanumerics.
2817
2818 =item *
2819
2820 C<digits> - if non-zero, the password must contain digits.
2821
2822 =item *
2823
2824 C<mixedcase> - if non-zero, the password must contain both upper and
2825 lower case letters.
2826
2827 =item *
2828
2829 C<categories> - the number of categories out of 5 required out of
2830 symbols, digits, upper case, lower case and extended ASCII/Unicode.
2831 This should typically never be 5.
2832
2833 =item *
2834
2835 C<notuser> - the password and user name may not match each other
2836 case-insensitively.
2837
2838 =item *
2839
2840 C<notu5er> - the password may not match the user name
2841 case-insensitively, even with symbol replacement (e.g. "5" for "S".
2842
2843 =back
2844
2845 =head2 [admin user passwords]
2846
2847 Rules for validating (not verifying) administrative user passwords.
2848 See L</[siteuser passwords]> on the keys that can be set.
2849
2850 =head2 [site user lockouts]
2851
2852 Controls when accounts and IP addresses are locked out due to repeated
2853 site user authentication failures.
2854
2855 =over
2856
2857 =item *
2858
2859 I<account maximum failures> - the maximum number of login failures for
2860 a given account in I<account time period>.  A successful login of the
2861 account resets the count.  Default: 3.
2862
2863 =item *
2864
2865 C<account_time_period> - the number of minutes in which
2866 C<account_maximum_failures> login failures occurring will cause an
2867 account lock-out. Default: 10.
2868
2869 =item *
2870
2871 C<account_lockout_time> - the number of minutes to lock out an account
2872 that fails too many logins. Default: 60.
2873
2874 =item *
2875
2876 C<ip_maximum_failures> - the maximum number of login failures for a
2877 given IP address with-in C<ip_time_period>.  A successful login of any
2878 account at the IP address resets the count.  Default: 10.
2879
2880 =item *
2881
2882 C<ip_time_period> - the number of minutes in which
2883 C<ip_maximum_failures> login failures occurring causes an IP address
2884 lock-out. Default: 30.
2885
2886 =item *
2887
2888 C<ip_lockout_time> - the number of minutes to lock out an IP
2889 address that fails too many logins. Default: 120.
2890
2891 =item *
2892
2893 C<ip_maximum_failures2> - the maximum number of login failures for a
2894 given IP address with-in C<ip_time_period>.  A successful login of any
2895 account at the IP address I<does not reset> the count. Default: 50.
2896
2897 =item *
2898
2899 C<ip_lockout_time2> - the number of minutes to lock out an IP address
2900 that fails too many logins against C<ip_maximum_failure2>. Default:
2901 120.
2902
2903 =back
2904
2905 Note: an administrator unlocking an account resets the account lock
2906 count but has no effect on the IP address lock count.  An
2907 administrator unlocking an IP address resets both IP address lock
2908 counts, but has no effect on account lock counts.
2909
2910 =head2 [admin user lockouts]
2911
2912 Control account and IP address lockouts for admin user authentication.
2913
2914 See L</[site user lockouts]> for details of the configuration
2915 possible.
2916
2917 =head2 [pregenerate]
2918
2919 Defines templates to be generated as base templates.
2920
2921 Each entry is of the form:
2922
2923 =over
2924
2925 I<output-template>=I<profile-name>,I<input-template>
2926
2927 =back
2928
2929 where:
2930
2931 =over
2932
2933 =item *
2934
2935 I<output-template> - the output template name, stored in the directory
2936 defined by [paths].templates
2937
2938 =item *
2939
2940 I<profile-name> - used to select a section in the config file to load
2941 dummy article settings from, as C<< [I<profile-name> settings] >>.
2942
2943 =item *
2944
2945 I<input-template> - the source template to generate from.
2946
2947 =back
2948
2949 =head1 AUTHOR
2950
2951 Tony Cook <tony@develop-help.com>
2952
2953 =cut