1
<?xml version="1.0" encoding="UTF-8"?>
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
6
<refentrytitle>libsasl</refentrytitle>
8
<manvolnum>5</manvolnum>
12
<refname>libsasl</refname>
14
<refpurpose>authentication library</refpurpose>
18
<para>Cyrus SASL library handling communication between an application and
19
the Cyrus SASL authentication framework.</para>
23
<title>Description</title>
25
<para>This document describes generic configuration options for the Cyrus
26
SASL authentication library <systemitem
27
class="library">libsasl</systemitem>.</para>
29
<para>The library handles communication between an application and the
30
Cyrus SASL authentication framework. Both exchange information before
31
<systemitem class="library">libsasl</systemitem> can start offering
32
authentication services for the application.</para>
34
<para>The application, among other data, sends the
35
<parameter>service_name</parameter>. The service name is the services name
36
as specified by IANA. SMTP servers, for example, send
37
<option>smtp</option> as <parameter>service_name</parameter>. This
38
information is handed over by <systemitem
39
class="library">libsasl</systemitem> e.g. when Kerberos or PAM
40
authentication takes place.</para>
42
<para>Configuration options in general are read either from a file or
43
passed by the application using <systemitem
44
class="library">libsasl</systemitem> during library initialization.</para>
47
<title>File-Based configuration</title>
49
<para>When an application (server) starts, it initializes the
50
<systemitem class="library">libsasl</systemitem> library. The
51
application passes <parameter>app_name</parameter> (application name) to
52
the SASL library. Its value is used to construct the name of the
53
application specific SASL configuration file. The Cyrus SASL
54
sample-server, for example, sends <option>sample</option> as
55
<parameter>app_name</parameter>. Using this value the SASL library will
56
search the configuration directories for a file named
57
<filename>sample.conf</filename> and read configuration options from
61
<para>Consult the applications manual to determine what
62
<parameter>app_name</parameter> it sends to the Cyrus SASL
68
<title>Application-Based Configuration</title>
70
<para>Configuration options for <systemitem
71
class="library">libsasl</systemitem> are written down together with
72
application specific options in the applications configuration file. The
73
application reads them and passes them over to <systemitem
74
class="library">libsasl</systemitem> when it loads the library.</para>
77
<para>An example for application-based configuration is the Cyrus IMAP
78
server <systemitem class="daemon">imapd</systemitem>. SASL
79
configuration is written to <filename>imapd.conf</filename> and passed
80
to the SASL library when the <systemitem
81
class="daemon">imapd</systemitem> server starts.</para>
87
<title>Configuration Syntax</title>
89
<para>The general format of Cyrus SASL configuration file is as
94
<term>Configuration options</term>
97
<para>Configuration options are written each on a single physical
98
line. Parameter and value must be separated by a colon and a single
101
<programlisting>parameter: value</programlisting>
104
<para>There must be no trailing whitespace after the value or
105
Cyrus SASL will fail to apply the value appropriately!</para>
111
<term>Comments, Emtpy lines and whitespace-only lines</term>
114
<para>Empty lines and whitespace-only lines are ignored, as are
115
lines whose first non-whitespace character is a
116
<quote>#</quote>.</para>
123
<title>Options</title>
125
<para>There are generic options and options specific to the password
126
verification service or auxiliary property plugin choosen by the
127
administrator. Such specific options are documented in manuals listed in
128
<xref linkend="seealso" />.</para>
130
<para>The following configuration parameters are generic configuration
135
<term><parameter>authdaemond_path</parameter> (default:
136
<option>/dev/null</option>)</term>
139
<para>Path to Courier MTA authdaemond's unix socket. Only applicable
140
when <parameter>pwcheck_method</parameter> is set to
141
<option>authdaemond</option>.</para>
146
<term><parameter>auto_transition</parameter>: (default:
147
<option>no</option>)</term>
150
<para>Automatically transition users to other mechanisms when they
151
do a successful plaintext authentication and if an auxprop plugin is
155
<para>This option does not apply to the <citerefentry>
156
<refentrytitle>ldapdb</refentrytitle>
158
<manvolnum>5</manvolnum>
159
</citerefentry> plugin. It is a read-only plugin.</para>
164
<term><option>no</option></term>
167
<para>Do not transition users to other mechanisms.</para>
172
<term><option>noplain</option></term>
175
<para>Transition users to other mechanisms, but write
176
non-plaintext secrets only.</para>
181
<term><option>yes</option></term>
184
<para>Transition users to other mechanisms.</para>
190
<para>The only mechanisms (as currently implemented) which don't
191
use plaintext secrets are OTP and SRP.</para>
197
<term><parameter>auxprop_plugin</parameter>: (default: empty)</term>
200
<para>A whitespace-separated list of one or more auxiliary plugins
201
used if the <parameter>pwcheck_method</parameter> parameter
202
specifies <option>auxprop</option> as an option. Plugins will be
203
queried in list order. If no plugin is specified, all available
204
plugins will be queried.</para>
208
<term><option>ldapdb</option></term>
211
<para>Specify <option>ldapdb</option> to use the Cyrus SASL
213
<refentrytitle>ldapdb</refentrytitle>
215
<manvolnum>5</manvolnum>
216
</citerefentry> plugin.</para>
221
<term><option>sasldb</option></term>
224
<para>Specify <option>sasldb</option> to use the Cyrus SASL
226
<refentrytitle>sasldb</refentrytitle>
228
<manvolnum>5</manvolnum>
229
</citerefentry> plugin.</para>
234
<term><option>sql</option></term>
237
<para>Specify <option>sql</option> to use the Cyrus SASL
239
<refentrytitle>sql</refentrytitle>
241
<manvolnum>5</manvolnum>
242
</citerefentry> plugin.</para>
250
<term><parameter>log_level</parameter>: (default:
251
<option>1</option>)</term>
254
<para>Specifies a numeric log level. Available log levels
259
<term><option>0</option></term>
262
<para>Don't log anything</para>
267
<term><option>1</option></term>
270
<para>Log unusual errors</para>
275
<term><option>2</option></term>
278
<para>Log all authentication failures</para>
283
<term><option>3</option></term>
286
<para>Log non-fatal warnings</para>
291
<term><option>4</option></term>
294
<para>More verbose than 3</para>
299
<term><option>5</option></term>
302
<para>More verbose than 4</para>
307
<term><option>6</option></term>
310
<para>Traces of internal protocols</para>
315
<term><option>7</option></term>
318
<para>Traces of internal protocols, including passwords</para>
324
<para>Cyrus SASL sends log messages to the application that runs
325
it. The application decides if it forwards such messages to the
327
<refentrytitle>sysklogd</refentrytitle>
329
<manvolnum>8</manvolnum>
330
</citerefentry> service, to which
331
<parameter>facility</parameter> they are sent and which
332
<parameter>priority</parameter> is given to the message.</para>
338
<term><parameter>mech_list</parameter>: (default: empty)</term>
341
<para>The optional <parameter>mech_list</parameter> parameter
342
specifies a whitespace-separated list of one or more mechanisms
343
allowed for authentication.</para>
348
<term><parameter>pwcheck_method</parameter>: (default:
349
<option>auxprop</option>)</term>
352
<para>A whitespace-separated list of one or more mechanisms. Cyrus
353
SASL provides the following mechanisms:</para>
357
<term><option>authdaemond</option></term>
360
<para>Configures Cyrus SASL to contact the Courier MTA
362
<refentrytitle>authdaemond</refentrytitle>
364
<manvolnum>8</manvolnum>
365
</citerefentry> password verification service for password
371
<term><option>alwaystrue</option></term>
379
<term><option>auxprop</option></term>
382
<para>Cyrus SASL will use its own plugin infrastructure to
383
verify passwords. The
384
<parameter><parameter>auxprop_plugin</parameter></parameter>
385
parameter controls which plugins will be used.</para>
390
<term><option>pwcheck</option></term>
393
<para>Verify passwords using the Cyrus SASL <citerefentry>
394
<refentrytitle>pwcheck</refentrytitle>
396
<manvolnum>8</manvolnum>
397
</citerefentry> password verification service. The pwcheck
398
daemon is considered deprecated and should not be used
399
anymore. Use the saslauthd password verification service
405
<term><option>saslauthd</option></term>
408
<para>Verify passwords using the Cyrus SASL <citerefentry>
409
<refentrytitle>saslauthd</refentrytitle>
411
<manvolnum>8</manvolnum>
412
</citerefentry> password verification service.</para>
420
<term><parameter>saslauthd_path</parameter>: (default: empty)</term>
423
<para>Path to <citerefentry>
424
<refentrytitle>saslauthd</refentrytitle>
426
<manvolnum>8</manvolnum>
427
</citerefentry> run directory (including the
428
<filename>/mux</filename> named pipe)</para>
434
<refsection id="seealso">
435
<title>See also</title>
438
<refentrytitle>authdaemond</refentrytitle>
440
<manvolnum>5</manvolnum>
441
</citerefentry>, <citerefentry>
442
<refentrytitle>ldapdb</refentrytitle>
444
<manvolnum>5</manvolnum>
445
</citerefentry>, <citerefentry>
446
<refentrytitle>libsasl</refentrytitle>
448
<manvolnum>5</manvolnum>
449
</citerefentry>, <citerefentry>
450
<refentrytitle>saslauthd</refentrytitle>
452
<manvolnum>8</manvolnum>
453
</citerefentry>, <citerefentry>
454
<refentrytitle>saslauthd.conf</refentrytitle>
456
<manvolnum>5</manvolnum>
457
</citerefentry>, <citerefentry>
458
<refentrytitle>saslpasswd2</refentrytitle>
460
<manvolnum>5</manvolnum>
461
</citerefentry>, <citerefentry>
462
<refentrytitle>sasldblistusers2</refentrytitle>
464
<manvolnum>5</manvolnum>
465
</citerefentry>, <citerefentry>
466
<refentrytitle>sasldb</refentrytitle>
468
<manvolnum>5</manvolnum>
469
</citerefentry>, <citerefentry>
470
<refentrytitle>sql</refentrytitle>
472
<manvolnum>5</manvolnum>
473
</citerefentry></para>
477
<title>Readme files</title>
479
<para><filename>README.Debian</filename></para>
483
<title>Author</title>
485
<para>This manual was written for the Debian distribution because the
486
original program does not have a manual page. Parts of the documentation
487
have been taken from the Cyrus SASL's
488
<filename>options.html</filename>.</para>
490
<para><address>Patrick Ben Koetter
491
<email>p@state-of-mind.de</email></address></para>
added
removed
debian/doc/libsasl.5.xml
