<?xml version='1.0' ?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>

  <article id="ext-auth-install">
    <title>Installation</title>

    <authorblurb>
      <para>
      by <ulink url="mailto:joel@aufrecht.org">Joel Aufrecht</ulink>
      </para>
    </authorblurb>

    <sect1 id="ext-auth-pam-install">
      <title>Installing PAM support</title>
      <para>OpenACS supports PAM authetication via the ns_pam module in AOLserver.</para>
      <orderedlist>
        <listitem>
          <formalpara>
            <title>Add PAM support to AOLserver</title>
            <para>OpenACS supports PAM support via the PAM AOLserver
        module.  PAM is system of modular support, and can provide
        local (unix password), RADIUS, LDAP (<ulink
        url="http://www.tldp.org/HOWTO/LDAP-Implementation-HOWTO/pamnss.html">more
        information</ulink>), and other forms of
        authentication.  Note that due to security issues, the
        AOLserver PAM module cannot be used for local password
        authentication.  </para>
            </formalpara>
          <orderedlist>
            <listitem>
              <formalpara id="install-nspam">
                <title>Compile and install ns_pam</title>
                <para>Download the <ulink url="/doc/nspam-download">tarball</ulink> to
            <computeroutput>/tmp</computeroutput>.</para>
              </formalpara>
              <para>Debian users: first do <userinput>apt-get install libpam-dev</userinput></para>
              <screen>[root@yourserver root]# <userinput>cd /usr/local/src/aolserver</userinput>
[root@yourserver aolserver]# <userinput>tar xzf /tmp/ns_pam-0.1.tar.gz</userinput>
[root@yourserver aolserver]# <userinput>cd nspam</userinput>
[root@yourserver nspam]# <userinput>make</userinput>
gcc -I/usr/include/pam -I/usr/local/aolserver/include -D_REENTRANT=1 
  -DNDEBUG=1 -g -fPIC -Wall -Wno-unused -mcpu=i686 -DHAVE_CMMSG=1 
  -DUSE_FIONREAD=1 -DHAVE_COND_EINTR=1   -c -o nspam.o nspam.c
nspam.c: In function `PamCmd':
nspam.c:107: warning: implicit declaration of function `Tcl_SetObjResult'
nspam.c:107: warning: implicit declaration of function `Tcl_NewIntObj'
gcc -I/usr/include/pam -I/usr/local/aolserver/include -D_REENTRANT=1 
  -DNDEBUG=1 -g -fPIC -Wall -Wno-unused -mcpu=i686 -DHAVE_CMMSG=1 
  -DUSE_FIONREAD=1 -DHAVE_COND_EINTR=1   -c -o pam_support.o pam_support.c
/bin/rm -f nspam.so
gcc -shared -nostartfiles -o nspam.so nspam.o pam_support.o -lpam
[root@yourserver nspam]# <userinput>make install</userinput>
[root@yourserver nspam]#
<action>cd /usr/local/src/aolserver
tar xzf /tmp/ns_pam-0.1.tar.gz
cd nspam
make
make install</action></screen>
            </listitem>
            
            <listitem>
              <formalpara>
                <title>Set up a PAM domain</title>
                <para>A PAM domain is a set of rules for granting
            privileges based on other programs.  Each instance of
              AOLserver uses a domain; different aolserver instances
              can use the same domain but one AOLserver instance
              cannot use two domains.  The domain describes
              which intermediate programs will be used to check
              permissions.  You may need to install software to
              perform new types of authentication.
</para>
              </formalpara>
              <itemizedlist>
                <listitem>
                  <formalpara>
                    <title>RADIUS in PAM</title>
                    <para></para>
                  </formalpara>
                  <orderedlist>
                    <listitem>
                      <para>Untar the <ulink url="/doc/individual-programs.html#pam-radius-download">pam_radius
                    tarball</ulink> and compile and install.  (<ulink
                    url="http://www.freeradius.org/pam_radius_auth/">more
                    information</ulink>)</para>
                      <screen>[root@yourserver root]# <userinput>cd /usr/local/src/</userinput>
[root@yourserver src]# <userinput>tar xf /tmp/pam_radius-1.3.16.tar</userinput>
[root@yourserver src]# <userinput>cd pam_radius-1.3.16</userinput>
[root@yourserver pam_radius-1.3.16]# <userinput>make</userinput>
cc -Wall -fPIC -c pam_radius_auth.c -o pam_radius_auth.o
cc -Wall -fPIC   -c -o md5.o md5.c
ld -Bshareable pam_radius_auth.o md5.o -lpam -o pam_radius_auth.so
[root@yourserver pam_radius-1.3.16]# <userinput>cp pam_radius_auth.so /lib/security/pam_radius_auth.so</userinput>
[root@yourserver pam_radius-1.3.16]#
<action>cd /usr/local/src/
tar xf /tmp/pam_radius-1.3.16.tar
cd pam_radius-1.3.16
make
cp pam_radius_auth.so /lib/security/pam_radius_auth.so</action></screen>
                      <para>Debian users: <userinput>apt-get install libpam-radius-auth</userinput></para>
                    </listitem>
                    <listitem>
                      <para>Set up the PAM domain.  Recent PAM
                distributions have a different file for each domain,
                all in <computeroutput>/etc/pam.d</computeroutput>.
                Previous PAM setups put all domain configuration lines
                into a single file,
                <computeroutput>/etc/pam.conf</computeroutput>.  On
                Red Hat, create the file
                <computeroutput>/etc/pam.d/<replaceable>service0</replaceable></computeroutput>
                with these contents:</para>
                      <programlisting>auth       sufficient   /lib/security/pam_radius_auth.so
</programlisting>
                      </listitem>
                    <listitem>
                      <para>Modify the AOLserver configuration file to use
                this PAM domain.  Edit the line</para>
                      <programlisting>ns_param   PamDomain             "<replaceable>service0</replaceable>"</programlisting>
                      <para>So that the value of the parameter matches the name (just the file name, not the fully pathed name) of the domain file in <programlisting>/etc/pam.d/</programlisting></para>
                    </listitem>
                  </orderedlist>
                </listitem>
                <listitem>
                  <formalpara>
                    <title>LDAP in PAM</title>
                    <para><ulink url="http://www.tldp.org/HOWTO/LDAP-Implementation-HOWTO/pamnss.html#AEN110">more information</ulink></para>
                  </formalpara>
                </listitem>
              </itemizedlist>
            </listitem>
            <listitem>
              <formalpara>
                <title>Modify the AOLserver configuration file to support ns_pam.</title>
                <para></para>
              </formalpara>
              <para>In
          <computeroutput>/var/lib/aolserver/<replaceable>service0</replaceable>/etc/config.tcl</computeroutput>, enable the nspam module by uncommenting this line:</para>
              <programlisting>ns_param   nspam           ${bindir}/nspam.so</programlisting>
            </listitem>
          </orderedlist>
        </listitem>
        <listitem>
          <formalpara>
            <title>Install auth-pam OpenACS service package</title>
            <para><ulink url="/acs-admin/install/">Install</ulink> <computeroutput>auth-pam</computeroutput> and restart the server.</para>
          </formalpara>
        </listitem>
        <listitem>
          <formalpara id="ext-auth-create-authority">
            <title>Create an OpenACS authority</title>
            <para>OpenACS supports multiple authentication authorities.
        The OpenACS server itself is the "Local Authority," used by
        default.</para>
          </formalpara>
          <orderedlist>
            <listitem>
              <para>Browse to the authentication administration page,
            <computeroutput>http://<replaceable>yourserver</replaceable><ulink
            url="/acs-admin/auth/">/acs-admin/auth/</ulink></computeroutput>.
             Create and name an authority (in the sitewide admin UI)</para>
            </listitem>
            <listitem>
              <para>Set Authentication to PAM.</para>
            </listitem>
            <listitem>
              <para>If the PAM domain defines a <computeroutput>password</computeroutput> command, you can set Password Management to PAM.  If not, the PAM module cannot change the user's password and you should leave this option Disabled.</para>
            </listitem>
            <listitem>
              <para>Leave Account Registration disabed.</para>
            </listitem>
            <listitem>
              <para><link linkend="configure-batch-sync">Configure Batch Synchronization</link>
</para>
            </listitem>
          </orderedlist>
        </listitem>
      </orderedlist>
    </sect1>

    <sect1 id="ext-auth-ldap-install">
      <title>Installing LDAP support</title>
      <para>...</para>
      <orderedlist>
        <listitem>
          <formalpara id="ext-auth-ldap-setup">
            <title>Installing AOLserver LDAP support</title>
            <para>Forthcoming.  (<ulink
        url="http://www.galileo.edu/obonilla/software/nsldap">more information</ulink>)</para>
          </formalpara>
        </listitem>
        <listitem>
          <formalpara>
            <title>Install auth-ldap OpenACS service package</title>
            <para><ulink url="/acs-admin/install/">Install</ulink> <computeroutput>auth-ldap</computeroutput> and restart the server.</para>
          </formalpara>
        </listitem>
      </orderedlist>
    </sect1>

    <sect1 id="configure-batch-sync">
      <title>Configure Batch Synchronization</title>
      <orderedlist>
            <listitem>
              <para>Browse to the authentication administration page,
            <computeroutput>http://<replaceable>yourserver</replaceable><ulink
            url="/acs-admin/auth/">/acs-admin/auth/</ulink></computeroutput>
            and choose an authority for batch sync.</para>
            </listitem>
            <listitem>
              <para>Set Batch sync enabled to Yes.  Set GetDocument
              Implementation to HTTP GET.  Set ProcessDocument Implementation to IMS Enterprise 1.1.  These settings will cause OpenACS to attempt to retrieve via HTTP a list of users in XML format from a location we will specify in a few steps.</para>
            </listitem>
            <listitem>
              <para>Click OK.</para>
            </listitem>
            <listitem>
              <para>On the next page, click <computeroutput>Configure</computeroutput> on the GetDocument Implementation line.</para>
            </listitem>
            <listitem>
              <para>Enter either or both the IncrementalURL and SnapshotURL.  These are the URLs which the external Authority will supply with XML files in IMS Enterprise 1.1 format.</para>
            </listitem>
          <listitem>
            <para>Configure your Authority (RADIUS server, etc) to
            supply XML files to the URLs IncrementalURL and
            SnapshotURL.  A typical set of incremental file record
            looks like:</para>
<programlisting><xi:include href="example.xml" xi:parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"><xi:fallback>example missing</xi:fallback></xi:include></programlisting>
          <para>A snapshot file is similar but doesn't have recstatus,
  since it's not a delta but a list of valid records.  See the larger example in the design document for more details.
</para>
              <para>(More information: <xref linkend="ims-sync-driver-design"/>, <ulink url="http://www.imsproject.org/enterprise/">The IMS 1.1 spec</ulink>)</para>
          </listitem>
      </orderedlist>
      <para><phrase role="cvstag">($Id: install.xml,v 1.4 2004/02/09 15:50:11 joela Exp $)</phrase></para>
    </sect1>
  </article>
