Provided by: dacs_1.4.38a-2build1_amd64 
NAME
dacs.install - DACS installation guide
DESCRIPTION
This document describes how to build and install this release of DACS. Please read it carefully.
Important
• Installation requires the GNU make command (gmake[1]) and GCC[2]. On macOS, LLVM/Clang[3] is
used.
• Our philosophy is that DACS should be used with the most recent stable versions of third-party
packages (such as OpenSSL) available at the time DACS is released. This helps to ensure that a
DACS deployment has the latest security features and bug fixes. A DACS release will most likely
not have been tested with older (or newer) third-party packages, and the DACS instructions for
configuring or building an older release may be incorrect. You may save yourself time and
headaches if you just use the recommended releases.
That said, third-party software used by DACS is often already installed or readily obtained using
yum, rpm, pkg, or a similar package manager. These are often not the latest versions, but
sometimes convenience outweighs other factors. Provided the DACS documentation does not forbid a
particular version and DACS seems to build and test correctly with it, you may elect to use it.
For a very 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.
Sometimes the recommended version of a third-party package will be fine on some platforms but is
buggy or will not build on another platform. Whenever possible, the DACS installation
instructions suggest an alternative version, and you may proceed with that version, or a recent
version of your choice - but keep the preceding comments regarding older releases in mind and
ensure that a "gmake test" of DACS completes successfully.
• Should a critical bug in a third-party package be found, the Post-Release Notes[4] section will
provide instructions.
• You should build third-party packages in the order in which they are discussed below because
packages that are discussed earlier may require some that appear later.
• The examples here and in other DACS documentation 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 the documentation. This also applies to third-party packages, which you may
install where convenient, provided you are careful not to confuse or combine different versions
of the same package; in this document's examples we install them under /usr/local and unpack
their source code under /local/src.
• In some examples, long lines have been split to improve readability. Copy-and-paste with care.
• Whenever you upgrade to a more recent version of DACS, do not forget to install the mod_auth_dacs
module that comes with your new version of DACS. DACS web-based access control (dacs_acs(8)[5])
will deny all access if it detects an incompatible version of mod_auth_dacs.
• On macOS you will probably need to install the Xcode[6] development environment.
• On some platforms, the PAM development environment is required if you need DACS to authenticate
against Unix accounts. If security/pam_appl.h is in a standard include directory, as is often the
case, it has probably been installed and no action is necessary. On platforms where this
development environment is optional (CentOS), it may be necessary to install it; for example,
# yum install pam-devel.x86_64
For details, refer to Using Pluggable Authentication Modules (PAM)[7].
• On some systems it will be necessary to use ldconfig(8)[8] (or equivalent) so that your system
finds the correct shared libraries for programs that are executed by the web server, including
the DACS web services. Command such as ldd(1)[9] and otool may be helpful.
• Solaris and OpenSolaris are no longer supported. Notes regarding these unsupported platforms and
deprecated releases of supported platforms may appear in the DACS documentation and source code.
• DACS is not supported on Microsoft Windows platforms. Cygwin[10], which provides a
GNU/Linux-like environment for Windows, is not an officially-supported platform, but earlier DACS
releases would usually build on it. At that time, running DACS utilities and commands on Windows
(such as dacscheck) required installing the binaries along with the Cygwin run-time libraries,
such as /bin/cygwin1.dll and /bin/cygcrypt-0.dll.
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)[11], 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. While this will leave your existing DACS configuration files alone, it will also leave
files that are no longer needed by the new DACS. Be sure to check the new distribution's release notes,
HISTORY file, and the rest of this manual page for any notable changes and incompatibilities - you may
need to make some adjustments to your pre-existing installation.
It is possible for minor, incompatible changes introduced by a new release to cause temporary,
user-visible problems. For example, changes to the format of credentials might invalidate sessions (i.e.,
DACS HTTP cookies) issued by the earlier release, requiring users to reauthenticate.
1. Make a backup copy of the previous install, just in case. It is especially important to make copies
of all data files (such as DACS password files, other kinds of account files, encryption keys) and
any custom configuration (such as access control rules).
2. Obtain and unpack the new distribution and chdir to it;
3. Review dacs.readme(7)[12] and the instructions in this document;
4. Copy src/config.nice from your installed version to the new src directory, make any updates and
corrections that are necessary, 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,bin,include,lib,man,www}
7. Stop httpd:
% apachectl stop
8. Install DACS:
% gmake install
9. Make and install the latest mod_auth_dacs module[13]:
% 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 web services
with appropriate arguments; for instance, try dacs_authenticate(8)[14]
dacs_current_credentials(8)[15], dacs_prenv(8)[16], dacs_list_jurisdictions(8)[17], dacs_conf(8)[18],
dacs_signout(8)[19], and dacs_version(8)[20]. Review the DACS log file for any error messages or
warnings.
Installation Layout Overview
By default, DACS is installed under /usr/local/dacs. It is sometimes installed as /usr/local/dacs-version
(e.g., /usr/local/dacs-1.4.30) with the current version symbolically linked to, and referenced as,
/usr/local/dacs. In the documentation and DACS configuration files, the root directory used is referred
to as DACS_HOME[21] or the configuration variable[22] ${Conf::DACS_HOME}. The locations of other
components are usually specified relative to the actual root directory, as in site.conf (and its
template, conf/site.conf-std) and dacs.conf. While the default layout of directories and files is
adequate, system administrators often customize it, which is not difficult to do. Customization might be
desirable for security, availability, aesthetic, or performance reasons.
Briefly, the default directory layout is as follows. The organization of files and directories within
these directories can be customized by system administrators through changes to site.conf and dacs.conf
and largely depends on how many federations and jurisdictions will be configured and how much
configuration is shared by different federations and jurisdictions. Also see Configuration Variables[22].
/usr/local/dacs
The installation root directory.
/usr/local/dacs/acls
Default access control list files for DACS web services and resources, copied from the distribution's
acls directory.
/usr/local/dacs/bin
This contains DACS commands and utilities (and excludes the mod_auth_dacs module[13], which is
installed in Apache's modules directory).
/usr/local/dacs/etc
Currently unused.
/usr/local/dacs/federations
This directory will contain one directory per federation, and each of those subdirectories will
contain one directory per jurisdiction. The following example shows a default configuration for a
site that belongs to two federations, having domains fed1.example.com and fed2.example.com. The site
has two jurisdictions (JUR1 and JUR2) at this site that belong to the former federation and one
jurisdiction (JUR8) in the latter federation.
/usr/local/dacs/federations/fed1.example.com
/usr/local/dacs/federations/fed1.example.com/federation_keyfile
/usr/local/dacs/federations/fed1.example.com/JUR1
/usr/local/dacs/federations/fed1.example.com/JUR1/jurisdiction_keyfile
/usr/local/dacs/federations/fed1.example.com/JUR1/acls
/usr/local/dacs/federations/fed1.example.com/JUR1/acls/revocations
/usr/local/dacs/federations/fed1.example.com/JUR1/auth_tokens
/usr/local/dacs/federations/fed1.example.com/JUR1/auth_token_keys
/usr/local/dacs/federations/fed1.example.com/JUR1/auth_token_keys.prev
/usr/local/dacs/federations/fed1.example.com/JUR1/groups
/usr/local/dacs/federations/fed1.example.com/JUR1/passwd
/usr/local/dacs/federations/fed1.example.com/JUR1/roles
/usr/local/dacs/federations/fed1.example.com/JUR2
/usr/local/dacs/federations/fed1.example.com/JUR2/jurisdiction_keyfile
/usr/local/dacs/federations/fed1.example.com/JUR2/acls
/usr/local/dacs/federations/fed1.example.com/JUR2/acls/revocations
/usr/local/dacs/federations/fed1.example.com/JUR2/auth_tokens
/usr/local/dacs/federations/fed1.example.com/JUR2/auth_token_keys
/usr/local/dacs/federations/fed1.example.com/JUR2/auth_token_keys.prev
/usr/local/dacs/federations/fed1.example.com/JUR2/groups
/usr/local/dacs/federations/fed1.example.com/JUR2/passwd
/usr/local/dacs/federations/fed1.example.com/JUR2/roles
/usr/local/dacs/federations/fed2.example.com
/usr/local/dacs/federations/fed2.example.com/federation_keyfile
/usr/local/dacs/federations/fed2.example.com/JUR8
/usr/local/dacs/federations/fed2.example.com/JUR8/jurisdiction_keyfile
/usr/local/dacs/federations/fed2.example.com/JUR8/acls
/usr/local/dacs/federations/fed2.example.com/JUR8/acls/revocations
/usr/local/dacs/federations/fed2.example.com/JUR8/auth_tokens
/usr/local/dacs/federations/fed2.example.com/JUR8/auth_token_keys
/usr/local/dacs/federations/fed2.example.com/JUR8/auth_token_keys.prev
/usr/local/dacs/federations/fed2.example.com/JUR8/groups
/usr/local/dacs/federations/fed2.example.com/JUR8/passwd
/usr/local/dacs/federations/fed2.example.com/JUR8/roles
If additional data or configuration files are needed, an administrator is free to place them wherever
convenient within this hierarchy by referencing them using appropriate configuration directives in
dacs.conf.
/usr/local/dacs/include
This directory contains header files for use with custom DACS code.
/usr/local/dacs/lib
Run-time libraries are installed here.
/usr/local/dacs/logs
Run-time log files are written here by dacs_acs(8)[5] and DACS commands.
/usr/local/dacs/sbin
Analogous to /usr/sbin, system administrative commands are installed here.
/usr/local/dacs/share/man
DACS manual pages for use by man(1)[23] are installed here.
/usr/local/dacs/tmp
Various temporary run-time files, such as lock files, are kept in this directory.
/usr/local/dacs/www
DACS HTML documentation is installed here.
Installing DACS
The following describes how to install DACS.
Important
• 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.
• Be careful not to mix DACS binaries and support files from different releases. This can lead to
strange behaviour that is often hard to resolve.
• If you are installing or upgrading a third-party package, make sure that you are building it
against the correct include files and libraries (e.g., ensure that the DACS build is not finding
an old version, or using include files from one version and library files from a different
version, or that httpd is trying to use the wrong version of an OpenSSL library). This is
frequently the cause of build and run-time problems.
1. Unpack the DACS distribution and move to its root directory.
2. Familiarize yourself with the system by:
• reading this document;
• running:
% src/configure --help
• browsing through the documentation (best done by loading man/index.html[24] into your browser);
• deciding where you want the various components to be installed; and
• considering which optional features you may want (you can easily make changes at any time, so do
not be too concerned about this).
3. A few third-party packages are required by DACS and must be built before DACS can be configured and
built. Please note carefully if any special exceptions apply to your particular platform and
third-party package needs. Although you may have better luck, sometimes we experienced problems
building the recommended packages (or combinations of packages) on certain platforms; whenever
possible, we try to provide a workable alternative. Late-breaking updates are sometimes available in
the release's Post-Release Notes[4].
Important
It is not necessary to actually install these packages, you only have to build them so that the
DACS build can use their libraries, include files, and so on, directly from where you build the
packages. You may chose to do this if you do not want to upgrade an existing version of the
package, or if you are unable to do so.
Shared libraries belonging to these packages must be accessible at run-time, so please make sure
that their path permissions enable them to be read by a program executing with Apache's CGI
permissions.
Build these packages in the order in which they are listed below.
If you install a package, you may need to be root or use sudo(8)[25] (e.g., "sudo make install").
These packages are not distributed with DACS and have licensing terms completely separate from
those of DACS that are your responsibility.
Third-Party Package Index:
• Expat: XML parser
• OpenSSL: Crytographic toolkit
• Apache: Web server
• Berkeley DB, gdbm, ndbm: dbm-type database libraries
• SQLite: SQL database engine
• Samba: Microsoft Windows interoperability suite
• libxml2, xmlsec1: XML toolkit and security libraries
• OpenLDAP: Lightweight Directory Access Protocol software
• Readline: Command line history and editing
1. Install the Expat XML parser
This release of DACS has been tested with Expat[26] 2.2.0 and we recommend that you use that
release.
For use with DACS, Expat can either be built with -prefix=/usr/local or something like
-prefix=/usr/local/expat-2.2.0, whichever you prefer. In the former case, you can omit the
--with-expat when configuring DACS or use --with-expat=/usr/local, and in the latter case you
must use --with-expat=/usr/local/expat-2.2.0. Here is how we usually build Expat after unpacking
it:
% cd expat-2.2.0
% ./configure --prefix=/usr/local/expat-2.2.0
% make
(All should go well.)
% make install
(All should go well here, too.)
Note
On Win2K/Cygwin, only a static library is needed. From the root of the expat distribution
directory:
% cd lib; ar rv libexpat.a *.o; ranlib libexpat.a
If the build fails, reconfigure using --enable-shared=no and --enable-static=yes and try to
build it again.
2. Install OpenSSL
DACS uses cryptographic functionality provided by OpenSSL[27]. This release of DACS has been
tested with openssl-1.0.2j and we recommend that you use that release with DACS. Apache should
be built using the version of OpenSSL recommended by the particular Apache release - using a more
recent version of OpenSSL may introduce build problems or run-time bugs in Apache. It is not
necessary for Apache and DACS to use the same release of OpenSSL.
Notes
• DACS will likely work with recent openssl-1.0.1x releases, although those versions are no
longer officially supported and may have important security issues.
• If you are enabling DACS support for Java, add the -fPIC flag to config when you are
building OpenSSL.
• In some configurations you may want or require shared OpenSSL libraries; if so, add the
shared command line flag to config when building OpenSSL.
• Here is how we built OpenSSL:
% ./config --prefix=/usr/local/openssl-1.0.2j --openssldir=/usr/local/openssl-1.0.2j \
-fPIC shared
• On macOS, however, it was necessary to explicitly request a 64-bit build of OpenSSL:
% ./Configure darwin64-x86_64-cc --prefix=/usr/local/openssl-1.0.2j \
--openssldir=/usr/local/openssl-1.0.2j -fPIC shared
3. Install Apache 2.4.23 or 2.2.31
You will need an SSL/TLS-capable Apache[28] server (build Apache with --enable-ssl) that uses a
recent version of OpenSSL (build Apache using --with-ssl=path, see above[29]).
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 dacshttp 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[13] 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).
Important
• This release of DACS has been tested with both Apache 2.2.31 and Apache 2.4.23. We
strongly recommend that you use either of those versions.
• If suitable APR, APR-UTIL, and other support libraries have already been installed on
your system, you may be able to perform a basic build and install of Apache 2.4 with a
command like:
% cd httpd-2.4.23
% ./configure --prefix=/usr/local/apache2-2.4.23 --enable-ssl \
--with-ssl=/usr/local/openssl-1.0.2j
% make install
• Detailed instructions for building Apache 2.4.23 can be found in Apache's INSTALL file.
For the testing platforms, we get the APR and APR-UTIL libraries from apr.apache.org[30]
and unpack them in the Apache distribution's srclib directory, then rename them
srclib/apr and srclib/apr-util, respectively, as it says in INSTALL. We currently use
apr-1.5.2 and apr-util-1.5.4. If you are building httpd this way, include the
--with-included-apr flag with configure.
• On CentOS 5.9 and later, the Apache build initially failed with a complaint about not
finding pcre-config. To solve this, we did:
# yum install pcre-devel.x86_64
• We sometimes run into minor problems configuring or building Apache 2.4 on macOS,
especially after a recent Xcode[6] upgrade. Ensure your PATH is correct. It is sometimes
necessary to make a symbolic link from an Xcode[6] directory
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/... to a
more conventional path so that it is found. If necessary, obtain Perl Compatible Regular
Expressions (PCRE) from http://pcre.org and install it, then make sure that pcre-config
is on your PATH.
• When building Apache 2.2, running configure as shown above will work in some cases
(distributions of the 2.2 branch include the APR and APR-UTIL libraries). Nevertheless,
we usually first build and install APR (srclib/apr) and APR-UTIL (srclib/apr-util), and
then build httpd using the --with-apr and --with-apr-util flags. This may be helpful to
know if you run into problems. Also, if you encounter problems building dacsversion, it
may be necessary for you to go back and build APR with the --disable-lfs flag to disable
large file support on your platform. When you build DACS in an upcoming step, you will
probably need to use the --with-apache and --with-apache-apr flags (see Third-party
support options[31]). If you are going to use the --with-berkeley-db flag when building
APR-UTIL (e.g., --with-berkeley-db=/usr/local/BerkeleyDB.5.3), you may want to
temporarily skip ahead to build Berkeley DB[32] before returning here to continue your
Apache build. (Note: apr-util will sometimes not work with the latest versions of
Berkeley DB; refer to documentation for its --with-dbm flag).
• Here is how we built Apache 2.2 after unpacking it:
% cd httpd-2.2.31
% cd srclib/apr
% ./configure --prefix=/usr/local/apache2-2.2.31/apr-httpd --disable-lfs CFLAGS=-fPIC
% make install
% cd ../apr-util
# See notes below for adding LDFLAGS
% ./configure --prefix=/usr/local/apache2-2.2.31/apr-util-httpd
--with-apr=/usr/local/apache2-2.2.31/apr-httpd
--with-expat=/usr/local/expat-2.2.0
--with-dbm=db53
% make install
% cd ../..
# See notes below for adding LDFLAGS
% ./configure --prefix=/usr/local/apache2-2.2.31 --enable-ssl
--with-ssl=/usr/local/openssl-1.0.2j
--with-apr=/usr/local/apache2-2.2.31/apr-httpd
--with-apr-util=/usr/local/apache2-2.2.31/apr-util-httpd
LDFLAGS="-rpath /usr/local/db-5.3.28/lib -rpath /usr/local/openssl-1.0.2j/lib"
% make install
This builds a very basic server; you can enable other options if you want.
Because we deal with multiple versions of third-party packages, each release is installed
separately, hence the version numbers in the pathnames.
On FreeBSD, when doing the top level Apache configuration above it was necessary to add
"-rpath /usr/local/db-5.3.28/lib -rpath /usr/local/openssl-1.0.2j/lib" to LDFLAGS so that
Apache commands could find shared libraries at run time. And on CentOS, when building
apr-util, and at the top level, it was necessary to use (instead of the -rpath flags)
"-Wl,-rpath /usr/local/db-5.3.28/lib -Wl,-rpath /usr/local/openssl-1.0.2j/lib" to
LDFLAGS.
Alternatively, on either platform the ldconfig command or LD_LIBRARY_PATH might be used.
It appears that the LDFLAGS above should be omitted on macOS.
• In some configurations an "undefined ssl_hook_Fixup symbol" error or "Cannot load
modules/mod_ssl.so into server" error is produced by httpd when it starts up. This was
also seen in earlier releases of Apache. These errors can be due to an apparent bug in
the Apache build procedure that results in the mod_ssl module not knowing where libssl.so
and libcrypto.so are, even though the correct path was specified at Apache build time
through the --with-ssl flag to configure.
One solution is to make mod_ssl a built-in module instead of a dynamically loaded module.
Build Apache using something similar to this (using the --enable-ssl=static flag is the
important change):
% ./configure --prefix=/usr/local/apache2-2.4.23 \
--with-ssl=/usr/local/openssl-1.0.2j --enable-ssl=static
Then do a "make install". Note that you will need to comment out the httpd.conf directive
that loads mod_ssl:
# LoadModule ssl_module modules/mod_ssl.so
Now, from the Apache installation directory, try:
% bin/httpd -l
% bin/httpd -M
If httpd cannot find your OpenSSL libraries, you will see an error message like this:
error while loading shared libraries: libssl.so.1.0.0: cannot open
shared object file: No such file or directory
Tell the linker where the OpenSSL libraries are by setting the LD_LIBRARY_PATH
environment variable for httpd; for example:
% sh -c "export LD_LIBRARY_PATH=/usr/local/openssl-1.0.2j/lib; bin/httpd -M"
You may also be able to resolve the problem using the ldconfig command, but we don't know
if that could possibly break other programs that expect a different version of the
OpenSSL library. You will need to always set LD_LIBRARY_PATH before running httpd, maybe
using an alias or script. If you use apachectl to manage Apache, you could simply have it
set LD_LIBRARY_PATH (also see the Apache envvars script, which is sourced by apachectl).
Another thing to try if Apache is unable to load a shared library is to re-run configure
without the --with-dbm flag.
• If you find that your Apache server on CentOS does not accept requests coming from the
network (non-localhost requests) it may be because the operating system's security policy
is disallowing them. As root, do:
# system-config-firewall
(This command was named system-config-securitylevel in earlier releases of CentOS). In
the "Other ports" section of the "Firewall Options", add the HTTP/HTTPS port(s) you want
to use for protocol TCP. Once the change is applied it is persistent. Another option, if
it is safe to do so, is to totally disable the firewall. On CentOS:
# service iptables stop
Note that this change is not persistent, however. Another alternative, for CentOS and
other systems, is to use the appropriate command (e.g., iptables, ipfw, or pfctl) to add
a firewall rule to allow TCP access to your HTTP/HTTPS port(s).
• One difference to be aware of between the Apache 2.0 branch and subsequent branches is
that the default Apache configuration of the newer branches may deny all access by
default; some DACS files should be publicly accessible, however, so you may need to
explicitly allow this. For example, in httpd.conf:
<Directory /usr/local/dacs/www>
Satisfy Any
Allow from all
Options Indexes FollowSymLinks
</Directory>
• Apache 1.3 is not supported; please consult the FAQ[33]. DACS has not been tested with
Apache 2.3 or 2.4.
• 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.
Tip
Check that Apache is working properly and that it is actually using the version of OpenSSL
that you are expecting. It is important to confirm that your server is working correctly with
your web resources before DACS gets involved. Doing so can 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 (note the last line
of output):
% telnet localhost 80
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
GET / HTTP/1.0
HTTP/1.1 200 OK
Date: Tue, 36 Sep 2016 16:34:10 GMT
Server: Apache/2.4.23 (Unix) OpenSSL/1.0.2j mod_auth_dacs/1.4.38(Release date 18-May-2016 12:01:11)
4. A few third-party packages are optional and whether you need them depends on which optional features
of DACS you require. These packages must be built before DACS can be configured and built. If you
decide you want to add or remove optional capabilities after building DACS, it is easy to do so
later.
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. Or, if you are not sure at this time which optional packages you
need, return to this step later.
1. Berkeley DB, gdbm, ndbm DB (dbm-type databases)
If you want to be able to store DACS configuration information in a database or need to access
files managed by Apache's mod_auth_dbm, you may use Berkeley DB[34] from Oracle Corporation[35]
(Sleepy Cat Software was acquired by Oracle in February, 2006). A suitable version may already be
installed on your system. Typically, Apache will only build with a version of Berkeley DB that is
somewhat older than the latest. Neither DACS nor Apache require Berkeley DB, and they do not need
to use the same version of Berkeley DB. Version db-5.3.28 is being used for testing, but somewhat
older versions should be fine. See the DACS configure arguments: --enable-bdb[36],
--disable-bdb[37], and --with-bdb[38].
Notes
Note that starting with db-6.x, licensing for Berkeley DB changed[39] from the Sleepycat
License[40] to the GNU AGPL v3[41]. Installations should consider whether they should use
db-5.3.28 or switch to another supported dbm-type database.
Tip
You may find that you must sign on to the Oracle site before you are allowed to download
Berkeley DB. You may be able to avoid this by using a URL such as:
http://download.oracle.com/berkeley-db/db-5.3.28.tar.gz
You may also be able to obtain Berkeley DB elsewhere, such as at linux.softpedia.com,
pkgs.fedoraproject.org, or fossies.org. Consider validating the downloaded file using a
checksum published on a different site, however.
The default is to use Berkeley DB if it is available. If you do not want to use Berkeley DB you
must disable it (--disable-bdb[37]). Similar functionality is provided by the NDBM library and
from GNU GDBM (versions 1.8.3 through 1.12). GNU GDBM must be built with its NDBM compatibility
mode. These libraries may already be installed on your system. Get GDBM from
ftp://ftp.gnu.org/gnu/gdbm[42]. See the --enable-ndbm[43], --with-gdbm-lib[44], and
--with-gdbm-includes[44] configure flags.
Notes
• It may be necessary to create (or update) links to the Berkeley DB installation directory
to avoid problems when building other packages. For example, if you install it in
/usr/local/db-5.3.28:
% ln -sf /usr/local/db-5.3.28 /usr/local/BerkeleyDB.5.3
% ln -sf /usr/local/db-5.3.28 /usr/local/db53
• Here is how we built Berkeley DB for DACS after unpacking it:
% cd build_unix
% ../dist/configure --prefix=/usr/local/db-5.3.28
% make
(All should go well.)
% make install
(All should go well here, too.)
• On some platforms, applications (including DACS) that use Berkeley DB may need to be
linked with the -lpthread flag.
• You cannot enable the NDBM library and GNU GDBM. You can use either one with Berkeley DB.
• GNU GDBM 1.9.1 and newer may not interoperate correctly with databases created by older
versions of GNU GDBM; consult its source code and documentation for details.
• A deficiency in configuration processing is that the location of the NDBM library cannot
be specified; the standard configuration search path is used. A future version should
provide a --with-ndbm flag.
• The NDBM-workalike, sdbm[45], is not currently supported. It may be added to a future
release if it is requested.
2. SQLite
The SQLite[46] database, which can be used together with the dbm-type databases[32], is another
option for storing DACS configuration information. Version 3.15.0 is being used for testing (we
use the "sqlite-autoconf" amalgamation tarball). See the DACS configure arguments:
--enable-sqlite[47], --disable-sqlite[48], and --with-sqlite[49].
Notes
• On FreeBSD at least, an apparent bug in the SQlite build procedure can cause a
compilation error. To avoid the error, edit the definition of the DEFS symbol in the
Makefile to remove the embedded space by changing:
-DPACKAGE_STRING=\"sqlite 3.15.1\"
to:
-DPACKAGE_STRING=\"sqlite-3.15.1\"
• Here is how we built SQlite:
% ./configure --prefix=/usr/local/sqlite-3.15.1
% make
% make install
3. Samba
If you want to be able to authenticate against Microsoft NTLM (see local_ntlm_authenticate[50]),
you must obtain Samba[51]. This release of DACS has been tested with samba-3.6.25, 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 officially support them.
DACS NTLM authentication is currently tested against services provided by Windows Server 2012 but
DACS should also interoperate with other MS Windows platforms.
Notes
• DACS requires the Samba source distribution to be built but it does not matter if Samba
is installed. The DACS build procedure looks for include files and libraries relative to
the Samba distribution's root directory.
• On systems where libexecinfo has been installed (FreeBSD), when building DACS it may be
necessary to add -lexecinfo to LDFLAGS if backtrace or backtrace_symbols are referenced
by Samba.
• The Samba 4.X releases use a different build system than earlier releases, unfortunately.
DACS does not currently work with the 4.X releases, mainly because we have had no success
getting a clean build of any 4.X release on either FreeBSD or macOS. We are looking at
alternatives for NTLM support.
To build Samba for DACS, from your Samba distribution's ./source3 directory do:
% ./configure --enable-static=yes --with-ads=no --with-ldap=no --disable-swat --disable-cups --disable-pie \
--enable-external-libtalloc=no --enable-external-libtdb=no
% make
Then, when configuring DACS, specify the directory where Samba was unpacked, for example:
--with-samba=/local/src/samba-3.6.25
See the DACS configure arguments: --enable-ntlm-auth[52] and --with-samba[53].
4. libxml2 and xmlsec1
InfoCard support is now deprecated and therefore these libraries are no longer needed.
See local_infocard_authenticate[54].
InfoCard support requires libxml2[55] and xmlsec1[56] are required. Build libxml2 and OpenSSL
first, because xmlsec1[56] depends on both of them. This release of DACS has been tested with
libxml2-2.8.0 or libxml2-2.9.1, and xmlsec1-1.2.20, and we strongly recommend that you use those
versions. It is not known whether this release of DACS will work with any other versions - we do
not officially support them.
Notes
• Here is how we built libxml2:
% ./configure --prefix=/usr/local/libxml2-2.9.1
Due to an apparent bug in the code (in threads.c) that results in a syntax error, it was
necessary to add --with-threads=no on some platforms, such as macOS.
• Here is how we built xmlsec1:
% ./configure --prefix=/usr/local/xmlsec1-1.2.20
--with-libxml=/usr/local/libxml2-2.9.1
--with-openssl=/usr/local/openssl-1.0.2j --with-gnu-ld
--enable-static-linking --disable-crypto-dl --disable-apps-crypto-dl
Except on macOS:
% ./configure --prefix=/usr/local/xmlsec1-1.2.20 \
--with-libxml=/usr/local/libxml2-2.9.1 --with-gnu-ld --enable-static=yes \
--enable-shared=yes --with-nss=/Applications/Firefox.app/Contents/MacOS \
--with-nspr=/Applications/Firefox.app/Contents/MacOS \
--with-openssl=/usr/local/openssl-1.0.2j \
--disable-crypto-dl
• Due to an apparent error in its build procedure, we sometimes encountered the following
error message:
*** Warning: Linking the shared library libxmlsec1-openssl.la against the
*** static library /local/openssl-1.0.2j/lib/libcrypto.a is not portable!
After ensuring that libcrypto.so (or libcrypto.dylib) had been installed when building
OpenSSL, to correct the xmlsec1 build problem we did "make clean", re-ran configure as
above, and edited src/openssl/Makefile under the root of the xmlsec1 distribution
directory to change all occurrences of "libcrypto.a" to "libcrypto.so". It was sometimes
also necessary to delete the -ldl flag on those same lines, and in other Makefile files
in the distribution (and making sure the flag was not specified by xmlsec1-config). After
those changes, we ran make again. Additionally, it was sometimes necessary to specify
CFLAGS="-I/usr/local/include -L/usr/local/lib".
• Another problem related to this library on a CentOS platform resulted in an error message
similar to this:
Cannot restore segment prot after reloc: Permission denied
The solution was to issue the command (adjust the path as necessary):
% chcon -t texrel_shlib_t /usr/local/xmlsec1-1.2.20/lib/libxmlsec1-openssl.so
• When including InfoCard support on macOS, it was necessary to tell the dynamic linker
where to find the xmlsec1 library (despite using the -rpath flag during the build). To
work around this, do something like the following (or equivalent):
% setenv DYLD_LIBRARY_PATH /usr/local/xmlsec1-1.2.20/lib
Ensure that "gmake test" does not fail.
• Due to an apparent bug in configure.in, on FreeBSD configure may incorrectly use the -ldl
flag in generated Makefiles. Either edit all Makefiles to remove all occurrences of the
-ldl flag, or edit configure.in, add a "*-*-freebsd*" case like the others in the
"OpenSSL" section, run autoconf to regenerate configure, and then "make clean" and re-run
configure.
• Your experience may differ, but we found xmlsec1 to not cooperate when we wanted to work
with multiple installations of libxml2 - apparently if a libxml2 directory or link has
been installed, its build procedure seems to use that version, regardless of what is
specified on the command line, requiring manual editing of its Makefiles. Check that the
correct instance of xml2-config is being used. Unfortunately, it may be necessary to
remove (or temporarily rename) older installed versions, or fall back to using an older
version already installed on your system.
• We also found it sometimes necessary to also upgrade the version of the libxslt library
(also available here[57]) to build against the same libxml2 as xmlsec1 library, otherwise
multiple versions of libxml2 may be referenced, leading to undefined symbols during the
DACS build procedure. We have had success using libxslt-1.1.28 (and then adding
--with-libxslt=/usr/local/libxslt-1.1.28 when configuring libxslt).
The DACS build procedure uses xmlsec1-config, a program that comes with xmlsec1. If InfoCard
support is enabled, the build procedure will look in some standard places for this command. You
can specify its location with the --with-xmlsec1-config[58] flag.
See the DACS configure arguments: --enable-infocard-auth[59] and --with-xmlsec1-config[58]
5. OpenLDAP
Authentication through LDAP or Microsoft Active Directory (see local_ldap_authenticate[60]) is
implemented using OpenLDAP[61]. This release of DACS has been tested only with openldap-2.4.44
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 LDAP authentication and role retrieval is currently tested against directory services
provided by Windows Server 2012 but DACS should also interoperate with other LDAP
implementations.
If the --with-ldap flag is not given (in which case LDAP authentication must be enabled; e.g.,
via --enable-ldap-auth), configure will search for OpenLDAP headers and libraries; if found, it
will assume they are a suitable version and use them.
If --with-ldap is given (either because OpenLDAP is not installed or an unsuitable version is
installed), headers and libraries relative to the root of the specified directory will be used
rather than any installed OpenLDAP files; it is not necessary to install OpenLDAP, you only need
to build it - so you do not need to be concerned about hassles associated with upgrading or any
other versions that might already be installed on your system.
To build OpenLDAP for DACS, from the root of your OpenLDAP distribution do:
% ./configure --with-tls=openssl --disable-slapd --enable-static \
CFLAGS=-I/usr/local/openssl-1.0.2j/include \
LDFLAGS=-L/usr/local/openssl-1.0.2j/lib
% make
If so instructed, do a "make depend" before the make.
See the DACS configure arguments: --enable-ldap-auth[62] and --with-ldap[63]
6. Readline
The history and editing functionality provided by the GNU Readline Library[64] is entirely
optional but can be nice to have when using dacsexpr(1)[65] interactively. This release of DACS
has been tested with version 7.0, although we have used readline-6.X with recent releases of
DACS. Note that you may need to compile Readline with the -fPIC flag ("make CFLAGS=-fPIC").
It is not necessary for you to install readline, you only need to build it - so you do not need
to be concerned about hassles associated with upgrading or any other versions that might already
be installed on your system. If readline/readline.h is in a standard include directory, it has
probably been installed and no action is necessary. On platforms where it is missing, it may be
simple to install using a command such as:
# yum install readline-devel.x86_64
or
# pkg install readline
Notes
• When building on macOS, it was sometimes necessary to fix a bug by editing shlib/Makefile
and making this change:
#SHOBJ_LDFLAGS = -dynamic
SHOBJ_LDFLAGS = -dynamiclib
See the DACS configure arguments: --with-readline[66]
5. Configure and build DACS libraries, services, commands, and utilities
See Build Options[67] for build alternatives and options to configure.
% cd src
% ./configure
% gmake
To confirm that DACS has been built with the third-party packages that you intended, from the 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 dacs.dss.ca:443
which should print the contents of https://dacs.dss.ca to the standard output. You should repeat this
test substituting the name of your server and port.
Tip
After building DACS, it is strongly recommended that you run the self-tests (expression
evaluation, crypto code, string handling, and so on) from the src directory:
% gmake test
If any error occurs during testing, testing will stop immediately and a message will be
displayed. In this event, first check that you are using the recommended software packages and
that your build flags are correct. Most often, problems are the result of mixing header files or
library files from different versions of a third-party package (e.g., OpenSSL) or incorrect file
permissions. If you cannot find anything wrong with your configuration, please submit a bug
report that includes the self test output and describes your platform (you can include the output
of "./version -v").
6. If all looks good, install DACS
% gmake install
Notes
• If gmake complains about not being able to find xsltproc, docbook.xsl, or something that
might be related to installing the documentation, try:
% (cd ../man; gmake touch)
% gmake install
• This will install the rules for the standard DACS web services and run dacsacl(1)[68] to
create and install an index for them.
• You can specify DESTDIR[69] to gmake when installing or uninstalling:
% gmake DESTDIR=/tmp/mydacs install
The installation process may prompt you for the owner name and group name to use for files and
directories; it will guess at reasonable defaults for your platform. 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[70] directive in
httpd.conf). For the group, it may help to look at /etc/group. If you need to change your owner or
group selection, remove src/.ownername or src/.groupname and try again.
Tip
While running "gmake install", important instructions regarding manual installation steps may be
displayed. A copy is written to .build_notes, truncating any previous contents.
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
While it is occasionally handy to view the manual pages using the man command, the HTML documentation
is far superior.
8. Build a DACS-enabled httpd
Please consult apache/README in the DACS distribution for details and, from the apache directory, do:
% gmake help
Security
You can build the mod_auth_dacs module[13] with a module identification string (a "version tag")
with varying amounts of detail, or without a tag. For a full-length tag, use "gmake tag", for a
simple tag use "gmake smalltag", or to disable the tag use "gmake notag" or "gmake module". We
suggest that you compile mod_auth_dacs with a tag so that Apache's SERVER_SIGNATURE and Server
response header field can include DACS version identification; this makes it easy to tell which
version of DACS the server is running and helps to detect mismatches. If mod_auth_dacs is
compiled with debugging enabled or if the SetDACSAuthDebug[71] directive enables debugging,
additional version information is added to the tag. For production use, identifying the modules
in your Apache server is considered by some to be a potential security weakness - you may
reasonably choose not to include the version tag. For some versions of Apache, module
identification can be suppressed at runtime through its ServerTokens[72] directive.
If you want mod_auth_dacs[13] to be a dynamic module, which is recommended, do:
% cd apache
% gmake tag
% gmake install
Check that your httpd.conf has the appropriate LoadModule directive.
Notes
When installing mod_auth_dacs on some platforms (such as FreeBSD 10.0), messages similar to the
following may be seen:
Warning! dlname not found in /usr/local/apache2.2/modules/mod_auth_dacs.la.
Assuming installing a .so rather than a libtool archive.
chmod 755 /usr/local/apache2.2/modules/mod_auth_dacs.so
chmod: /usr/local/apache2.2/modules/mod_auth_dacs.so: No such file or directory
apxs:Error: Command failed with rc=65536
In this situation you should notice that a shared library (a .so file) has not been created in
the Apache modules directory. This problem is apparently caused by a buggy version of libtool
that ships with Apache (e.g., /usr/local/apache2.2/apr-httpd/build-1/libtool) and is invoked by
apxs by gmake install. To work around this issue, edit the apxs command that is run from the
Makefile in the DACS apache directory (e.g., /usr/local/apache2.2/bin/apxs). Modify the apxs
script to execute the system's libtool instead of Apache's. This change will suffice, for
example:
#my $libtool = `$apr_config --apr-libtool`;
my $libtool = "/usr/local/bin/libtool";
After the change, repeat the gmake install. If this fails with the error message:
libtool: compile: unable to infer tagged configuration
try:
my $libtool = "/usr/local/bin/libtool --tag=CC";
If you want mod_auth_dacs module[13] to be a static module:
1. Copy apache/mod_auth_dacs.c to Apache's modules/aaa directory
2. Re-run Apache's configure, adding mod_auth_dacs (--with-module=aaa:auth_dacs)
3. Reinstall Apache:
% make install
4. Verify that mod_auth_dacs appears in the list of Apache modules:
% httpd -l
Tip
Because mod_auth_dacs[13] references symbols in mod_ssl, apparently those symbols must be loaded
before mod_auth_dacs is loaded. This can be ensured by statically compiling mod_ssl into httpd
(configure httpd with --enable-ssl and verify with "httpd -l") and using the following directive
in httpd.conf to dynamically load the mod_auth_dacs module:
LoadModule auth_dacs_module modules/mod_auth_dacs.so
Alternatively, it may be sufficient to dynamically load mod_ssl before mod_auth_dacs.
If mod_ssl symbols are unavailable when they are needed, you'll probably see a message like the
following when you try to start httpd:
mod_auth_dacs.so: undefined symbol: ssl_hook_Fixup
After you've installed mod_auth_dacs, restart httpd.
If you built the module with a tag, 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:
% dacshttp "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.
• 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.
9. 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[73] 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 /infocards "/usr/local/dacs/www/infocards/"
Alias /man "/usr/local/dacs/www/man/"
Alias /misc "/usr/local/dacs/www/misc/"
Alias /mod "/usr/local/dacs/www/mod/"
To see the DACS DTD files from your browser, you can also add:
AddType text/plain .dtd
These .dtd files are only used to document XML structures and messages used by DACS and are cited in
the documentation.
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.
10. 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.
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 (this is done for the DACS web services by the default ACLs).
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
# Note: For Apache 2.4, instead use:
# Require dacs-authz
Options ExecCGI
</Location>
Tip
Remember to restart Apache after making changes to httpd.conf.
Some administrators may choose to make all content or all CGIs DACS-wrapped. 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.
Tip
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.
Initial Configuration
Tip
At this point, reviewing dacs.quick(7)[11] is strongly recommended. It provides a detailed example of
what needs to be done to make your DACS operational and how to do some basic testing. If you
encounter problems installing or running Apache or DACS, please refer to dacs.quick(7)[11].
Tip
The interactive dacsinit utility can perform the steps described below quickly. You will find
dacsinit in the installation bin directory. It can be run anytime after DACS has been built and
installed. It produces a directory structure for the federation, copies the distribution's site
configuration file, creates a minimal dacs.conf for the federation and one jurisdiction, makes
federation and jurisdiction encryption keys, and generates metadata for the jurisdiction. The
resulting configuration can be used immediately by DACS commands and by DACS web services after
Apache has been configured for DACS.
Passing the -d flag to dacsinit causes it to append a string to certain paths and filenames so that,
for debugging or test purposes, it is unlikely to overwrite any "real" configuration files. Passing
it the -n flag causes it to display what it would do without performing any of the actions.
Having installed DACS, the next major step is to do some initial configuration of your federation and
jurisdiction(s). At each jurisdiction in your federation you will need to do the following:
1. Install the default site configuration file. 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
that is already there, copy federations/site.conf-std to federations/site.conf, applying any
customizations you require (customizations are usually done in dacs.conf though, so that you can
simply copy on top of the previous site.conf). Note that conf/site.conf-std may well change in a new
release and you should use the latest version.
2. As part of the installation procedure, a default set of access control rules is copied into the DACS
acls directory (default: /usr/local/dacs/acls). The default site.conf file (site.conf-std) configures
DACS to look in that directory for the default rules. These rules control access to DACS web services
and are sufficient for proper operation.
Tip
If your installed DACS web services have a filename suffix (e.g., .cgi, you should probably build
DACS with an appropriate --with-cgi-suffix flag or customize the rules manually. If it is
necessary to change the default rules, consider overriding them at the jurisdiction level instead
of editing a default ACL file - this will make it easier for you to upgrade because you will not
have to carry these changes forward to future releases of DACS.
Security
Access to some administrative and experimental DACS web services is completely disabled or
restricted by default; change these with care and at your own risk, particularly if your web
server is reachable from the Internet.
3. Configure your dacs.conf file at each jurisdiction. At the very least, you must provide
FEDERATION_DOMAIN[74], FEDERATION_NAME[75], and JURISDICTION_NAME[76] directives; all other required
directives will come from the site.conf file installed in an earlier step if you do not specify them.
4. Use dacskey(1)[77] to make encryption keys for the federation (if you are creating a new federation)
or obtain a copy of the federation's encryption keys for each new jurisdiction (if you are joining an
existing federation). Each jurisdiction in a federation must have a copy of the same federation keys.
5. Use dacskey(1)[77] to make encryption keys for each new jurisdiction (each jurisdiction will have
different keys).
6. Create a group definition that describes your jurisdictions - see dacs.groups(5)[78] - and install an
identical copy at each jurisdiction.
7. Check ownership and permissions on DACS executables and data files.
Security
All access to DACS configuration files (dacs.conf, site.conf) and keys must be limited to the
DACS administrator and the DACS CGI programs called by 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).
Initial Testing
Having configured Apache and DACS, you should try some basic DACS web services to make sure that they are
working properly before you go on to make customizations.
For example, invoke dacs_version(8)[20] from your browser to check that it is properly DACS-wrapped
(adjust the URL for your environment):
% dacshttp "http://myserver/cgi-bin/dacs/dacs_version"
Review the DACS log files (default: /usr/local/dacs/logs/*) to see what happened. The Apache log files
can also be helpful, as messages from mod_auth_dacs can be found there if they have been enabled.
You can also try dacsversion(1)[79] from the command line.
You should verify that dacs_list_jurisdictions(8)[17] works properly.
Security
If your browser successfully retrieves a DACS-wrapped resource it may retain a copy in its cache. A
later attempt to retrieve the same resource may appear to succeeed, because the cached copy is
returned, even if the DACS configuration or other context has changed so that access to the resource
should be denied. To ensure that DACS is handling every request when testing, always clear or disable
your browser's cache before beginning. If a request is granted when you expect it to be denied, try
the request again, making sure that your browser sends the request to the web server.
The next step is to configure an authentication method - see dacs_authenticate(8)[14] and try to
authenticate. Once that appears to be working, you can try dacs_current_credentials(8)[15],
dacs_prenv(8)[16], dacs_conf(8)[18], and dacs_signout(8)[19].
Security
Before deploying your DACS-enabled system, after an upgrade, or following configuration changes,
always carefully test to ensure that resources are being protected as you require. It is best to
configure and test DACS on a development platform that looks as much as possible like the intended
production platform. When you are satisfied, a clone of the development platform can become the new
production platform, which should also be tested.
Build Options
Running configure generates config.nice (over-writing any previous contents), which can be executed at
some later time if you want to re-run configure with the same arguments.
Tip
After you are 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 is possible to "bundle" several of the DACS utility programs together into a single binary called
dacs. This is similar to what OpenSSL does with its openssl command. Instead of running:
% dacsacl ...
you would run:
% dacs dacsacl ...
Running dacs without arguments displays the list of built-in utilities. Some utilities have multiple
names that are equivalent; these appear in a comma-separated list. To build this combined command, add
the flag bundle=yes to command lines when building and installing:
% gmake bundle=yes
% gmake bundle=yes install
The commands that are bundled into the dacs command won't be built as separate programs. To build and
install both bundled and unbundled commands:
% gmake bundle=both
% gmake bundle=both install
Command: gmake or "gmake 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.
Tip
If you encounter problems while building DACS with shared libraries, use --disabled-shared and
--enable-static with configure and try building it again.
Command: "gmake 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: "gmake clean"
Removes binaries, object files, and other junk in the build directory
Command: "gmake distclean"
Does a "gmake clean" and cleans up so that configure can be re-done.
Command: "gmake extraclean"
Does a "gmake distclean" and removes configure. After this, do:
% autoconf -I../include
and then run configure.
Command: "gmake uninstall"
Removes installed binaries, include files, and libraries
Other useful build commands (these should be self-explanatory):
% gmake build-services
% gmake build-progs
% gmake build-static
% gmake build-shared
% gmake build-static-services
% gmake build-shared-services
% gmake build-static-progs
% gmake build-shared-progs
% gmake build-shared-lib
% gmake install-libs
% gmake install-shared-lib
% gmake install-static-lib
% gmake install-progs
% gmake install-services
Configure Options
To verify that this documentation is up-to-date, please run:
% configure --help
This will also tell you which features are enabled (or disabled) by default. Standard build and
install options.PP
--prefix=PREFIX
The root for the installation hierarchy [/usr/local/dacs], which is referred to as the symbol and
variable DACS_HOME[21]
--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; the prefix path check does some sanity tests on PREFIX
Feature selection options.PP
--enable-access-tokens
Compile with the authorization caching feature
--enable-addons
Compile with optional add-on features[80]; add-on source code files for the version of DACS being
built must be present in the src directory
--enable-all-auth
Enable all authentication methods; you can use this flag and then individually disable methods
(e.g., --enable-all-auth --disable-apache-auth would enable all methods except Apache password
authentication
--enable-apache-auth
Enable Apache password authentication directly through DACS
--enable-bdb
Enable Berkeley DB support (default is yes); if you don't want it, use --disable-bdb
--enable-cas-auth
Enable CAS authentication
--enable-cert-auth
Enable X.509 client certificate authentication
--enable-dacs-conf
Specify default DACS config file
--enable-dacs-log
Specify initial DACS log file
--enable-debug
Compile with debugging
--enable-developer
Compile with development flags
--enable-fts
Use included fts(3)[81] library
--enable-grid-auth
Enable one-time password grid authentication
--enable-hush-startup-logging
Enable suppression of informational log messages at startup
--enable-infocard-auth
Enable InfoCard authentication and support
--enable-java
Enable Java support
--enable-ldap-auth
Enable LDAP authentication and roles
--enable-local-roles
Enable private DACS roles module (enabled by default)
--enable-native-auth
Enable authentication via Apache modules
--enable-ndbm
Enable native Unix ndbm API support (this is often supplied by the Berkeley DB compatibility API)
--enable-ntlm-auth
Enable NTLM authentication
--enable-pam-auth
Enable PAM authentication
Important
The PAM module should be considered experimental. Test it carefully before production use.
--enable-passwd-auth
Enable DACS password-protected account authentication
--enable-rule-patterns
Enable extended URL patterns when matching a request against ACLs (this is an add-on feature[80])
--enable-simple-auth
Enable simple DACS account authentication
--enable-sqlite
Enable SQLite support (default is no). If you don't want it, use --disable-sqlite
--enable-token-auth
Enable one-time password token authentication
--enable-unix-roles
Enable Unix groups roles module (enabled by default on Unix platforms)
--enable-user-info
Compile with the user information reporting feature
Third-party support options.PP
--with-apache=DIR
Root Apache install directory; if DIR is "omit", however, a basic subset of DACS will be
installed (also see above[82]) (example: if Apache files have been installed in
/usr/local/apache2.2/include, /usr/local/apache2.2/conf, etc., use
--with-apache=/usr/local/apache2.2).
--with-apache-apr=DIR
Root Apache APR install directory; required only when Apache 2.2 or 2.4 are used (example:
--with-apache-apr=/usr/local/apache2.2/apr-httpd).
--with-apache-apr-config=PATH
Apache APR configuration program; required only when Apache 2.2 or 2.4 are used and the correct
program is not on the search path; this flag may be required if the build system has more than
one instance of Apache installed or if you have installed Apache in a non-standard location
(example: --with-apache-apr-config=/usr/local/apache2.2/apr-httpd/bin/apr-1-config).
--with-apache-apr-cpp-defs=FLAGS
Preprocessor flags required when compiling files that include Apache APR code; may be required
with some "non-standard" cases when Apache 2.2 or 2.4 are used and "apr-1-config --cppflags" is
unavailable or does not report the correct flags (example:
--with-apache-apr-cpp-defs=-D_LARGEFILE64_SOURCE).
Note
It has been reported that on some GNU/Linux platforms, such as Ubuntu, it is necessary to
define these symbols when building DACS code that includes APR header files (such as
dacsversion):
#define LINUX 2
#define _REENTRANT
#define _GNU_SOURCE
#define _LARGEFILE64_SOURCE
--with-apache-apr-includes=DIR
Apache APR include files directory; required with some "non-standard" cases when Apache 2.2 or
2.4 are used and apr-1-config is unavailable or does not report the correct directory (example:
--with-apache-apr-includes=/usr/bin/include/apr-1.0).
--with-apxs=PATH
By default, the build procedure expects the Apache apxs utility to be bin/apxs, relative to
Apache's installation directory. On systems where this is incorrect, you must specifically
configure the path for apxs. (example: --with-apxs=/usr/sbin/apxs2).
--with-bdb=DIR
Location of the root of the installed Berkeley DB libraries, include files, etc.; for example
--with-bdb=/usr/local/db-5.3.28. This implies --enable-bdb.
--with-cgi-bin=DIR
Location of Apache CGI files for DACS web services. 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-cgi-suffix=SUFFIX
When installing CGI executables, add SUFFIX as the file extension. A typical value for SUFFIX is
".cgi". The default access control rules for DACS web services (via the VFS item type dacs_acls)
respect this suffix. On Windows platforms, where ".exe" is the standard extension for programs,
SUFFIX is set to that by default. Using a SUFFIX of "no" sets the extension to the null string.
--with-dacs-conf=PATH
Specify default DACS config file (default: PREFIX/federations/dacs.conf).
--with-dacs-log=PATH
Specify initial DACS log file (default: PREFIX/logs/error_log).
--with-default-cipher-list=CIPHERSTRING
Specify a default OpenSSL cipher string specification (the argument to
SSL_CTX_set_cipher_list()[83]) to be used with sslclient(1)[84] and therefore by SSL/TLS
connections internal to DACS. By default, these connections may use SSLv3 or TLS. By setting
CIPHERSTRING appropriately, connections can be restricted to TLS, for instance. This is separate
from any Apache SSL/TLS configuration.
--with-expat=DIR
Root directory of installed Expat libraries and include files. If Expat files have been installed
in /usr/local/expat/include, /usr/local/expat/lib, etc., use --with-expat=/usr/local/expat.
--with-federations-root=DIR
Location of DACS federations root directory (default: PREFIX/federations).
--with-gdbm-includes=DIR
Enable ndbm support using gdbm's compatibility API (gdbm(3)[85]), specifying the include flags to
use. (Example: --with-gdbm-includes=-I/local/src/gdbm-1.11/include). (CentOS Example:
--with-gdbm-includes=-I/usr/include/gdbm).
--with-gdbm-lib=LIB
Enable ndbm support using gdbm's compatibility API (gdbm(3)[85]), specifying the link flags to
use, the pathname for the library, and any other necessary flags. (FreeBSD Example:
--with-gdbm-lib="-Wl,-rpath,/local/src/gdbm-1.11/lib -L/local/src/gdbm-1.11/lib -lgdbm"). (CentOS
Example: --with-gdbm-lib="-L/usr/lib64 -lgdbm").
--with-htdocs=DIR
Location of Apache DACS files if not the htdocs subdirectory of the Apache install directory.
--with-iconv=DIR
Path to parent of iconv installation. This flag may be required if you are enabling Samba
support.
--with-jdk-bin
If Java support is enabled, this identifies the directory containing the java, javac, javah, and
jar commands. If this flag is absent, configure will look for those programs using the current
PATH variable. (Example: --with-jdk-bin=/usr/local/java/bin).
--with-jdk-includes
If Java support is enabled, this is a list of one or more GCC include flags for JDK include
directories (Example: --with-jdk-includes="-I/usr/local/jdk/include
-I/usr/local/jdk/include/freebsd")
--with-ldap=DIR
Location of OpenLDAP source files. This is the root directory for the OpenLDAP source
distribution (Example: /local/src/openldap-2.4.44). This implies --enable-ldap-auth.
--with-mailer-prog=PATH
Location of a mailer program to use instead of sendmail. This is only needed if email support is
required. If --with-mailer-args is also specified, it will be used as the command line arguments.
See dacsemail(1)[86] for a description of how the mailer is expected to behave.
--with-mailer-args=STRING
Command line arguments to use with the selected mailer program. This is only required if email
support is required. See dacsemail(1)[86] for a description of how the mailer is expected to
behave.
--with-readline=LIB
Use GNU Readline[64] when available. If LIB is given, it is the link flag to use or the pathname
for the library (other flags may also be specified). (Example:
--with-readline="-Wl,-rpath,/local/src/readline-7.0/lib -L/local/src/readline-7.0/lib
-I/local/src/readline-7.0/include").
--with-samba=DIR
Location of Samba source files. This is the root directory for the Samba source distribution
(Example: /local/src/samba-3.6.25). This implies --enable-ntlm-auth.
--with-sendmail=PATH
Location of sendmail(8)[87]. This is only needed if email support is required and the location of
the sendmail command found at configuration time must be overridden. If --with-mailer-args is
also specified, it will be used instead of the default sendmail command line arguments. See
dacsemail(1)[86] for additional details.
--with-sqlite=DIR
Location of the root of the installed SQLite libraries, include files, etc.; for example
--with-sqlite=/usr/local/sqlite-3.14.2. This implies --enable-sqlite.
--with-ssl=DIR
Location of the root of the installed OpenSSL libraries and include files. If OpenSSL files have
been installed in /usr/local/openssl/include, /usr/local/openssl/lib, etc., use
--with-expat=/usr/local/openssl.
--with-xmlsec1-config=PATH
If the build procedure cannot find xmlsec1-config, or if it finds the wrong one, you can specify
its location as PATH. This may only be required if InfoCard authentication has been enabled.
To specify additional flags for compiling or linking DACS, set CFLAGS or LDFLAGS, respectively.
To specify additional flags for compiling or linking the mod_auth_dacs module[13], set APACHE_CFLAGS
or APACHE_LDFLAGS, respectively. For example, this command will cause mod_auth_dacs to be built with
the -m64 flag and DACS to be built with both the -m64 flag and the -O3 flag:
% ./configure "APACHE_CFLAGS=-m64" "CFLAGS=-O3 -m64" ...
SEE ALSO
dacs(1)[88], dacs.readme(7)[12], dacs.quick(7)[11]
AUTHOR
Distributed Systems Software (www.dss.ca[89])
COPYING
Copyright2003-2016 Distributed Systems Software. See the LICENSE[90] file that accompanies the
distribution for licensing information.
NOTES
1. gmake
http://directory.fsf.org/project/make
2. GCC
http://gcc.gnu.org
3. LLVM/Clang
http://llvm.org
4. Post-Release Notes
http://dacs.dss.ca/download.html
5. dacs_acs(8)
http://dacs.dss.ca/man/dacs_acs.8.html
6. Xcode
https://developer.apple.com/xcode
7. Using Pluggable Authentication Modules (PAM)
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Managing_Smart_Cards/Pluggable_Authentication_Modules.html
8. ldconfig(8)
http://www.freebsd.org/cgi/man.cgi?query=ldconfig&apropos=0&sektion=8&manpath=FreeBSD+10.1-RELEASE&format=html
9. ldd(1)
http://www.freebsd.org/cgi/man.cgi?query=ldd&apropos=0&sektion=1&manpath=FreeBSD+10.1-RELEASE&format=html
10. Cygwin
http://cygwin.com
11. dacs.quick(7)
http://dacs.dss.ca/man/dacs.quick.7.html
12. dacs.readme(7)
http://dacs.dss.ca/man/dacs.readme.7.html
13. mod_auth_dacs module
http://dacs.dss.ca/man/mod_auth_dacs.html
14. dacs_authenticate(8)
http://dacs.dss.ca/man/dacs_authenticate.8.html
15. dacs_current_credentials(8)
http://dacs.dss.ca/man/dacs_current_credentials.8.html
16. dacs_prenv(8)
http://dacs.dss.ca/man/dacs_prenv.8.html
17. dacs_list_jurisdictions(8)
http://dacs.dss.ca/man/dacs_list_jurisdictions.8.html
18. dacs_conf(8)
http://dacs.dss.ca/man/dacs_conf.8.html
19. dacs_signout(8)
http://dacs.dss.ca/man/dacs_signout.8.html
20. dacs_version(8)
http://dacs.dss.ca/man/dacs_version.8.html
21. DACS_HOME
http://dacs.dss.ca/man/dacs.conf.5.html#var_dacs_home
22. configuration variable
http://dacs.dss.ca/man/dacs.conf.5.html#config-vars
23. man(1)
http://www.freebsd.org/cgi/man.cgi?query=man&apropos=0&sektion=1&manpath=FreeBSD+10.1-RELEASE&format=html
24. man/index.html
http://dacs.dss.ca/man/index.html
25. sudo(8)
http://www.freebsd.org/cgi/man.cgi?query=sudo&apropos=0&sektion=8&manpath=FreeBSD+10.1-RELEASE&format=html
26. Expat
http://sourceforge.net/projects/expat
27. OpenSSL
http://www.openssl.org
28. Apache
http://httpd.apache.org
29. above
http://dacs.dss.ca/man/#install-openssl
30. apr.apache.org
http://apr.apache.org
31. Third-party support options
http://dacs.dss.ca/man/#third-party-support-options
32. build Berkeley DB
http://dacs.dss.ca/man/#dbm-databases
33. FAQ
http://dacs.dss.ca/man//faq.html
34. Berkeley DB
http://www.oracle.com/us/products/database/berkeley-db/overview/index.html
35. Oracle Corporation
http://www.oracle.com
36. --enable-bdb
http://dacs.dss.ca/man/#build_flag_--enable-bdb
37. --disable-bdb
http://dacs.dss.ca/man/#build_flag_--disable-bdb
38. --with-bdb
http://dacs.dss.ca/man/#build_flag_--with-bdb
39. changed
http://www.infoworld.com/article/2611450/open-source-software/oracle-switches-berkeley-db-license.html
40. Sleepycat License
http://opensource.org/licenses/Sleepycat
41. GNU AGPL v3
http://www.oracle.com/technetwork/products/berkeleydb/downloads/oslicense-093458.html
42. ftp://ftp.gnu.org/gnu/gdbm
ftp://ftp.gnu.org/gnu/gdbm/
43. --enable-ndbm
http://dacs.dss.ca/man/#build_flag_--enable-ndbm
44. --with-gdbm-lib
http://dacs.dss.ca/man/#build_flag_--with-gdbm-lib
45. sdbm
http://search.cpan.org/src/NWCLARK/perl-5.8.8/ext/SDBM_File/sdbm/README
46. SQLite
http://www.sqlite.org
47. --enable-sqlite
http://dacs.dss.ca/man/#build_flag_--enable-sqlite
48. --disable-sqlite
http://dacs.dss.ca/man/#build_flag_--disable-sqlite
49. --with-sqlite
http://dacs.dss.ca/man/#build_flag_--with-sqlite
50. local_ntlm_authenticate
http://dacs.dss.ca/man/dacs_authenticate.8.html#local_ntlm_authenticate
51. Samba
http://www.samba.org
52. --enable-ntlm-auth
http://dacs.dss.ca/man/#build_flag_--enable-ntlm-auth
53. --with-samba
http://dacs.dss.ca/man/#build_flag_--with-samba
54. local_infocard_authenticate
http://dacs.dss.ca/man/dacs_authenticate.8.html#local_infocard_authenticate
55. libxml2
http://xmlsoft.org
56. xmlsec1
http://www.aleksey.com/xmlsec
57. here
ftp://xmlsoft.org/libxslt/
58. --with-xmlsec1-config
http://dacs.dss.ca/man/#build_flag_--with-xmlsec1-config
59. --enable-infocard-auth
http://dacs.dss.ca/man/#build_flag_--enable-infocard-auth
60. local_ldap_authenticate
http://dacs.dss.ca/man/dacs_authenticate.8.html#local_ldap_authenticate
61. OpenLDAP
http://www.openldap.org
62. --enable-ldap-auth
http://dacs.dss.ca/man/#build_flag_--enable-ldap-auth
63. --with-ldap
http://dacs.dss.ca/man/#build_flag_--with-ldap
64. GNU Readline Library
http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html
65. dacsexpr(1)
http://dacs.dss.ca/man/dacsexpr.1.html
66. --with-readline
http://dacs.dss.ca/man/#build_flag_--with-readline
67. Build Options
http://dacs.dss.ca/man/#build_options
68. dacsacl(1)
http://dacs.dss.ca/man/dacsacl.1.html
69. DESTDIR
http://www.gnu.org/prep/standards/standards.html#DESTDIR
70. Group
http://httpd.apache.org/docs/2.2/mod/mpm_common.html#group
71. SetDACSAuthDebug
http://dacs.dss.ca/man/mod_auth_dacs.html#SetDACSAuthDebug
72. ServerTokens
http://httpd.apache.org/docs/current/mod/core.html#servertokens
73. Alias
http://httpd.apache.org/docs/2.2/mod/mod_alias.html#alias
74. FEDERATION_DOMAIN
http://dacs.dss.ca/man/dacs.conf.5.html#FEDERATION_DOMAIN
75. FEDERATION_NAME
http://dacs.dss.ca/man/dacs.conf.5.html#FEDERATION_NAME
76. JURISDICTION_NAME
http://dacs.dss.ca/man/dacs.conf.5.html#JURISDICTION_NAME
77. dacskey(1)
http://dacs.dss.ca/man/dacskey.1.html
78. dacs.groups(5)
http://dacs.dss.ca/man/dacs.groups.5.html#dacs_metadata
79. dacsversion(1)
http://dacs.dss.ca/man/dacsversion.1.html
80. add-on features
http://dacs.dss.ca/man/dacs.readme.7.html#addons
81. fts(3)
http://www.freebsd.org/cgi/man.cgi?query=fts&apropos=0&sektion=3&manpath=FreeBSD+10.1-RELEASE&format=html
82. also see above
http://dacs.dss.ca/man/#building_subset
83. SSL_CTX_set_cipher_list()
http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html
84. sslclient(1)
http://dacs.dss.ca/man/sslclient.1.html
85. gdbm(3)
http://directory.fsf.org/gdbm.html
86. dacsemail(1)
http://dacs.dss.ca/man/dacsemail.1.html
87. sendmail(8)
http://www.freebsd.org/cgi/man.cgi?query=sendmail&apropos=0&sektion=8&manpath=FreeBSD+10.1-RELEASE&format=html
88. dacs(1)
http://dacs.dss.ca/man/dacs.1.html
89. www.dss.ca
http://www.dss.ca
90. LICENSE
http://dacs.dss.ca/man/../misc/LICENSE
DACS 1.4.38a 02/05/2018 DACS.INSTALL(7)