Ubuntu Manpage: dacs.quick - DACS Quick Start Tutorial

NAME

       dacs.quick - DACS Quick Start Tutorial

DESCRIPTION

The purpose of DACS Quick Start is to explain, step-by-step, how to configure a very basic DACS-enabled
web site from scratch so that you can try DACS with minimal effort. We hope that by performing the entire
example configuration yourself, you will gain a better understanding of how DACS works and how to go
about configuring it to meet your needs. By following along with some simple examples, you will create a
completely stand-alone, single jurisdiction DACS federation on one of your hosts. You will become
familiar with some of the DACS utilities and web services. When you are done, you can simply delete a few
directories to uninstall everything. The tutorial should take about 30 minutes to complete the first
time.

After successfully completing Quick Start, you should understand DACS well enough that you can proceed to
experiment with configuration and features, and perhaps use the example configuration as a starting point
to meet your requirements.

We do not provide much background or technical information about DACS here, or tell you how to set up a
fully functional, production-quality DACS system. You may find it worthwhile to review the FAQ[1] before
beginning, but if you're itching to get started right away you may do so. For technical details, please
refer to the manual pages[2] and other documentation.

We assume that you've got some hands-on experience configuring and using Apache, although Quick Start
tells you exactly what to do. To avoid frustrating problems, we recommend that you resist the temptation
to stray from the instructions except when indicated. Experienced Apache administrators may recognize the
opportunity for some shortcuts, but since we're trying to keep things simple for a wide audience, we'd
rather not get sidetracked by mentioning them. Likewise, experienced DACS administrators may recognize
alternative ways - maybe even better ways - of doing things. But our goal is to get beginners started
quickly, so we'll progress in small steps, explaining what is being done, and providing assurance that
everything is correct so far. That way if you run into a problem, you should be able to isolate and fix
it more easily.

Perhaps it's just us, but despite working with Apache for many years, we have found that it can often be
unconscionably difficult to configure to do what you want, and to be certain that it is not doing
something you do not want.

We'll assume that you've already obtained the latest version of DACS, unpacked it, and at least skimmed
through dacs.readme(7)[3] and dacs.install(7)[4]. This document should have come from that version of
DACS.

Note
1. You will be installing and configuring a basic Apache server (httpd) as part of this tutorial.
You may perform this installation on any supported platform, whether your desktop Unix host or
some other host, such as a remote server. You will find the former somewhat easier and safer to
do, so it is recommended when possible. If doing the installation on a particular host may expose
the tutorial's web server to requests from the Internet, be sure to carefully consider the
security implications and take appropriate precautions before proceeding. Nothing in the tutorial
ought to make the host running the web server more vulnerable, but if you experiment with DACS on
your own there could be unintended consequences. It is probably a good idea to stop Apache when
you are no longer using it.

2. You will find it much easier to follow along if you use the HTML version of this document because
it includes links that save you from having to type examples. Obviously these links will only
work if you have configured the tutorial's environment. Some links from this document to other
documentation point at the tutorial environment, so they will not function if that environment is
not available. Also, your web browser must be capable of handling cookies and have that feature
enabled.

3. Make sure that this document came with the DACS release that you are working with.

4. The Quick Start procedure has been performed successfully on FreeBSD and CentOS, but we expect it
to work on most Unix-like systems. If you run into a problem, you should not proceed until you
have fixed it.

5. Depending on your environment, some tasks may need to be done as root (e.g., using sudo). In
particular, editing /etc/hosts and DACS configuration files, setting file ownership and
permissions, and the make install commands are likely to need this. No program or web service
used in the examples needs to run as root. Except for one or two optional DACS web services, none
of the DACS web services needs to run set-uid or set-gid.

6. Ordinarily, all DACS-related network communication must be done over SSL/TLS. Setting up SSL/TLS
appropriately is primarily an Apache configuration task[5], requiring a server certificate;
anyone who has done this before will likely understand what needs to be done after completing
Quick Start. But to help keep this document simple and because our goal is not to create a
production-quality DACS installation, we will neither use SSL/TLS in the examples nor mention
SSL/TLS again.

7. It's a challenge to write instructions that will work everywhere, everytime, for everyone, so
please accept our apologies for any deficiencies in this document. We are keen to improve it, so
if you encounter any problems while trying this tutorial, or if you have any questions, please
contact us[6]. Our goal is to make it as easy as possible to get started with DACS.

Quick Start Steps:

1. Step 1: Install required third-party packages

2. Step 2: Install and configure Apache

3. Step 3: Build and install DACS

4. Step 4: DACS-enable Apache

5. Step 5: Do basic DACS configuration

6. Step 6: Do basic Apache configuration for DACS

7. Step 7: Test basic DACS services

8. Step 8: Try DACS authentication

9. Step 9: DACS-wrapping a web service

10. Step 10: What's next?

11. Step 11: Clean up

Step 1: Install required third-party packages
Obtain the versions of Apache[7], OpenSSL[8], and Expat[9] that are specified in dacs.install(7)[4]. If
your system already has suitable versions of OpenSSL[8], and Expat[9] installed, you may use them if you
are comfortable deviating from these instructions; you may have to adjust paths that are used below,
however. Detailed instructions have been provided for building OpenSSL[10] and Expat[11]. This document
assumes that Apache 2.2 is being used; you may use 2.4 if you are able to adapt the instructions on your
own.

For the purposes of this exercise, those are the only third-party packages that you need, other than
gmake, GCC, and the usual software development tools. Install OpenSSL and Expat now; we will deal with
Apache in the next step.

Note
We will assume that these packages are installed under /usr/local. If you installing elsewhere, be
sure to adjust paths appropriately in the examples below.

Some administrators prefer to use a particular file extension, such as ".cgi", for CGI executables.
The easiest way to make DACS accommodate this is to pass the --with-cgi-suffix flag to configure (see
dacs.install(7)[4]). This results in the configuration variable ${Conf::dacs_cgi_bin_suffix} being
set to the suffix. In this document, we will assume that no special file extension is required.

Step 2: Install and configure Apache
Because you probably do not want to use a production web server for this exercise, so that we're on the
same page to begin with, and to make it easier for you to clean up later, we'll build and install a fresh
Apache server. It will be best if you start from scratch by unpacking an Apache distribution into a new
directory, building and installing it, and then verifying that the default Apache configuration works. We
will install this Apache in /usr/local/apache-dacs so that it does not interfere with anything already on
your system - you may change this path, but remember to make appropriate changes to the instructions that
follow.

1. From the root of the Apache distribution, you need to build Apache. Review the Apache INSTALL file.
Unfortunately, there is no simple way to build Apache that will work on all platforms, so you will
need to review the detailed instructions[12]. Then build and install Apache.

Do not configure any Apache modules or customizations. We want to create a vanilla web server. The
path /usr/local/apache-dacs is being used to avoid any existing Apache installation; when you are
finished with the tutorial, you will remove this directory.

2. We will soon configure a virtual host for a (fake) domain name that we have reserved for this
purpose, but first we must make dodgers.dacstest.dss.ca an alias for the host that will run httpd.
Choose one of the following two options:

1. If you are installing Apache on the same machine from which you are running your web browser,
edit /etc/hosts as follows:

127.0.0.1 localhost dodgers.dacstest.dss.ca

2. If you will be running your browser on a host different from where Apache is running, you will
need to add an alias in /etc/hosts for that host's IP address on both machines. The entry will
have the format:

hostip hostname dodgers.dacstest.dss.ca

For example, on my system I used:

10.0.0.125 i7.dss.ca i7 dodgers.dacstest.dss.ca

So the hostip I selected above is 10.0.0.125.

Notes
1. If your desktop is a Windows platform rather than Unix-based, you will need to edit
C:\Windows\system32\drivers\etc\hosts or C:\WINNT\system32\drivers\etc\hosts (or similar)
instead of /etc/hosts.

2. You can use the domain dodgers.dacstest.dss.ca and the others in this document no matter
where your host is located. These domain names will not be visible outside of the hosts on
which you define them by hand.

3. After you have completed this exercise, please remember to delete the aliases.
To verify the change, use ping:

% ping dodgers.dacstest.dss.ca

(You may need to run it as /sbin/ping or something similar on your system.)

3. We need to make a few changes to Apache's default configuration, in case you are already running a
web server on this machine and as a first step towards some customization that we will need shortly.
We will add a virtual host definition and do some initial set up for DACS. Edit
/usr/local/apache-dacs/conf/httpd.conf, advance to the bottom of the file, and insert the text that
appears below:

# Permit access to the DACS documents
<Directory /usr/local/dacs/www/*>
Options Indexes FollowSymLinks
Order allow,deny
Allow from all
</Directory>

# Permit access
# Configure a virtual host and make the DACS documents available
Listen dodgers.dacstest.dss.ca:18123
# Grrr! In some cases it seems to be necessary to use the IP address instead...
# Listen 10.0.0.125:18123

<VirtualHost *:18123>
ServerName dodgers.dacstest.dss.ca:18123
DocumentRoot "/usr/local/apache-dacs/htdocs"
ErrorLog "/usr/local/apache-dacs/logs/error_log"
TransferLog "/usr/local/apache-dacs/logs/access_log"
ScriptAlias /cgi-bin/ "/usr/local/apache-dacs/cgi-bin/"

Alias /css "/usr/local/dacs/www/css/"
Alias /dacs "/usr/local/dacs/www/"
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/"
</VirtualHost>

This VirtualHost[13] section is going to correspond to the DACS jurisdiction that we will define
shortly. The purpose of the Directory[14] and Alias[15] directives is to make various web resources
available without having to copy them under your DocumentRoot[16].

Note
1. In our examples, we use port 18123, which we're guessing is unlikely to already be in use on
your machine. If you are unlucky and it is in use, Apache will complain when you start it and
you will obviously need to select a different port number. So that the examples will continue
to work, consider creating a copy of this document and changing all occurrences of "18123" to
the port number you have selected. If available, commands such as netstat(1)[17] and
sockstat(1)[18] can tell you which ports are currently in use. In the event that you will be
accessing your server from the other side of a firewall (which is not recommended, as
previously mentioned), keep in mind that traffic may not ordinarily be passed through on this
port.

2. If you are already running Apache on port 80 (the default) or if you are not root whenever
you run apachectl in any of the following steps, you must comment out (or delete) all
Listen[19] directives for port 80 in httpd.conf. Therefore, comment out all directives that
look like any of the following:

Listen 80
Listen 0.0.0.0:80
Listen [::]:80

4. Some versions of Apache do not build and enable mod_cgi[20] by default. We require it, so make sure
that it has been done. Run this command; cgi_module should appear in the output list:

# bin/httpd -M

The shared library mod_cgi.so should be in the Apache installation's modules subdirectory or it
should have been built-in to httpd; in the former case, also check that there is a LoadModule[21]
directive for it:

LoadModule cgi_module modules/mod_cgi.so

5. It is good practice to run httpd as an unprivileged user id and Apache does this by default through
the User[22] directive in httpd.conf:

User nobody

DACS web services are run as the same user id as httpd, but they must be able to read and sometimes
write files within the DACS installation directory. These files should not be readable or writable by
other processes or anyone other than a DACS administrator. Using mod_suexec[23] is one approach, but
for the purpose of this tutorial we want to keep things simple. Note that setting User[22] (or
Group[24]) to root is not a good idea.

The Apache documentation recommends setting up a new group specifically for running the server, and
we will take this approach. We will assume in our examples that this group is called www. You may
need to create this group (see group(5)[25]) or you may already have a different but suitable group
name to use (e.g., webservd, _www, or daemon). Whatever group name you choose, when DACS is installed
in the next step you will be prompted for this group id and you must make the appropriate change to
httpd.conf:

Group www

Because we will refer to this group name often in later steps, save its name as the value of the
shell variable dacsgroup (we will use csh/tcsh syntax - use the syntax preferred by your shell):

% set dacsgroup=www

Note
Consider adding yourself to this group while you are working on this tutorial because you will
have to do much less of the work as root. Remember to logout and login again after adding
yourself, and verify the change using the groups command.
Change the group id of files in the Apache installation directory to this group and adjust
permissions (you may have to do this as root):

% chgrp -R $dacsgroup /usr/local/apache-dacs/
% chmod -R g+w /usr/local/apache-dacs/

6. As root, start your httpd...

# /usr/local/apache-dacs/bin/apachectl start

The reason you must do this as root is because it is required by Apache's User[22] and Group[24]
directives.

Note
On FreeBSD, Apache may produce a message like:

Failed to enable the 'httpready' Accept Filter

You may be able to fix this by doing (as root):

# kldload accf_http

See this[26].

7. Use your favourite browser (or link fetcher, such as wget) to verify that Apache is serving content,
starting with this link:

http://dodgers.dacstest.dss.ca:18123

If this fails, check again that your host has the correct IP address for dodgers.dacstest.dss.ca. If
you are running your browser on a different host than Apache, check for a networking or firewall
related problem (and try the browser on the same host as Apache).

Note
It appears that CentOS disallows non-localhost connection requests by default; to allow Apache to
receive non-localhost requests on CentOS, run (as root):

# 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 port 18123 for protocol tcp. Once the change is
applied it is persistent, so remember to remove the port from the list when you are finished with
this tutorial.

Another option, if it is safe to do so, is to totally disable the firewall. On CentOS:

# service iptables stop

If you choose to do this you should either restart the firewall when you are done ("service
iptables start") or reboot.

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 port 18123.

8. You should now check that your httpd was built properly. First, make sure that test-cgi is executable
(a CGI that is installed by Apache):

% chmod 0750 /usr/local/apache-dacs/cgi-bin/test-cgi

And then invoke it:

http://dodgers.dacstest.dss.ca:18123/cgi-bin/test-cgi

Look for the SERVER_SOFTWARE variable in its output and ensure that its value shows the correct
versions of Apache, mod_ssl, and OpenSSL; if you find something unexpected, you probably didn't
configure and/or install Apache or OpenSSL correctly.

Note
Check your file permissions and paths, and do not use different paths (via one or more symbolic
links) to specify the same directory in your configuration if the response is:

Forbidden You don't have permission to access /cgi-bin/test-cgi on this server.

Make sure to follow the Apache instructions for enabling script execution (e.g., using Options
ExecCGI), setting permissions on script files and their paths, and setting up the first line of
script files so that they are executed by the appropriate interpreter.

9. You have confirmed that Apache is properly installed, so stop the web server:

% /usr/local/apache-dacs/bin/apachectl stop

Step 3: Build and install DACS
Now it is time to build and install the DACS utilities and web services. Make your working directory the
src subdirectory of the DACS distribution.

1. Build and install DACS web services and utilities. You must use gmake, the GNU Make utility. Adjust
the paths specified for Expat, Apache, and OpenSSL as necessary. The DACS installation directory must
be writable to you and you must be able to set file user and group ownership (see below); you may
need to be root.

% ./configure --prefix=/usr/local/dacs \
--disable-shared --enable-static \
--enable-passwd-auth --disable-bdb \
--with-apache=/usr/local/apache-dacs \
--with-apache-apr=/usr/local/apache-dacs/apr-httpd \
--with-expat=/usr/local/expat-2.0.1 \
--with-ssl=/usr/local/openssl-1.0.1p
% gmake

If all goes well:

% gmake install

You can ignore any warnings about ACLs.

You will be prompted for the user id and group id to be used for DACS files and directories. The
group id you give should match the value you used for Apache's Group directive (that is, the value of
$dacsgroup). The user id can be your user id; if it is not, you will need to do the upcoming install
command (and some later commands) as root. You will need to do gmake install as root if your account
has insufficient privileges to set the user and group ids that you specify. The installation
procedure will remember your answers to the prompts; if you make a mistake or want to change them,
do:

% conftools/setaccess-sh reset

and try gmake install again.

Step 4: DACS-enable Apache
We'll continue by installing the mod_auth_dacs[27] module for Apache. Make your working directory the
apache subdirectory of the DACS distribution.

1. Compile and install the mod_auth_dacs module. As earlier, you will need to do gmake install as root
if your account has insufficient privileges to set the user and group ids that you specify.

% gmake tag
% gmake install

If this succeeds, your Apache httpd.conf[28] file should now contain the following directive:

LoadModule auth_dacs_module modules/mod_auth_dacs.so

Please check that this is so. If you cannot find that directive, add it manually near the part of
httpd.conf that talks about the LoadModule[21] directive.

2. Start Apache again (as root):

# /usr/local/apache-dacs/bin/apachectl start

and take another look at the SERVER_SOFTWARE variable:

http://dodgers.dacstest.dss.ca:18123/cgi-bin/test-cgi

The SERVER_SOFTWARE variable ought to look the same as before, except it should now also mention
mod_auth_dacs.

Congratulations - you are now running a DACS-enabled web server! DACS is not configured to do
anything at the moment, mind you, but your web server is now capable of DACS-wrapping web services.
You should be able to view the DACS manual pages served from the web server you just installed:

http://dodgers.dacstest.dss.ca:18123/man

Step 5: Do basic DACS configuration
Although your Apache is now DACS-enabled, a little more configuration of both DACS and Apache are
necessary before you can do anything interesting. We'll continue by working with the DACS configuration
(see dacs.conf(5)[29]).

We begin this step by defining a new DACS federation that consists of one jurisdiction. We will call the
new federation DACSTEST and associate it with the domain name dacstest.dss.ca. We will call our
jurisdiction LA. Incidentally, the names that we are using in this tutorial for our federation and
jurisdiction ("DACSTEST", "LA", and "dacstest.dss.ca") are not "special"; there's an underlying theme
that should be apparent to any baseball fan but we could have chosen any syntactically valid names. The
domain name for our jurisdiction (dodgers.dacstest.dss.ca) is only special in that it is a subdomain of
dacstest.dss.ca; this must be the case for all jurisdictions in our example federation.

Security
All of the files and directories that we create in this and future steps must be readable by DACS web
services. This means that they must have their group ownership set to $dacsgroup and have group read
and write permissions, as discussed earlier.

We're going to be using a few long pathnames in this step and later on, so to help unclutter the
instructions, and for your convenience, we will represent them as shell variables. For example, the
pathname /usr/local/dacs/federations will be referred to as $feds and the pathname
$feds/dacstest.dss.ca/LA will be $la. You may find it useful at this time to define the following
variables in your shell using the particular syntax it prefers (we use tcsh):

% set dacs=/usr/local/dacs
% set bin=$dacs/bin
% set feds=$dacs/federations
% set la=$feds/dacstest.dss.ca/LA

If you are using a compatible shell, such as csh, you will then be able to copy and paste command lines
and other text that follows in the tutorial.

Tip
At this point you can use the dacsinit(1)[30] program, found in the distribution's src directory, to
perform the operations in this step for you. By default, the program uses the default paths that were
established when DACS was built and the example paths used in this step. When prompted, simply use
the dacsinit default values (just hit Return/Enter), which should result in the same configuration as
you would obtain by manually following the directions in this step.

You can also use dacsinit to create a configuration for a federation with one very basic jurisdiction
based on names of your choosing. You can later extend or customize this configuration manually. Also
see Initial Configuration[31].

Although you can get away with having a single DACS configuration file on a host, we recommend a
hierarchical organization. The file site.conf, although optional, holds standard default configuration
directives as well as site-specific directives for all federations configured on this host. One or more
files named dacs.conf can be used on a per-jurisdiction, per-federation, or per-host basis; that is, each
jurisdiction on a host can have its own dacs.conf, or all (or some) of the jurisdictions on a host can
share a dacs.conf, or everything can just be lumped into one dacs.conf. It's entirely up to you.

When configure is run to build DACS, you can specify default locations for various configuration files,
including site.conf and dacs.conf. We did not change the defaults when we built DACS above, so our
examples will use the default paths.

Tip
We recommend that you always use the site.conf-std that comes with your DACS distribution as your
site.conf file and that you do not make any modifications to it, instead putting customizations in
your dacs.conf file. This will make upgrades easier and less error-prone.

1. Proceed by installing the default site configuration file as $feds/site.conf (recall that we defined
the shell variables earlier[32], and that you may have to be root to be able to install correctly):

% install -c -g $dacsgroup -m 0640 $feds/site.conf-std $feds/site.conf

Note
If the install command is unavailable on your system, you can use src/conftools/install-sh
relative to your DACS distribution directory. Or just use cp (or mkdir), chgrp, and chmod.

2. Since we are not using SSL in this tutorial, edit $feds/site.conf and change the value of the
SECURE_MODE[33] directive to "off". For production use, the directive's value should always be "on":

SECURE_MODE "off"

3. It is convenient - though not required - to collect the configuration directives for all
jurisdictions on this host in a single file. It's not unusual for a host to be associated with just
one jurisdiction (and one federation), but this is certainly not always the case.

% install -c -g $dacsgroup -m 0660 /dev/null $feds/dacs.conf

4. We will create a directory where most of the files associated with our new federation will live:

% install -d -g $dacsgroup -m 0770 $feds/dacstest.dss.ca

5. And a subdirectory within it where most of the files associated with our new jurisdiction will live:

% install -d -g $dacsgroup -m 0770 $la

6. Create a directory where we will put access control rules (also called ACLs, access control lists, or
simply rules) for our jurisdiction, and we also need an empty revocation file:

% install -d -g $dacsgroup -m 0770 $la/acls
% install -c -g $dacsgroup -m 0660 /dev/null $la/acls/revocations

7. Create directories where we will put group definitions for our jurisdiction and define the membership
of our federation:

% install -d -g $dacsgroup -m 0770 $la/groups $la/groups/LA $la/groups/DACS
% install -c -g $dacsgroup -m 0660 /dev/null $la/groups/DACS/jurisdictions.grp

Paste the following text into the $la/groups/DACS/jurisdictions.grp file:

(Remember to change 18123 if you are using a different port.) The purpose of jurisdictions.grp is to
provide DACS with information about the jurisdictions in this federation. All jurisdictions in a
federation should use identical jurisdictions.grp files. We're not going to make much use of this in
the tutorial, but if you add a jurisdiction or if any of this information changes, jurisdictions.grp
would ordinarily be updated everywhere in your federation. For instance, if you were to add a
jurisdiction to your federation, you should add another group_member element to the group_definition
that describes the new jurisdiction, and then copy the updated jurisdictions.grp file to each
jurisdiction. Please see dacs.groups(5)[34] for additional information.

8. We need some basic configuration directives for the jurisdiction LA. Paste the following text into
the $feds/dacs.conf file:

<Default>
FEDERATION_DOMAIN "dacstest.dss.ca"
FEDERATION_NAME "DACSTEST"
LOG_LEVEL "info"
</Default>

<Jurisdiction uri="dodgers.dacstest.dss.ca">
JURISDICTION_NAME "LA"
</Jurisdiction>

</Configuration>

9. And let's make this the default configuration file for DACS jurisdictions at this site:

% rm -f $la/dacs.conf
% ln -s $feds/dacs.conf $la/dacs.conf

10. Now, let's ask DACS to display its configuration by running the dacsconf(1)[35] utility:

% $bin/dacsconf -uj LA -q

This configuration is the result of merging the contents of $la/dacs.conf (which points to
$feds/dacs.conf) and $feds/site.conf, with directives in the former file overriding directives in the
latter.

11. We must create encryption keys for this federation using the dacskey(1)[36] utility:

% install -c -g $dacsgroup -m 0640 /dev/null $feds/dacstest.dss.ca/federation_keyfile
% $bin/dacskey -uj LA -q $feds/dacstest.dss.ca/federation_keyfile
% ls -l $feds/dacstest.dss.ca/federation_keyfile

We could not do this until after the jurisdiction had been configured because dacskey needs to look
at dacs.conf.

Security
The federation key file must be kept secret. Any person or process that can read the federation
key file can create DACS identities. It should be readable only by its owner and DACS and not
readable by anyone else.

12. Similarly, we should create encryption keys for our jurisdiction:

% install -c -g $dacsgroup -m 0640 /dev/null $la/jurisdiction_keyfile
% $bin/dacskey -uj LA -q $la/jurisdiction_keyfile
% ls -l $la/jurisdiction_keyfile

Like the federation keys, these keys must also be kept secret. But the jurisdiction keys are private
to their jurisdiction and are not shared among federation members.

13. Make sure that all of the files and directories starting with /usr/local/dacs have appropriate
permissions, as discussed earlier.

Note
If you modify httpd.conf you must restart Apache for the changes to take effect. If you modify
dacs.conf, site.conf, or any other DACS configuration file, the changes take effect immediately and
do not require restarting Apache.

Step 6: Do basic Apache configuration for DACS
Your Apache is now DACS-enabled and we've configured DACS. Before we can do anything interesting we must
make some changes to the Apache configuration. We will begin by DACS-wrapping DACS web services, which is
required.

1. Edit /usr/local/apache-dacs/conf/httpd.conf and locate the VirtualHost[13] section that you added
earlier. Inside that VirtualHost section and near its end, add the following text (remember to adjust
paths as necessary):

AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs "-t -v"
SetDACSAuthMethod dacs-acs external
SetDACSAuthConf dacs-acs "/usr/local/dacs/federations/dacs.conf"

<Location /cgi-bin/dacs>
Require valid-user
# Note: For Apache 2.4, instead use:
# Require dacs-authz
Options ExecCGI
AuthType DACS
AuthDACS dacs-acs
</Location>

These directives configure the virtual host to DACS-wrap the contents of all URLs that fall under the
/cgi-bin/dacs namespace. The first three directives tell mod_auth_dacs where to find the external
DACS access control program (dacs_acs(8)[37]) and the DACS configuration file.

2. Start (or restart) Apache so that it uses its new configuration (as root):

# /usr/local/apache-dacs/bin/apachectl restart

DACS should now be enforcing access control on the /cgi-bin/dacs part of the server's URL space.

3. Check that you can still access test-cgi (which you have not DACS-wrapped):

http://dodgers.dacstest.dss.ca:18123/cgi-bin/test-cgi

4. Now, let's see what happens when we try to access dacs_prenv:

http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_prenv[38]

Apache should produce a "403 Forbidden" error, which causes DACS to display an "Access Denied by
DACS" page (actually, it is the contents of the file /usr/local/dacs/www/handlers/acs_failed.html,
which is set by the ACS_ERROR_HANDLER[39] directive in site.conf). This happens because the default
rules do not grant access to dacs_prenv, so all access will be denied.

5. To finish up this step, let's add a rule that will grant everyone access to dacs_prenv. Create
$la/acls/acl-tutorial.0 with appropriate permissions:

% install -c -g $dacsgroup -m 0660 /dev/null $la/acls/acl-tutorial.0

and then paste the following text into it:

<acl_rule status="enabled">
<services>
<service url_expr='"${Conf::dacs_cgi_bin_prefix}/dacs_prenv${Conf::dacs_cgi_bin_suffix}"'/>
<service url_expr='"${Conf::dacs_cgi_bin_prefix}/dacs_version${Conf::dacs_cgi_bin_suffix}"'/>
</services>

Whenever you add or change an access rule, you must rebuild the rule index for the jurisdiction:

% $bin/dacsacl -uj LA -q -build
% chgrp $dacsgroup $la/acls/INDEX

It's currently only really necessary to run dacsacl if you add a rule or modify any part of a rule's
services element, but this may change in a future release so just do it always. We make sure that the
index file's group ID is correct.

This time dacs_prenv should work because our new rule grants access to everyone. Try it:

http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_prenv[38]

This output includes some new environment variables that are passed to all DACS-wrapped programs.
These variables begin with "DACS_", such as DACS_VERSION - see dacs_acs(8)[40] for additional
information.

Step 7: Test basic DACS services
There's still not too much you can do at this point, but there are a few DACS services that you can try.
If one of these requests fails, take a look at the DACS log files in the /usr/local/dacs/logs directory
for clues. The most likely cause is incorrect permissions on a file or directory, or possibly you made an
editing mistake.

1. The dacs_version(8)[41] web service displays various version information, naturally enough:

http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_version

2. The dacs_list_jurisdictions(8)[42] web service displays information about jurisdictions:

http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_list_jurisdictions

You may recognize some of this material from the jurisdictions.grp file.

3. We saw the conf utility earlier. We can get the same information from a web service:

http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_conf

Ooops! You should have been denied access to this web service. If you examine the default ACL (see
dacs.acls(5)[43]) for this web service, which can be found in /usr/local/dacs/acls/acl-conf.0, you
might suspect that access to dacs_conf will only be granted to identities that satisfy the expression
"dacs_admin()" (see dacs.exprs(5)[44]). And since you have not signed on to obtain a DACS identity,
the ACL should deny access. After we do a little more DACS configuration work in the next step, we
will give this another try.

Step 8: Try DACS authentication
It is possible to create accounts or identities specifically for DACS users. These identities are managed
by the dacspasswd(1)[45] utility (there are user accounts managed by other DACS commands, but we will not
discuss them here). Similar to Apache's htpasswd[46] command, these accounts are "private" in that they
are unrelated to any other identities you might have on your system, unless you tie them together. For
example, we can create a DACS identity named "root" that has no relationship to a Unix system's superuser
- perhaps you are creating a DACS account for actor Stephen Root[47].

1. We begin this step by creating an empty password file for dacspasswd (to ensure correct permissions).
Then we create a DACS account for username "sandy".

% install -c -g $dacsgroup -m 0660 /dev/null $la/passwd
% $bin/dacspasswd -uj LA -q -a sandy

You will be prompted for a password to assign to sandy's account. Choose any password you like as
long as it is at least six characters long. You can change sandy's password by running this command
again.

2. Next, we edit $la/dacs.conf and add the following text in the Jurisdiction section for
dodgers.dacstest.dss.ca:

<Auth id="passwd">
URL \
"http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/local_passwd_authenticate"
STYLE "pass"
CONTROL "sufficient"
</Auth>

This configuration enables authentication (see dacs_authenticate(8)[48]) for accounts managed by the
dacspasswd utility. Check again that all files starting with /usr/local/dacs have appropriate
permissions, as discussed earlier.

3. We should now be able to authenticate ("login") as sandy by providing the password you set up
earlier. If successful, your browser will be sent credentials (in an HTTP cookie) for the identity
DACS calls LA:sandy. Note that the cookies DACS creates are deleted when your browser exits. Even if
a cookie is not deleted, DACS credentials have a limited lifetime and will become useless when they
expire.

DACS comes with examples of simple HTML login pages with which you can authenticate:

http://dodgers.dacstest.dss.ca:18123/examples/login.html

Your browser must have JavaScript enabled to use this page. Select the jurisdiction (LA), enter the
username (sandy) and password, and then click "Login". If all is well, you should see the "DACS
Authentication Succeeded" page, which is the contents of /usr/local/dacs/www/handlers/auth_ok.html.
Of course in a production environment you would write custom login and signout pages, or integrate
the functionality with a portal or in whatever way you prefer for your site.

4. Things get a bit more interesting now that you are able to authenticate. You can follow one link on
the "DACS Authentication Succeeded" page to see your current credentials (using
dacs_current_credentials[49]) or another to visit a page that will allow you to signout
(dacs_signout(8)[50]) from all or some identities (you can also invoke dacs_signout directly[51] to
signout from all identities). If you signout, there will be a link that you can follow to login
again.

5. Now use dacspasswd to create another account:

% $bin/dacspasswd -uj LA -q -a don

If you are curious, you can take a peek at the password file, which we have configured to be
$la/passwd.

You can now authenticate as sandy or don. You can have more than one identity active at the same time
(i.e., you could be signed on as both sandy and don), but this is disallowed by default; see
ACS_CREDENTIALS_LIMIT[52] and AUTH_SINGLE_COOKIE[53].

6. Now that you're able to authenticate, let's have another try at running dacs_conf (recall you were
not granted access to it earlier). We must first make one of the identities that you have created a
DACS administrator identity. Edit $la/dacs.conf and add the following text in the Jurisdiction
section for dodgers.dacstest.dss.ca (but not within the Auth section):

ADMIN_IDENTITY "LA:sandy"

As you might assume, this confers special privileges to LA:sandy.

Authenticate as sandy using the login page and then try this link again (it should work this time):

http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_conf

If you signout[54] as sandy, then authenticate as don, and try
http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_conf again, you should be denied access.

7. In an earlier step, you created an ACL ($la/acls/acl-tutorial.0) that grants access to dacs_prenv to
any user, whether authenticated or not. Edit that rule and replace:

user("any")

with:

user("auth")

Try invoking dacs_prenv[55] when you are not authenticated - you should be denied access. Now
authenticate and try dacs_prenv[55] again - it should work. Edit the rule again and replace:

user("auth")

with:

user("LA:don")

Now you should only be granted access if you've authenticated as the DACS username LA:don.

Step 9: DACS-wrapping a web service
To use DACS to control access to a resource, there are just a few things you need to do:

• Make the URL space in which the resource lies within the scope of a Location[56] directive for the
VirtualHost that corresponds to the DACS jurisdiction responsible for the resource.

• Make an appropriate DACS access control rule for the jurisdiction responsible for the URL space in
which the resource lies.

Basically, you have to configure Apache to allow DACS to perform access control for the resource, and you
have to configure DACS to enforce the selective access that you want. This is ordinarily both easy to do
and something that is done infrequently because closely related resources are typically grouped together
within the URL space you have defined (for example, all image files may be collected under /images in the
URL space, related applications are collected somewhere under /cgi-bin, and so on) and because ACLs can
be written with wildcard patterns that will match everything "under" a given URL space prefix.

Security
It is important to verify that all resources that you intend to be DACS-wrapped really are access
controlled and that DACS cannot be bypassed (e.g., by using different URLs for the same resource).
For instance, despite many improvements, getting Apache's Virtual Hosts[57] configured exactly as you
require can be challenging - make sure that security cannot be bypassed through selection of a
particular hostname or port number.

Also, note that DACS performs access control on resource names rather than on the resources
themselves. This means that if a particular resource is known by multiple names, because of symbolic
links, for example, then to correctly manage access to the resource all of its names must be
DACS-wrapped.

Step 10: What's next?
Having successfully completed all of the previous steps, you should have a feel for some of the things
that you can do with DACS. Of course, there's much more to DACS than what we've covered. You should be
capable of using the system you've configured to this point to try some things on your own. Here are a
few ideas (in order of increasing difficulty):

• Add a DACS-wrapped resource and experiment with access control rules. It might be a static web page
or a CGI program. Remember that by default, your site-specific ACLs for the jurisdiction LA are files
in the $la/acls directory. Review dacs.acls(5)[58] before beginning.

• Assign a few roles to DACS user sandy and modify an access control rule to consider roles when
granting or denying access. Roles provide a convenient way to classify users so that access control
rules can be concisely written to grant (or deny) access to a set of users that are related in some
way. For example, you might assign some users to "students", some to "staff", and some to "faculty",
and then write rules that reference those roles rather than individual DACS usernames. Roles only
have meaning with respect to how they are used in ACLs, so you can make up any syntactically valid
words you want.

Here are some hints to get you started. You'll need to do two things: assign roles to users and
enable roles. Once enabled, your DACS will look for roles in the file $la/roles. Each line of that
file assigns roles to a user and consists of the username, a colon, and a comma-separated list of
roles. For example:

sandy:pitchers,retired-players
don:pitchers,retired-players
eric:pitchers,active-players
cesar:infielders,active-players

The other thing you'll need is some DACS configuration to enable roles. Add the following to the
Jurisdiction section of dacs.conf:

<Roles id="roles">
URL "http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/local_roles"
</Roles>

Now you can create rules that depend on the user making the request having certain roles. For
example, a rule can be written to grant access to a resource only if the user making the request has
the role "pitchers" by using the predicate (see dacs.exprs(5)[59]):

user("%LA:pitchers")

Or you can create a rule that will grant access only if the user has the roles "active-players" and
"pitchers"; use the predicate:

user("%LA:pitchers") and user("%LA:active-players")

• If you create a DACS account for a username that corresponds to a user on your system, you can
configure DACS to assign roles to that user based on the Unix groups that she belongs to. This is
very easy to do: instead of using local_roles as in the example above, use local_unix_roles instead.
If you create a DACS account for alice, for example, and the account "alice" has group membership on
your system (see group(5)), then alice would authenticate using her DACS password and be assigned
roles from her Unix group membership.

Instead of using a DACS account to authenticate alice, you can easily configure DACS to use alice's
Unix password. The DACS module local_unix_authenticate, which must be installed set-uid root so that
it can access passwords, provides this functionality.

• Add a DACS jurisdiction named NY (yankees.dacstest.dss.ca) on the same host where you configured
dodgers.dacstest.dss.ca. You do not have to configure authentication at the new jurisdiction. Notice
that you can authenticate at dodgers.dacstest.dss.ca and then access resources at
yankees.dacstest.dss.ca. This is "single sign-on".

• Run DACS on an additional host. The procedure is basically the same as what you already did in this
tutorial. Name the jurisdiction BOSTON and assign it the domain name redsox.dacstest.dss.ca. You
won't be able to use the IP address 127.0.0.1 for this; you'll have to alias the domain names to the
IP addresses of real interfaces and make the same changes to /etc/hosts on both hosts. You'll also
have to use the identical federation_keyfile on both hosts (simply copy the file you've already
made).

• Configure a different (or additional) authentication method for your jurisdiction. See
dacs_authenticate(8)[60]. For the password style of authentication, you might try the NTLM
authentication method. For a bit more of a challenge, see if you can make the expr or cert style of
authentication work.

Step 11: Clean up
If you are done, you may want to do some clean up now. First, stop Apache:

# /usr/local/apache-dacs/bin/apachectl stop

Next, delete dodgers.dacstest.dss.ca and any other domain names you created for this exercise from
/etc/hosts. Delete any groups you created. Remove /usr/local/apache-dacs, /usr/local/dacs, and everything
underneath them.

Troubleshooting
The first thing to do if you encounter a problem is to check that you've got the latest version of DACS;
a newer version might fix your problem. Also, visit the Post-Release Notes[61] area for your release in
case a newer edition of this document is available or a bug fix has been posted.

By default, the DACS log files are put in the /usr/local/dacs/logs directory. If you encounter any
problems or just want to see what's going on, examine the log files in that directory. Depending on the
DACS LOG_LEVEL[62] and LOG_FILTER[63] directives in effect, log files can quickly become big. It is safe
to delete them or truncate them at any time.

In the event of problems, you should also take a look at the Apache logs (in
/usr/local/apache-dacs/logs).

There are five main sources of problems:

1. Typos (you got the spelling or punctuation incorrect, or didn't paste text correctly),

2. File permissions are incorrect (DACS cannot read or write its files or directories),

3. You didn't follow the instructions correctly (you skipped something or misunderstood something),

4. You ran into unexpected platform dependencies, or

5. We goofed.

If you're sure the problem is either of the last two types, please contact us[6]. and tell us what
happened. Be sure to mention which steps succeeded and which one failed.

AUTHOR

       Distributed Systems Software (www.dss.ca[65])

COPYING

       Copyright2003-2015 Distributed Systems Software. See the LICENSE[66] file that accompanies the
       distribution for licensing information.

NOTES

        1. FAQ
           http://dacs.dss.ca/faq.html

        2. manual pages
           http://dacs.dss.ca/man

        3. dacs.readme(7)
           http://dacs.dss.ca/man/dacs.readme.7.html

        4. dacs.install(7)
           http://dacs.dss.ca/man/dacs.install.7.html

        5. an Apache configuration task
           http://httpd.apache.org/docs-2.2/ssl/

        6. contact us
           http://www.dss.ca/contactus.html

        7. Apache
           http://httpd.apache.org

        8. OpenSSL
           http://www.openssl.org

        9. Expat
           http://sourceforge.net/projects/expat

       10. OpenSSL
           http://dacs.dss.ca/man/dacs.install.7.html#install-openssl

       11. Expat
           http://dacs.dss.ca/man/dacs.install.7.html#install-expat

       12. detailed instructions
           http://dacs.dss.ca/man/dacs.install.7.html#install-apache

       13. VirtualHost
           http://httpd.apache.org/docs-2.2/mod/core.html#virtualhost

       14. Directory
           http://httpd.apache.org/docs-2.2/mod/core.html#directory

       15. Alias
           http://httpd.apache.org/docs-2.2/mod/mod_alias.html#alias

       16. DocumentRoot
           http://httpd.apache.org/docs-2.2/mod/core.html#documentroot

       17. netstat(1)
           http://www.freebsd.org/cgi/man.cgi?query=netstat&apropos=0&sektion=1&manpath=FreeBSD+10.1-RELEASE&format=html

       18. sockstat(1)
           http://www.freebsd.org/cgi/man.cgi?query=sockstat&apropos=0&sektion=1&manpath=FreeBSD+10.1-RELEASE&format=html

       19. Listen
           http://httpd.apache.org/docs/2.0/mod/mpm_common.html#listen

       20. mod_cgi
           http://httpd.apache.org/docs-2.2/mod/mod_cgi.html

       21. LoadModule
           http://httpd.apache.org/docs-2.2/mod/mod_so.html#loadmodule

       22. User
           http://httpd.apache.org/docs-2.2/mod/mpm_common.html#user

       23. mod_suexec
           http://httpd.apache.org/docs-2.2/mod/mod_suexec.html

       24. Group
           http://httpd.apache.org/docs-2.2/mod/mpm_common.html#group

       25. group(5)
           http://www.freebsd.org/cgi/man.cgi?query=group&apropos=0&sektion=5&manpath=FreeBSD+10.1-RELEASE&format=html

       26. this
           http://unix.derkeiler.com/Newsgroups/comp.unix.bsd.freebsd.misc/2005-04/0624.html

       27. mod_auth_dacs
           http://dacs.dss.ca/man/mod_auth_dacs.html

       28. httpd.conf
           file:///usr/local/apache-dacs/conf/httpd.conf

       29. dacs.conf(5)
           http://dodgers.dacstest.dss.ca:18123/man/dacs.conf.5.html

       30. dacsinit(1)
           http://dacs.dss.ca/man/dacsinit.1.html

       31. Initial Configuration
           http://dacs.dss.ca/man/dacs.install.7.html#initial_config

       32. earlier
           http://dacs.dss.ca/man/#var-defs

       33. SECURE_MODE
           http://dacs.dss.ca/man/dacs.conf.5.html#SECURE_MODE

       34. dacs.groups(5)
           http://dacs.dss.ca/man/dacs.groups.5.html#dacs_metadata

       35. dacsconf(1)
           http://dodgers.dacstest.dss.ca:18123/man/dacsconf.1.html

       36. dacskey(1)
           http://dodgers.dacstest.dss.ca:18123/man/dacskey.1.html

       37. dacs_acs(8)
           http://dodgers.dacstest.dss.ca:18123/man/dacs_acs.8.html

       38. http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_prenv
           http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_prenv?FORMAT=html

       39. ACS_ERROR_HANDLER
           http://dacs.dss.ca/man/dacs.conf.5.html#ACS_ERROR_HANDLER

       40. dacs_acs(8)
           http://dacs.dss.ca/man/dacs_acs.8.html#exported_envars

       41. dacs_version(8)
           http://dodgers.dacstest.dss.ca:18123/man/dacs_version.8.html

       42. dacs_list_jurisdictions(8)
           http://dodgers.dacstest.dss.ca:18123/man/dacs_list_jurisdictions.8.html

       43. dacs.acls(5)
           http://dodgers.dacstest.dss.ca:18123/man/dacs.acls.5.html

       44. dacs.exprs(5)
           http://dodgers.dacstest.dss.ca:18123/man/dacs.exprs.5.html

       45. dacspasswd(1)
           http://dodgers.dacstest.dss.ca:18123/man/dacspasswd.1.html

       46. htpasswd
           http://httpd.apache.org/docs-2.2/programs/htpasswd.html

       47. Stephen Root
           http://us.imdb.com/name/nm0740535/

       48. dacs_authenticate(8)
           http://dodgers.dacstest.dss.ca:18123/man/dacs_authenticate.8.html

       49. dacs_current_credentials
           http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_current_credentials

       50. dacs_signout(8)
           http://dodgers.dacstest.dss.ca:18123/man/dacs_signout.8.html

       51. invoke dacs_signout directly
           http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_signout

       52. ACS_CREDENTIALS_LIMIT
           http://dacs.dss.ca/man/dacs.conf.5.html#ACS_CREDENTIALS_LIMIT

       53. AUTH_SINGLE_COOKIE
           http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_SINGLE_COOKIE

       54. signout
           http://dodgers.dacstest.dss.ca:18123/examples/signout.html

       55. dacs_prenv
           http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_prenv

       56. Location
           http://httpd.apache.org/docs-2.2/mod/core.html#location

       57. Virtual Hosts
           http://httpd.apache.org/docs/2.2/vhosts/

       58. dacs.acls(5)
           http://dacs.dss.ca/man/dacs.acls.5.html

       59. dacs.exprs(5)
           http://dacs.dss.ca/man/dacs.exprs.5.html

       60. dacs_authenticate(8)
           http://dacs.dss.ca/man/dacs_authenticate.8.html

       61. Post-Release Notes
           http://dacs.dss.ca/download.html

       62. LOG_LEVEL
           http://dacs.dss.ca/man/dacs.conf.5.html#LOG_LEVEL

       63. LOG_FILTER
           http://dacs.dss.ca/man/dacs.conf.5.html#LOG_FILTER

       64. dacs(1)
           http://dacs.dss.ca/man/dacs.1.html

       65. www.dss.ca
           http://www.dss.ca

       66. LICENSE
           http://dacs.dss.ca/man/../misc/LICENSE

NAME

DESCRIPTION

SEE ALSO

AUTHOR

COPYING

NOTES