0.14_01 commit

[bse.git] / site / docs / config.pod

=head1 NAME

config.pod - documents BSE configuration file options

=head1 DESCRIPTION

BSE historically used Constants.pm to keep most configuration
information.  The plan is to make sure any new configuration is kept
in bse.cfg, and to slowly move most configuration information into
bse.cfg.

Keeping configuration information in Constants.pm makes it difficult
to perform upgrades and makes it impossible to use tools such as
mod_perl, at least if you want more than one site on the machine.

=head1 CONFIGURATION ENTRIES

=head2 [paths]

Contains various file system paths.

=over

=item downloads

This is where the files uploads with the file wizard are stored.  It
must be writable by the web server user.

=item admin_templates

Directory containing administrative templates.  Note: this is not
completely implemented for now, so assume the default.  Default: admin
directory under $TMPLDIR.

=item templates

Directory base for most templates.

=item local_templates

Local Directory base for templates.  This is searched before the
templates directory.

=item images

Where uploaded images are stored.  This is not yet completely
implemented.  Default: $IMAGEDIR.

=item libraries

Local search path for BSE::Custom, or the class configured by
C<custom_class> in [basic].

=back

=head2 [extensions]

This section is used by the file wizard to map uploaded file
extensions to MIME content types.  This can be used to extend
BSE::FileEditor's internal extension map.  It cannot override that
map.

The key for each entry is the extension, without the leading '.'.

eg.

  xls = application/msexcel

=head2 [templates]

Used for translating symbolic template names into full names under the
template directory.

In each case the default is the name with a C<.tmpl> extension.

=over

=item user/logon

user logon page

=item user/register

user registration page

=back

=head2 [admin templates]

Used for translating the names of administration templates into filenames.

In each case the default is the name with a C<.tmpl> extension.

=over

=item filelist

article file wizard

=item catalog

Catalog editor page.  Default admin/edit_catalog.tmpl

=item 1

=item 2

=item 3

=item 4

=item 5

Article edit pages.  Default admin/edit_<number>.tmpl

=item steps

Step child/parent management page.  Default admin/edit_steps.tmpl

=back

=head2 [html]

Minor html items.

=over

=item charset

The value of the charset keyword when outputting HTML from a script.
Set to the empty string to suppress the charset keyword.  Default:
iso-8859-1.

=back

=head2 [basic]

=over

=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).  Default: +3h

=item minpassword

Minimum password length in characters.  Default: 4.

=item randomdata

Device to read random data from.  This device should not block when it
runs out of entropy.

=item sign

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 link_titles

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 access_control

If this is true then the user/group/permissions database is used to
control access to the system.  Default: False.

=item htusers

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 custom_class

The name of the custom class for your site.  This is currently only
used for article editing customizations.  This class should derive
from BSE::CustomBase.  Default: BSE::Custom.

=back

=head2 [mail]

This section controls how BSE sends email.

=over

=item smtp_server

The host or IP address of your mail server.  If this is not set
C<sendmail> will be used instead.  If this is set you must also set
I<helo>.

=item helo

The name that BSE uses to identify itself when sending mail via SMTP.
Required if I<smtp_server> is set.

=item sendmail

The path to the C<sendmail> binary.  Default: /usr/lib/sendmail

=item sendmail_opts

The options supplied to sendmail.  Default: -t -oi

You may want to add the -odq option to this if you want mail queued
rather than sent immediately.

=back

=head2 [children of I<id>]

Where I<id> is the identifier for an article.

=over

=item template

the name of the default template for children of the given parent

=item template_dirs

a comma-separated list of extra directories under $TMPLDIR to search
for templates that can be used for children of the given parent article.

=back

=head2 [article I<id>]

Where I<id> is the identifier of an article.

=over

=item template_dirs

A comma-separated list of extra directories under $TMPLDIR to search
for templates that can be used for children of the given parent
article.

=item extra_templates

A comma-separated list of extra templates under $TMPLDIR that can be
used for the given article.

=back

=head2 [level I<level>]

=over

=item template

The default template for this level of article, assuming it hasn't
been set in the [children of I<article id>] section.

=item template_dirs

A comma-separated list of extra directories under $TMPLDIR to search
for templates that can be used for articles at the given I<level>.

=back

=head2 [catalogs]

=over

=item template

The default template for catalogs.

=back

=head2 [products]

=over

=item template

The default template for products.

=back

=head2 [messages]

This can be used to control translation of error messages.  Each key
has a prefix identifying the module that uses the error, followed by
'/' followed by a specific identifier for the message.

Message parameters, expressed as $I<digit>, are replaced with the
parameters passed to the message.  C<$$> is replaced with C<$>.

Each message identifier below is documented with the id, when it
occurs, the default message, and any parameters.

=over

=item user/needlogon

the user attempted to logon without entering a logon name.  Default:
"Please enter a logon name".  No parameters.

=item user/needpass

the user attempted to logon without entering a password.  Default:
"Please enter your password."  No parameters.

=item user/baduserpass

the user's logon name or password was not found or did not match.
Default: "Invalid user or password".  No parameters.

=item user/notloggedon

the user attempted to logoff while not logged on.  Default: "You
aren't logged on".  No parameters.

=item user/optsoldpass

the user entered a new password on the options page without entering
their old password.  Default: "You need to enter your old password to
change your password".  No parameters.

=back

=head2 [downloads]

=over

=item must_be_paid

if non-zero, the order must be marked as paid for before the file can
be downloaded.

=item must_be_filled

if non-zero the order must be marked as filled before the files can be
downloaded.

=item require_logon

if non-zero the user must be registered/logged on to download I<any>
file.

=back

=head2 [confirmations]

Control over confirmation emails.

=over

=item subject

The subject of email confirmation emails.  Default: Subcription
Confirmation.

=item from

The from field for the email.  Default: $SHOP_FROM

=back

=head2 [subscriptions]

Control over subscription messages.

=over

=item from

The from field for the email.  Default: $SHOP_FROM.

=item testname

Default for the "Test Name" field for sending test subscription
messages.

=item testemail

Default for the "Test Email" field for sending test subscription
messages.

=item testtextonly

Set to 1 if you want the "Test Text Only" box checked by default for
sending test subscription messages.

=item testing

Set to 0 to disable display of the test subscription messages portions
of the subscriptions send form.

=back

=head2 [search]

=over

=item highlight_partial

If this is true then partial matches will be highlight in search
result excerpts.  Default: True

=back

=head2 [shop]

=over

=item enabled

Used by some templates to check if the shop is enabled.  Set this to 1
to enable the shop, or 0 to disable it.

=item register_if_files

If true the customer is required to register before checkout if there
are any for sale files attached to products in the cart.  Default: True

=item require_logon

If true the customer is required to be logged on before checkout,
whether or not for sale files are attached to products in the cart.
Default: False.

=item payment_types

A comma-separated list of acceptable payment types.  Default: 0

The possible payment types are:

=over

=item *

0 - the user enters a credit card number, name and expiry date

=item *

1 - the customer will send a cheque

=item *

2 - contact customer for details

=back

=item address1

=item address2

=item address3

These are used by various shop templates to present an address that a
cheque payment should be sent to.

=item from

From email address for emails sent by the shop.  Overides $SHOP_FROM
in Constants.pm

=item to_name

To name for emailed orders sent by the shop.  Overrides $SHOP_TO_NAME
in Constants.pm

=item to_email

To email for emailed orders sent by the shop.  Overrides $SHOP_TO_EMAIL
in Constants.pm

=item noencrypt

If this is true then orders sent to you by the shop will not be
encrypted.  Enabling this disabled acceptance of credit card orders,
and the default for C<payment_types> will become C<1> instead or C<0>.

Please realize that other potentially commercially sensitive
information is being sent in the clear to a central location,
unencrypted.

=item email_order

If true, then the order is email to to_email, possibly with credit
card information included.  Default: $SHOP_EMAIL_ORDER.

=back

=head2 [fields]

=over

=item title_size

The maximum length of the article title field.  Default: 255.  Should
not be set higher than this unless you change the database schema.

=back

=head2 [interest]

Controls the interest.pl script.

=over

=item notify

Email address that is notified of the interest.  Defaults to $SHOP_FROM.

=back

=head2 [debug]

Used for debugging.

=over

=item logon_cookies

When a user logs on, and the site url is different to the secure url
BSE attempts to refresh to the other "side" of the site to set the
same cookie.

BSE does some simple comparisons to attempt to determine whether the
logon form was triggered on the secure side of the site (possibly from
the shop) or on the insecure side.  Since CGI doesn't necessarily give
us all the information required, it's possible it will guess wrong.

Setting this option to 1 will enable debugging information sent to
standard error, which will be sent to the error log on Apache.  This
probably isn't useful on IIS.

=item file_unlink

Reports errors to STDERR (hence to the error log on Apache) if there
is a problem deleting the actual file when an attached file is
removed.

=item mail_encryption

Reports debugging information to standard error while encrypting your
mail.

=back

=head2 [uri]

Contains various URIs.

This is underused, so don't rely on it yet.

=over

=item cgi

The URI to the CGI directory.  Default: /cgi-bin

=item images

The URI where images are kept.  Default: /images

=item shop

=item articles

=back

=head2 [articles]

This will provide translations from symbolic names to article ids.

Currently this is used for converting article ids in the access
control code, and for looking up the id of the shop.

=head2 [printable type]

If the user supplies a template name to printable.pl then you can use
a different content type by adding an entry to this section.  The key
is the template name, and the value is the full content type.

=head2 [search index scores]

This section is used when generating the search index to override the
default scores for each field in the articles.

The default scores are:

  Field   Score
  -----   -----
  title     5
  body      3
  keyword   4

A special key C<file_description> can be used here to set the score
for indexing downloadable file descriptions, which aren't indexed by
default.  A good value is probably 2 or 1.

=head2 [article flags]

=head2 [product flags]

=head2 [catalog flags]

Flags that can be set for articles, products and catalogs
respectively.  Note that flags for articles are also visible in
products and catalogs.

All flag Ids are single letters or digits.  Uppercase letters are
reserved for use by BSE internally, leaving lower-case letters and
digits for your own use.

Use the id of the flag as the key, and a description of the flag as
it's value.

=head2 [article uris]

Each key is an article id, the values are base URIs to store the HTML
form of those articles and their children under.

=head2 [protect link]

The keys are ids of articles that shouldn't have their link field
overwritten.  The value should be a true value, but is otherwise
ignored.

=head2 [datadump]

=over

=item to

The recipient for the data dump email sent by datadump.pl. Default:
$DATA_EMAIL.

=item from

the From for the data dump email sent by datadump.pl.  Default:
$SHOP_FROM.

=back

=head2 [site users]

Configuration for site users.

=over

=item nopassword

If this is set to true then no passwords are required during
registration, a confirmation email is sent immediately upon
registration and that confirmation email contains a link the user can
use to manage their details.

This option has some security concerns since it can leave links to the
user's information in the browser history.  This option is not
recommended.

You cannot use this to control access to the shop.

=item require_name1

=item require_name2

=item require_address

=item require_city

=item require_state

=item require_postcode

=item require_telephone

=item require_facsimile

=item require_country

=item require_title

=item require_organization

Set these to true to require the corresponding field during
registration, and to keep it required after modification.  Default:
false.

If you enable any of these, you should enable C<info_on_register> as
well, or modify the registration template to include the given fields.

=item display_I<field name>

Controls how the given field is displayed in error messages.  If you
change the field names on the registration and/or options forms you
should probably change them here too.  Default: internal field name
with the first character converted to upper-case.

=item info_on_register

If this is set then the user info is prompted for during user
registration.  The information still isn't required unless the
appropriate require_I<field> option is set.  Default: false.

=item register_refresh

The default URL to refresh to on completing registration if no r
parameter is supplied.

=item subscribe_all

If this is set then the subcription checkboxes are all checked on
registration by default.  Default: false.

The user will only receive the subscriptions if they leave them checked
and follow the link in the confirmation email.

=item subscribe_I<id>

Where I<id> is the number identifying a subscription.  If this is set
then the subscription checkbox for that subscription will be checked
by default on the registration form.  Default: false.

The user will only receive the subscriptions if they leave it checked
and follow the link in the confirmation email.

You can get the I<id> of a subcription by looking at the Edit link on the
subscriptions management page, the number after "id=" is the id.

=back

=head1 AUTHOR

Tony Cook <tony@develop-help.com>

=cut