fiddling with dist target
[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
86=back
87
88=head2 [html]
89
90Minor html items.
91
92=over
93
94=item charset
95
96The value of the charset keyword when outputting HTML from a script.
97Set to the empty string to suppress the charset keyword. Default:
98iso-8859-1.
99
100=back
101
102=head2 [basic]
103
104=over
105
106=item cookie_lifetime
107
108The expiry time for cookies. This should be in the form supported by
109CGI.pm for the -expires parameter. Typically you want a plus ('+'), a
110number, and a time character (s - seconds, m - minutes, h - hours, d -
111days, M - months). Default: +3h
112
113=item minpassword
114
115Minimum password length in characters. Default: 4.
116
b19047a6
TC
117=item randomdata
118
119Device to read random data from. This device should not block when it
120runs out of entropy.
121
6e3d2da5
TC
122=item sign
123
124If this is true then the encrypted messages containing the customer's
125credit card number are sent to the shop owner signed. To avoid
126keeping a passphrase and signing key on the server you can set this to
127false (0). This has the effect that anyone could send you an unsigned
128message encrypted with your public key, though this may not be a
129security threat. Default: True.
130
b19047a6
TC
131=back
132
133=head2 [mail]
134
135This section controls how BSE send email.
136
137=over
138
139=item smtp_server
140
141The host or IP address of your mail server. If this is not set
142C<sendmail> will be used instead. If this is set you must also set
143I<helo>.
144
145=item helo
146
147The name that BSE uses to identify itself when sending mail via SMTP.
148Required if I<smtp_server> is set.
149
150=item sendmail
151
152The path to the C<sendmail> binary. Default: /usr/lib/sendmail
153
154=item sendmail_opts
155
156The options supplied to sendmail. Default: -t -oi
157
158You may want to add the -odq option to this if you want mail queued
159rather than sent immediately.
160
61551101
TC
161=back
162
721cd24c
TC
163=head2 [children of id]
164
165Where I<id> is the identifier for an article.
166
167=over
168
169=item template
170
171the name of the default template for children of the given parent
172
173=item template_dirs
174
175a comma-separated list of extra directories under $TMPLDIR to search
176for templates that can be used for children of the given parent article.
177
178=back
179
61551101
TC
180=head2 [messages]
181
182This can be used to control translation of error messages. Each key
183has a prefix identifying the module that uses the error, followed by
184'/' followed by a specific identifier for the message.
185
186Message parameters, expressed as $I<digit>, are replaced with the
187parameters passed to the message. C<$$> is replaced with C<$>.
188
189Each message identifier below is documented with the id, when it
190occurs, the default message, and any parameters.
191
192=over
193
194=item user/needlogon
195
196the user attempted to logon without entering a logon name. Default:
197"Please enter a logon name". No parameters.
198
199=item user/needpass
200
201the user attempted to logon without entering a password. Default:
202"Please enter your password." No parameters.
203
204=item user/baduserpass
205
206the user's logon name or password was not found or did not match.
207Default: "Invalid user or password". No parameters.
208
209=item user/notloggedon
210
211the user attempted to logoff while not logged on. Default: "You
212aren't logged on". No parameters.
213
214=item user/optsoldpass
215
216the user entered a new password on the options page without entering
217their old password. Default: "You need to enter your old password to
218change your password". No parameters.
219
220=back
221
2404a911
TC
222=head2 [downloads]
223
224=over
225
226=item must_be_paid
227
228if non-zero, the order must be marked as paid for before the file can
229be downloaded.
230
231=item must_be_filled
232
233if non-zero the order must be marked as filled before the files can be
234downloaded.
235
4afdbb1b
TC
236=item require_logon
237
238if non-zero the user must be registered/logged on to download I<any>
239file.
240
2404a911
TC
241=back
242
b19047a6
TC
243=head2 [confirmations]
244
245Control over confirmation emails.
246
247=over
248
249=item subject
250
251The subject of email confirmation emails. Default: Subcription
252Confirmation.
253
254=item from
255
256The from field for the email. Default: $SHOP_FROM
257
258=back
259
531fb3bc
TC
260=head2 [subscriptions]
261
262Control over subscription messages.
263
264=over
265
266=item from
267
268The from field for the email. Default: $SHOP_FROM.
269
270=back
271
6e3d2da5
TC
272=head2 [search]
273
274=over
275
276=item highlight_partial
277
278If this is true then partial matches will be highlight in search
279result excerpts. Default: True
280
281=back
282
283=head2 [shop]
284
285=over
286
287=item register_if_files
288
289If true the customer is required to register before checkout if there
290are any for sale files attached to products in the cart. Default: True
291
292=item require_logon
293
294If true the customer is required to be logged on before checkout,
295whether or not for sale files are attached to products in the cart.
296Default: False.
297
298=back
299
300=head2 [fields]
301
302=over
303
304=item title_size
305
306The maximum length of the article title field. Default: 255. Should
307not be set higher than this unless you change the database schema.
308
309=back
310
311=head2 [debug]
312
313Used for debugging.
314
315=over
316
317=item logon_cookies
318
319When a user logs on, and the site url is different to the secure url
320BSE attempts to refresh to the other "side" of the site to set the
321same cookie.
322
323BSE does some simple comparisons to attempt to determine whether the
324logon form was triggered on the secure side of the site (possibly from
325the shop) or on the insecure side. Since CGI doesn't necessarily give
326us all the information required, it's possible it will guess wrong.
327
328Setting this option to 1 will enable debugging information sent to standard error, which will be sent to the error log on Apache. This probably isn't useful on IIS.
329
330=back
331
61551101
TC
332=head1 AUTHOR
333
334Tony Cook <tony@develop-help.com>
335
336=cut