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