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 | ||
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 | |
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 | ||
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/) | |
24 | * GNU make ([12]http://www.gnu.org/software/make/) | |
25 | * The "expect" command. expect is usually included with most systems. | |
26 | Expect can be downloaded from http://expect.nist.gov/ if it's not | |
27 | installed on your system. This utility is used to change system login | |
28 | passwords, by scripting the passwd command. If you do not have expect | |
29 | installed you will not be able to change system login passwords. | |
30 | However non-system authentication modules (LDAP, PostgreSQL, and | |
31 | others) will work. | |
32 | ||
33 | Courier-authlib uses Libtool to build shared libraries. Libtool is not | |
dd184caf | 34 | strictly required, but Libtool should be installed unless a good -- a |
d9898ee8 | 35 | very-very good -- reason exists not to. If Libtool is not installed, a |
36 | copy of Libtool in courier-authlib's source will be used. However, this | |
37 | may cause problems later down the road, if either another Libtool-using | |
38 | package is installed later, or if Libtool itself is installed. Bottom | |
39 | line: install Libtool. | |
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 | ||
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 | |
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 | ||
148 | * If an earlier version of the Courier authentication library is already | |
149 | installed in the same directory, the userid and the groupid is the | |
150 | same as the earlier version, otherwise: | |
151 | * If an earlier version of the Courier package is installed (only the | |
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: | |
155 | * The userid is the first userid from the following list which exists in | |
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 | ||
221 | * GDBM or Berkeley DB library - The userdb authentication module will be | |
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. | |
227 | * OpenLDAP - The LDAP authentication modules requires OpenLDAP client | |
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. | |
233 | * MySQL/PostgreSQL - The MySQL and PostgreSQL authentication modules | |
234 | require, obviously, MySQL/PostgreSQL development libraries. | |
235 | ||
236 | What gets installed | |
237 | ||
238 | * /usr/local/etc/authlib - the configuration files. | |
239 | * /usr/local/sbin - the authdaemond startup script; several utility | |
240 | programs (courierlogger, authconfig, authtest, authenumerate); and | |
241 | userdb scripts. | |
242 | * /usr/local/lib/courier-authlib - various authentication modules, as | |
243 | shared libraries. | |
244 | * /usr/local/libexec/courier-authlib - some miscellaneous stuff. | |
245 | * /usr/local/var/authdaemon - a subdirectory that contains the | |
246 | filesystem socket which authdaemond listens on. | |
247 | * /usr/local/include - a header file that Courier packages will use to | |
248 | build against courier-authlib. | |
249 | ||
250 | Toolchain options to the configure script may be used to select | |
251 | alternative installation directories for these components. | |
252 | ||
253 | Post-installation cleanup | |
254 | ||
255 | On most systems, after running make install-configure all static libraries | |
256 | can be removed from the /usr/local/lib/courier-authlib directory: | |
257 | ||
258 | rm -rf /usr/local/lib/courier-authlib/*.a | |
259 | ||
260 | The Courier authentication library uses only the shared libraries. The | |
261 | static versions of the shared libraries are not used. They are installed | |
262 | by default, via libtool, but are not really needed. On most platforms the | |
263 | libtool files, "*.la" can also be removed. Do not remove any soft links. | |
264 | ||
265 | For more information | |
266 | ||
267 | Following "make install", see the [13]README_authlib.html file for details | |
268 | on setting up the authentication modules. The README_authlib.html file | |
269 | gets assembled as part of the build process. | |
270 | ||
271 | Before proceding to install any other packages, be sure to verify that the | |
272 | authentication library is working by running the authtest command, as | |
273 | documented in the README_authlib.html file. | |
274 | ||
275 | Starting and stopping the authentication daemon | |
276 | ||
277 | The following command must be added to your system startup script, in | |
278 | order to initialize the authentication library when booting: | |
279 | ||
280 | /usr/local/sbin/authdaemond start | |
281 | ||
282 | Similarly, the authentication library can be stopped by the "authdaemond | |
283 | stop" command. After editing the authdaemonrc configuration file use | |
284 | "authdaemond restart" command to reconfigure the daemon process. Systems | |
285 | that use SYSV-derived initscripts can use the "courier-authlib.sysvinit" | |
286 | script, which gets built in the source directory, to start and stop | |
287 | authdaemond when the system boots or halts. | |
288 | ||
289 | Building RPMs | |
290 | ||
291 | See http://www.courier-mta.org/FAQ.html#rpm for instructions on building | |
292 | binary RPMs from the source tarball. Those instructions will work for this | |
293 | package. | |
294 | ||
295 | NOTE: | |
296 | ||
297 | RPM will refuse to build the Courier authentication library unless all | |
298 | prerequisite development libraries for LDAP, MySQL, and PostgreSQL are | |
299 | installed. Do not try to hack the RPM build script to ignore these | |
300 | dependencies! For simplicity's and maintainability sake the RPM build | |
301 | script creates all available authentication modules. All extra | |
302 | authentication modules will be built as optional subpackages. They do | |
303 | not have to be installed at runtime. Install the LDAP, MySQL, and | |
304 | PostgreSQL development libraries only for the duration of building | |
305 | binary RPMs. They can be uninstalled afterwards. | |
306 | ||
307 | Guidelines for using other package managers | |
308 | ||
309 | The recommended way to build packages can be inferred from the RPM build | |
310 | script. It is summarized here for convenience: | |
311 | ||
312 | * Decide whether or not Courier-specific userid and groupid needs to be | |
313 | created, and, if so, make the necessary arrangements. | |
314 | * Ensure that all prerequisite development libraries are available. | |
315 | * Run the configure script, run make, then make install as usual. | |
8d138742 CE |
316 | * Copy the "sysconftool" script somewhere into the installation tree. A |
317 | good place would be %libexecdir%/courier-authlib. This is the 'make | |
318 | install-upgrade' command. Don't run this at build time. Instead, | |
319 | arrange for the package installation script to run the "sysconftool | |
320 | %sysconfdir%/authlib/*.dist" after the package is installed OR | |
321 | UPGRADED. | |
d9898ee8 | 322 | * The "authdaemond", "authenumerate", and "authtest" commands can be |
323 | renamed, to avoid name clashes. | |
324 | * Remove all static libraries from %libdir%/courier-authlib. | |
325 | ||
326 | Now, create the installable packages, as follows: | |
327 | ||
328 | * %libdir%/courier-authlib/libauthldap* goes into the LDAP subpackage. | |
329 | * %libdir%/courier-authlib/libauthmysql* goes into the MySQL subpackage. | |
330 | * %libdir%/courier-authlib/libauthpgsql* goes into the PostgreSQL | |
331 | subpackage. | |
332 | * %libdir%/courier-authlib/libauthuserdb* goes into the userdb | |
333 | subpackage. | |
334 | * Everything else can go into the main package. Optionally, the | |
335 | courierauthconfig binary, stuff in %includedir%, and in %mandir%/man3, | |
336 | can go into a devel subpackage. |