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