=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. F is read as a utf-8 encoded file. =head1 CONFIGURATION ENTRIES =head2 [site] Contains URL configuration for the site. =over =item url The normal URL for the non-secure parts of the site. =item secureurl The secure URL for the shop, products and other portions of the site that should use SSL. This isn't checked to make sure it is https. =item name Used as the site "name" in a few places. =item adminurl If set, this is used as the base URL for accessing the administrative functions of your site. =item secureadmin Ignored if C is set. If this is true then C is used as the base URL for accessing the administrative functions of your site, otherwise C is used as the base URL. Default: false (C's value is used) =item forward_from Configure the IP address of one or more front-end proxies. This can be a regular expression except that C<.> is translated to C<\.> and C<*> is tranlated to C<.*> to give more glob() like matching. If the reqesting host matches then admin site URL matching is done against HTTP_X_FORWARDED_SERVER instead of SERVER_NAME. 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] 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. This can contain references like $(section/key) to other configuration entries. Split on the systems PATH separators (run: perl -V:path_sep) =item local_templates Local Directory base for templates. This is searched before the templates directory. This can contain references like $(section/key) to other configuration entries. Split on the system's PATH separator. =item public_html Web server document root. Static pages are generated under this directory. Default: $CONTENTBASE. =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 in [basic]. =item scalecache The directory where cached versions of scaled thumbnails are stored. Defaults to I<[paths].images>F. 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 config file. The default bse.cfg include an entry to use the current values of [paths].downloads =item dynamic_cache Pregenerated dynamic article pages are stored here. This must be defined if you site contains any dynamicly generated pages. =item public_files The directory to store public BSE::TB::File content in (currently used for application specific files.) =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 Z<>1 =item Z<>2 =item Z<>3 =item Z<>4 =item Z<>5 Article edit pages. Default admin/edit_.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. =item redirect_links If this is a non-zero number, then all but mailto links are redirected to C so you can display a diclaimer. If this contained alphabetics it's treated as a comma separated list of url schemes that should be handled via C. If 0 or not present, no redirection is done. The redirect URL includes a hash of the url, title and the redirect salt to prevent using this mechanism by external sites for cookie stealing attacks. =item redirect_salt The salt used in generating the has for redirect_links. Default: an empty string. =item validate If non-zero then any HTML output is validated with HTML::Tidy. 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. =item formatter_image_class The default class to use for image[...] tags in body text. Default: C. =back =head2 [basic] =over =item access_control If this is true then the user/group/permissions database is used to control access to the system. Default: False. =item access_filter_parents 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 access_filter_steps 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 alias_prefix The prefix applied to articles that use a linkAlias url. This should start with a /. =item alias_recursive If this is non-zero then the link is formed by the C, followed by slash (C) separated aliases from the ancestors starting from the section, followed by the C. You may need to change your redirect handling if you enable this. Default: Off. =item alias_suffix If this is non-zero then the title is cleaned up (all but alphanumerics removed) and appended to the alias URL generated. =item all_dynamic If true then all articles are treated as dynamic. Default: false. =item auto_images 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 to 0. An alternative is to set C in C<[article defaults]> to C which will default articles to not auto-inserting images. =item cache_templates 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. =item cache_templates_locally If true, BSE will cache compiled templates in memory. This may significantly improve performance but may increase memory use. Default: disabled. =item cache_thumbnails If set to zero the results of the thumbimage/gthumbimage body/template tags will not be cached. Default: 1 (caching is enabled). =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 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. =item default_popupimage This is the default popup image class for the popimage[] and gpopimage[] tags. Default: popup. =item dynamic_access_filter If set to 0, dynamic article iterators will no access control filter their results. Default: 1. =item error_not_defined 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 http_only_session If this is non-zero, the default, the session cookie sent to the browser has the C attribute set. This can prevent session cookie hijacking. Default: 1. =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 index_file The name of the file to generate for static articles when the link is terminated by "/". Default: C. =item jit_dynamic_pregen If this is true, then pre-generation for dynamic pages will be delayed until the page is displayed to a user. Default: off. =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 make_userid_cookie If this is non-zero, the default, then when the site member logs in, a javascript visible cookie, C 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 minpassword Previously the minimum length of site user passwords in characters. You must now set C in C<[siteuser passwords]>. =item no_cache_dynamic If non-zero, the default, dynamic responses will include a C header. This can be overridden for articles via , article flags, C<[template > IC<].no_cache_dynamic> and [article].no_cache_dynamic. Default: 1. =item preload_template 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. =item randomdata Device to read random data from. This device should not block when it runs out of entropy. =item redir_to_alias 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 If this is non-zero then the session cookie sent to the browser has the C attribute set. This means that the cookie will only be visible over https. This is only useful when the only URL the site is visited over is a https URL. Default: 0. =item server_auth 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 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 staticajax 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. 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 =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 will be used instead. If this is set you must also set I. =item helo The name that BSE uses to identify itself when sending mail via SMTP. Required if I is set. =item sendmail The path to the C 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. =item set_errors_to_from If true, we add an Errors-To header set to the same as the From header. Default: true. =item html_system_email If non-zero then emails sent via the compose mail system that aren't being sent to a member record, will be sent as HTML, if the HTML template is available. =item inline_css If this is C