DACS.INSTALL(7) DACS Miscellaneous DACS.INSTALL(7)

Name

dacs.install — DACS installation guide

DESCRIPTION

This document describes how to configure and install DACS. Please read it carefully.

Important

  • Installation requires GNU make (gmake) and gcc.

  • The examples in this document assume that DACS is installed in its default location, /usr/local/dacs. If you specify a different location at build time, please keep this in mind as you read this document.

  • Whenever you upgrade to a more recent version of DACS, please do not forget to install the Apache mod_auth_dacs module that comes with your new version of DACS.

  • Please pay careful attention to the descriptions of the third-party packages below.

  • You should build third-party packages in the order in which they appear below. This is because packages that are discussed earlier may require some that appear later.

  • For a few third-party packages, it is important that you use the exact version that is mentioned. Do not use anything newer or older.

  • For some third-party packages, a particular release is recommended. It is less critical that you use the recommended release, but older releases may have important bugs, including security problems. Releases newer than the one(s) specified will not have been tested with DACS - you're on your own.

  • You may save yourself time and headaches if you just use the recommended releases.

Trying DACS

If at this time you only want to try DACS rather than doing a full install, review the information below regarding third-party packages and then proceed to follow the instructions you will find in dacs.quick(7), which is a step-by-step tutorial for installing and configuring DACS.

Upgrading DACS

If DACS 1.4 is already installed on your system and you are not changing any third-party packages or installation options, for a "quick and dirty" upgrade you can often install a new release on top of a previous release. This will leave your existing DACS configuration files alone but it will also leave files that are no longer needed by the new DACS. Check the new distribution's release notes for any notable differences and incompatibilities.

  1. Make a backup copy of the previous install, just in case.

  2. Obtain and unpack the new distribution and chdir to it;

  3. Review the README and instructions in this document;

  4. Copy the src/config.nice from your installed version to the new src directory and configure DACS:

    % cd src; sh ./config.nice
    

  5. Build DACS:

    % gmake
    

  6. We recommend that you remove some of the files from the previous release in case they are no longer required or have been renamed. Unless you have put non-standard files in them or made non-standard customizations, it is safe to simply delete these directories and their contents:

    % rm -f -r /usr/local/dacs/{acls,man,bin,lib,include,www}
    

  7. Stop httpd:

    % apachectl stop
    

  8. Install DACS:

    % gmake install
    

  9. Make and install the latest mod_auth_dacs module:

    % cd ../apache; gmake tag install
    

  10. Restart httpd:

    % apachectl start
    

    or

    % apachectl startssl
    

  11. Check that DACS appears to be working correctly. You may find it handy to construct a set of links or bookmarks that you can use after installing or configuring DACS to invoke various DACS services with appropriate arguments; for instance, try dacs_authenticate, dacs_list_jurisdictions, dacs_conf, and dacs_version.

Installing DACS

The following describes how to install DACS.

Tip

If another release of DACS is present, rename your previous release, install the new release, and then copy any site-specific configuration files from the previous release to the new release.

  1. Unpack the DACS distribution.

  2. Familiarize yourself with the system by:

    • reading this document

    • running:

      % src/configure --help

    • browsing through the documentation by loading man/index.html into your browser, and

    • deciding which optional features you want and where you want the various components to be installed.

  3. A few third-party packages are required by DACS and must be built (though not necessarily installed) before DACS can be configured and built. These packages are not distributed with DACS and have licensing terms completely separate from those of DACS.

    1. Install OpenSSL

      DACS uses crypto from OpenSSL. This release of DACS has been tested with openssl-0.9.8a and we recommend that you use that release with both DACS and Apache (but see below). It is not necessary for Apache and DACS to use the same release of OpenSSL, however.

      Note

      • Releases of Apache prior to 2.0.55 do not work (as shipped) with OpenSSL 0.9.8 or newer.

      • Solaris 8 (and perhaps other platforms) may require a patch before OpenSSL will work properly. Please consult the latest OpenSSL documentation.

    2. Install Apache 2.0.55

      You will need an SSL-capable Apache server (--enable-ssl) built with a recent version of OpenSSL (--with-ssl, see above).

      Tip

      You can install a subset of DACS that does not require Apache and does not require any DACS configuration. These stand-alone, general-purpose utility commands, such as http and sslclient, might be of interest to you even if you are not interested in any other parts of DACS. Look for BASIC_PROGS in Makefile.in to see which commands will be installed.

      To build this subset, use --with-apache=omit when running configure. Please continue to review the information about third-party packages in this document, but you can ignore anything that follows that is related to Apache and mod_auth_dacs.

      If you want to use mod_auth_dacs as a dynamic module, which is the recommended configuration, make sure that mod_so is built in to your httpd (httpd -l displays a list).

      Also make sure that mod_ssl is either statically compiled with httpd or dynamically loaded before mod_auth_dacs (using the LoadModule directive in httpd.conf). If neither is the case, you'll probably see a message like the following when you try to start Apache:

      mod_auth_dacs.so: undefined symbol: ssl_hook_Fixup

      Check that Apache is working properly and that it is actually using the version of OpenSSL that you're expecting. It is important to confirm that your server is working correctly with your web resources before DACS gets involved - doing so may save you time and frustration.

      You can see your httpd's Server response-header by connecting to your server (e.g., using telnet) and engaging in an interaction with it similar to the following:

      % telnet localhost 8080
      Trying 127.0.0.1...
      Connected to localhost
      Escape character is '^]'.
      GET / HTTP/1.0
      
      HTTP/1.1 200 OK
      Date: Fri, 22 Apr 2005 17:58:07 GMT
      Server: Apache/2.0.55 (Unix) mod_auth_dacs/1.4.7(Release date
      20-Oct-05 13:22:28) mod_ssl/2.0.55 OpenSSL/0.9.8a
      

      Important

      This release of DACS has been tested only with Apache 2.0.55 and mainly for that reason we recommend that you use that version, but also because it may include security-related bug fixes. If necessary, DACS will probably also work with 2.0.5[1-4], but no release older than that.

      Apache 1.3.X is not supported.

      We do not support using mod_auth_dacs with a non-source install of Apache; we have received feedback that it can be done manually without much effort, however. In this case, we believe that the install may go more smoothly if you use the configure flag --disable-shared.

    3. Install the Expat XML parser

      This release of DACS has been tested with Expat 2.0.0 and we recommend that you use that release.

      On Win2K/Cygwin, we only require a static library:

      % cd lib; ar rv libexpat.a *.o; ranlib libexpat.a

      If the make fails, reconfigure using --enable-shared=no and --enable-static=yes and try to make it again.

  4. A few third-party packages are optional and whether you need them depends on which optional features of DACS you want. These packages must be built before DACS can be configured and built.

    Tip

    If you are new to DACS, it may be a good idea to first build it without any optional packages. After you have gotten the basic system working to your satisfaction, rebuild DACS with the optional components you need.

    1. Berkeley DB, gdbm, or ndbm

      If you want to be able to store DACS configuration information in a database, you may need to get and install Berkeley DB from Sleepy Cat Software. We are using db-4.4.20 for testing, but somewhat older or newer versions should be fine. The default is to use Berkeley DB if it is available. See the DACS configure arguments: --enable-bdb and --disable-bdb

      If you do not want to use Berkeley DB, you can get similar functionality from your system's ndbm library, or from GNU gdbm (version 1.8.3) in its ndbm compatibility mode. Get it from ftp://ftp.gnu.org/gnu/gdbm. See the --enable-ndbm and --enable-gdbm configure flags.

      Note

      You cannot use both --enable-ndbm and --enable-gdbm, but you can use either one along with --enable-bdb.

    2. Microsoft NTLM

      If you want to be able to authenticate against NTLM, you must obtain Samba. This release of DACS has been tested with samba-3.0.21a, and we strongly recommend that you use that version. It is not known whether this release of DACS will work with any other version of Samba - we do not support them. DACS may work properly with Samba versions at least as old as 3.0.11, if you really must use one of them.

      DACS has been tested against Windows 2000 Server (the same code could not be made to work with Windows XP Home).

      It is not necessary for you to install Samba, you only need to build it - so you do not need to be concerned about hassles associated with upgrading. The DACS build procedure looks for include files and libsmbclient.a relative to the root of the Samba distribution directory.

      To build Samba for DACS, from your Samba distribution's ./source directory do:

      % ./configure --enable-static=yes --with-ads=no --with-ldap=no
      % make
      

      See the DACS configure arguments: --enable-ntlm-auth and --with-samba

    3. LDAP or Microsoft Active Directory

      If you want to be able to authenticate through LDAP, including Microsoft's ADS, you must obtain OpenLDAP. This release of DACS has been tested only with openldap-2.3.18 and we strongly recommend that you use that version.

      It is not known whether this release of DACS will work with any other version of OpenLDAP - we do not support them. DACS may work properly with OpenLDAP versions at least as old as 2.2.24, if you really must use one of them.

      DACS has been tested against Windows 2000 Server.

      It is not necessary for you to install OpenLDAP, you only need to build it - so you do not need to be concerned about hassles associated with upgrading. The DACS build procedure looks for include files and libraries to the root of the OpenLDAP distribution directory.

      To build OpenLDAP for DACS, from the root of your OpenLDAP distribution do:

      % ./configure --disable-slapd --enable-static
      % make
      

      See the DACS configure arguments: --enable-ldap-auth and --with-ldap

      Before using LDAP authentication with DACS, you should first make sure that your LDAP server is functioning as you expect. One way to do this is to use the OpenLDAP ldapsearch(1) command (found in clients/tools, refer to its man page for details) to bind to the directory and perform some searches. You should run this command on the same machine that will be running DACS's LDAP authentication module (local_ldap_authenticate). Some of the information that you obtain from this exercise may be helpful when you configure DACS to use this form of authentication. Examples (adapt these for your site):

      % ./ldapsearch -h win2k.fedroot.com -x -b "dc=fedroot,dc=com" \
           -D "CN=Administrator,CN=Users,DC=fedroot,DC=com" -W -LLL
      % ./ldapsearch -h win2k.fedroot.com -x -b "dc=fedroot,dc=com" \
           -D "CN=Auggie Doggie,CN=Users,DC=fedroot,DC=com" -W -LLL
      % ./ldapsearch -h win2k.fedroot.com -x -b "dc=fedroot,dc=com" \
           -D "CN=Administrator,CN=Users,DC=fedroot,DC=com" -W -LLL \
           "(cn=Administrator)" memberOf
      % ./ldapsearch -h win2k.fedroot.com -x -b "dc=fedroot,dc=com" \
           -D "CN=Administrator,CN=Users,DC=fedroot,DC=com" -W -LLL \
           "(sAMAccountName=auggie)"
      

      In these examples, you would be prompted for the LDAP password (in Windows, the login password) for either Administrator or Auggie Doggie.

  5. Configure and build DACS libraries, services, and utilities

    See BUILD OPTIONS below for build alternatives and options to configure.

    % cd src
    % ./configure
    % make
    

    To confirm that DACS has been built with the third-party packages that you intended, from the src directory run:

    % ./version -v
    

    You should ensure that the sslclient utility is working correctly. From the src directory, you can test it using the following command:

    % perl -e 'printf "GET / HTTP/1.0\n\n";' | ./sslclient fedroot.com:443
    

    which should print the contents of https://fedroot.com to the standard output. You should repeat this test substituting the name of your server and port.

  6. If all looks good, install DACS

    % make install
    

    The installation process may prompt you for the owner name and group name to use for files and directories. The appropriate responses will depend on local conventions, but to start with you might set the owner to your login name or root, and the group name to the same name that is used by Apache (specified by the Group directive in httpd.conf).

  7. As part of the installation procedure, the DACS manual pages are copied into the DACS man directory (default: /usr/local/dacs/man). If you adjust your MANPATH environment variable to include that directory, try:

    % man dacs
    

  8. The distribution comes with a default site configuration file found in the distribution's conf/site.conf-std file. The installation procedure copies this file into the DACS federations directory. After making a backup copy of any federations/site.conf file, copy federations/site.conf-std to federations/site.conf, applying any customizations you require (customizations are usually done in dacs.conf though).

  9. Build a DACS-enabled httpd

    Please consult apache/README for details. We recommend that you compile mod_auth_dacs with -DDACS_VERSION so that Apache's SERVER_SIGNATURE includes a DACS version identifier stamp; this makes it easy to tell which version the server is running and to detect mismatches.

    Security

    For servers that are subject to attack, identifying exactly which modules are in your Apache server is thought to be a weakness by some administrators - you may reasonably choose not to include the stamp.

    If you want mod_auth_dacs to be a dynamic module, which is recommended:

    % cd apache
    % make module
    % make install
    

    Check that your httpd.conf has the appropriate LoadModule directive.

    If you want mod_auth_dacs to be a static module:

    • Copy apache/mod_auth_dacs.c to Apache's modules/aaa directory

    • Re-run Apache's configure, adding mod_auth_dacs (--with-module=aaa:auth_dacs)

    • Do:

      % make install
      

    • To make sure mod_auth_dacs is available:

      % httpd -l
      

      Verify that it appears in the list.

    After you've done either of the above, restart httpd.

    If you compiled with -DDACS_VERSION, verify that the DACS version identifier appears in SERVER_SIGNATURE. You can do this by hitting Apache's printenv CGI program from your browser or using a command like:

    % http "http://myserver:myserverport/cgi-bin/printenv"
    

    first making sure that Apache's printenv CGI is executable) and examining the SERVER_SIGNATURE environment variable, or by running:

    % telnet myserver myserverport
    

    and typing:

    OPTIONS * HTTP/1.0
    

    followed by a blank line and examining the Server response header.

    Note

    The URLs that follow will use http and omit myserverport. Substitute https and/or include myserverport as necessary for your configuration.

    Note

    If you install a new version of DACS, please make sure that you use the mod_auth_dacs module that comes with it. Follow the instructions above.

  10. An assortment of DACS files, including HTML documentation and CSS files, are copied into the DACS www directory (default: /usr/local/dacs/www).

    While you can view the documentation simply by pointing your web browser at the DACS www directory, it is recommended that you make it available through Apache using its Alias directive because the default site configuration (site.conf-std) expects handlers and DTDs to be available using certain URLs.

    Add lines like the following to your httpd.conf:

    Alias /dacs     "/usr/local/dacs/www/"
    Alias /css      "/usr/local/dacs/www/css/"
    Alias /dtd-xsd  "/usr/local/dacs/www/dtd-xsd/"
    Alias /examples "/usr/local/dacs/www/examples/"
    Alias /handlers "/usr/local/dacs/www/handlers/"
    Alias /man      "/usr/local/dacs/www/man/"
    Alias /misc     "/usr/local/dacs/www/misc/"
    Alias /mod      "/usr/local/dacs/www/mod/"
    

    You should also uncomment these two directives in your site.conf file:

    XSD_BASE_URL "/dacs/dtd-xsd"
    DTD_BASE_URL "/dacs/dtd-xsd"
    

    Tip

    After restarting httpd, you can view the documentation using a URL that looks like http://myserver/dacs/man or simply http://myserver/man.

  11. Access to all DACS web services (everything installed in the .../cgi-bin/dacs directory) must be controlled by DACS; that is, they must be "DACS-wrapped". Assuming you are following the defaults for installing DACS, these are the only files that are required to be DACS-wrapped.

    Some administrators may choose to make all content or all CGIs DACS-wrapped, however. That is probably a more secure approach, although of course it can be somewhat less efficient than segmenting the server's URL space into "secure" and "insecure" areas. Content that is not DACS-wrapped is totally oblivious to DACS and incurs no overhead due to DACS. Also, this approach may necessitate making "holes" in the URL space for non-access controlled resources, which must be done with care.

    Note

    If you decide to DACS-wrap everything, you will likely want to add rules to grant access to various public resources, such as CSS files, robots.txt, favicon.ico, and various public DACS resources, such as its man, dtd-xsd, etc. directories (see the instructions for the Alias directive above). The default ACL acl-stddocs.0 does this for some resources, but you may need to extend the list to grant access to additional public resources.

    The installation procedure copies default access control rules for the DACS web services into the acls directory (default: /usr/local/dacs/acls) and the default site.conf file (site.conf-std) configures DACS to look in that directory for the default rules.

    DACS-wrapping a resource or set of related resources involves:

    • Configuring Apache so that it uses DACS to manage access to the contents of a directory or portion of URL space and

    • Configuring one or more DACS access control rules for the jurisdiction responsible for the resources.

    Configuring Apache involves, at minimum, adding directives like the following to the appropriate VirtualHost section of httpd.conf:

    AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs "-t -v"
    SetDACSAuthMethod dacs-acs external
    SetDACSAuthConf dacs-acs "/usr/local/dacs/dacs.conf"
    <Location /cgi-bin/dacs>
       AuthType DACS
       AuthDACS dacs-acs
       Require valid-user
       Options ExecCGI
    </Location>
    

    Tip

    Remember to restart Apache after making changes to httpd.conf.

  12. Consult the DACS documentation on how to configure your DACS federation and/or jurisdiction. You will need to configure your dacs.conf file, use mkkey(1) to make encryption keys, and so on. To see a concrete example of what needs to done, review dacs.quick(7).

  13. Check ownership and permissions on DACS executables and data files

    Security

    Access to DACS configuration files (dacs.conf, site.conf) and keys must only be accessible by the DACS administrator and the DACS CGI programs run through Apache. The installation process tries to set this reasonably, but you should re-check now and after making changes because it is vital to maintain a secure system (e.g., ls -lR /usr/local/dacs).

  14. Having configured Apache and DACS, try one of the DACS web services. Invoke dacs_version from your browser or the command line and check that it is properly DACS-wrapped:

    % http "http://myserver/cgi-bin/dacs/dacs_version"
    

    Review the DACS log files ((default: /usr/local/dacs/logs/*) to see what happened.

Build Options

Running configure generates config.nice, which can be executed at some later time if you want to re-run configure with the same arguments.

Tip

After you're happy with your configuration, consider squirrelling away a copy of config.nice in case you want to reconfigure DACS or for use with later releases of DACS.

It's possible to "bundle" several of the DACS utility programs together into a single binary called dacs. Instead of running:

% aclcheck ...

you would run:

% dacs aclcheck ...

Running dacs without arguments displays the list of built-in utilities. To build this combined command, add the make flag bundle=yes to command lines when building and installing:

% make bundle=yes
% make bundle=yes install

The commands that are bundled into the dacs command won't be built as separate programs. To make and install both bundled and unbundled commands:

% make bundle=both
% make bundle=both install

Command: make or make build

This will build libraries, services, and utilities in the source directory. By default, the build process will create shared libraries and binaries if they are supported on your platform.

Command: make install

This will install all DACS components. We recommend that everything other than CGI binaries be put under /usr/local/dacs, which is the default. The CGI binaries are by default installed in .../your-apache-dir/cgi-bin/dacs. By default, DACS utilities will be installed in /usr/local/dacs/bin, which you may want to put on your PATH for convenience.

Command: make clean

Removes binaries, object files, and other junk in the build directory

Command: make distclean

Does a "make clean" and cleans up so that configure can be re-done.

Command: make extraclean

Does a "make distclean" and removes configure. After this, do:

% autoconf -I../include

and then run configure.

Command: make uninstall

Removes installed binaries, include files, and libraries

Other useful make commands (these should be self-explanatory):

% make build-services
% make build-progs
% make build-static
% make build-shared
% make build-static-services
% make build-shared-services
% make build-static-progs
% make build-shared-progs
% make build-shared-lib
% make install-libs
% make install-shared-lib
% make install-static-lib
% make install-progs
% make install-services

Configure Options

To verify that this documentation is up-to-date, please run:

% configure --help

--prefix=PREFIX

The root for the installation hierarchy [/usr/local/dacs]

--exec-prefix=EPREFIX

The root for the architecture-dependent hierarchy [PREFIX]

--bindir=DIR

Where DACS utilities are installed [EPREFIX/bin]

--libdir=DIR

Where DACS libraries are installed [EPREFIX/lib]

--includedir=DIR

Where DACS include files are installed [EPREFIX/include]

--mandir=DIR

Where DACS manual pages are installed [EPREFIX/man]

--enable-shared

Generate shared libraries

--enable-static

Generate static libraries

--disable-prefix-check

Disable prefix path check

--enable-bdb

Enable Berkeley DB support (default is yes) If you don't want it, use --disable-bdb

--enable-ndbm

Enable native Unix ndbm API support

--enable-gdbm

Enable ndbm support using gdbm's compatibility API (gdbm(3))

--enable-unix-auth

Enable Unix password authentication

--enable-native-auth

Enable native Apache authentication

--enable-cert-auth

Enable X.509 cert authentication

--enable-ntlm-auth

Enable NTLM authentication

--enable-ldap-auth

Enable LDAP authentication

--enable-all-auth

Enable all authentication methods

--enable-dacs-log

Specify initial DACS log file

--enable-debug

Compile with debugging

--enable-developer

Compile with development flags

--enable-dacs-conf

Specify default DACS config file

--enable-fts

Use included fts(3) library

--with-ssl=DIR

Location of installed OpenSSL libraries/include files

--with-expat=DIR

Root directory of installed Expat libraries/include files (e.g., if Expat files have been installed in /usr/local/expat/include, /usr/local/expat/lib, etc., use --with-expat=/usr/local/expat)

--with-apache=DIR

Apache install directory If DIR is "omit", a basic subset of DACS will be installed (also see above).

--with-htdocs=DIR

Location of Apache DACS files

--with-cgi-bin=DIR

Location of Apache CGI files This will resolve to DIR/cgi-bin/dacs if it exists, or DIR/dacs if that exists, or DIR if its last component is "dacs".

--with-federations-root=DIR

Location of DACS federations root directory

--with-dacs-conf=PATH

Specify default DACS config file

--with-dacs-log=PATH

Specify initial DACS log file

--with-readline=LIB

Use GNU readline when available If LIB is given, it is the link flag to use or the pathname for the library

--with-bdb=DIR

Location of installed Berkeley DB libraries/include files

--with-samba=DIR

Location of Samba source files (Example: /usr/local/src/samba-3.0.21a) This implies --enable-ntlm-auth.

--with-iconv=DIR

Path to parent of iconv installation

--with-ldap=DIR

Location of OpenLDAP source files Root directory for the OpenLDAP source distribution (Example: /usr/local/src/openldap-2.2.26) This implies --enable-ldap-auth.

SEE ALSO

dacs(1), dacs.readme(7), dacs.quick(7)

AUTHOR

Distributed Systems Software (www.dss.ca)

COPYING

Copyright 2003-2006 Distributed Systems Software. See the LICENSE file that accompanies the distribution for licensing information.

DACS Version 1.4.11 22-Mar-06 DACS.INSTALL(7)

Table of Contents
Font:

$Id: dacs.install.7.xml 992 2006-01-23 19:40:16Z brachman $