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 10This 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 GIT, 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 25learn how to configure libsasl in depth. There is also a <A 26HREF="upgrading.html">document</A> that covers migrating from libsasl v1 27to libsasl v2 applications. 28 29<p>You may also be interested in the contents of <tt>configure --help</tt> 30which can reveal the many possible configure options that can be used 31to build Cyrus SASL. 32 33<h3>Details</h3> 34 35<p>Note that the library looks for plugins in <tt>/usr/lib/sasl2</tt>, 36but installs them into <tt>${prefix}/lib/sasl2</tt>, where 37<tt>${prefix}</tt> is usually something like <tt>/usr/local</tt>. 38This is intentional - we want the plugins installed with the rest of 39the package (wherever things get installed at your site), but we want 40the 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 42the 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 45where the library will look for plugins by setting the environment 46variable SASL_PATH to the path the library should use. 47 48<h2>Slower and Cleaner</h2> 49 50Before reading this section, please be sure you are comfortable with 51the concepts presented in the <a href=components.html>components discussion</a> 52and in the <a href=readme.html>Read Me First</a> document.<p> 53 54You will want to have answered the following questions about your intended 55installation:<p> 56 57<ol> 58<li>What mechanisms do you want to support? Are they plaintext (LOGIN, PLAIN), 59shared secret (DIGEST-MD5, CRAM-MD5), or Kerberos (KERBEROS_V4, GSSAPI)? 60Perhaps you will use some combination (generally plaintext with one of 61the other two types).</li> 62<li>Given the answer to the previous question, how will the mechanisms 63perform user verification? 64 <ul> 65 <li>The Kerberos mechanisms just need your existing 66Kerberos infroastructure.</li> 67 <li>The shared secret mechanisms will need an auxprop 68plugin 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 72with a kerberos module for plaintext authentication. To use Shared Secret 73and 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 77if 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? 80Kerberos? PAM?</li> 81<li>Also if you are using saslauthd, what communication (IPC) method do 82you 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 84to be more stable than equivilant Solaris systems using unix sockets.</li> 85</ol> 86 87Once you have answered these questions, properly configuring a working 88configuration 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 93writing <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. 96libsasl2 can use gdbm, Berkeley db, or ndbm to implement its 97user/password lookup. Most systems come with ndbm these days; as of 98this writing, gdbm is available <a 99href="ftp://ftp.gnu.org/pub/gnu/gdbm/">here</a>. 100Berkeley DB is available from: <a 101href="http://www.sleepycat.com/">Sleepycat</a> 102 103<p>If you are using SQL, you'll need to properly configure your server/tables, 104and build the necessary client libraries on the system where you will be 105building and using SASL. Currently we support <a href=http://postgresql.org> 106PostgreSQL</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 109href="http://www.openldap.org">OpenLDAP</a> 2.1.27 (or higher) or 2.2.6 (or 110higher) is support.</p> 111 112<p>For Kerberos support, you'll need the kerberos libraries. At CMU, the 113version 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 123ready to build SASL. Building SASL is done with the aid of 124an autoconf <tt>configure</tt> script, which has a <b>lot</b> of options. 125Be sure to read the outpit of <tt>configure --help</tt> to be sure you 126aren't missing any (they are all documented). Note that often times 127a <tt>--enable-foo</tt> option has a counterpart like <tt>--disable-foo</tt> 128to not enable that feature. 129 130<p>Some of the most important configuration options are those which allow 131you to turn off the comiplation of modules you do not need. This is often 132the easiest way to solve compilation problems with Cyrus SASL. 133If you're not going to need a particular mechanism, don't build it! Not 134building them can also add performance improvements as it does take system 135resources 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 139be applicable to all systems include CRAM-MD5, DIGEST-MD5, OTP, KERBEROS_V4, 140GSSAPI, 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 147of <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 149with 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 153auxprop plugin (and LDAP enabled saslauthd) introduces a circular dependency 154between OpenLDAP and SASL. I.e., you must have OpenLDAP already built when 155building LDAPDB in SASL. In order for LDAPDB to work at runtime, you must have 156OpenLDAP already built with SASL support. One way to solve this issue is to 157build Cyrus SASL first without ldap support, then build OpenLDAP, and then come 158back to SASL and build LDAPDB.</p> 159 160<p>Given the myriad of ways that Berkeley DB can be installed on a system, 161people 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 163specifying 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 166your time to disable its use entirely with the <tt>--with-dblib=none</tt> 167option. 168 169<p>If you are planning on using LDAP with saslauthd, be sure to specify 170the <tt>--with-ldap=PATH</tt> option to <tt>configure</tt>. 171 172<h3>Building and Installation</h3> 173 174After configure runs, you should be able to build SASL just by 175running <tt>make</tt>. If this runs into problems, be sure that you 176have disabled everything that your system doesn't need, and that you have 177correctly specified paths to any dependencies you may have.<p> 178 179To 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 181installation path as appropriate). Be sure to do this last step or 182SASL 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 187using vendor compilers. We use <tt>gcc</tt> extensively, but you'll 188probably have more luck if you use the same compiler for the library 189as you do for your applications. You can see what compilers we use on 190our 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 195needs to be configured so that applications can successfully use the SASL 196library. This is also covered in the <a href=readme.html>Read Me First</a> 197document. 198 199<p>You will want to ensure that the settings of <tt>pwcheck_method</tt> 200and <tt>auxprop_plugin</tt> match the decisions you made about your 201authentication infrastructure. (For example, if you are using 202saslauthd 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 207at boot. If you are not going to be using saslauthd, then this is 208not 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 216Solaris 2.8. It should work under any platform where dynamic objects 217can be linked against other dynamic objects, and where the dynamic 218library file extension is ".so", or where libtool creates the .la 219files 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> 224Back to the <a href="index.html">index</a> 225 226</body> 227</html> 228