-
=head1 NAME
config.pod - documents BSE configuration file options
Default: no front-end server configured.
+=item secret
+
+A secret used (currently) for hashing cookie values passed between the
+secure and non-secure parts of the site. This must be set. A
+suitable value can be created with:
+
+ openssl rand -base64 32
+
=back
=head2 [paths]
Local search path for BSE::Custom, or the class configured by
C<custom_class> in [basic].
+=item scalecache
+
+The directory where cached versions of scaled thumbnails are stored.
+Defaults to I<[paths].images>F</scaled>. This must be in the document tree. If
+you set this you should also set I<[uri].scalecache>.
+
=item siteuser_images
Where uploaded siteuser images are stored. This must be set in the
Pregenerated dynamic article pages are stored here. This must be
defined if you site contains any dynamicly generated pages.
-=item scalecache
-
-The directory where cached versions of scaled thumbnails are stored.
-Defaults to image_dir/scaled. This must be in the document tree. If
-you set this you should also set scalecacheurl.
-
-=item scalecacheurl
+=item public_files
-The URL to the directory represented by scalecache. Defaults to
-/images/scaled.
+The directory to store public BSE::TB::File content in (currently used
+for application specific files.)
=back
Catalog editor page. Default admin/edit_catalog.tmpl
-=item 1
+=item Z<>1
-=item 2
+=item Z<>2
-=item 3
+=item Z<>3
-=item 4
+=item Z<>4
-=item 5
+=item Z<>5
Article edit pages. Default admin/edit_<number>.tmpl
Validation errors and warnings are sent to the audit log. See [html
tidy].
+=item tagformat
+
+The default tag formatting to use for C<< <:= ... :> >> tags.
+Default: C<html>.
+
+=item formatter_image_class
+
+The default class to use for image[...] tags in body text. Default:
+C<bse_image_inline>.
+
=back
=head2 [basic]
=over
-=item cookie_lifetime
+=item access_control
-The expiry time for cookies. This should be in the form supported by
-CGI.pm for the -expires parameter. Typically you want a plus ('+'), a
-number, and a time character (s - seconds, m - minutes, h - hours, d -
-days, M - months). Default: +3h
+If this is true then the user/group/permissions database is used to
+control access to the system. Default: False.
-=item cookie_domain
+=item access_filter_parents
-This overrides the domain value set for cookies. This is useful if
-you allow the site to run under both example.com and www.example.com,
-if you set cookie_domain to example.com then a user visiting
-www.example.com will still have their cookies when they visit
-example.com.
+If this is true, then the drop-down lists of possible parents on the
+newsletter edit pages are filtered for access control.
+Default: False.
-=item cookie_name
+=item access_filter_steps
-This overrides the cookie name used to store the session id. Default:
-sessionid. This is useful when you have 2 sites under the same
-top-level domain, and helps disambiguate the cookie returned by the
-browser.
+If this is true, then the drop-down lists of possible stepparents and
+stepchildren on the article edit pages are filtered for access control.
+Default: False.
-=item minpassword
+=item alias_prefix
-Minimum password length in characters. Default: 4.
+The prefix applied to articles that use a linkAlias url. This should
+start with a /.
-=item randomdata
+=item alias_recursive
-Device to read random data from. This device should not block when it
-runs out of entropy.
+If this is non-zero then the link is formed by the C<alias_prefix>,
+followed by slash (C</>) separated aliases from the ancestors starting
+from the section, followed by the C<alias_suffix>. You may need to
+change your redirect handling if you enable this. Default: Off.
-=item sign
+=item alias_suffix
-If this is true then the encrypted messages containing the customer's
-credit card number are sent to the shop owner signed. To avoid
-keeping a passphrase and signing key on the server you can set this to
-false (0). This has the effect that anyone could send you an unsigned
-message encrypted with your public key, though this may not be a
-security threat. Default: True.
+If this is non-zero then the title is cleaned up (all but
+alphanumerics removed) and appended to the alias URL generated.
-=item link_titles
+=item all_dynamic
-If this is true then the links to your articles within BSE will be
-followed by a / and then by a simplified version of the article title.
-The aim is to include at least some title information in the URL
-without modifying the name of the HTML file. Default: False.
+If true then all articles are treated as dynamic. Default: false.
-=item access_control
+=item auto_images
-If this is true then the user/group/permissions database is used to
-control access to the system. Default: False.
+By default, if the author doesn't use any image tags, BSE will insert
+any unnamed article images into the body text of an article. You can
+disable this on a per-article basis in the image tool, or disable it
+globally by setting C<auto_images> to 0.
-=item access_filter_steps
+An alternative is to set C<imagePos> in C<[article defaults]> to
+C<xx> which will default articles to not auto-inserting images.
-If this is true, then the drop-down lists of possible stepparents and
-stepchildren on the article edit pages are filtered for access control.
-Default: False.
+=item cache_templates
-=item access_filter_parents
+If true, BSE will cache compiled templates using the configured BSE
+cache, if any. Depending on the configured cache this may slow things
+down. Default: disabled.
-If this is true, then the drop-down lists of possible parents on the
-newsletter edit pages are filtered for access control.
-Default: False.
+=item cache_templates_locally
-=item server_auth
+If true, BSE will cache compiled templates in memory. This may
+significantly improve performance but may increase memory use.
+Default: disabled.
-Set this to non-zero to enable authentication via server
-authentication (usually Basic Authentication.) You should normally
-set this if you set htusers below. Default: 0 (disabled)
+=item cache_thumbnails
-=item htusers
+If set to zero the results of the thumbimage/gthumbimage body/template
+tags will not be cached. Default: 1 (caching is enabled).
-This should be the path to a file to be updated with the list of users
-and crypt() versions of their passwords. If this is set then the
-security system will check for a user set by the browser before
-attempting a form based logon. Default: None.
+=item cookie_domain
+
+This overrides the domain value set for cookies. This is useful if
+you allow the site to run under both example.com and www.example.com,
+if you set cookie_domain to example.com then a user visiting
+www.example.com will still have their cookies when they visit
+example.com.
+
+=item cookie_lifetime
+
+The expiry time for cookies. This should be in the form supported by
+CGI.pm for the -expires parameter. Typically you want a plus ('+'), a
+number, and a time character (s - seconds, m - minutes, h - hours, d -
+days, M - months). Set to an empty string for session cookies.
+Default: +3h
+
+=item cookie_name
+
+This overrides the cookie name used to store the session id. Default:
+sessionid. This is useful when you have 2 sites under the same
+top-level domain, and helps disambiguate the cookie returned by the
+browser.
=item custom_class
used for article editing customizations. This class should derive
from BSE::CustomBase. Default: BSE::Custom.
-=item jit_dynamic_pregen
+=item default_popupimage
-If this is true, then pre-generation for dynamic pages will be delayed
-until the page is displayed to a user. Default: off.
+This is the default popup image class for the popimage[] and
+gpopimage[] tags. Default: popup.
-=item staticajax
+=item dynamic_access_filter
-If true, the ifAjax and ajax tags will be active for static pages.
+If set to 0, dynamic article iterators will no access control filter
+their results. Default: 1.
-=item cache_thumbnails
+=item error_not_defined
-If set to zero the results of the thumbimage/gthumbimage body/template
-tags will not be cached. Default: 1 (caching is enabled).
+If non-zero, during dynamic page generation, inserts a message
+explaining which variable is not set, instead of just leaving the tag
+unreplaced. Default: 1.
-=item static_thumbnails
+=item http_only_session
-If true and cache_thumbnails is true then thumbnails for the thumbnail
-cache will be generated when a static page is regenerated, and the
-link from the page will link to the image in the cache rather than to
-C<thumb.pl>. Default: 1 (static thumbnails enabled).
+If this is non-zero, the default, the session cookie sent to the
+browser has the C<HttpOnly> attribute set. This can prevent session
+cookie hijacking. Default: 1.
-=item alias_prefix
+=item htusers
-The prefix applied to articles that use a linkAlias url. This should
-start with a /.
+This should be the path to a file to be updated with the list of users
+and crypt() versions of their passwords. If this is set then the
+security system will check for a user set by the browser before
+attempting a form based logon. Default: None.
-=item use_alias
+=item index_file
-If this is non-zero then an article with linkAlias set will use an
-alias url instead of the "real" url. You will need to configure a
-RewriteRule or ErrorDocument to page.pl to direct the user to the
-correct URL. Default: 1.
+The name of the file to generate for static articles when the link is
+terminated by "/". Default: C<index.html>.
-=item alias_suffix
+=item jit_dynamic_pregen
-If this is non-zero then the title is cleaned up (all but
-alphanumerics removed) and appended to the alias URL generated.
+If this is true, then pre-generation for dynamic pages will be delayed
+until the page is displayed to a user. Default: off.
-=item alias_recursive
+=item link_titles
-If this is non-zero then the link is formed by the C<alias_prefix>,
-followed by slash (C</>) separated aliases from the ancestors starting
-from the section, followed by the C<alias_suffix>. You may need to
-change your redirect handling if you enable this. Default: Off.
+If this is true then the links to your articles within BSE will be
+followed by a / and then by a simplified version of the article title.
+The aim is to include at least some title information in the URL
+without modifying the name of the HTML file. Default: False.
-=item default_popupimage
+=item make_userid_cookie
-This is the default popup image class for the popimage[] and
-gpopimage[] tags. Default: popup.
+If this is non-zero, the default, then when the site member logs in, a
+javascript visible cookie, C<userid> will be set that contains the
+login name of the user. BSE's back-end doesn't use this cookie, its
+only use is for Javascript to enable/disable user interface elements.
+Default: 1.
-=item warn_obsolete
+=item minpassword
-Some obsolete tags will warn to stderr if this is non-zero. Default:
-don't warn.
+Previously the minimum length of site user passwords in characters.
+You must now set C<length> in C<[siteuser passwords]>.
=item no_cache_dynamic
I<templatename>C<].no_cache_dynamic> and [article].no_cache_dynamic.
Default: 1.
-=item redir_to_alias
+=item preload_template
-If true then page.pl will 301 redirect (Moved Permanently) requests
-for an article by its id to the generated link if the article has a
-link alias. Default: false. Must only be used with use_alias true.
-
-=item track_uploads
+Preload the named template, searching the template search part. Any
+text that would normally be produced by the preloaded template is
+ignored. This can be useful for common definitions and variables for
+use in many templates. Default: none.
-If this is non-zero, and a cache is configured (see [cache]), file
-uploads are tracked in entries in the cache.
+=item randomdata
-The fileprogress.pl script can be called by Ajax to display file
-upload progress information to the user. The upload state is updated
-a maximum of once a second.
+Device to read random data from. This device should not block when it
+runs out of entropy.
-=item http_only_session
+=item redir_to_alias
-If this is non-zero, the default, the session cookie sent to the
-browser has the C<HttpOnly> attribute set. This can prevent session
-cookie hijacking. Default: 1.
+If true then page.pl will 301 redirect (Moved Permanently) requests
+for an article by its id to the generated link if the article has a
+link alias. Default: false. Must only be used with use_alias true.
=item secure_session
visible over https. This is only useful when the only URL the site is
visited over is a https URL. Default: 0.
-=item make_userid_cookie
+=item server_auth
-If this is non-zero, the default, then when the site member logs in, a
-javascript visible cookie, C<userid> will be set that contains the
-login name of the user. BSE's back-end doesn't use this cookie, its
-only use is for Javascript to enable/disable user interface elements.
-Default: 1.
+Set this to non-zero to enable authentication via server
+authentication (usually Basic Authentication.) You should normally
+set this if you set htusers below. Default: 0 (disabled)
-=item dynamic_access_filter
+=item sign
-If set to 0, dynamic article iterators will no access control filter
-their results. Default: 1.
+If this is true then the encrypted messages containing the customer's
+credit card number are sent to the shop owner signed. To avoid
+keeping a passphrase and signing key on the server you can set this to
+false (0). This has the effect that anyone could send you an unsigned
+message encrypted with your public key, though this may not be a
+security threat. Default: True.
-=item index_file
+=item staticajax
-The name of the file to generate for static articles when the link is
-terminated by "/". Default: C<index.html>.
+If true, the ifAjax and ajax tags will be active for static pages.
+
+=item static_thumbnails
+
+If true and cache_thumbnails is true then thumbnails for the thumbnail
+cache will be generated when a static page is regenerated, and the
+link from the page will link to the image in the cache rather than to
+C<thumb.pl>. Default: 1 (static thumbnails enabled).
+
+=item track_uploads
+
+If this is non-zero, and a cache is configured (see [cache]), file
+uploads are tracked in entries in the cache.
+
+The fileprogress.pl script can be called by Ajax to display file
+upload progress information to the user. The upload state is updated
+a maximum of once a second.
+
+=item use_alias
+
+If this is non-zero then an article with linkAlias set will use an
+alias url instead of the "real" url. You will need to configure a
+RewriteRule or ErrorDocument to page.pl to direct the user to the
+correct URL. Default: 1.
+
+=item warn_obsolete
+
+Some obsolete tags will warn to stderr if this is non-zero. Default:
+don't warn.
=back
a lot of memory. Otherwise, set this to C<memory> to reduce memory
usage.
-C<memory> priority index building requires that the DBM::Deep module
-be installed.
+C<memory> priority index building requires that the C<DBM::Deep>
+module be installed.
+
+=item level
+
+Articles with a higher level than this are indexed as their ancestor.
+Default: C<$SEARCH_LEVEL> which defaults to 5.
+
+=item case_sensitive
+
+Level of case-sensitivity in the search engine. This can be one of:
+
+=over
+
+=item *
+
+C<none> - no case-sensitive searches
+
+=item *
+
+C<context> - case-sensitive if there are any upper-case characters in
+the search string, case-insensitive otherwise.
+
+=item *
+
+C<controlled> - case-sensitive via a query parameter. This is
+currently not supported by the built-in search engie.
+
+=back
+
+Renegerate your search indexes after changing this value. Default:
+context.
=back
[search highlight]
body_prefix=<span class="searchfound">
body_suffix=</span>
+
+The default prefix and suffix can also be redefined:
+
+ [search highlight]
+ prefix=<mark>
+ suffix=</mark>
=head2 [shop]
AustraliaPost::Air". These will be made available as shipping methods
on the checkout page.
+=item quoted
+
+If true then a default "Quote shipping charges later" shipping method
+will be added to the shipping methods list.
+
=item sourcepostcode
The post code from which products are shipped.
If non-zero then the ifUserCan tag will output some trace information
to STDERR.
+=item trace_noimpl
+
+Enables some trace messages from tags that return an ENOIMPL
+exception. This can be useful for tracking down why a tag isn't being
+replaced. This will produce a lot of output during page regeneration.
+
=back
=head2 [uri]
=over
+=item articles
+
=item cgi
The URI to the CGI directory. Default: /cgi-bin
+=item dist_images
+
+The URI where images included with BSE can be found.
+
+This includes images such as F<trans_pixel.gif> and C<admin/error.gif>.
+
+Default: C</images>
+
=item images
-The URI where images are kept. Default: /images
+The URI where managed images are kept which should correspond to
+C<images> in C<[paths]>.
-=item shop
+Default: C</images> (from C<$Constants::IMAGES_URI>)
-=item articles
+=item scalecache
+
+The URL to the directory represented by scalecache. Defaults to
+I<[uri].images>F</scaled>.
+
+=item public_files
+
+The URL to the directory configured as I<[paths].public_files>.
+
+=item shop
=back
=item require_name2
-=item require_address
+=item require_street
-=item require_city
+=item require_suburb
=item require_state
1=some name
[query group some name]
- sql=select id from site_users where id = ? and name1 like '%some%'
+ sql=select id from bse_siteusers where id = ? and name1 like '%some%'
Each entry also has a corresponding [Query Group I<name>] section.
=back
-=over
-
-=back
-
=head2 [inpho]
This is used to configure the DevHelp::Payments::Inpho module.
Each key identifies an update specification for userupdate.pl, the
value is a description of the specification.
-See L<<[siteuser update I<specid>]>> for the rest of the import
+See L<< [siteuser update I<specid>] >> for the rest of the import
specification.
=item *
mail_max_dump - if non-zero this is the size limit of the dump stored
-in the audit log when [audit log].mail is enabled.
+in the audit log when [audit log].mail is enabled. Default: 50000.
=back
Keys with a prefix of C<bse_> are reserved for BSE internal use.
+=head2 [undeletable articles]
+
+Keys are the ids of articles that may not be deleted.
+
+This applies if the value of the entry is a true perl value.
+
+ [undeletable articles]
+ 1=home page
+ 2=more home page
+ ; article 3 is deletable
+ 3=
+
+=head2 [dummy shipping methods]
+
+Configures extra shipping methods only selectable from the order
+detail page.
+
+Entries are sorted by value.
+
+If the value contains a comma the text up to the comma is removed and
+the remains used as the label, otherwise the key is used as the label.
+
+=head2 [article custom fields]
+
+=head2 [product custom fields]
+
+=head2 [catalog custom fields]
+
+These can be used to define article, product and catalog custom fields
+respectively, in a similar manner to L<formmail>.
+
+The field names are predefined, C<customDate1>, C<customDate2>,
+C<customInt1>, C<customInt2>, C<customInt3>, C<customInt4>,
+C<customStr1> and C<customStr2>, but are only active if a description
+is defined for the field:
+
+ [article custom fields]
+ customInt1_description=Stock Level
+
+=head2 [siteuser passwords]
+
+Rules for validating (not verifying) site user passwords. Possible
+keys are:
+
+=over
+
+=item *
+
+C<length> - the minimum length of passwords. This replaces
+C<minpassword> in C<[basic]>.
+
+=item *
+
+C<entropy> - the minimum password entropy as measured by
+L<Data::Password::Entropy>.
+
+=item *
+
+C<symbols> - if non-zero, the password must contain non-alphanumerics.
+
+=item *
+
+C<digits> - if non-zero, the password must contain digits.
+
+=item *
+
+C<mixedcase> - if non-zero, the password must contain both upper and
+lower case letters.
+
+=item *
+
+C<categories> - the number of categories out of 5 required out of
+symbols, digits, upper case, lower case and extended ASCII/Unicode.
+This should typically never be 5.
+
+=item *
+
+C<notuser> - the password and user name may not match each other
+case-insensitively.
+
+=item *
+
+C<notu5er> - the password may not match the user name
+case-insensitively, even with symbol replacement (e.g. "5" for "S".
+
+=back
+
+=head2 [admin user passwords]
+
+Rules for validating (not verifying) administrative user passwords.
+See L</[siteuser passwords]> on the keys that can be set.
+
+=head2 [site user lockouts]
+
+Controls when accounts and IP addresses are locked out due to repeated
+site user authentication failures.
+
+=over
+
+=item *
+
+I<account maximum failures> - the maximum number of login failures for
+a given account in I<account time period>. A successful login of the
+account resets the count. Default: 3.
+
+=item *
+
+C<account_time_period> - the number of minutes in which
+C<account_maximum_failures> login failures occurring will cause an
+account lock-out. Default: 10.
+
+=item *
+
+C<account_lockout_time> - the number of minutes to lock out an account
+that fails too many logins. Default: 60.
+
+=item *
+
+C<ip_maximum_failures> - the maximum number of login failures for a
+given IP address with-in C<ip_time_period>. A successful login of any
+account at the IP address resets the count. Default: 10.
+
+=item *
+
+C<ip_time_period> - the number of minutes in which
+C<ip_maximum_failures> login failures occurring causes an IP address
+lock-out. Default: 30.
+
+=item *
+
+C<ip_lockout_time> - the number of minutes to lock out an IP
+address that fails too many logins. Default: 120.
+
+=item *
+
+C<ip_maximum_failures2> - the maximum number of login failures for a
+given IP address with-in C<ip_time_period>. A successful login of any
+account at the IP address I<does not reset> the count. Default: 50.
+
+=item *
+
+C<ip_lockout_time2> - the number of minutes to lock out an IP address
+that fails too many logins against C<ip_maximum_failure2>. Default:
+120.
+
+=back
+
+Note: an administrator unlocking an account resets the account lock
+count but has no effect on the IP address lock count. An
+administrator unlocking an IP address resets both IP address lock
+counts, but has no effect on account lock counts.
+
+=head2 [admin user lockouts]
+
+Control account and IP address lockouts for admin user authentication.
+
+See L</[site user lockouts]> for details of the configuration
+possible.
+
+=head2 [pregenerate]
+
+Defines templates to be generated as base templates.
+
+Each entry is of the form:
+
+=over
+
+I<output-template>=I<profile-name>,I<input-template>
+
+=back
+
+where:
+
+=over
+
+=item *
+
+I<output-template> - the output template name, stored in the directory
+defined by [paths].templates
+
+=item *
+
+I<profile-name> - used to select a section in the config file to load
+dummy article settings from, as C<< [I<profile-name> settings] >>.
+
+=item *
+
+I<input-template> - the source template to generate from.
+
+=back
+
=head1 AUTHOR
Tony Cook <tony@develop-help.com>
projects / bse.git / blobdiff