source: postlfs/security/cyrus-sasl.xml

trunk
Last change on this file was 1241ea19, checked in by Bruce Dubbs <bdubbs@…>, 2 months ago

Tag xfce and dependencies
  • Property mode set to 100644
File size: 14.2 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY cyrus-sasl-download-http "https://github.com/cyrusimap/cyrus-sasl/releases/download/cyrus-sasl-&cyrus-sasl-version;/cyrus-sasl-&cyrus-sasl-version;.tar.gz">
8 <!ENTITY cyrus-sasl-download-ftp " ">
9 <!ENTITY cyrus-sasl-md5sum "6f228a692516f5318a64505b46966cfa">
10 <!ENTITY cyrus-sasl-size "3.9 MB">
11 <!ENTITY cyrus-sasl-buildsize "28 MB">
12 <!ENTITY cyrus-sasl-time "0.2 SBU">
13]>
14
15<sect1 id="cyrus-sasl" xreflabel="Cyrus SASL-&cyrus-sasl-version;">
16 <?dbhtml filename="cyrus-sasl.html"?>
17
18
19 <title>Cyrus SASL-&cyrus-sasl-version;</title>
20
21 <indexterm zone="cyrus-sasl">
22 <primary sortas="a-Cyrus-SASL">Cyrus SASL</primary>
23 </indexterm>
24
25 <sect2 role="package">
26 <title>Introduction to Cyrus SASL</title>
27
28 <para>
29 The <application>Cyrus SASL</application> package contains a Simple
30 Authentication and Security Layer implementation, a method for adding
31 authentication support to connection-based protocols. To use SASL, a
32 protocol includes a command for identifying and authenticating a user to
33 a server and for optionally negotiating protection of subsequent protocol
34 interactions. If its use is negotiated, a security layer is inserted
35 between the protocol and the connection.
36 </para>
37
38 &lfs121_checked;
39
40 <!-- To test this package at freeze, run the following command:
41 testsaslauthd -u <current user> -p <password>
42 after saslauthd is started. -->
43 <bridgehead renderas="sect3">Package Information</bridgehead>
44 <itemizedlist spacing="compact">
45 <listitem>
46 <para>
47 Download (HTTP): <ulink url="&cyrus-sasl-download-http;"/>
48 </para>
49 </listitem>
50 <listitem>
51 <para>
52 Download (FTP): <ulink url="&cyrus-sasl-download-ftp;"/>
53 </para>
54 </listitem>
55 <listitem>
56 <para>
57 Download MD5 sum: &cyrus-sasl-md5sum;
58 </para>
59 </listitem>
60 <listitem>
61 <para>
62 Download size: &cyrus-sasl-size;
63 </para>
64 </listitem>
65 <listitem>
66 <para>
67 Estimated disk space required: &cyrus-sasl-buildsize;
68 </para>
69 </listitem>
70 <listitem>
71 <para>
72 Estimated build time: &cyrus-sasl-time;
73 </para>
74 </listitem>
75 </itemizedlist>
76
77 <!-- Not needed anymore
78 <bridgehead renderas="sect3">Additional Downloads</bridgehead>
79 <itemizedlist spacing="compact">
80 <listitem>
81 <para>
82 Required patch:
83 <ulink url="&patch-root;/cyrus-sasl-&cyrus-sasl-version;-doc_fixes-1.patch"/>
84 </para>
85 </listitem>
86 <!- -<listitem>
87 <para>
88 Required patch:
89 <ulink url="&patch-root;/cyrus-sasl-&cyrus-sasl-version;-openssl-1.1.0-1.patch"/>
90 </para>
91 </listitem>- ->
92 </itemizedlist>
93 -->
94
95 <bridgehead renderas="sect3">Cyrus SASL Dependencies</bridgehead>
96
97 <bridgehead renderas="sect4">Recommended</bridgehead>
98 <para role="recommended">
99 <xref linkend="lmdb"/>
100 </para>
101
102 <bridgehead renderas="sect4">Optional</bridgehead>
103 <para role="optional">
104 <xref linkend="linux-pam"/>,
105 <xref linkend="mitkrb"/>,
106 <xref linkend="mariadb"/> or <ulink url="https://www.mysql.com/">MySQL</ulink>,
107 <xref linkend="openldap"/>,
108 <xref linkend="postgresql"/>,
109 <xref linkend="sphinx"/>,
110 <xref linkend="sqlite"/>,
111 &berkeley-db;,
112 <ulink url="https://stuff.mit.edu/afs/net.mit.edu/project/attic/krb4/">krb4</ulink>,
113 <ulink url="https://dmalloc.com/">Dmalloc</ulink>, and
114 <ulink url="https://metacpan.org/pod/Pod::POM::View::Restructured">Pod::POM::View::Restructured</ulink>
115 </para>
116
117 </sect2>
118
119 <sect2 role="installation">
120 <title>Installation of Cyrus SASL</title>
121
122 <note>
123 <para>
124 This package does not support parallel build.
125 </para>
126 </note>
127
128 <!-- Without this patch, having Sphinx and/or doctools (doctools not tested)
129 on the system causes an FTBFS when man pages are generated. The Sphinx
130 and Docutils API has changed significantly between Sphinx-{1,2} and
131 Sphinx-3.0.
132
133 <para>
134 First, fix a build failure if Sphinx or
135 <xref role="nodep" linkend="docutils"/> is installed on the system:
136 </para>
137
138<screen><userinput remap="pre">patch -Np1 -i ../cyrus-sasl-2.1.27-doc_fixes-1.patch</userinput></screen>
139 -->
140
141 <para>
142 Install <application>Cyrus SASL</application> by
143 running the following commands:
144 </para>
145
146<screen><userinput>./configure --prefix=/usr \
147 --sysconfdir=/etc \
148 --enable-auth-sasldb \
149 --with-dblib=lmdb \
150 --with-dbpath=/var/lib/sasl/sasldb2 \
151 --with-sphinx-build=no \
152 --with-saslauthd=/var/run/saslauthd &amp;&amp;
153make -j1</userinput></screen>
154
155 <para>
156 This package does not come with a test suite. If you are planning
157 on using the GSSAPI authentication mechanism, test
158 it after installing the package using the sample server and client
159 programs which were built in the preceding step. Instructions for
160 performing the tests can be found at
161 <ulink url="&hints-root;/downloads/files/cyrus-sasl.txt"/>.
162 </para>
163
164 <para>
165 Now, as the <systemitem class="username">root</systemitem> user:
166 </para>
167
168<screen role="root"><userinput>make install &amp;&amp;
169install -v -dm755 /usr/share/doc/cyrus-sasl-&cyrus-sasl-version;/html &amp;&amp;
170install -v -m644 saslauthd/LDAP_SASLAUTHD /usr/share/doc/cyrus-sasl-&cyrus-sasl-version; &amp;&amp;
171install -v -m644 doc/legacy/*.html /usr/share/doc/cyrus-sasl-&cyrus-sasl-version;/html &amp;&amp;
172install -v -dm700 /var/lib/sasl</userinput></screen>
173
174 </sect2>
175
176 <sect2 role="commands">
177 <title>Command Explanations</title>
178
179 <para>
180 <parameter>--with-dbpath=/var/lib/sasl/sasldb2</parameter>: This
181 switch forces the <command>sasldb</command> database to be created
182 in <filename class="directory">/var/lib/sasl</filename> instead of
183 <filename class="directory">/etc</filename>.
184 </para>
185
186 <para>
187 <parameter>--with-saslauthd=/var/run/saslauthd</parameter>: This
188 switch forces <command>saslauthd</command> to use the FHS compliant
189 directory <filename class="directory">/var/run/saslauthd</filename>
190 for variable run-time data.
191 </para>
192
193 <para>
194 <parameter>--enable-auth-sasldb</parameter>: This switch enables
195 SASLDB authentication backend.
196 </para>
197
198 <para>
199 <option>--with-dblib=gdbm</option>: This switch forces
200 <application>GDBM</application> to be used instead of
201 <application>LMDB</application>.
202 </para>
203
204 <para>
205 <option>--with-ldap</option>: This switch enables the
206 <application>OpenLDAP</application> support.
207 </para>
208
209 <para>
210 <option>--enable-ldapdb</option>: This switch enables the
211 LDAPDB authentication backend.
212 </para>
213
214<!-- Removed in 2.1.28
215 <para>
216 <option>- -enable-java</option>: This switch enables compiling of the
217 <application>Java</application> support libraries.
218 </para>
219-->
220
221 <para>
222 <option>--enable-login</option>: This option enables unsupported
223 LOGIN authentication.
224 </para>
225
226 <para>
227 <option>--enable-ntlm</option>: This option enables unsupported
228 NTLM authentication.
229 </para>
230
231 <para>
232 <command>install -v -m644 ...</command>: These commands
233 install documentation which is not installed by the
234 <command>make install</command> command.
235 </para>
236
237 <para>
238 <command>install -v -m700 -d /var/lib/sasl</command>: This directory
239 must exist when starting <command>saslauthd</command> or using the
240 sasldb plugin. If you're not going to be running the daemon or
241 using the plugins, you may omit the creation of this directory.
242 </para>
243
244 </sect2>
245
246 <sect2 role="configuration">
247 <title>Configuring Cyrus SASL</title>
248
249 <sect3 id="cyrus-sasl-config">
250 <title>Config Files</title>
251
252 <para>
253 <filename>/etc/saslauthd.conf</filename>
254 (for <command>saslauthd</command> LDAP configuration) and
255 <filename>/etc/sasl2/Appname.conf</filename>
256 (where "Appname" is the application defined name of the application)
257 </para>
258
259 <indexterm zone="cyrus-sasl cyrus-sasl-config">
260 <primary sortas="e-etc-saslauthd.conf">/etc/saslauthd.conf</primary>
261 </indexterm>
262
263 </sect3>
264
265 <sect3>
266 <title>Configuration Information</title>
267
268 <para>
269 See
270 <ulink url="https://www.cyrusimap.org/sasl/sasl/sysadmin.html"/>
271 for information on what to include in the application configuration files.
272 </para>
273
274 <para>
275 See
276 <ulink url="file:///usr/share/doc/cyrus-sasl-&cyrus-sasl-version;/LDAP_SASLAUTHD"/>
277 for configuring <command>saslauthd</command> with
278 <application>OpenLDAP</application>.
279 </para>
280
281 <para>
282 See
283 <ulink url="https://www.cyrusimap.org/sasl/sasl/gssapi.html#gssapi"/>
284 for configuring <command>saslauthd</command> with <application>Kerberos</application>.
285 </para>
286
287 </sect3>
288
289 <sect3 id="cyrus-sasl-init">
290 <title><phrase revision="sysv">Init Script</phrase>
291 <phrase revision="systemd">Systemd Unit</phrase></title>
292
293 <para revision="sysv">
294 If you need to run the <command>saslauthd</command> daemon at system
295 startup, install the <filename>/etc/rc.d/init.d/saslauthd</filename>
296 init script included in the
297 <xref linkend="bootscripts"/> package using the following command:
298 </para>
299
300 <para revision="systemd">
301 If you need to run the <command>saslauthd</command> daemon at system
302 startup, install the <filename>saslauthd.service</filename> unit
303 included in the <xref linkend="systemd-units"/> package using the
304 following command:
305 </para>
306
307 <indexterm zone="cyrus-sasl cyrus-sasl-init">
308 <primary sortas="f-saslauthd">saslauthd</primary>
309 </indexterm>
310
311<screen role="root"><userinput>make install-saslauthd</userinput></screen>
312
313 <note>
314 <para>
315 You'll need to modify
316 <filename revision="sysv">/etc/sysconfig/saslauthd</filename>
317 <filename revision="systemd">/etc/default/saslauthd</filename>
318 and modify the
319 <option revision="sysv">AUTHMECH</option>
320 <option revision="systemd">MECHANISM</option>
321 parameter with your desired authentication mechanism.
322 <phrase revision="systemd">The default authentication
323 mechanism is "shadow".</phrase>
324 </para>
325 </note>
326
327 </sect3>
328
329 </sect2>
330
331 <sect2 role="content">
332 <title>Contents</title>
333
334 <segmentedlist>
335 <segtitle>Installed Programs</segtitle>
336 <segtitle>Installed Library</segtitle>
337 <segtitle>Installed Directories</segtitle>
338
339 <seglistitem>
340 <seg>
341 pluginviewer, saslauthd, sasldblistusers2, saslpasswd2 and
342 testsaslauthd
343 </seg>
344 <seg>
345 libsasl2.so
346 </seg>
347 <seg>
348 /usr/include/sasl,
349 /usr/lib/sasl2,
350 /usr/share/doc/cyrus-sasl-&cyrus-sasl-version; and
351 /var/lib/sasl
352 </seg>
353 </seglistitem>
354 </segmentedlist>
355
356 <variablelist>
357 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
358 <?dbfo list-presentation="list"?>
359 <?dbhtml list-presentation="table"?>
360
361 <varlistentry id="pluginviewer">
362 <term><command>pluginviewer</command></term>
363 <listitem>
364 <para>
365 is used to list loadable SASL plugins and their properties
366 </para>
367 <indexterm zone="cyrus-sasl pluginviewer">
368 <primary sortas="b-pluginviewer">pluginviewer</primary>
369 </indexterm>
370 </listitem>
371 </varlistentry>
372
373 <varlistentry id="saslauthd">
374 <term><command>saslauthd</command></term>
375 <listitem>
376 <para>
377 is the SASL authentication server
378 </para>
379 <indexterm zone="cyrus-sasl saslauthd">
380 <primary sortas="b-saslauthd">saslauthd</primary>
381 </indexterm>
382 </listitem>
383 </varlistentry>
384
385 <varlistentry id="sasldblistusers2">
386 <term><command>sasldblistusers2</command></term>
387 <listitem>
388 <para>
389 is used to list the users in the SASL password database
390 <filename>sasldb2</filename>
391 </para>
392 <indexterm zone="cyrus-sasl sasldblistusers2">
393 <primary sortas="b-sasldblistusers2">sasldblistusers2</primary>
394 </indexterm>
395 </listitem>
396 </varlistentry>
397
398 <varlistentry id="saslpasswd2">
399 <term><command>saslpasswd2</command></term>
400 <listitem>
401 <para>
402 is used to set and delete a user's SASL password and
403 mechanism specific secrets in the SASL password
404 database <filename>sasldb2</filename>
405 </para>
406 <indexterm zone="cyrus-sasl saslpasswd2">
407 <primary sortas="b-saslpasswd2">saslpasswd2</primary>
408 </indexterm>
409 </listitem>
410 </varlistentry>
411
412 <varlistentry id="testsaslauthd">
413 <term><command>testsaslauthd</command></term>
414 <listitem>
415 <para>
416 is a test utility for the SASL authentication server
417 </para>
418 <indexterm zone="cyrus-sasl testsaslauthd">
419 <primary sortas="b-testsaslauthd">testsaslauthd</primary>
420 </indexterm>
421 </listitem>
422 </varlistentry>
423
424 <varlistentry id="libsasl2">
425 <term><filename class="libraryfile">libsasl2.so</filename></term>
426 <listitem>
427 <para>
428 is a general purpose authentication library for server
429 and client applications
430 </para>
431 <indexterm zone="cyrus-sasl libsasl2">
432 <primary sortas="c-libsasl2">libsasl2.so</primary>
433 </indexterm>
434 </listitem>
435 </varlistentry>
436
437 </variablelist>
438
439 </sect2>
440
441</sect1>
Note: See TracBrowser for help on using the repository browser.