doc/install.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   2                       "http://www.w3.org/TR/html4/loose.dtd">
   3 <html><head>
   4 <title>Cyrus SASLv2 INSTALL Documentation</title>
   5 <!-- $Id: install.html,v 1.18 2005/02/16 20:52:05 shadow Exp $ -->
   6 </head>
   7 <body>
   8 <h1>Installation Procedure</h1>
   9
  10 This document offers a general overview of installing the SASL library.
  11
  12 <h2>Quick and Dirty</h2>
  13 <pre>
  14   cd (directory it was untarred into)
  15   ./configure
  16   make
  17   make install
  18   ln -s /usr/local/lib/sasl2 /usr/lib/sasl2
  19 </pre>
  20
  21 <p>If you're checking this directly out of CVS, you'll need to run "sh
  22 ./SMakefile" to build the configure script first.
  23
  24 <p>Read <A HREF="sysadmin.html">the System Administrator's Guide</A> to
  25 learn how to configure libsasl in depth.  There is also a <A
  26 HREF="upgrading.html">document</A> that covers migrating from libsasl v1
  27 to libsasl v2 applications.
  28
  29 <p>You may also be interested in the contents of <tt>configure --help</tt>
  30 which can reveal the many possible configure options that can be used
  31 to build Cyrus SASL.
  32
  33 <h3>Details</h3>
  34
  35 <p>Note that the library looks for plugins in <tt>/usr/lib/sasl2</tt>,
  36 but installs them into <tt>${prefix}/lib/sasl2</tt>, where
  37 <tt>${prefix}</tt> is usually something like <tt>/usr/local</tt>.
  38 This is intentional - we want the plugins installed with the rest of
  39 the package (wherever things get installed at your site), but we want
  40 the library to <em>always</em> be able to find its plugins under
  41 <tt>/usr/lib/sasl2</tt>, no matter where you install things, so that
  42 the SASL plugin ABI on all platforms is roughly the same.
  43
  44 <p>If you don't want to do this for some reason, you can set the location
  45 where the library will look for plugins by setting the environment
  46 variable SASL_PATH to the path the library should use.
  47
  48 <h2>Slower and Cleaner</h2>
  49
  50 Before reading this section, please be sure you are comfortable with
  51 the concepts presented in the <a href=components.html>components discussion</a>
  52 and in the <a href=readme.html>Read Me First</a> document.<p>
  53
  54 You will want to have answered the following questions about your intended
  55 installation:<p>
  56
  57 <ol>
  58 <li>What mechanisms do you want to support?  Are they plaintext (LOGIN, PLAIN),
  59 shared secret (DIGEST-MD5, CRAM-MD5), or Kerberos (KERBEROS_V4, GSSAPI)?
  60 Perhaps you will use some combination (generally plaintext with one of
  61 the other two types).</li>
  62 <li>Given the answer to the previous question, how will the mechanisms
  63 perform user verification?
  64   <ul>
  65   <li>The Kerberos mechanisms just need your existing
  66 Kerberos infroastructure.</li>
  67   <li>The shared secret mechanisms will need an auxprop
  68 plugin backend.</li>
  69   <li>The plaintext mechanisms can make do with saslauthd, Courier authdaemond (not included),
  70 *or* by using an auxprop plugin backend.</li>
  71   <li>To use Kerberos and Plaintext, you'll likely want to use saslauthd
  72 with a kerberos module for plaintext authentication.  To use Shared Secret
  73 and plaintext, you'll want to use the auxprop plugin for password verification.
  74   </li>
  75   </ul></li>
  76 <li>If you are using an auxprop plugin, will you be using SASLdb (and
  77 if so, Berkeley DB [recommended], GDBM, or NDBM?), LDAP or an SQL backend
  78 (Postgres? MySQL?).</li>
  79 <li>If you are using saslauthd, what module will you be using?  LDAP?
  80 Kerberos?  PAM?</li>
  81 <li>Also if you are using saslauthd, what communication (IPC) method do
  82 you want to use?  On most systems, the correct answer is the default
  83 (unix sockets), but on Solaris you can use IPC doors, which have proven
  84 to be more stable than equivilant Solaris systems using unix sockets.</li>
  85 </ol>
  86
  87 Once you have answered these questions, properly configuring a working
  88 configuration of Cyrus SASL becomes significantly easier.
  89
  90 <h3>Requirements</h3>
  91
  92 <p>You'll probably need the GNU make program, available as of this
  93 writing <a href="ftp://ftp.gnu.org/pub/gnu/make/">here</a>.<p>
  94
  95 <p>If you are using SASLdb, you will need to pick your backend.
  96 libsasl2 can use gdbm, Berkeley db, or ndbm to implement its
  97 user/password lookup. Most systems come with ndbm these days; as of
  98 this writing, gdbm is available <a
  99 href="ftp://ftp.gnu.org/pub/gnu/gdbm/">here</a>.
 100 Berkeley DB is available from: <a
 101 href="http://www.sleepycat.com/">Sleepycat</a>
 102
 103 <p>If you are using SQL, you'll need to properly configure your server/tables,
 104 and build the necessary client libraries on the system where you will be
 105 building and using SASL.  Currently we support <a href=http://postgresql.org>
 106 PostgreSQL</a> v7.2 (or higher) and <a href=http://mysql.org>MySQL</a>.
 107
 108 <p>If you are using LDAPDB, you'll need SASL enabled OpenLDAP libraries.  <a
 109 href="http://www.openldap.org">OpenLDAP</a> 2.1.27 (or higher) or 2.2.6 (or
 110 higher) is support.</p>
 111
 112 <p>For Kerberos support, you'll need the kerberos libraries.  At CMU, the
 113 version we use comes from <a href="http://www.pdc.kth.se/kth-krb/">here</a>.
 114
 115 <p>For GSSAPI support you will need either <a href="http://web.mit.edu/kerberos/www/">MIT Kerberos 5</a>
 116 , the <a href="http://www.pdc.kth.se/heimdal">Heimdal</a> or
 117 <a href="http://www.cybersafe.com/">CyberSafe</a> implementation.
 118
 119 <h3>Build Configuration</h3>
 120
 121 <p>Once you have ansered all the necessary questions and installed
 122 (and tested!) any required packages for your configuration, you are
 123 ready to build SASL.  Building SASL is done with the aid of
 124 an autoconf <tt>configure</tt> script, which has a <b>lot</b> of options.
 125 Be sure to read the outpit of <tt>configure --help</tt> to be sure you
 126 aren't missing any (they are all documented).  Note that often times
 127 a <tt>--enable-foo</tt> option has a counterpart like <tt>--disable-foo</tt>
 128 to not enable that feature.
 129
 130 <p>Some of the most important configuration options are those which allow
 131 you to turn off the comiplation of modules you do not need.  This is often
 132 the easiest way to solve compilation problems with Cyrus SASL.
 133 If you're not going to need a particular mechanism, don't build it!  Not
 134 building them can also add performance improvements as it does take system
 135 resources to load a given plugin, even if that plugin is otherwise unused
 136 (even when it is disabled via the <tt>mech_list</tt> <a href=options.html>option</a>).
 137
 138 <p>As of this writing, modules that are enabled by default but may not
 139 be applicable to all systems include CRAM-MD5, DIGEST-MD5, OTP, KERBEROS_V4,
 140 GSSAPI, PLAIN, and ANONYMOUS.  These can be disabled with
 141 <tt>--disable-cram</tt>,
 142 <tt>--disable-digest</tt>, <tt>--disable-otp</tt>,
 143 <tt>--disable-krb4</tt>, <tt>--disable-gssapi</tt>,
 144 <tt>--disable-plain</tt>, and <tt>--disable-anon</tt> respecively.
 145
 146 <p>If you are using an SQL auxprop plugin, you may want to specify one or more
 147 of <tt>--enable-sql</tt>, <tt>--with-mysql=PATH</tt>, and
 148 <tt>--with-pgsql=PATH</tt>, note that PATH in the later two should be replaced
 149 with the path where you installed the necessary client libraries.
 150
 151 <p>If you are using LDAPDB auxprop plugin, you will need to specify
 152 <tt>--enable-ldapdb</tt> and <tt>--with-ldap=PATH</tt>.  <b>Warning:</b> LDAPDB
 153 auxprop plugin (and LDAP enabled saslauthd) introduces a circular dependency
 154 between OpenLDAP and SASL.  I.e., you must have OpenLDAP already built when
 155 building LDAPDB in SASL.  In order for LDAPDB to work at runtime, you must have
 156 OpenLDAP already built with SASL support. One way to solve this issue is to
 157 build Cyrus SASL first without ldap support, then build OpenLDAP, and then come
 158 back to SASL and build LDAPDB.</p>
 159
 160 <p>Given the myriad of ways that Berkeley DB can be installed on a system,
 161 people useing it may want to look at the <tt>--with-bdb-libdir</tt> and
 162 <tt>--with-bdb-incdir</tt> as alternatives to <tt>--with-dbbase</tt> for
 163 specifying the paths to the Berkeley DB Library and Include directories.
 164
 165 <p>In fact, if you're not planning on using SASLdb at all, it may be worth
 166 your time to disable its use entirely with the <tt>--with-dblib=none</tt>
 167 option.
 168
 169 <p>If you are planning on using LDAP with saslauthd, be sure to specify
 170 the <tt>--with-ldap=PATH</tt> option to <tt>configure</tt>.
 171
 172 <h3>Building and Installation</h3>
 173
 174 After configure runs, you should be able to build SASL just by
 175 running <tt>make</tt>.  If this runs into problems, be sure that you
 176 have disabled everything that your system doesn't need, and that you have
 177 correctly specified paths to any dependencies you may have.<p>
 178
 179 To install the library, run <tt>make install</tt> as <tt>root</tt> followed by
 180 <tt>ln -s /usr/local/lib/sasl2 /usr/lib/sasl2</tt> (modified for your
 181 installation path as appropriate).  Be sure to do this last step or
 182 SASL will not be able to locate your plugins!
 183
 184 <h3>Compilation Hints</h3>
 185
 186 <p>You may need to play with your CPPFLAGS and LDFLAGS a little if you're
 187 using vendor compilers. We use <tt>gcc</tt> extensively, but you'll
 188 probably have more luck if you use the same compiler for the library
 189 as you do for your applications. You can see what compilers we use on
 190 our platforms by looking at the "SMakefile".
 191
 192 <h3>Application Configuration</h3>
 193
 194 <p>Plesae read about the <a href=options.html>SASL Options</a> to learn what
 195 needs to be configured so that applications can successfully use the SASL
 196 library.  This is also covered in the <a href=readme.html>Read Me First</a>
 197 document.
 198
 199 <p>You will want to ensure that the settings of <tt>pwcheck_method</tt>
 200 and <tt>auxprop_plugin</tt> match the decisions you made about your
 201 authentication infrastructure.  (For example, if you are using
 202 saslauthd as a password verifier, you'll want to be sure to set
 203 <tt>pwcheck_method: saslauthd</tt>).
 204
 205 <p>If you are using saslauthd, you will want to arrange for
 206 <tt>saslauthd -a pam</tt> (or ldap, or kerberos4, etc) to be run
 207 at boot.  If you are not going to be using saslauthd, then this is
 208 not necessary.
 209
 210 <p>Many of these pieces are covered in more detail in the
 211 <a href=sysadmin.html>SASL System Administrator's Guide</a>.
 212
 213 <h2>Supported platforms</h2>
 214
 215 <p>This has been tested under Linux 2.2, Linux 2.4, Solaris 2.7 and
 216 Solaris 2.8.  It should work under any platform where dynamic objects
 217 can be linked against other dynamic objects, and where the dynamic
 218 library file extension is ".so", or where libtool creates the .la
 219 files correctly.  There is also documentation for
 220 <a href=windows.html>Win32</a>, <a href=macosx.html>MacOS X</a>, and
 221 <a href=os390.html>OS/390</a>.
 222
 223 <hr>
 224 Back to the <a href="index.html">index</a>
 225
 226 </body>
 227 </html>