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