| 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/). 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. |
| 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 | |
| 36 | Courier-authlib uses Libtool to build shared libraries. Libtool must be |
| 37 | installed, together with its libltdl library and its header files. |
| 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 | |
| 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 |
| 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 |
| 65 | make install-migrate # Only if upgrading from pre-authlib Courier packages |
| 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 | |
| 146 | * If an earlier version of the Courier authentication library is already |
| 147 | installed in the same directory, the userid and the groupid is the |
| 148 | same as the earlier version, otherwise: |
| 149 | * If an earlier version of the Courier package is installed (only the |
| 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: |
| 153 | * The userid is the first userid from the following list which exists in |
| 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 | |
| 219 | * GDBM or Berkeley DB library - The userdb authentication module will be |
| 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. |
| 225 | * OpenLDAP - The LDAP authentication modules requires OpenLDAP client |
| 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. |
| 231 | * MySQL, PostgreSQL, and SQLite - The MySQL, PostgreSQL, and SQLite |
| 232 | authentication modules require, obviously, MySQL/PostgreSQL/SQLite |
| 233 | development libraries. |
| 234 | |
| 235 | What gets installed |
| 236 | |
| 237 | * /usr/local/etc/authlib - the configuration files. |
| 238 | * /usr/local/sbin - the authdaemond startup script; several utility |
| 239 | programs (courierlogger, authconfig, authtest, authenumerate); and |
| 240 | userdb scripts. |
| 241 | * /usr/local/lib/courier-authlib - various authentication modules, as |
| 242 | shared libraries. |
| 243 | * /usr/local/libexec/courier-authlib - some miscellaneous stuff. |
| 244 | * /usr/local/var/authdaemon - a subdirectory that contains the |
| 245 | filesystem socket which authdaemond listens on. |
| 246 | * /usr/local/include - a header file that Courier packages will use to |
| 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 |
| 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 |
| 301 | authentication modules will be built as optional subpackages. They do |
| 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. |
| 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 | |
| 311 | * Decide whether or not Courier-specific userid and groupid needs to be |
| 312 | created, and, if so, make the necessary arrangements. |
| 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 |
| 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. |
| 321 | * The "authdaemond", "authenumerate", and "authtest" commands can be |
| 322 | renamed, to avoid name clashes. |
| 323 | * Remove all static libraries from %libdir%/courier-authlib. |
| 324 | |
| 325 | Now, create the installable packages, as follows: |
| 326 | |
| 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 |
| 330 | 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. |