0.12_06 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
61551101
TC
231=head2 [messages]
232
233This can be used to control translation of error messages. Each key
234has a prefix identifying the module that uses the error, followed by
235'/' followed by a specific identifier for the message.
236
237Message parameters, expressed as $I<digit>, are replaced with the
238parameters passed to the message. C<$$> is replaced with C<$>.
239
240Each message identifier below is documented with the id, when it
241occurs, the default message, and any parameters.
242
243=over
244
245=item user/needlogon
246
247the user attempted to logon without entering a logon name. Default:
248"Please enter a logon name". No parameters.
249
250=item user/needpass
251
252the user attempted to logon without entering a password. Default:
253"Please enter your password." No parameters.
254
255=item user/baduserpass
256
257the user's logon name or password was not found or did not match.
258Default: "Invalid user or password". No parameters.
259
260=item user/notloggedon
261
262the user attempted to logoff while not logged on. Default: "You
263aren't logged on". No parameters.
264
265=item user/optsoldpass
266
267the user entered a new password on the options page without entering
268their old password. Default: "You need to enter your old password to
269change your password". No parameters.
270
271=back
272
2404a911
TC
273=head2 [downloads]
274
275=over
276
277=item must_be_paid
278
279if non-zero, the order must be marked as paid for before the file can
280be downloaded.
281
282=item must_be_filled
283
284if non-zero the order must be marked as filled before the files can be
285downloaded.
286
4afdbb1b
TC
287=item require_logon
288
289if non-zero the user must be registered/logged on to download I<any>
290file.
291
2404a911
TC
292=back
293
b19047a6
TC
294=head2 [confirmations]
295
296Control over confirmation emails.
297
298=over
299
300=item subject
301
302The subject of email confirmation emails. Default: Subcription
303Confirmation.
304
305=item from
306
307The from field for the email. Default: $SHOP_FROM
308
309=back
310
531fb3bc
TC
311=head2 [subscriptions]
312
313Control over subscription messages.
314
315=over
316
317=item from
318
319The from field for the email. Default: $SHOP_FROM.
320
321=back
322
6e3d2da5
TC
323=head2 [search]
324
325=over
326
327=item highlight_partial
328
329If this is true then partial matches will be highlight in search
330result excerpts. Default: True
331
332=back
333
334=head2 [shop]
335
336=over
337
338=item register_if_files
339
340If true the customer is required to register before checkout if there
341are any for sale files attached to products in the cart. Default: True
342
343=item require_logon
344
345If true the customer is required to be logged on before checkout,
346whether or not for sale files are attached to products in the cart.
347Default: False.
348
349=back
350
351=head2 [fields]
352
353=over
354
355=item title_size
356
357The maximum length of the article title field. Default: 255. Should
358not be set higher than this unless you change the database schema.
359
360=back
361
ee6577c3
TC
362=head2 [interest]
363
364Controls the interest.pl script.
365
366=over
367
368=item notify
369
370Email address that is notified of the interest. Defaults to $SHOP_FROM.
371
ca9aa2bf 372=back
ee6577c3 373
6e3d2da5
TC
374=head2 [debug]
375
376Used for debugging.
377
378=over
379
380=item logon_cookies
381
382When a user logs on, and the site url is different to the secure url
383BSE attempts to refresh to the other "side" of the site to set the
384same cookie.
385
386BSE does some simple comparisons to attempt to determine whether the
387logon form was triggered on the secure side of the site (possibly from
388the shop) or on the insecure side. Since CGI doesn't necessarily give
389us all the information required, it's possible it will guess wrong.
390
d2730773
TC
391Setting this option to 1 will enable debugging information sent to
392standard error, which will be sent to the error log on Apache. This
393probably isn't useful on IIS.
394
395=item file_unlink
396
397Reports errors to STDERR (hence to the error log on Apache) if there
398is a problem deleting the actual file when an attached file is
399removed.
400
401=item mail_encryption
402
403Reports debugging information to standard error while encrypting your
404mail.
6e3d2da5 405
ca9aa2bf
TC
406=back
407
408=head2 [uri]
409
410Contains various URIs.
411
412This is underused, so don't rely on it yet.
413
414=over
415
416=item cgi
417
418The URI to the CGI directory. Default: /cgi-bin
419
420=item images
421
422The URI where images are kept. Default: /images
423
424=item shop
425
426=item articles
427
428
429
6e3d2da5
TC
430=back
431
61551101
TC
432=head1 AUTHOR
433
434Tony Cook <tony@develop-help.com>
435
436=cut