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

Obtain and unpack the new distribution and chdir to it;

Review the README and instructions in this document;

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

% cd src; sh ./config.nice

Build DACS:

% gmake

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

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

Stop httpd:

% apachectl stop

Install DACS:

% gmake install

Make and install the latest mod_auth_dacs module:

% cd ../apache; gmake tag install

Restart httpd:

% apachectl start

or

% apachectl startssl

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

Unpack the DACS distribution.

Familiarize yourself with the system by:

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

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

Configure and build DACS libraries, services, and utilities

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

% cd src
% ./configure
% make

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

% ./version -v

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

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

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

If all looks good, install DACS

% make install

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

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

% man dacs

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

Build a DACS-enabled httpd

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

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

% cd apache
% make module
% make install

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

If you want mod_auth_dacs to be a static module:

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

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

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

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

% telnet myserver myserverport

and typing:

OPTIONS * HTTP/1.0

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

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

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

Add lines like the following to your httpd.conf:

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

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

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

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

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

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

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

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

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

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

Check ownership and permissions on DACS executables and data files

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

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

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