| DACS.INSTALL(7) | DACS Miscellaneous Information | DACS.INSTALL(7) |
NAME¶
dacs.install - DACS installation guide
DESCRIPTION¶
This document describes how to build and install this release of DACS. Please read it carefully.
Important
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.
# yum install pam-devel.x86_64
For details, refer to Using Pluggable Authentication Modules (PAM)[7].
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.
% cd src; sh ./config.nice
% gmake
% rm -f -r /usr/local/dacs/{acls,bin,include,lib,man,www}
% apachectl stop
% gmake install
% cd ../apache; gmake tag install
% apachectl start
or
% apachectl startssl
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
/usr/local/dacs/acls
/usr/local/dacs/bin
/usr/local/dacs/etc
/usr/local/dacs/federations
/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
/usr/local/dacs/lib
/usr/local/dacs/logs
/usr/local/dacs/sbin
/usr/local/dacs/share/man
/usr/local/dacs/tmp
/usr/local/dacs/www
Installing DACS¶
The following describes how to install DACS.
Important
% src/configure --help
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:
This release of DACS has been tested with Expat[26] 2.2.5 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.5, 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.5. Here is how we usually build Expat after unpacking it:
% cd expat-2.2.5 % ./configure --prefix=/usr/local/expat-2.2.5 % 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.
DACS uses cryptographic functionality provided by OpenSSL[27]. This release of DACS has been tested with openssl-1.0.2n 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
% ./config --prefix=/usr/local/openssl-1.0.2n --openssldir=/usr/local/openssl-1.0.2n \
-fPIC shared
% ./Configure darwin64-x86_64-cc --prefix=/usr/local/openssl-1.0.2n \
--openssldir=/usr/local/openssl-1.0.2n -fPIC shared
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]).
Important
DACS 1.4.40 is the final version to officially support the Apache 2.2 series. Future releases of DACS will not be maintained, tested, or documented with Apache 2.2 series servers.
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.
Important
% cd httpd-2.4.29 % ./configure --prefix=/usr/local/apache2-2.4.29 --enable-ssl \
--with-ssl=/usr/local/openssl-1.0.2n % make install
# yum install pcre-devel.x86_64
After unpacking fresh copies of APR (as srclib/apr) and APR-UTIL (as srclib/apr-util), configure, build, and install them. We then build httpd using the --with-apr and --with-apr-util flags. 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).
% cd httpd-2.2.34 % cd srclib/apr % ./configure --prefix=/usr/local/apache2-2.2.34/apr-httpd --disable-lfs CFLAGS=-fPIC % make install % cd ../apr-util # See notes below for adding LDFLAGS % ./configure --prefix=/usr/local/apache2-2.2.34/apr-util-httpd
--with-apr=/usr/local/apache2-2.2.34/apr-httpd
--with-expat=/usr/local/expat-2.2.5
--with-dbm=db53 % make install % cd ../.. # See notes below for adding LDFLAGS % ./configure --prefix=/usr/local/apache2-2.2.34 --enable-ssl
--with-ssl=/usr/local/openssl-1.0.2n
--with-apr=/usr/local/apache2-2.2.34/apr-httpd
--with-apr-util=/usr/local/apache2-2.2.34/apr-util-httpd
LDFLAGS="-rpath /usr/local/db-5.3.28/lib -rpath /usr/local/openssl-1.0.2n/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.
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.
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.2n/lib" to LDFLAGS so that Apache commands could find shared libraries at run time.
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.2n/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.
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.29 \
--with-ssl=/usr/local/openssl-1.0.2n --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.2n/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.
# system-config-firewall
(This command is sometimes named system-config-securitylevel, or system-config-firewall-tui in various 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
(Alternative: systemctl disable firewalld) 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).
<Directory /usr/local/dacs/www>
Satisfy Any
Allow from all
Options Indexes FollowSymLinks </Directory>
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, 20 Jan 2018 18:08:11 GMT Server: Apache/2.4.29 (Unix) OpenSSL/1.0.2n mod_auth_dacs/1.4.40(Release date 31-Jan-2018 09:49:34) PHP/5.6.14
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.
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:
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.
Notes
% ln -sf /usr/local/db-5.3.28 /usr/local/BerkeleyDB.5.3 % ln -sf /usr/local/db-5.3.28 /usr/local/db53
% 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.)
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.22.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
-DPACKAGE_STRING=\"sqlite 3.22.0\"
to:
-DPACKAGE_STRING=\"sqlite-3.22.0\"
% ./configure --prefix=/usr/local/sqlite-3.22.0 % make % make install
If you want to be able to authenticate using Microsoft's SMB[50]/NTLM[51] protocol (see local_ntlm_authenticate[52]), you must either configure DACS to use the custom implementation of the libdsm library that ships with DACS or obtain Samba[53], a Microsoft Windows interoperability suite.
DACS NTLM authentication is currently tested against services provided by Windows Server 2012 but DACS should also interoperate with other MS Windows platforms.
Important
For a very long time, Samba 3.x provided NTLM client authentication for DACS and was the only option. But because Samba 3.x has not been supported by the Samba team for quite some time, and Samba 4.x has proved to be difficult to build on DACS platforms and is not a drop-in replacement for Samba 3.x in any case, the smaller and simpler libdsm will replace Samba. Samba 3.x can still be used by this version of DACS but support for Samba will be removed.
libdsm Notes
Although the library is currently functional and tested, configuration of libdsm is not quite fully integrated or documented within the main DACS build. To use libdsm:
We continue here with a brief outline of the procedure to build the library. If you are going to enable NTLM authentication, or think you might do so later, build the library before running configure for DACS. If you do not need NTLM authentication, you need not build the library.
--with-samba
use
--with-libdsm=./libdsm
Test authentication again, this time using dacsauth (refer to dacsauth(1)[56] and local_ntlm_authenticate[57] for examples).
OPTION 'SAMBA_PORT="0"'
in the appropriate Auth clause. If you are using the standard ports, you may delete that option entirely since the library knows which port(s) to try.
Samba Notes
% ./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
--with-samba=/local/src/samba-3.6.25
InfoCard support is now deprecated and therefore these libraries are no longer needed. This section may be removed in a future release.
See local_infocard_authenticate[62].
InfoCard support requires libxml2[63] and xmlsec1[64] are required. Build libxml2 and OpenSSL first, because xmlsec1[64] 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
% ./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.
% ./configure --prefix=/usr/local/xmlsec1-1.2.20
--with-libxml=/usr/local/libxml2-2.9.1
--with-openssl=/usr/local/openssl-1.0.2n --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.2n \
--disable-crypto-dl
*** Warning: Linking the shared library libxmlsec1-openssl.la against the *** static library /local/openssl-1.0.2n/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".
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
% setenv DYLD_LIBRARY_PATH /usr/local/xmlsec1-1.2.20/lib
Ensure that "gmake test" does not fail.
See the DACS configure arguments: --enable-infocard-auth[67] and --with-xmlsec1-config[66]
Authentication through LDAP or Microsoft Active Directory (see local_ldap_authenticate[68]) is implemented using OpenLDAP[69]. This release of DACS has been tested only with openldap-2.4.45 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.2n/include \
LDFLAGS=-L/usr/local/openssl-1.0.2n/lib % make
If so instructed, do a "make depend" before the make.
See the DACS configure arguments: --enable-ldap-auth[70] and --with-ldap[71]
The history and editing functionality provided by the GNU Readline Library[72] is entirely optional but can be nice to have when using dacsexpr(1)[73] 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
#SHOBJ_LDFLAGS = -dynamic SHOBJ_LDFLAGS = -dynamiclib
See Build Options[75] 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:
% printf "GET https://dacs.dss.ca:8443 HTTP/1.0\r\n\r\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").
% gmake install
Notes
% (cd ../man; gmake touch) % gmake install
% gmake DESTDIR=/tmp/mydacs install
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.
% man dacs
While it is occasionally handy to view the manual pages using the man command, the HTML documentation is far superior.
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[79] 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[80] directive.
% 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";
% make install
% 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
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
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[81] 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"
DACS-wrapping a resource or set of related resources involves:
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.
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:
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.
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)[87] 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"
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"
Command: "gmake clean"
Command: "gmake distclean"
Command: "gmake extraclean"
% autoconf -I../include
and then run configure.
Command: "gmake uninstall"
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
--exec-prefix=EPREFIX
--bindir=DIR
--libdir=DIR
--includedir=DIR
--mandir=DIR
--enable-shared
--enable-static
--disable-prefix-check
--enable-access-tokens
--enable-addons
--enable-all-auth
--enable-apache-auth
--enable-bdb
--enable-cas-auth
--enable-cert-auth
--enable-dacs-conf
--enable-dacs-log
--enable-debug
--enable-developer
--enable-fts
--enable-grid-auth
--enable-hush-startup-logging
--enable-infocard-auth
--enable-java
--enable-ldap-auth
--enable-local-roles
--enable-native-auth
--enable-ndbm
--enable-ntlm-auth
--enable-pam-auth
Important
The PAM module should be considered experimental. Test it carefully before production use.
--enable-passwd-auth
--enable-radius-auth
--enable-rule-patterns
--enable-simple-auth
--enable-sqlite
--enable-system-libradius
--enable-token-auth
--enable-unix-roles
--enable-user-info
--with-apache=DIR
--with-apache-apr=DIR
--with-apache-apr-config=PATH
--with-apache-apr-cpp-defs=FLAGS
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
--with-apache-apu-config=PATH
--with-apache-apu-includes=DIR
--with-apxs=PATH
--with-bdb=DIR
--with-cgi-bin=DIR
--with-cgi-suffix=SUFFIX
--with-dacs-conf=PATH
--with-dacs-log=PATH
--with-default-cipher-list=CIPHERSTRING
--with-expat=DIR
--with-federations-root=DIR
--with-gdbm-includes=DIR
--with-gdbm-lib=LIB
--with-htdocs=DIR
--with-iconv=DIR
--with-jdk-bin
--with-jdk-includes
--with-ldap=DIR
--with-libdsm=DIR
--with-mailer-prog=PATH
--with-mailer-args=STRING
--with-readline=LIB
--with-samba=DIR
--with-sendmail=PATH
--with-sqlite=DIR
--with-ssl=DIR
--with-xmlsec1-config=PATH
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)[96], dacs.readme(7)[12], dacs.quick(7)[11]
AUTHOR¶
Distributed Systems Software (www.dss.ca[97])
COPYING¶
Copyright © 2003-2018 Distributed Systems Software. See the LICENSE[98] file that accompanies the distribution for licensing information.
NOTES¶
- 1.
- gmake
- 2.
- GCC
- 3.
- LLVM/Clang
- 4.
- Post-Release Notes
- 5.
- dacs_acs(8)
- 6.
- Xcode
- 7.
- Using Pluggable Authentication Modules (PAM)
- 8.
- ldconfig(8)
- 9.
- ldd(1)
- 10.
- Cygwin
- 11.
- dacs.quick(7)
- 12.
- dacs.readme(7)
- 13.
- mod_auth_dacs module
- 14.
- dacs_authenticate(8)
- 15.
- dacs_current_credentials(8)
- 16.
- dacs_prenv(8)
- 17.
- dacs_list_jurisdictions(8)
- 18.
- dacs_conf(8)
- 19.
- dacs_signout(8)
- 20.
- dacs_version(8)
- 21.
- DACS_HOME
- 22.
- configuration variable
- 23.
- man(1)
- 24.
- man/index.html
- 25.
- sudo(8)
- 26.
- Expat
- 27.
- OpenSSL
- 28.
- Apache
- 29.
- above
- 30.
- apr.apache.org
- 31.
- Third-party support options
- 32.
- build Berkeley DB
- 33.
- FAQ
- 34.
- Berkeley DB
- 35.
- Oracle Corporation
- 36.
- --enable-bdb
- 37.
- --disable-bdb
- 38.
- --with-bdb
- 39.
- changed
- 40.
- Sleepycat License
- 41.
- GNU AGPL v3
- 43.
- --enable-ndbm
- 44.
- --with-gdbm-lib
- 45.
- sdbm
- 46.
- SQLite
- 47.
- --enable-sqlite
- 48.
- --disable-sqlite
- 49.
- --with-sqlite
- 50.
- SMB
- 51.
- NTLM
- 52.
- local_ntlm_authenticate
- 53.
- Samba
- 54.
- libtasn1
- 55.
- libiconv
- 56.
- dacsauth(1)
- 57.
- local_ntlm_authenticate
- 58.
- dacs_authenticate
- 59.
- --enable-ntlm-auth
- 60.
- --with-samba
- 61.
- --with-libdsm
- 62.
- local_infocard_authenticate
- 63.
- libxml2
- 64.
- xmlsec1
- 65.
- here
- 66.
- --with-xmlsec1-config
- 67.
- --enable-infocard-auth
- 68.
- local_ldap_authenticate
- 69.
- OpenLDAP
- 70.
- --enable-ldap-auth
- 71.
- --with-ldap
- 72.
- GNU Readline Library
- 73.
- dacsexpr(1)
- 74.
- --with-readline
- 75.
- Build Options
- 76.
- dacsacl(1)
- 77.
- DESTDIR
- 78.
- Group
- 79.
- SetDACSAuthDebug
- 80.
- ServerTokens
- 81.
- Alias
- 82.
- FEDERATION_DOMAIN
- 83.
- FEDERATION_NAME
- 84.
- JURISDICTION_NAME
- 85.
- dacskey(1)
- 86.
- dacs.groups(5)
- 87.
- dacsversion(1)
- 88.
- add-on features
- 89.
- fts(3)
- 90.
- also see above
- 91.
- SSL_CTX_set_cipher_list()
- 92.
- sslclient(1)
- 93.
- gdbm(3)
- 94.
- dacsemail(1)
- 95.
- sendmail(8)
- 96.
- dacs(1)
- 97.
- www.dss.ca
- 98.
- LICENSE
| 08/23/2020 | DACS 1.4.40 |