0.12_22 commit
[bse.git] / site / docs / config.pod
CommitLineData
61551101
TC
1=head1 NAME
2
3config.pod - documents BSE configuration file options
4
5=head1 DESCRIPTION
6
7BSE historically used Constants.pm to keep most configuration
8information. The plan is to make sure any new configuration is kept
9in bse.cfg, and to slowly move most configuration information into
10bse.cfg.
11
12Keeping configuration information in Constants.pm makes it difficult
13to perform upgrades and makes it impossible to use tools such as
14mod_perl, at least if you want more than one site on the machine.
15
16=head1 CONFIGURATION ENTRIES
17
18=head2 [paths]
19
20Contains various file system paths.
21
22=over
23
24=item downloads
25
26This is where the files uploads with the file wizard are stored. It
27must be writable by the web server user.
28
29=item admin_templates
30
31Directory containing administrative templates. Note: this is not
32completely implemented for now, so assume the default. Default: admin
33directory under $TMPLDIR.
34
35=item templates
36
aefcabcb
TC
37Directory base for most templates.
38
39=item local_templates
40
41Local Directory base for templates. This is searched before the
42templates directory.
61551101 43
ca9aa2bf
TC
44=item images
45
46Where uploaded images are stored. This is not yet completely
47implemented. Default: $IMAGEDIR.
48
61551101
TC
49=back
50
51=head2 [extensions]
52
53This section is used by the file wizard to map uploaded file
54extensions to MIME content types. This can be used to extend
55BSE::FileEditor's internal extension map. It cannot override that
56map.
57
58The key for each entry is the extension, without the leading '.'.
59
60eg.
61
62 xls = application/msexcel
63
64=head2 [templates]
65
66Used for translating symbolic template names into full names under the
67template directory.
68
69In each case the default is the name with a C<.tmpl> extension.
70
71=over
72
73=item user/logon
74
75user logon page
76
77=item user/register
78
79user registration page
80
81=back
82
83=head2 [admin templates]
84
85Used for translating the names of administration templates into filenames.
86
87In each case the default is the name with a C<.tmpl> extension.
88
89=over
90
91=item filelist
92
93article file wizard
94
d2730773
TC
95=item catalog
96
97Catalog editor page. Default admin/edit_catalog.tmpl
98
99=item 1
100
101=item 2
102
103=item 3
104
105=item 4
106
107=item 5
108
109Article edit pages. Default admin/edit_<number>.tmpl
110
111=item steps
112
113Step child/parent management page. Default admin/edit_steps.tmpl
114
61551101
TC
115=back
116
117=head2 [html]
118
119Minor html items.
120
121=over
122
123=item charset
124
125The value of the charset keyword when outputting HTML from a script.
126Set to the empty string to suppress the charset keyword. Default:
127iso-8859-1.
128
129=back
130
131=head2 [basic]
132
133=over
134
135=item cookie_lifetime
136
137The expiry time for cookies. This should be in the form supported by
138CGI.pm for the -expires parameter. Typically you want a plus ('+'), a
139number, and a time character (s - seconds, m - minutes, h - hours, d -
140days, M - months). Default: +3h
141
142=item minpassword
143
144Minimum password length in characters. Default: 4.
145
b19047a6
TC
146=item randomdata
147
148Device to read random data from. This device should not block when it
149runs out of entropy.
150
6e3d2da5
TC
151=item sign
152
153If this is true then the encrypted messages containing the customer's
154credit card number are sent to the shop owner signed. To avoid
155keeping a passphrase and signing key on the server you can set this to
156false (0). This has the effect that anyone could send you an unsigned
157message encrypted with your public key, though this may not be a
158security threat. Default: True.
159
ca9aa2bf
TC
160=item link_titles
161
162If this is true then the links to your articles within BSE will be
163followed by a / and then by a simplified version of the article title.
164The aim is to include at least some title information in the URL
165without modifying the name of the HTML file. Default: False.
166
9168c88c
TC
167=item access_control
168
169If this is true then the user/group/permissions database is used to
170control access to the system. Default: False.
171
172=item htusers
173
174This should be the path to a file to be updated with the list of users
175and crypt() versions of their passwords. If this is set then the
176security system will check for a user set by the browser before
177attempting a form based logon. Default: None.
178
b19047a6
TC
179=back
180
181=head2 [mail]
182
35c0719f 183This section controls how BSE sends email.
b19047a6
TC
184
185=over
186
187=item smtp_server
188
189The host or IP address of your mail server. If this is not set
190C<sendmail> will be used instead. If this is set you must also set
191I<helo>.
192
193=item helo
194
195The name that BSE uses to identify itself when sending mail via SMTP.
196Required if I<smtp_server> is set.
197
198=item sendmail
199
200The path to the C<sendmail> binary. Default: /usr/lib/sendmail
201
202=item sendmail_opts
203
204The options supplied to sendmail. Default: -t -oi
205
206You may want to add the -odq option to this if you want mail queued
207rather than sent immediately.
208
61551101
TC
209=back
210
ca9aa2bf 211=head2 [children of I<id>]
721cd24c
TC
212
213Where I<id> is the identifier for an article.
214
215=over
216
217=item template
218
219the name of the default template for children of the given parent
220
221=item template_dirs
222
223a comma-separated list of extra directories under $TMPLDIR to search
224for templates that can be used for children of the given parent article.
225
226=back
227
ca9aa2bf
TC
228=head2 [article I<id>]
229
230Where I<id> is the identifier of an article.
231
232=over
233
234=item template_dirs
235
236A comma-separated list of extra directories under $TMPLDIR to search
237for templates that can be used for children of the given parent
238article.
239
240=item extra_templates
241
242A comma-separated list of extra templates under $TMPLDIR that can be
243used for the given article.
244
245=back
246
caa7299c
TC
247=head2 [level I<level>]
248
249=over
250
251=item template
252
253The default template for this level of article, assuming it hasn't
254been set in the [children of I<article id>] section.
255
256=item template_dirs
257
258A comma-separated list of extra directories under $TMPLDIR to search
259for templates that can be used for articles at the given I<level>.
260
261=back
262
263=head2 [catalogs]
264
265=over
266
267=item template
268
269The default template for catalogs.
270
271=back
272
273=head2 [products]
274
275=over
276
277=item template
278
279The default template for products.
280
281=back
282
61551101
TC
283=head2 [messages]
284
285This can be used to control translation of error messages. Each key
286has a prefix identifying the module that uses the error, followed by
287'/' followed by a specific identifier for the message.
288
289Message parameters, expressed as $I<digit>, are replaced with the
290parameters passed to the message. C<$$> is replaced with C<$>.
291
292Each message identifier below is documented with the id, when it
293occurs, the default message, and any parameters.
294
295=over
296
297=item user/needlogon
298
299the user attempted to logon without entering a logon name. Default:
300"Please enter a logon name". No parameters.
301
302=item user/needpass
303
304the user attempted to logon without entering a password. Default:
305"Please enter your password." No parameters.
306
307=item user/baduserpass
308
309the user's logon name or password was not found or did not match.
310Default: "Invalid user or password". No parameters.
311
312=item user/notloggedon
313
314the user attempted to logoff while not logged on. Default: "You
315aren't logged on". No parameters.
316
317=item user/optsoldpass
318
319the user entered a new password on the options page without entering
320their old password. Default: "You need to enter your old password to
321change your password". No parameters.
322
323=back
324
2404a911
TC
325=head2 [downloads]
326
327=over
328
329=item must_be_paid
330
331if non-zero, the order must be marked as paid for before the file can
332be downloaded.
333
334=item must_be_filled
335
336if non-zero the order must be marked as filled before the files can be
337downloaded.
338
4afdbb1b
TC
339=item require_logon
340
341if non-zero the user must be registered/logged on to download I<any>
342file.
343
2404a911
TC
344=back
345
b19047a6
TC
346=head2 [confirmations]
347
348Control over confirmation emails.
349
350=over
351
352=item subject
353
354The subject of email confirmation emails. Default: Subcription
355Confirmation.
356
357=item from
358
359The from field for the email. Default: $SHOP_FROM
360
361=back
362
531fb3bc
TC
363=head2 [subscriptions]
364
365Control over subscription messages.
366
367=over
368
369=item from
370
371The from field for the email. Default: $SHOP_FROM.
372
373=back
374
6e3d2da5
TC
375=head2 [search]
376
377=over
378
379=item highlight_partial
380
381If this is true then partial matches will be highlight in search
382result excerpts. Default: True
383
384=back
385
386=head2 [shop]
387
388=over
389
7b81711b
TC
390=item enabled
391
392Used by some templates to check if the shop is enabled. Set this to 1
393to enable the shop, or 0 to disable it.
394
6e3d2da5
TC
395=item register_if_files
396
397If true the customer is required to register before checkout if there
398are any for sale files attached to products in the cart. Default: True
399
400=item require_logon
401
402If true the customer is required to be logged on before checkout,
403whether or not for sale files are attached to products in the cart.
404Default: False.
405
08123550
TC
406=item payment_types
407
408A comma-separated list of acceptable payment types. Default: 0
409
410The possible payment types are:
411
412=over
413
414=item *
415
4160 - the user enters a credit card number, name and expiry date
417
418=item *
419
4201 - the customer will send a cheque
421
422=item *
423
4242 - contact customer for details
425
426=back
427
428=item address1
429
430=item address2
431
432=item address3
433
434These are used by various shop templates to present an address that a
435cheque payment should be sent to.
436
6e3d2da5
TC
437=back
438
439=head2 [fields]
440
441=over
442
443=item title_size
444
445The maximum length of the article title field. Default: 255. Should
446not be set higher than this unless you change the database schema.
447
448=back
449
ee6577c3
TC
450=head2 [interest]
451
452Controls the interest.pl script.
453
454=over
455
456=item notify
457
458Email address that is notified of the interest. Defaults to $SHOP_FROM.
459
ca9aa2bf 460=back
ee6577c3 461
6e3d2da5
TC
462=head2 [debug]
463
464Used for debugging.
465
466=over
467
468=item logon_cookies
469
470When a user logs on, and the site url is different to the secure url
471BSE attempts to refresh to the other "side" of the site to set the
472same cookie.
473
474BSE does some simple comparisons to attempt to determine whether the
475logon form was triggered on the secure side of the site (possibly from
476the shop) or on the insecure side. Since CGI doesn't necessarily give
477us all the information required, it's possible it will guess wrong.
478
d2730773
TC
479Setting this option to 1 will enable debugging information sent to
480standard error, which will be sent to the error log on Apache. This
481probably isn't useful on IIS.
482
483=item file_unlink
484
485Reports errors to STDERR (hence to the error log on Apache) if there
486is a problem deleting the actual file when an attached file is
487removed.
488
489=item mail_encryption
490
491Reports debugging information to standard error while encrypting your
492mail.
6e3d2da5 493
ca9aa2bf
TC
494=back
495
496=head2 [uri]
497
498Contains various URIs.
499
500This is underused, so don't rely on it yet.
501
502=over
503
504=item cgi
505
506The URI to the CGI directory. Default: /cgi-bin
507
508=item images
509
510The URI where images are kept. Default: /images
511
512=item shop
513
514=item articles
515
9168c88c 516=back
ca9aa2bf 517
9168c88c 518=head2 [articles]
ca9aa2bf 519
9168c88c
TC
520This will provide translations from symbolic names to article ids.
521
522Currently this is used for converting article ids in the access
523control code, and for looking up the id of the shop.
6e3d2da5 524
0b406a07
TC
525=head2 [printable type]
526
527If the user supplies a template name to printable.pl then you can use
528a different content type by adding an entry to this section. The key
529is the template name, and the value is the full content type.
530
61551101
TC
531=head1 AUTHOR
532
533Tony Cook <tony@develop-help.com>
534
535=cut