Commit | Line | Data |
---|---|---|
d9898ee8 | 1 | Table of Contents |
2 | ||
3 | In this document (see INSTALL.html for the formatted version of this | |
4 | INSTALL file): | |
5 | ||
b0322a85 CE |
6 | * [1]Requirements |
7 | * [2]Installation overview | |
8 | * [3]Dependencies | |
9 | * [4]What gets installed | |
10 | * [5]For more information | |
11 | * [6]Starting and stopping the authentication daemon | |
12 | * [7]Building RPMs | |
13 | * [8]Guidelines for using other package managers | |
d9898ee8 | 14 | |
15 | Requirements | |
16 | ||
17 | See the README file for a general description of this library. The | |
18 | following software should be installed before building the Courier | |
19 | authentication library: | |
20 | ||
b0322a85 CE |
21 | * A modern version of gcc ([9]http://www.gnu.org/software/gcc/) |
22 | * The GNU linker ([10]http://www.gnu.org/software/binutils/) | |
23 | * Libtool ([11]http://www.gnu.org/software/libtool/). Additional, | |
24 | libtool's libltdl library, and its development files, must be | |
25 | installed. On some platforms this is a separate package. On Fedora, | |
26 | this is the libtool-ltdl-devel package, for example. | |
27 | * GNU make ([12]http://www.gnu.org/software/make/) | |
28 | * The "expect" command. expect is usually included with most systems. | |
d9898ee8 | 29 | Expect can be downloaded from http://expect.nist.gov/ if it's not |
30 | installed on your system. This utility is used to change system login | |
31 | passwords, by scripting the passwd command. If you do not have expect | |
32 | installed you will not be able to change system login passwords. | |
33 | However non-system authentication modules (LDAP, PostgreSQL, and | |
34 | others) will work. | |
d50284c4 CE |
35 | * Courier Unicode Library. Before installing Courier-IMAP, download and |
36 | install [13]http://www.courier-mta.org/unicode/. | |
d9898ee8 | 37 | |
b0322a85 CE |
38 | Courier-authlib uses Libtool to build shared libraries. Libtool must be |
39 | installed, together with its libltdl library and its header files. | |
d9898ee8 | 40 | |
41 | On non-Linux platforms the GNU linker is also required. Courier-authlib's | |
42 | build script uses some GNU linker-specific options. It's possible to | |
43 | manually specify the native linker's equivalent options manually, if they | |
44 | exist. If the native linker does not have the equivalent options, the GNU | |
45 | linker will have to be installed. | |
46 | ||
47 | On the other hand, GNU make will be required in almost every case. | |
48 | SYSV-derived make variants (probably) will not work. | |
49 | ||
50 | The same line of logic also applies to gcc. So, strictly speaking, only a | |
51 | basic C compiler, GNU make and libtool, are really needed to build | |
52 | courier-authlib. Still, try the following before giving up if problems | |
53 | occur when building this package: | |
54 | ||
b0322a85 CE |
55 | 1. Install a recent version of the GNU linker |
56 | 2. Install the current version of Libtool | |
57 | 3. Install the current version of gcc | |
d9898ee8 | 58 | |
59 | Installation overview | |
60 | ||
61 | The following sequence of commands should be sufficient to install | |
62 | courier-authlib in most cases: | |
63 | ||
64 | ./configure [options] [variable=value]*... | |
65 | make | |
66 | make install | |
dd184caf | 67 | make install-migrate # Only if upgrading from pre-authlib Courier packages |
d9898ee8 | 68 | make install-configure |
69 | ||
70 | NOTE: On the BSD family, GNU make is usually the 'gmake' command. Use | |
71 | the 'gmake' command, instead of 'make'. | |
72 | ||
73 | NOTE: It might appear that the configure script is stuck in an infinite | |
74 | loop. This is only an optical illusion. The configure script takes | |
75 | several minutes to complete. The Courier authentication library consists | |
76 | of many small modules, each with its own configuration script; and all | |
77 | configuration scripts are built from the same template. When they are | |
78 | invoked, one at a time, an illusion of an infinite loop appears. | |
79 | ||
80 | Courier-authlib is a requirement starting with the following Courier | |
81 | package versions: Courier 0.48, Courier-IMAP 4.0, SqWebMail 5.0. When | |
82 | upgrading from earlier versions of these packages, install the | |
83 | Courier-authlib package first, then upgrade the existing package. | |
84 | ||
85 | The 'make install-migrate' command imports the authentication | |
86 | configuration from earlier versions of these packages. 'make | |
87 | install-migrate' is not needed otherwise. | |
88 | ||
89 | The 'make install-migrate' command searches all the known default | |
90 | installation directories for Courier, Courier-IMAP, and SqWebMail, and | |
91 | imports the older configuration files. If the older versions of these | |
92 | packages are installed in some unusual, non-standard, directories, the | |
93 | make install-migrate command won't find them. Instead, copy those | |
94 | configuration files (authdaemonrc, authldaprc, authmysqlprc, authpgsqlprc, | |
95 | and userdb) by hand. DO NOT COPY authdaemonrc.dist, authldaprc.dist, | |
96 | authmysqlprc.dist, and authpgsqlprc.dist. | |
97 | ||
98 | After finishing 'make install-migrate', the rest of the installation | |
99 | steps, and after upgrading Courier, Courier-IMAP, or SqWebMail to the new | |
100 | versions, to avoid future confusion the old copies of these configuration | |
101 | files (including the .dist files), should be removed from | |
102 | Courier/Courier-IMAP/SqWebMail's configuration directory. They now live in | |
103 | Courier-authlib's configuration directory (/usr/local/etc/authlib, or | |
104 | whatever was specified to the configure script). | |
105 | ||
106 | The 'make install-configure' command is required; it installs and updates | |
107 | the configuration files; this command must be executed when installing | |
108 | Courier-authlib for the first time, and when upgrading from an older | |
109 | version. | |
110 | ||
111 | Configuration options | |
112 | ||
113 | The configure script takes the usual autoconf options: --prefix, --bindir, | |
114 | and the rest of the usual toolchain options. The default installation | |
115 | directories should be sufficient, though. | |
116 | ||
117 | DO NOT USE the --disable-static, or --enable-static=no option. Both static | |
118 | and shared library options must be enabled for courier-authlib to build | |
119 | properly (but see "Post-installation cleanup" below). | |
120 | ||
121 | --without-stdheaderdir | |
122 | ||
123 | The default configuration installs development files in /usr/local/include | |
124 | (see "What gets installed", below). This directory is usually in the | |
125 | compiler's search path for header files. This option must be specified if | |
126 | the compiler does NOT search for header files in /usr/local/include by | |
127 | default. | |
128 | ||
129 | This option must also be specified if other configuration options (such as | |
130 | --prefix or --includedir) specify a different installation directory, and | |
131 | the new directory is also not searched by the compiler, by default | |
132 | ||
133 | --with-mailuser=userid, --with-mailgroup=groupid | |
134 | ||
135 | "userid" is a reserved system username, "groupid" is a reserved system | |
136 | groupname. These two options should be used before installing Courier for | |
137 | the first time. These options are not required before installing | |
138 | Courier-IMAP or SqWebMail. | |
139 | ||
140 | These options specify the user/group that will own the configuration | |
141 | files, and the socket that authentication daemon process listens on. This | |
142 | is a key part of Courier's security model. | |
143 | ||
144 | These options should not be necessary if upgrading from an earlier version | |
145 | of Courier and/or this authentication library. The default userid and | |
146 | groupid are computed as follows: | |
147 | ||
b0322a85 | 148 | * If an earlier version of the Courier authentication library is already |
d9898ee8 | 149 | installed in the same directory, the userid and the groupid is the |
150 | same as the earlier version, otherwise: | |
b0322a85 | 151 | * If an earlier version of the Courier package is installed (only the |
d9898ee8 | 152 | Courier package, the Courier-IMAP and SqWebMail packages do not carry |
153 | this information), the userid and the groupid is the same as the ones | |
154 | used to configure Courier, otherwise: | |
b0322a85 | 155 | * The userid is the first userid from the following list which exists in |
d9898ee8 | 156 | the system: courier, daemon, adm, bin, root; and the groupid is the |
157 | first groupid from the following list which exists in the system: | |
158 | courier, daemon, adm, sys, root. | |
159 | ||
160 | When installing Courier authentication library for the first time, it is | |
161 | highly recommended to create a "courier" userid and groupid, so that | |
162 | specifying these options will not be necessary. | |
163 | ||
164 | This configure script descends from the old authentication library that | |
165 | was included in the older Courier, Courier-IMAP, and SqWebMail packages. | |
166 | As such, it also has many other undocumented options that manually disable | |
167 | specific authentication modules. | |
168 | ||
169 | These options are no longer officially documented. Individual modules can | |
170 | be disabled after installation, by editing the authdaemonrc configuration | |
171 | file. | |
172 | ||
173 | VARIABLE=value | |
174 | ||
175 | Environment variables may be set either before running the configure | |
176 | script, or by providing the environment variables as parameters to the | |
177 | configure script. Example: | |
178 | ||
179 | ./configure --with-mailuser=mail --with-mailgroup=mail \ | |
180 | CC=/opt/fsf/bin/gcc LDFLAGS=-L/opt/fsf/lib \ | |
181 | MAKE=gmake | |
182 | ||
183 | The CC environment variable specifies the name of the C compiler that will | |
184 | be used to compile the authentication library. For some reason, on this | |
185 | oddball system some system libraries are installed in /opt/fsf/lib, and | |
186 | the compiler doesn't search this directory by default. Therefore, the | |
187 | compiler needs the "-L/opt/fsf/lib" to properly link all programs, and | |
188 | this option is specified in the LDFLAGS environment variable. | |
189 | ||
190 | Another possibility is to add the /opt/fsf/bin directory to the PATH | |
191 | environment variable, prior to running the configure script. The configure | |
192 | script searches for all needed software in the current PATH. Explicitly | |
193 | pointing configure to something, like CC, is only needed if the program is | |
194 | not already in the default PATH. | |
195 | ||
196 | Finally, Courier authentication library must be built with GNU make. On | |
197 | this example system the make command is the old SysV-derived make, which | |
198 | will not work. GNU make is installed here as the "gmake" command. The | |
199 | configure script will ordinarily find the make command and be happy with | |
200 | it, by mistake. Explicitly setting MAKE to gmake fixes that (and the human | |
201 | operator also needs to invoke the gmake command also). | |
202 | ||
203 | Dependencies | |
204 | ||
205 | On a minimum, bare-bones system, the Courier authentication library builds | |
206 | support for garden-variety authentication against system accounts (from | |
207 | the system's password file, /etc/passwd). | |
208 | ||
209 | If the configure script detects that certain optional software components | |
210 | are installed, additional authentication modules will be built and | |
211 | installed. This chapter describes what needs to be installed in order to | |
212 | build the optional authentication modules. | |
213 | ||
214 | NOTE: In all cases, it is not sufficient to install the runtime support | |
215 | libraries for the following components. In order to build the | |
216 | authentication modules the DEVELOPMENT LIBRARIES for the following | |
217 | software packages must be installed. The development libraries are | |
218 | usually a separate package, that must be installed in addition to the | |
219 | package that adds alleged support for the following software libraries. | |
220 | ||
b0322a85 | 221 | * GDBM or Berkeley DB library - The userdb authentication module will be |
d9898ee8 | 222 | built if either library is installed. The userdb authentication module |
223 | includes Perl scripts that maintain a list of available accounts in | |
224 | plain text files. A Perl script then compiles the account list into a | |
225 | binary database, either GDBM or DB, which is then used to look up | |
226 | account information. | |
b0322a85 | 227 | * OpenLDAP - The LDAP authentication modules requires OpenLDAP client |
d9898ee8 | 228 | libraries to be installed. Sometimes there's some confusion when |
229 | commercial LDAP servers are used, which come with their own | |
230 | development toolkits, which use a different API than OpenLDAP. Even if | |
231 | a commercial LDAP server is used to provide LDAP services, OpenLDAP is | |
232 | still required to enable LDAP services in Courier. | |
b0322a85 CE |
233 | * MySQL, PostgreSQL, and SQLite - The MySQL, PostgreSQL, and SQLite |
234 | authentication modules require, obviously, MySQL/PostgreSQL/SQLite | |
235 | development libraries. | |
d9898ee8 | 236 | |
237 | What gets installed | |
238 | ||
b0322a85 CE |
239 | * /usr/local/etc/authlib - the configuration files. |
240 | * /usr/local/sbin - the authdaemond startup script; several utility | |
d9898ee8 | 241 | programs (courierlogger, authconfig, authtest, authenumerate); and |
242 | userdb scripts. | |
b0322a85 | 243 | * /usr/local/lib/courier-authlib - various authentication modules, as |
d9898ee8 | 244 | shared libraries. |
b0322a85 CE |
245 | * /usr/local/libexec/courier-authlib - some miscellaneous stuff. |
246 | * /usr/local/var/authdaemon - a subdirectory that contains the | |
d9898ee8 | 247 | filesystem socket which authdaemond listens on. |
b0322a85 | 248 | * /usr/local/include - a header file that Courier packages will use to |
d9898ee8 | 249 | build against courier-authlib. |
250 | ||
251 | Toolchain options to the configure script may be used to select | |
252 | alternative installation directories for these components. | |
253 | ||
254 | Post-installation cleanup | |
255 | ||
256 | On most systems, after running make install-configure all static libraries | |
257 | can be removed from the /usr/local/lib/courier-authlib directory: | |
258 | ||
259 | rm -rf /usr/local/lib/courier-authlib/*.a | |
260 | ||
261 | The Courier authentication library uses only the shared libraries. The | |
262 | static versions of the shared libraries are not used. They are installed | |
263 | by default, via libtool, but are not really needed. On most platforms the | |
264 | libtool files, "*.la" can also be removed. Do not remove any soft links. | |
265 | ||
266 | For more information | |
267 | ||
d50284c4 | 268 | Following "make install", see the [14]README_authlib.html file for details |
d9898ee8 | 269 | on setting up the authentication modules. The README_authlib.html file |
270 | gets assembled as part of the build process. | |
271 | ||
272 | Before proceding to install any other packages, be sure to verify that the | |
273 | authentication library is working by running the authtest command, as | |
274 | documented in the README_authlib.html file. | |
275 | ||
276 | Starting and stopping the authentication daemon | |
277 | ||
278 | The following command must be added to your system startup script, in | |
279 | order to initialize the authentication library when booting: | |
280 | ||
281 | /usr/local/sbin/authdaemond start | |
282 | ||
283 | Similarly, the authentication library can be stopped by the "authdaemond | |
284 | stop" command. After editing the authdaemonrc configuration file use | |
285 | "authdaemond restart" command to reconfigure the daemon process. Systems | |
286 | that use SYSV-derived initscripts can use the "courier-authlib.sysvinit" | |
287 | script, which gets built in the source directory, to start and stop | |
288 | authdaemond when the system boots or halts. | |
289 | ||
290 | Building RPMs | |
291 | ||
292 | See http://www.courier-mta.org/FAQ.html#rpm for instructions on building | |
293 | binary RPMs from the source tarball. Those instructions will work for this | |
294 | package. | |
295 | ||
296 | NOTE: | |
297 | ||
298 | RPM will refuse to build the Courier authentication library unless all | |
b0322a85 CE |
299 | prerequisite development libraries for LDAP, MySQL, PostgreSQL, and |
300 | SQLite are installed. Do not try to hack the RPM build script to ignore | |
301 | these dependencies! For simplicity's and maintainability sake the RPM | |
302 | build script creates all available authentication modules. All extra | |
d9898ee8 | 303 | authentication modules will be built as optional subpackages. They do |
b0322a85 CE |
304 | not have to be installed at runtime. Install the LDAP, MySQL, |
305 | PostgreSQL, and SQLite development libraries only for the duration of | |
306 | building binary RPMs. They can be uninstalled afterwards. | |
d9898ee8 | 307 | |
308 | Guidelines for using other package managers | |
309 | ||
310 | The recommended way to build packages can be inferred from the RPM build | |
311 | script. It is summarized here for convenience: | |
312 | ||
b0322a85 | 313 | * Decide whether or not Courier-specific userid and groupid needs to be |
d9898ee8 | 314 | created, and, if so, make the necessary arrangements. |
b0322a85 CE |
315 | * Ensure that all prerequisite development libraries are available. |
316 | * Run the configure script, run make, then make install as usual. | |
317 | * Copy the "sysconftool" script somewhere into the installation tree. A | |
8d138742 CE |
318 | good place would be %libexecdir%/courier-authlib. This is the 'make |
319 | install-upgrade' command. Don't run this at build time. Instead, | |
320 | arrange for the package installation script to run the "sysconftool | |
321 | %sysconfdir%/authlib/*.dist" after the package is installed OR | |
322 | UPGRADED. | |
b0322a85 | 323 | * The "authdaemond", "authenumerate", and "authtest" commands can be |
d9898ee8 | 324 | renamed, to avoid name clashes. |
b0322a85 | 325 | * Remove all static libraries from %libdir%/courier-authlib. |
d9898ee8 | 326 | |
327 | Now, create the installable packages, as follows: | |
328 | ||
b0322a85 CE |
329 | * %libdir%/courier-authlib/libauthldap* goes into the LDAP subpackage. |
330 | * %libdir%/courier-authlib/libauthmysql* goes into the MySQL subpackage. | |
331 | * %libdir%/courier-authlib/libauthsqlite* goes into the SQLite | |
d9898ee8 | 332 | subpackage. |
b0322a85 | 333 | * %libdir%/courier-authlib/libauthpgsql* goes into the PostgreSQL |
d9898ee8 | 334 | subpackage. |
b0322a85 CE |
335 | * %libdir%/courier-authlib/libauthuserdb* goes into the userdb |
336 | subpackage. | |
337 | * Everything else can go into the main package. Optionally, the | |
d9898ee8 | 338 | courierauthconfig binary, stuff in %includedir%, and in %mandir%/man3, |
339 | can go into a devel subpackage. |