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 |
64ff59ba |
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 |
64ff59ba |
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. |
316 | * Copy the "sysconftool" and "authmigrate" scripts somewhere into the |
317 | installation tree. A good place would be %libexecdir%/courier-authlib. |
318 | This is the 'make install-migrate' and 'make install-upgrade' |
319 | commands. Don't run them at build time. Instead, arrange for the |
320 | package installation script to run the authmigrate script first, then |
321 | "sysconftool %sysconfdir%/authlib/*.dist", after the package is |
322 | installed OR UPGRADED. |
323 | * The "authdaemond", "authenumerate", and "authtest" commands can be |
324 | renamed, to avoid name clashes. |
325 | * Remove all static libraries from %libdir%/courier-authlib. |
326 | |
327 | Now, create the installable packages, as follows: |
328 | |
329 | * %libdir%/courier-authlib/libauthldap* goes into the LDAP subpackage. |
330 | * %libdir%/courier-authlib/libauthmysql* goes into the MySQL subpackage. |
331 | * %libdir%/courier-authlib/libauthpgsql* goes into the PostgreSQL |
332 | subpackage. |
333 | * %libdir%/courier-authlib/libauthuserdb* goes into the userdb |
334 | subpackage. |
335 | * Everything else can go into the main package. Optionally, the |
336 | courierauthconfig binary, stuff in %includedir%, and in %mandir%/man3, |
337 | can go into a devel subpackage. |