source: postlfs/security/cyrus-sasl.xml

trunk
Last change on this file was b475e4e, checked in by Thomas Trepl <thomas@…>, 9 days ago

Fix cyrus-sasl (gcc14)
  • Property mode set to 100644
File size: 14.4 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 First, fix a flaw revealed by gcc-14:
143 </para>
144<screen><userinput>sed '/saslint/a #include &lt;time.h&gt;' -i lib/saslutil.c
145sed '/plugin_common/a #include &lt;time.h&gt;' -i plugins/cram.c</userinput></screen>
146
147 <para>
148 Install <application>Cyrus SASL</application> by
149 running the following commands:
150 </para>
151
152<screen><userinput>./configure --prefix=/usr \
153 --sysconfdir=/etc \
154 --enable-auth-sasldb \
155 --with-dblib=lmdb \
156 --with-dbpath=/var/lib/sasl/sasldb2 \
157 --with-sphinx-build=no \
158 --with-saslauthd=/var/run/saslauthd &amp;&amp;
159make -j1</userinput></screen>
160
161 <para>
162 This package does not come with a test suite. If you are planning
163 on using the GSSAPI authentication mechanism, test
164 it after installing the package using the sample server and client
165 programs which were built in the preceding step. Instructions for
166 performing the tests can be found at
167 <ulink url="&hints-root;/downloads/files/cyrus-sasl.txt"/>.
168 </para>
169
170 <para>
171 Now, as the <systemitem class="username">root</systemitem> user:
172 </para>
173
174<screen role="root"><userinput>make install &amp;&amp;
175install -v -dm755 /usr/share/doc/cyrus-sasl-&cyrus-sasl-version;/html &amp;&amp;
176install -v -m644 saslauthd/LDAP_SASLAUTHD /usr/share/doc/cyrus-sasl-&cyrus-sasl-version; &amp;&amp;
177install -v -m644 doc/legacy/*.html /usr/share/doc/cyrus-sasl-&cyrus-sasl-version;/html &amp;&amp;
178install -v -dm700 /var/lib/sasl</userinput></screen>
179
180 </sect2>
181
182 <sect2 role="commands">
183 <title>Command Explanations</title>
184
185 <para>
186 <parameter>--with-dbpath=/var/lib/sasl/sasldb2</parameter>: This
187 switch forces the <command>sasldb</command> database to be created
188 in <filename class="directory">/var/lib/sasl</filename> instead of
189 <filename class="directory">/etc</filename>.
190 </para>
191
192 <para>
193 <parameter>--with-saslauthd=/var/run/saslauthd</parameter>: This
194 switch forces <command>saslauthd</command> to use the FHS compliant
195 directory <filename class="directory">/var/run/saslauthd</filename>
196 for variable run-time data.
197 </para>
198
199 <para>
200 <parameter>--enable-auth-sasldb</parameter>: This switch enables
201 SASLDB authentication backend.
202 </para>
203
204 <para>
205 <option>--with-dblib=gdbm</option>: This switch forces
206 <application>GDBM</application> to be used instead of
207 <application>LMDB</application>.
208 </para>
209
210 <para>
211 <option>--with-ldap</option>: This switch enables the
212 <application>OpenLDAP</application> support.
213 </para>
214
215 <para>
216 <option>--enable-ldapdb</option>: This switch enables the
217 LDAPDB authentication backend.
218 </para>
219
220<!-- Removed in 2.1.28
221 <para>
222 <option>- -enable-java</option>: This switch enables compiling of the
223 <application>Java</application> support libraries.
224 </para>
225-->
226
227 <para>
228 <option>--enable-login</option>: This option enables unsupported
229 LOGIN authentication.
230 </para>
231
232 <para>
233 <option>--enable-ntlm</option>: This option enables unsupported
234 NTLM authentication.
235 </para>
236
237 <para>
238 <command>install -v -m644 ...</command>: These commands
239 install documentation which is not installed by the
240 <command>make install</command> command.
241 </para>
242
243 <para>
244 <command>install -v -m700 -d /var/lib/sasl</command>: This directory
245 must exist when starting <command>saslauthd</command> or using the
246 sasldb plugin. If you're not going to be running the daemon or
247 using the plugins, you may omit the creation of this directory.
248 </para>
249
250 </sect2>
251
252 <sect2 role="configuration">
253 <title>Configuring Cyrus SASL</title>
254
255 <sect3 id="cyrus-sasl-config">
256 <title>Config Files</title>
257
258 <para>
259 <filename>/etc/saslauthd.conf</filename>
260 (for <command>saslauthd</command> LDAP configuration) and
261 <filename>/etc/sasl2/Appname.conf</filename>
262 (where "Appname" is the application defined name of the application)
263 </para>
264
265 <indexterm zone="cyrus-sasl cyrus-sasl-config">
266 <primary sortas="e-etc-saslauthd.conf">/etc/saslauthd.conf</primary>
267 </indexterm>
268
269 </sect3>
270
271 <sect3>
272 <title>Configuration Information</title>
273
274 <para>
275 See
276 <ulink url="https://www.cyrusimap.org/sasl/sasl/sysadmin.html"/>
277 for information on what to include in the application configuration files.
278 </para>
279
280 <para>
281 See
282 <ulink url="file:///usr/share/doc/cyrus-sasl-&cyrus-sasl-version;/LDAP_SASLAUTHD"/>
283 for configuring <command>saslauthd</command> with
284 <application>OpenLDAP</application>.
285 </para>
286
287 <para>
288 See
289 <ulink url="https://www.cyrusimap.org/sasl/sasl/gssapi.html#gssapi"/>
290 for configuring <command>saslauthd</command> with <application>Kerberos</application>.
291 </para>
292
293 </sect3>
294
295 <sect3 id="cyrus-sasl-init">
296 <title><phrase revision="sysv">Init Script</phrase>
297 <phrase revision="systemd">Systemd Unit</phrase></title>
298
299 <para revision="sysv">
300 If you need to run the <command>saslauthd</command> daemon at system
301 startup, install the <filename>/etc/rc.d/init.d/saslauthd</filename>
302 init script included in the
303 <xref linkend="bootscripts"/> package using the following command:
304 </para>
305
306 <para revision="systemd">
307 If you need to run the <command>saslauthd</command> daemon at system
308 startup, install the <filename>saslauthd.service</filename> unit
309 included in the <xref linkend="systemd-units"/> package using the
310 following command:
311 </para>
312
313 <indexterm zone="cyrus-sasl cyrus-sasl-init">
314 <primary sortas="f-saslauthd">saslauthd</primary>
315 </indexterm>
316
317<screen role="root"><userinput>make install-saslauthd</userinput></screen>
318
319 <note>
320 <para>
321 You'll need to modify
322 <filename revision="sysv">/etc/sysconfig/saslauthd</filename>
323 <filename revision="systemd">/etc/default/saslauthd</filename>
324 and modify the
325 <option revision="sysv">AUTHMECH</option>
326 <option revision="systemd">MECHANISM</option>
327 parameter with your desired authentication mechanism.
328 <phrase revision="systemd">The default authentication
329 mechanism is "shadow".</phrase>
330 </para>
331 </note>
332
333 </sect3>
334
335 </sect2>
336
337 <sect2 role="content">
338 <title>Contents</title>
339
340 <segmentedlist>
341 <segtitle>Installed Programs</segtitle>
342 <segtitle>Installed Library</segtitle>
343 <segtitle>Installed Directories</segtitle>
344
345 <seglistitem>
346 <seg>
347 pluginviewer, saslauthd, sasldblistusers2, saslpasswd2 and
348 testsaslauthd
349 </seg>
350 <seg>
351 libsasl2.so
352 </seg>
353 <seg>
354 /usr/include/sasl,
355 /usr/lib/sasl2,
356 /usr/share/doc/cyrus-sasl-&cyrus-sasl-version; and
357 /var/lib/sasl
358 </seg>
359 </seglistitem>
360 </segmentedlist>
361
362 <variablelist>
363 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
364 <?dbfo list-presentation="list"?>
365 <?dbhtml list-presentation="table"?>
366
367 <varlistentry id="pluginviewer">
368 <term><command>pluginviewer</command></term>
369 <listitem>
370 <para>
371 is used to list loadable SASL plugins and their properties
372 </para>
373 <indexterm zone="cyrus-sasl pluginviewer">
374 <primary sortas="b-pluginviewer">pluginviewer</primary>
375 </indexterm>
376 </listitem>
377 </varlistentry>
378
379 <varlistentry id="saslauthd">
380 <term><command>saslauthd</command></term>
381 <listitem>
382 <para>
383 is the SASL authentication server
384 </para>
385 <indexterm zone="cyrus-sasl saslauthd">
386 <primary sortas="b-saslauthd">saslauthd</primary>
387 </indexterm>
388 </listitem>
389 </varlistentry>
390
391 <varlistentry id="sasldblistusers2">
392 <term><command>sasldblistusers2</command></term>
393 <listitem>
394 <para>
395 is used to list the users in the SASL password database
396 <filename>sasldb2</filename>
397 </para>
398 <indexterm zone="cyrus-sasl sasldblistusers2">
399 <primary sortas="b-sasldblistusers2">sasldblistusers2</primary>
400 </indexterm>
401 </listitem>
402 </varlistentry>
403
404 <varlistentry id="saslpasswd2">
405 <term><command>saslpasswd2</command></term>
406 <listitem>
407 <para>
408 is used to set and delete a user's SASL password and
409 mechanism specific secrets in the SASL password
410 database <filename>sasldb2</filename>
411 </para>
412 <indexterm zone="cyrus-sasl saslpasswd2">
413 <primary sortas="b-saslpasswd2">saslpasswd2</primary>
414 </indexterm>
415 </listitem>
416 </varlistentry>
417
418 <varlistentry id="testsaslauthd">
419 <term><command>testsaslauthd</command></term>
420 <listitem>
421 <para>
422 is a test utility for the SASL authentication server
423 </para>
424 <indexterm zone="cyrus-sasl testsaslauthd">
425 <primary sortas="b-testsaslauthd">testsaslauthd</primary>
426 </indexterm>
427 </listitem>
428 </varlistentry>
429
430 <varlistentry id="libsasl2">
431 <term><filename class="libraryfile">libsasl2.so</filename></term>
432 <listitem>
433 <para>
434 is a general purpose authentication library for server
435 and client applications
436 </para>
437 <indexterm zone="cyrus-sasl libsasl2">
438 <primary sortas="c-libsasl2">libsasl2.so</primary>
439 </indexterm>
440 </listitem>
441 </varlistentry>
442
443 </variablelist>
444
445 </sect2>
446
447</sect1>
Note: See TracBrowser for help on using the repository browser.