DACS.INSTALL(7) | DACS Miscellaneous | DACS.INSTALL(7) |
dacs.install — DACS installation guide
This document describes how to configure and install DACS. Please read it carefully.
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.
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.
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.
Make a backup copy of the previous install, just in case.
Obtain and unpack the new distribution and chdir to it;
Review the README and instructions in this document;
Copy the src/config.nice
from your
installed version to the new src
directory and configure
DACS:
% cd src; sh ./config.nice
Build DACS:
% gmake
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}
Stop httpd:
% apachectl stop
Install DACS:
% gmake install
Make and install the latest
mod_auth_dacs
module:
% cd ../apache; gmake tag install
Restart httpd:
% apachectl start
or
% apachectl startssl
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.
The following describes how to install DACS.
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.
Unpack the DACS distribution.
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.
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.
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.
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.
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).
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
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
.
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.
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.
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.
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.
You cannot use both --enable-ndbm
and --enable-gdbm
,
but you can use either one along with --enable-bdb
.
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
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
.
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.
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
).
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
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).
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.
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:
% telnetmyserver
myserverport
and typing:
OPTIONS * HTTP/1.0
followed by a blank line
and examining the Server
response header.
The URLs that follow will use http
and omit
myserverport
.
Substitute https
and/or include
myserverport
as necessary for your configuration.
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.
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"
After restarting httpd,
you can view the documentation using a URL that looks like
http://
or simply
myserver
/dacs/manhttp://
.
myserver
/man
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.
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>
Remember to restart Apache after making changes
to httpd.conf
.
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).
Check ownership and permissions on DACS executables and data files
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
).
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.
Running configure generates
config.nice
, which can be executed at
some later time if you want to re-run
configure with the same arguments.
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
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.
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
.../
.
By default, DACS utilities will be installed in
your-apache-dir
/cgi-bin/dacs/usr/local/dacs/bin
,
which you may want to put on your PATH
for convenience.
make clean
Removes binaries, object files, and other junk in the build directory
make distclean
Does a "make clean
"
and cleans up so that
configure can be re-done.
make extraclean
Does a "make distclean
" and removes
configure
.
After this, do:
% autoconf -I../include
and then run configure.
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
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
if it exists,
or DIR
/cgi-bin/dacs
if that exists, or DIR
/dacs
if its last component is "DIR
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
.
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 $