1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
|
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>INSTALL</title>
<!-- Copyright 2004-2024 Double Precision, Inc. See COPYING for -->
<!-- distribution information. -->
<style type="text/css">
/*<![CDATA[*/
span.c1 {font-family: monospace}
/*]]>*/
</style>
</head>
<body>
<h1>Table of Contents</h1>
<p>In this document (see INSTALL.html for the formatted version of this
INSTALL file):</p>
<ul>
<li>
<a href="#Requirements">Requirements</a>
</li>
<li>
<a href="#Installation">Installation overview</a>
</li>
<li>
<a href="#deps">Dependencies</a>
</li>
<li>
<a href="#What">What gets installed</a>
</li>
<li>
<a href="#manpage">For more information</a>
</li>
<li>
<a href="#Starting">Starting and stopping the authentication daemon</a>
</li>
<li>
<a href="#Guidelines">Guidelines for using other package managers</a>
</li>
</ul>
<h2><a id="Requirements">Requirements</a></h2>
<p>See the README file for a general description of this library. The
following software should be installed before building the Courier
authentication library:</p>
<ul>
<li>gcc that supports at least C++17 (<a href=
"http://www.gnu.org/software/gcc/">http://www.gnu.org/software/gcc/</a>)
</li>
<li>The GNU linker (<a href=
"http://www.gnu.org/software/binutils/">http://www.gnu.org/software/binutils/</a>)
</li>
<li>Libtool (<a href=
"http://www.gnu.org/software/libtool/">http://www.gnu.org/software/libtool/</a>).
Additionally, libtool's <span class="c1">libltdl</span> library, and its
development files, must be installed. On some platforms this is a separate
package. On Fedora, this is the <span class="c1">libtool-ltdl-devel</span>
package, for example.
</li>
<li>GNU make (<a href=
"http://www.gnu.org/software/make/">http://www.gnu.org/software/make/</a>)
</li>
<li>The "<span class="c1">expect</span>" command. <span class=
"c1">expect</span> is usually included with most systems. <span class=
"c1">Expect</span> can be downloaded from <span class=
"c1">http://expect.nist.gov/</span> if it's not installed on your system.
This utility is used to change system login passwords, by scripting the
<span class="c1">passwd</span> command. If you do not have <span class=
"c1">expect</span> installed you will not be able to change system login
passwords. However non-system authentication modules (LDAP, PostgreSQL, and
others) will work.</li>
<li>Courier Unicode Library. Before installing this package, download and
install <a href=
"https://www.courier-mta.org/unicode/">https://www.courier-mta.org/unicode/</a>.
</li>
</ul>
<p>Courier-authlib uses Libtool to build shared libraries. Libtool must be
installed, together with its <span class="c1">libltdl</span> library and its
header files.</p>
<p>On non-Linux platforms the GNU linker is also required. Courier-authlib's
build script uses some GNU linker-specific options. It's possible to manually
specify the native linker's equivalent options manually, if they exist. If
the native linker does not have the equivalent options, the GNU linker will
have to be installed.</p>
<p>On the other hand, GNU make will be required in almost every case.
SYSV-derived make variants (probably) will not work.</p>
<p>The same line of logic also applies to gcc. So, strictly speaking, only a
basic C++ compiler, GNU make and libtool, are really needed to build
courier-authlib. Still, try the following before giving up if problems occur
when building this package:</p>
<ol>
<li>Install a recent version of the GNU linker</li>
<li>Install the current version of Libtool</li>
<li>Install the current version of gcc</li>
</ol>
<h2><a id="Installation">Installation overview</a></h2>
<h3>rpm and deb packages</h3>
<p>These are not the same packages as the ones from the distributions'
repositories. These packages carry a higher internal revision level in order
to prevent them from getting upgraded by the distributions' packages. This
packaging exists in order to have a convenient way of updating after a
release without waiting for the distributions' packages to get built.</p>
<p><b>NOTE:</b> If a distribution package is already installed it should be
removed completely before switching to the upstream version (<span class=
"c1">dnf remove</span> or <span class="c1">apt purge</span>). Preserve any
existing configuration files, beforehand, in order to restore it after
switching packages. This applies to all Courier packages. A switch to this
courier-authlib package requires switching to the courier-unicode package
too.</p>
<p><b>NOTE:</b> These packages use their own, generic, installation layout
that may deviate slightly from the package installation conventions preferred
by the distributions.</p>
<h3>rpm</h3>
<p>Run <span class="c1">dnf install rpm-build</span> if it's not installed
already, then:</p>
<pre>rpmbuild -ta courier-authlib-VERSION.tar.bz2</pre>
<p>If this fails due to any missing dependencies, install them. This builds:
the main (runtime libraries); a subpackage for each authentication module
(LDAP, MariaDB/MySQL, etc...); the development (link libraries, header files)
package. All development libraries needed to build all authentication modules
must be installed to build the rpms, but do not need to be installed at
runtime unless the corresponding authentication module rpm is also
installed.</p>
<p>This creates rpms that can be installed with "rpm -U":</p>
<ul>
<li>The "courier-authlib" package with the commands and standard
authentication modules.</li>
<li>The "courier-authlib-devel" package with development libraries and
header files.</li>
<li>The "courier-authlib-config-<i>username</i>-<i>groupname</i> package.
This is a metapackage that captures the user/group used by the
authentication library (<span class="c1">daemon</span>/<span class=
"c1">daemon</span>) by default. The dependencies on the metapackage are set
up in a way to prevent unitended updates to an incompatible newer version
that's configured with different user and group names.</li>
<li>Other "courier-authlib-<i>name</i>" authentication modules.</li>
</ul>
<h4>Rocky/RHEL 8/9 notes</h4>
<p>Courier packages require C++17 support, but the default version
of gcc does not fully support it, and a newer gcc is needed:</p>
<pre>dnf install --enablerepo=crb -y gcc-toolset-14
scl enable gcc-toolset-14 "rpmbuild -ta courier-authlib-VERSION.tar.bz2"</pre>
<h4>Using non-default courier username and groupname</h4>
<p>Pass <span class="c1">--define "mailuser courier"</span> and <span class=
"c1">--define "mailgroup courier"</span> options to <command />rpmbuild to
build the library with a non-default user and group name.</p>
<h3>deb</h3>
<p>Run "apt install devscripts debhelper", if they're not installed already.
Create an empty directory and copy/move the tarball into it:</p>
<pre>
$ mkdir tmp
$ mv courier-authlib-VERSION.tar.bz2 tmp
$ cd tmp</pre>
<p>Unpack the tarball and cd into the unpacked subdirectory:</p>
<pre>
$ tar xvf courier-authlib-VERSION.tar.bz2
$ cd courier-authlib-VERSION</pre>
<p>Run the <span class="c1">courier-debuild</span> script, which is a wrapper
for <span class="c1">debuild</span>, and forwards its parameters to it:</p>
<pre>$ ./courier-debuild -us -uc</pre>
<p>NOTE: the above steps must be followed strictly. The <span class=
"c1">courier-debuild</span> script expects the distributed tarball in its
parent directory.</p>
<p>This eventually produces a deb subdirectory with <span class=
"c1">.deb</span> packages that can be installed with "dpkg -i":</p>
<ul>
<li>The "libcourier-auth" package with the commands and standard
authentication modules; and "libcourier-auth-<i><N></i>" with
versioned client shared libraries.</li>
<li>The "libcourier-auth-dev" package with development libraries and header
files.</li>
<li>Other "libcourier-auth-<i>name</i>" authentication modules.</li>
<li>The "<span class=
"c1">libcourier-auth-config-<i>mailuser</i>-<i>mailgroup</i></span>"
package. This package sets up the reserved user and group id the library
and the rest of the Courier packages use. When the built <span class=
"c1">.deb</span> packages get manually installed directly with <span class=
"c1">dpkg</span> this "config" package must get installed first, by itself,
followed by the rest of the packages. Higher level tools, like <span class=
"c1">apt</span> should figure this out by themselves.</li>
</ul>
<p>NOTE: if the courier-debuild script stops with an error complaining about
missing dependencies, then use "apt install" to install them, then try
again.</p>
<pre>$ DEBGCC=10 ./courier-debuild -us -uc</pre>
<p>Setting the <span class="c1">DEBGCC</span> environment variable selects a
non-default gcc version.</p>
<p>NOTE: All Courier packages should be built with the same version of gcc,
which is selected by the <span class="c1">DEBGCC</span> environment variable
before running <span class="c1">courier-debuild</span>. <a href=
"https://www.courier-mta.org/unicode/INSTALL.html">See
<i>courier-unicode</i>'s <i>INSTALL</i> for more information</a>.</p>
<h4>Using non-default courier username and groupname</h4>
<pre>$ mailuser=courier mailgroup=courier ./courier-debuild -us -uc</pre>
<p>Setting the <span class="c1">mailuser</span> and <span class=
"c1">mailgroup</span> environment builds the library with a non-default user
and group name.</p>
<h4>Ubuntu and Debian</h4>
<p>Courier packages require C++17 support, but the default version
of gcc on Ubuntu 20 does not fully support it, and a newer gcc is needed:</p>
<pre>$ sudo apt install -y gcc-10 g++-10
$ DEBGCC=10 ./courier-debuild -us -uc</pre>
<p><code>make check</code> requires both the ISO-8859-1 based
<code>en_US</code> locale in addition to the default
<code>en_US.UTF-8</code>, on all versions of Ubuntu and Debian.</p>
<h3>Maintainer Mode (see README in the git repository to set up)</h3>
<p><span class="c1">make rpm</span> or <span class="c1">make deb</span>, as
appropriate, will:</p>
<ol>
<li>
<p>Increment an internal release number.</p>
</li>
<li>
<p>Run <span class="c1">make dist</span>.</p>
</li>
<li>
<p>Proceed and build a new release, creating the native packages in the
rpm or deb subdirectory.</p>
</li>
<li>
<p>Execute either <span class="c1">$HOME/bin/rpmrepos.sh</span> or
<span class="c1">$HOME/bin/debrepos.sh</span>. This can be a script that
does nothing, or it's intended to be the maintainer's script that pushes
out the packages to a repository.</p>
</li>
</ol>
<h3>Manual installation</h3>
<p>The following sequence of commands should be sufficient to install
courier-authlib in most cases:</p>
<pre>
./configure [options] [variable=value]*...
make
make install
make install-configure
</pre>
<blockquote>
<p><strong>NOTE:</strong> On the BSD family, GNU make is usually the
'gmake' command. Use the 'gmake' command, instead of 'make'.</p>
</blockquote>
<p>The '<span class="c1">make install-configure</span>' command is required;
it installs and updates the configuration files; this command must be
executed when installing courier-authlib for the first time, and when
upgrading from an older version.</p>
<h3>Configuration options</h3>
<p>The configure script takes the usual <span class="c1">autoconf</span>
options: <span class="c1">--prefix</span>, <span class="c1">--bindir</span>,
and the rest of the usual toolchain options. The default installation
directories should be sufficient, though.</p>
<p><strong>DO NOT USE</strong> the <span class="c1">--disable-static</span>,
or <span class="c1">--enable-static=no</span> option. Both static and shared
library options must be enabled for courier-authlib to build properly (but
see "Post-installation cleanup" below).</p>
<h4><span class="c1">--without-stdheaderdir</span></h4>
<p>The default configuration installs development files in <span class=
"c1">/usr/local/include</span> (see "What gets installed", below). This
directory is usually in the compiler's search path for header files. This
option must be specified if the compiler does NOT search for header files in
<span class="c1">/usr/local/include</span> by default.</p>
<p>This option must also be specified if other configuration options (such as
<span class="c1">--prefix</span> or <span class="c1">--includedir</span>)
specify a different installation directory, and the new directory is also not
searched by the compiler, by default</p>
<h4><span class="c1">--with-mailuser=<em>userid</em>,
--with-mailgroup=<em>groupid</em></span></h4>
<p>"userid" is a reserved system username, "groupid" is a reserved system
groupname. These two options should be used before installing Courier for the
first time. These options are not required before installing Courier-IMAP or
SqWebMail.</p>
<p>These options specify the user/group that will own the configuration
files, and the socket that authentication daemon process listens on. This is
a key part of Courier's security model.</p>
<p>These options should not be necessary if upgrading from an earlier version
of Courier and/or this authentication library. The default userid and groupid
are computed as follows:</p>
<ul>
<li>If an earlier version of the Courier authentication library is already
installed in the same directory, the userid and the groupid is the same as
the earlier version, otherwise:</li>
<li>The userid is the first userid from the following list which exists in
the system: courier, daemon, adm, bin, root; and the groupid is the first
groupid from the following list which exists in the system: courier,
daemon, adm, sys, root.</li>
</ul>
<p>When installing Courier authentication library for the first time, it is
highly recommended to create a "courier" userid and groupid, so that
specifying these options will not be necessary.</p>
<h4><span class="c1">VARIABLE=</span><em><span class=
"c1">value</span></em></h4>
<p>Environment variables may be set either before running the configure
script, or by providing the environment variables as parameters to the
configure script. Example:</p>
<blockquote>
<pre>
./configure --with-mailuser=mail --with-mailgroup=mail \
CC=gcc-10 CXX=g++-10 LDFLAGS=-L/opt/fsf/lib \
MAKE=gmake
</pre>
</blockquote>
<p>The <span class="c1">CC</span> and <span class="c1">CXX</span> environment
variables specify the C compiler that will be used to compile the
authentication library. <span class="c1">LDFLAGS</span> specifies additiona
linker flags, etc...</p>
<h2><a id="deps">Dependencies</a></h2>
<p>On a minimum, bare-bones system, the Courier authentication library builds
support for garden-variety authentication against system accounts (from the
system's password file, <span class="c1">/etc/passwd</span>).</p>
<p>If the <span class="c1">configure</span> script detects that certain
optional software components are installed, additional authentication modules
will be built and installed. This chapter describes what needs to be
installed in order to build the optional authentication modules.</p>
<blockquote>
<p><strong>NOTE:</strong> In all cases, it is not sufficient to install the
runtime support libraries for the following components. In order to build
the authentication modules the <strong>DEVELOPMENT LIBRARIES</strong> for
the following software packages must be installed. The development
libraries are usually a separate package, that must be installed in
addition to the package that adds alleged support for the following
software libraries.</p>
</blockquote>
<ul>
<li><strong>GDBM or Berkeley DB library</strong> - The <span class=
"c1">userdb</span> authentication module will be built if either library is
installed. The <span class="c1">userdb</span> authentication module
includes Perl scripts that maintain a list of available accounts in plain
text files. A Perl script then compiles the account list into a binary
database, either GDBM or DB, which is then used to look up account
information.</li>
<li><strong>OpenLDAP</strong> - The LDAP authentication modules requires
OpenLDAP client libraries to be installed. Sometimes there's some confusion
when commercial LDAP servers are used, which come with their own
development toolkits, which use a different API than OpenLDAP. Even if a
commercial LDAP server is used to provide LDAP services, OpenLDAP is still
required to enable LDAP services in Courier.</li>
<li><strong>MariaDB/MySQL</strong>, <strong>PostgreSQL</strong>, and
<strong>SQLite</strong> - The MariaDB, PostgreSQL, and SQLite
authentication modules require, obviously, MariaDB/PostgreSQL/SQLite
development libraries.<br /></li>
</ul>
<h2><a id="What">What gets installed</a></h2>
<ul>
<li><span class="c1">/usr/local/etc/authlib</span> - the configuration
files.</li>
<li><span class="c1">/usr/local/sbin</span> - the authdaemond startup
script; several utility programs (courierlogger, authconfig, authtest,
authenumerate); and userdb scripts.</li>
<li><span class="c1">/usr/local/lib/courier-authlib</span> - various
authentication modules, as shared libraries.</li>
<li><span class="c1">/usr/local/libexec/courier-authlib</span> - some
miscellaneous stuff.</li>
<li><span class="c1">/usr/local/var/authdaemon</span> - a subdirectory that
contains the filesystem socket which authdaemond listens on.</li>
<li><span class="c1">/usr/local/include</span> - a header file that Courier
packages will use to build against courier-authlib.</li>
</ul>
<p>Toolchain options to the <span class="c1">configure</span> script may be
used to select alternative installation directories for these components.</p>
<h3>Post-installation cleanup</h3>
<p>On most systems, after running <span class="c1">make
install-configure</span> all static libraries can be removed from the
<span class="c1">/usr/local/lib/courier-authlib</span> directory:</p>
<p><span class="c1">rm -rf /usr/local/lib/courier-authlib/*.a</span></p>
<p>The Courier authentication library uses only the shared libraries. The
static versions of the shared libraries are not used. They are installed by
default, via libtool, but are not really needed. On most platforms the
libtool files, "*.la" can also be removed. Do not remove any soft links.</p>
<h2><a id="manpage">For more information</a></h2>
<p>Following "<span class="c1">make install</span>", see the <a href=
"README_authlib.html"><span class="c1">README_authlib.html</span></a> file
for details on setting up the authentication modules. The <span class=
"c1">README_authlib.html</span> file gets assembled as part of the build
process.</p>
<p>Before proceding to install any other packages, be sure to verify that the
authentication library is working by running the <span class=
"c1">authtest</span> command, as documented in the <span class=
"c1">README_authlib.html</span> file.</p>
<h2><a id="Starting">Starting and stopping the authentication daemon</a></h2>
<p>Arrangements must be made to run the <span class=
"c1">courier-authlib.sysvinit</span> script with "start" and "stop"
parameters at system startup and shutdown. <span class="c1">make
install</span> does not install this script from the source directory, it
needs to be installed manually.</p>
<h2><a id="Guidelines">Guidelines for using other package managers</a></h2>
<p>The recommended way to build packages can be inferred from the RPM build
script. It is summarized here for convenience:</p>
<ul>
<li>Decide whether or not Courier-specific userid and groupid needs to be
created, and, if so, make the necessary arrangements.</li>
<li>Ensure that all prerequisite development libraries are available.</li>
<li>Run the <span class="c1">configure</span> script, run <span class=
"c1">make</span>, then <span class="c1">make install</span> as usual.</li>
<li>Copy the "<span class="c1">sysconftool</span>" script somewhere into
the installation tree. A good place would be <span class=
"c1">%libexecdir%/courier-authlib</span>. This is the '<span class=
"c1">make install-upgrade</span>' command. Don't run this at build time.
Instead, arrange for the package installation script to run the
"<span class="c1">sysconftool %sysconfdir%/authlib/*.dist</span>" after the
package is installed <strong>OR UPGRADED</strong>.</li>
<li>The "<span class="c1">authdaemond</span>", "<span class=
"c1">authenumerate</span>", and "<span class="c1">authtest</span>" commands
can be renamed, to avoid name clashes.</li>
<li>There are two types of libraries that get installed in <span class=
"c1">%libdir%</span>:
<ol>
<li>Common libraries that application link with, <span class=
"c1">libcourier*</span>.</li>
<li>Dynamically-loaded authentication modules: <span class=
"c1">libauth*</span>.</li>
</ol>
<p>Remove all static libraries from <span class=
"c1">%libdir%/courier-authlib</span>. Keep the <span class=
"c1">*.la</span> and <span class="c1">*.so</span> for <span class=
"c1">libcourier*</span>, and include them in a devel subpackage. Remove
<span class="c1">*.la</span> and <span class="c1">*.so</span> for all
<span class="c1">libauth*</span> libraries, they are not needed.</p>
</li>
</ul>
<p>Now, create the installable packages, as follows:</p>
<ul>
<li><span class="c1">%libdir%/courier-authlib/libauthldap*</span> goes into
the LDAP subpackage.</li>
<li><span class="c1">%libdir%/courier-authlib/libauthmysql*</span> goes
into the MariaDB/MySQL subpackage.</li>
<li><span class="c1">%libdir%/courier-authlib/libauthsqlite*</span> goes
into the SQLite subpackage.</li>
<li><span class="c1">%libdir%/courier-authlib/libauthpgsql*</span> goes
into the PostgreSQL subpackage.</li>
<li><span class="c1">%libdir%/courier-authlib/libauthuserdb*</span> goes
into the userdb subpackage.</li>
<li>Everything else can go into the main package. Optionally, the
<span class="c1">courierauthconfig</span> binary, stuff in <span class=
"c1">%includedir%</span>, and in <span class="c1">%mandir%/man3</span>, can
go into a devel subpackage.</li>
</ul>
</body>
</html>
|
