/usr/share/doc/dacs-examples/man/dacs.quick.7.html

<!-- Copyright (c) 2003-2013 -->
<!-- Distributed Systems Software.  All rights reserved. -->
<!-- See the file LICENSE for redistribution information. -->
<!-- $Id: copyright-html 2625 2013-01-22 18:15:12Z brachman $ -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>dacs.quick</title><link rel="stylesheet" type="text/css" href="css/dacsdocs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div id="refentry" class="para16">
<script language="javascript" type="text/javascript" src="css/js/fontselector.js"></script>
<table width="100%"><tr>
<td align="left">
<b>DACS.QUICK(7)</b></td>
<td align="center">
<b>DACS Miscellaneous</b></td>
<td align="right">
<b>DACS.QUICK(7)</b></td>
</tr></table>
<div class="refnamediv"><h2>NAME</h2><p>dacs.quick &#8212; <span class="command"><strong>DACS</strong></span> Quick Start Tutorial</p></div><div class="refsect1"><a name="idm11"></a><h2>DESCRIPTION</h2><p>The purpose of <span class="command"><strong>DACS</strong></span>
Quick Start is to explain, step-by-step, how to configure a very basic
<span class="command"><strong>DACS</strong></span>-enabled web site from scratch so that you can
try <span class="command"><strong>DACS</strong></span> with minimal effort.
We hope that by performing the entire example configuration
yourself, you will gain a better understanding of how
<span class="command"><strong>DACS</strong></span> 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 <span class="command"><strong>DACS</strong></span> federation on one of your hosts.
You will become familiar with some of the <span class="command"><strong>DACS</strong></span>
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.
</p><p>After successfully completing Quick Start, you should understand
<span class="command"><strong>DACS</strong></span> 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.
</p><p>We do not provide much background or technical information about
<span class="command"><strong>DACS</strong></span> here, or tell you how to set up a fully functional,
production-quality <span class="command"><strong>DACS</strong></span> system.
You may find it worthwhile to review the
<a class="ulink" href="http://dacs.dss.ca/faq.html" target="_top">FAQ</a> before beginning,
but if you're itching to get started right away you may do so.
For technical details, please refer to the
<a class="ulink" href="http://dacs.dss.ca/man" target="_top">manual pages</a>
and other documentation.
</p><p>We assume that you've got some hands-on experience configuring
and using <span class="command"><strong>Apache</strong></span>, although Quick Start tells you exactly
what to do.
<span class="emphasis"><em>To avoid frustrating problems, we recommend that you resist
the temptation to stray from the instructions except when indicated</em></span>.
Experienced <span class="command"><strong>Apache</strong></span> 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 <span class="command"><strong>DACS</strong></span> 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.
</p><p>Perhaps it's just us, but despite working with
<span class="command"><strong>Apache</strong></span> 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.
</p><p>We'll assume that you've already obtained the
<span class="emphasis"><em>latest version</em></span> of <span class="command"><strong>DACS</strong></span>,
unpacked it, and at least skimmed through
<a class="ulink" href="dacs.readme.7.html" target="_top">dacs.readme(7)</a> and
<a class="ulink" href="dacs.install.7.html" target="_top">dacs.install(7)</a>.
This document should have come from that version of
<span class="command"><strong>DACS</strong></span>.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note1"></a>Note</h3><p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>You will be installing and configuring a basic
<span class="command"><strong>Apache</strong></span> server
(<span class="command"><strong>httpd</strong></span>) 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 <span class="command"><strong>DACS</strong></span>
on your own there could be unintended consequences.
It is probably a good idea to stop <span class="command"><strong>Apache</strong></span> when you are
no longer using it.
</p></li><li class="listitem"><p>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.
</p></li><li class="listitem"><p>Make sure that this document came with the
<span class="command"><strong>DACS</strong></span> release that you are working with.
</p></li><li class="listitem"><p>The Quick Start procedure has been performed successfully on
<span class="osname">FreeBSD</span> and
<span class="osname">CentOS</span>,
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.
</p></li><li class="listitem"><p>Depending on your environment, some
tasks may need to be done as
<span class="username">root</span>
(e.g., using <span class="command"><strong>sudo</strong></span>).
In particular, editing <code class="filename">/etc/hosts</code> and
<span class="command"><strong>DACS</strong></span> configuration files,
setting file ownership and permissions,
and the <strong class="userinput"><code>make install</code></strong> commands are likely to need this.
No program or web service used in the examples
needs to run as <span class="username">root</span>.
Except for one or two optional <span class="command"><strong>DACS</strong></span> web services,
none of the <span class="command"><strong>DACS</strong></span> web services needs to run set-uid
or set-gid.
</p></li><li class="listitem"><p>Ordinarily, all <span class="command"><strong>DACS</strong></span>-related
network communication <span class="emphasis"><em>must</em></span> be done over SSL/TLS.
Setting up SSL/TLS appropriately is primarily
<a class="ulink" href="http://httpd.apache.org/docs-2.2/ssl/" target="_top">an Apache configuration
task</a>,
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 <span class="command"><strong>DACS</strong></span> installation, we will neither
use SSL/TLS in the examples nor mention SSL/TLS again.
</p></li><li class="listitem"><p>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
<a class="ulink" href="http://www.dss.ca/contactus.html" target="_top">contact us</a>.
Our goal is to make it as easy as possible to get started with
<span class="command"><strong>DACS</strong></span>.
</p></li></ol></div><p>
</p></div><div class="highlights"><a name="step_index"></a><p>Quick Start Steps:</p><div class="nomarker"><div class="column1"><p><a class="xref" href="#Step%201" title="Step 1: Install required third-party packages">Step 1: Install required third-party packages</a>
</p></div><div class="column1"><p><a class="xref" href="#Step%202" title="Step 2: Install and configure Apache">Step 2: Install and configure Apache</a>
</p></div><div class="column1"><p><a class="xref" href="#Step%203" title="Step 3: Build and install DACS">Step 3: Build and install DACS</a>
</p></div><div class="column1"><p><a class="xref" href="#Step%204" title="Step 4: DACS-enable Apache">Step 4: DACS-enable Apache</a>
</p></div><div class="column1"><p><a class="xref" href="#Step%205" title="Step 5: Do basic DACS configuration">Step 5: Do basic DACS configuration</a>
</p></div><div class="column1"><p><a class="xref" href="#Step%206" title="Step 6: Do basic Apache configuration for DACS">Step 6: Do basic Apache configuration for DACS</a>
</p></div><div class="column2 reset"><p><a class="xref" href="#Step%207" title="Step 7: Test basic DACS services">Step 7: Test basic DACS services</a>
</p></div><div class="column2"><p><a class="xref" href="#Step%208" title="Step 8: Try DACS authentication">Step 8: Try DACS authentication</a>
</p></div><div class="column2"><p><a class="xref" href="#Step%209" title="Step 9: DACS-wrapping a web service">Step 9: DACS-wrapping a web service</a>
</p></div><div class="column2"><p><a class="xref" href="#Step%2010" title="Step 10: What's next?">Step 10: What's next?</a>
</p></div><div class="column2"><p><a class="xref" href="#Step%2011" title="Step 11: Clean up">Step 11: Clean up</a>
</p></div></div></div><div class="refsect2"><a name="Step%201"></a><h3><span class="refsect2_spec"><a name="step_1"></a>Step 1: Install required third-party packages</span></h3><p>Obtain the versions of
<a class="ulink" href="http://httpd.apache.org" target="_top">Apache</a>,
<a class="ulink" href="http://www.openssl.org" target="_top">OpenSSL</a>, and
<a class="ulink" href="http://sourceforge.net/projects/expat" target="_top">Expat</a>
that are specified in
<a class="ulink" href="dacs.install.7.html" target="_top">dacs.install(7)</a>.
If your system already has suitable versions of
<a class="ulink" href="http://www.openssl.org" target="_top">OpenSSL</a>, and
<a class="ulink" href="http://sourceforge.net/projects/expat" target="_top">Expat</a>
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
<a class="ulink" href="dacs.install.7.html#install-openssl" target="_top">OpenSSL</a>
and
<a class="ulink" href="dacs.install.7.html#install-expat" target="_top">Expat</a>.
This document assumes that <span class="command"><strong>Apache</strong></span>
<span class="version">2.2</span> is being used;
you may use <span class="version">2.4</span> if you are able to
adapt the instructions on your own.
</p><p>
For the purposes of this exercise, those are the only third-party packages
that you need, other than <span class="command"><strong>gmake</strong></span>, <span class="command"><strong>GCC</strong></span>,
and the usual software development tools.
Install <span class="command"><strong>OpenSSL</strong></span> and
<span class="command"><strong>Expat</strong></span> now;
we will deal with <span class="command"><strong>Apache</strong></span> in the next step.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note2"></a>Note</h3><p>We will
assume that these packages are installed
under <span class="directory">/usr/local</span>.
If you installing elsewhere, be sure to adjust paths appropriately
in the examples below.
</p><p>Some administrators prefer to use a particular file extension,
such as "<span class="extension">.cgi</span>", for CGI executables.
The easiest way to make <span class="command"><strong>DACS</strong></span> accommodate this is to
pass the <code class="option">--with-cgi-suffix</code> flag to
<span class="command"><strong>configure</strong></span>
(see <a class="ulink" href="dacs.install.7.html" target="_top">dacs.install(7)</a>).
This results in the configuration variable
<code class="varname">${Conf::dacs_cgi_bin_suffix}</code> being set to the suffix.
In this document, we will assume that no special file extension is required.
</p></div></div><div class="refsect2"><a name="Step%202"></a><h3><span class="refsect2_spec"><a name="step_2"></a>Step 2: Install and configure Apache</span></h3><p>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
<span class="command"><strong>Apache</strong></span> server.
It will be best if you start from scratch by unpacking an
<span class="command"><strong>Apache</strong></span> distribution into a new directory,
building and installing it, and then verifying that
the default <span class="command"><strong>Apache</strong></span> configuration works.
We will install this <span class="command"><strong>Apache</strong></span> in
<span class="directory">/usr/local/apache-dacs</span>
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.
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>From the root of the <span class="command"><strong>Apache</strong></span> distribution,
you need to build <span class="command"><strong>Apache</strong></span>.
Review the <span class="command"><strong>Apache</strong></span> <code class="filename">INSTALL</code> file.
Unfortunately, there is no simple way to build <span class="command"><strong>Apache</strong></span>
that will work on all platforms, so you will need to review the
<a class="ulink" href="dacs.install.7.html#install-apache" target="_top">detailed instructions</a>.
Then build and install <span class="command"><strong>Apache</strong></span>.
</p><p>Do not configure any <span class="command"><strong>Apache</strong></span> modules or customizations.
We want to create a vanilla web server.
The path <span class="directory">/usr/local/apache-dacs</span>
is being used to avoid
any existing <span class="command"><strong>Apache</strong></span> installation;
when you are finished with the tutorial, you will remove this directory.
</p></li><li class="listitem"><p>We will soon configure a virtual host
for a (fake) domain name that we have reserved for this purpose, but first
we must make
<span class="domainname">dodgers.dacstest.dss.ca</span>
an alias for the host that will run <span class="command"><strong>httpd</strong></span>.
Choose one of the following two options:
</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>If you are installing <span class="command"><strong>Apache</strong></span> on the
same machine from which you are running your web browser,
edit <code class="filename">/etc/hosts</code> as follows:
</p><pre class="programlisting">
127.0.0.1     localhost dodgers.dacstest.dss.ca
</pre><p>
</p></li><li class="listitem"><p>If you will be running your browser on a host different
from where <span class="command"><strong>Apache</strong></span>
is running, you will need to add an alias
in <code class="filename">/etc/hosts</code>
for that host's IP address <span class="emphasis"><em>on both machines</em></span>.
The entry will have the format:
</p><pre class="programlisting">
<em class="replaceable"><code>hostip</code></em>       <em class="replaceable"><code>hostname</code></em> dodgers.dacstest.dss.ca
</pre><p>
For example, on my system I used:
</p><pre class="programlisting">
10.0.0.125     i7.dss.ca i7 dodgers.dacstest.dss.ca
</pre><p>
So the <em class="replaceable"><code>hostip</code></em> I selected above is
<span class="ipaddress">10.0.0.125</span>.
</p></li></ol></div><p>

</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note3"></a>Notes</h3><p>
</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>If your desktop is a Windows platform rather than Unix-based,
you will need to edit
<code class="filename">C:\Windows\system32\drivers\etc\hosts</code> or
<code class="filename">C:\WINNT\system32\drivers\etc\hosts</code> (or similar)
instead of <code class="filename">/etc/hosts</code>.
</p></li><li class="listitem"><p>You can use the domain
<span class="domainname">dodgers.dacstest.dss.ca</span>
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.
</p></li><li class="listitem"><p>After you have completed this exercise,
please remember to delete the aliases.
</p></li></ol></div><p>
</p></div><p>
To verify the change, use <span class="command"><strong>ping</strong></span>:
</p><pre class="programlisting">
% ping dodgers.dacstest.dss.ca
</pre><p>
(You may need to run it as
<code class="filename">/sbin/ping</code> or something similar on your system.)
</p></li><li class="listitem"><p>We need to make a few changes to <span class="command"><strong>Apache's</strong></span>
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 <span class="command"><strong>DACS</strong></span>.
Edit <code class="filename">/usr/local/apache-dacs/conf/httpd.conf</code>,
advance to the bottom of the file, and insert the text that appears below:
</p><pre class="programlisting">
# Permit access to the DACS documents
&lt;Directory /usr/local/dacs/www/*&gt;
  Options Indexes FollowSymLinks
  Order allow,deny
  Allow from all
&lt;/Directory&gt;

# 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

&lt;VirtualHost *:18123&gt;
  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/"
&lt;/VirtualHost&gt;
</pre><p>
</p><p>This
<a class="ulink" href="http://httpd.apache.org/docs-2.2/mod/core.html#virtualhost" target="_top"><span class="property">VirtualHost</span></a>
section is going to correspond to the <span class="command"><strong>DACS</strong></span> jurisdiction
that we will define shortly.
The purpose of the
<a class="ulink" href="http://httpd.apache.org/docs-2.2/mod/core.html#directory" target="_top"><span class="property">Directory</span></a>
and
<a class="ulink" href="http://httpd.apache.org/docs-2.2/mod/mod_alias.html#alias" target="_top"><span class="property">Alias</span></a>
directives is to make various web resources available without having
to copy them under your
<a class="ulink" href="http://httpd.apache.org/docs-2.2/mod/core.html#documentroot" target="_top"><span class="property">DocumentRoot</span></a>.

</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note4"></a>Note</h3><p>
</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>In our examples, we use port
<span class="port">18123</span>,
which we're guessing
is unlikely to already be in use on your machine.
If you are unlucky and it is in use, <span class="command"><strong>Apache</strong></span> 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 "<code class="literal">18123</code>" to the port number you have selected.
If available, commands such as
<a class="ulink" href="http://www.freebsd.org/cgi/man.cgi?query=netstat&amp;apropos=0&amp;sektion=1&amp;manpath=FreeBSD+10.1-RELEASE&amp;format=html" target="_top">netstat(1)</a>
and
<a class="ulink" href="http://www.freebsd.org/cgi/man.cgi?query=sockstat&amp;apropos=0&amp;sektion=1&amp;manpath=FreeBSD+10.1-RELEASE&amp;format=html" target="_top">sockstat(1)</a>
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.
</p></li><li class="listitem"><p>If you are already running <span class="command"><strong>Apache</strong></span> on
port <span class="port">80</span> (the default)
or if you are not <span class="username">root</span>
whenever you run <span class="command"><strong>apachectl</strong></span> in any of the following steps,
you must comment out (or delete) all
<a class="ulink" href="http://httpd.apache.org/docs/2.0/mod/mpm_common.html#listen" target="_top"><span class="property">Listen</span></a>
directives for port <span class="port">80</span>
in <code class="filename">httpd.conf</code>.
Therefore, comment out all directives that look like any of the following:
</p><pre class="programlisting">
Listen 80
Listen 0.0.0.0:80
Listen [::]:80
</pre><p>
</p></li></ol></div><p>

</p></div><p>
</p></li><li class="listitem"><p>Some versions of <span class="command"><strong>Apache</strong></span>
do not build and enable
<a class="ulink" href="http://httpd.apache.org/docs-2.2/mod/mod_cgi.html" target="_top"><span class="property">mod_cgi</span></a>
by default.
We require it, so make sure that it has been done.
Run this command;
<code class="literal">cgi_module</code> should appear in the output list:
</p><pre class="programlisting">
# bin/httpd -M
</pre><p>
The shared library
<code class="filename">mod_cgi.so</code> should be in the
<span class="command"><strong>Apache</strong></span> installation's
<span class="directory">modules</span> subdirectory
or it should have been built-in to <span class="command"><strong>httpd</strong></span>;
in the former case, also check that there is a
<a class="ulink" href="http://httpd.apache.org/docs-2.2/mod/mod_so.html#loadmodule" target="_top"><span class="property">LoadModule</span></a> directive for it:
</p><pre class="programlisting">
LoadModule cgi_module modules/mod_cgi.so
</pre><p>
</p></li><li class="listitem"><p>It is good practice to run
<span class="command"><strong>httpd</strong></span> as an unprivileged user id
and <span class="command"><strong>Apache</strong></span> does this by default through the
<a class="ulink" href="http://httpd.apache.org/docs-2.2/mod/mpm_common.html#user" target="_top"><span class="property">User</span></a>
directive in <code class="filename">httpd.conf</code>:
</p><pre class="programlisting">
User nobody
</pre><p>
<span class="command"><strong>DACS</strong></span> web services are run as the same user id as
<span class="command"><strong>httpd</strong></span>, but they must be able to read and sometimes write
files within the <span class="command"><strong>DACS</strong></span> installation directory.
These files should not be readable or writable by other processes
or anyone other than a <span class="command"><strong>DACS</strong></span> administrator.
Using
<a class="ulink" href="http://httpd.apache.org/docs-2.2/mod/mod_suexec.html" target="_top">mod_suexec</a>
is one approach, but for the purpose of this tutorial we want to keep
things simple.
Note that setting
<a class="ulink" href="http://httpd.apache.org/docs-2.2/mod/mpm_common.html#user" target="_top"><span class="property">User</span></a>
(or <a class="ulink" href="http://httpd.apache.org/docs-2.2/mod/mpm_common.html#group" target="_top"><span class="property">Group</span></a>)
to <span class="username">root</span> is not a good idea.
</p><p>The <span class="command"><strong>Apache</strong></span> 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
<span class="groupname">www</span>.
You may need to create this group (see
<a class="ulink" href="http://www.freebsd.org/cgi/man.cgi?query=group&amp;apropos=0&amp;sektion=5&amp;manpath=FreeBSD+10.1-RELEASE&amp;format=html" target="_top">group(5)</a>)
or you may already have a different but suitable group name to use
(e.g., <span class="groupname">webservd</span>,
<span class="groupname">_www</span>, or
<span class="groupname">daemon</span>).
Whatever group name you choose, when <span class="command"><strong>DACS</strong></span> is installed
in the next step you will be prompted for this group id
and you must make the appropriate change to <code class="filename">httpd.conf</code>:
</p><pre class="programlisting">
Group www
</pre><p>
</p><p>Because we will refer to this group name often in later steps,
save its name as the value of the shell variable <code class="varname">dacsgroup</code>
(we will use <span class="command"><strong>csh</strong></span>/<span class="command"><strong>tcsh</strong></span> syntax - use
the syntax preferred by your shell):
</p><pre class="programlisting">
% set dacsgroup=www
</pre><p>
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Note</h3><p>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
<span class="username">root</span>.
Remember to logout and login again after adding yourself,
and verify the change using the <span class="command"><strong>groups</strong></span> command.
</p></div><p>Change the group id of files in the <span class="command"><strong>Apache</strong></span>
installation directory to this group and adjust permissions
(you may have to do this as <span class="username">root</span>):
</p><pre class="programlisting">
% chgrp -R $dacsgroup /usr/local/apache-dacs/
% chmod -R g+w /usr/local/apache-dacs/
</pre><p>
</p></li><li class="listitem"><p>As
<span class="username">root</span>,
start your httpd...
</p><pre class="programlisting">
# /usr/local/apache-dacs/bin/apachectl start
</pre><p>
The reason you must do this as <span class="username">root</span>
is because it is required by Apache's
<a class="ulink" href="http://httpd.apache.org/docs-2.2/mod/mpm_common.html#user" target="_top"><span class="property">User</span></a> and
<a class="ulink" href="http://httpd.apache.org/docs-2.2/mod/mpm_common.html#group" target="_top"><span class="property">Group</span></a> directives.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Note</h3><p>
On <span class="osname">FreeBSD</span>,
<span class="command"><strong>Apache</strong></span> may produce a message like:
</p><pre class="screen"><span class="errortext">Failed to enable the 'httpready' Accept Filter</span></pre><p>
You may be able to fix this by doing
(as <span class="username">root</span>):
</p><pre class="screen"><strong class="userinput"><code>
# kldload accf_http
</code></strong></pre><p>
See
<a class="ulink" href="http://unix.derkeiler.com/Newsgroups/comp.unix.bsd.freebsd.misc/2005-04/0624.html" target="_top">this</a>.
</p></div><p>
</p></li><li class="listitem"><p>Use your favourite browser (or link fetcher,
such as <span class="command"><strong>wget</strong></span>) to verify that <span class="command"><strong>Apache</strong></span>
is serving content, starting with this link:
</p><pre class="screen">
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123" target="_top">http://dodgers.dacstest.dss.ca:18123</a>
</pre><p>
If this fails, check again that your host has the correct IP address for
<span class="domainname">dodgers.dacstest.dss.ca</span>.
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).
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Note</h3><p>It appears that <span class="osname">CentOS</span>
disallows non-localhost connection requests by default;
to allow Apache to receive non-localhost requests on
<span class="osname">CentOS</span>, run
(as <span class="username">root</span>):
</p><pre class="screen">
# system-config-firewall
</pre><p>
(This command was named <span class="command"><strong>system-config-securitylevel</strong></span>
in earlier releases of <span class="osname">CentOS</span>).
In the "Other ports" section of the "Firewall Options",
add port <span class="port">18123</span> for protocol
<code class="literal">tcp</code>.
Once the change is applied it is persistent, so remember to remove the port
from the list when you are finished with this tutorial.
</p><p>
Another option, if it is safe to do so, is to totally disable the firewall.
On <span class="osname">CentOS</span>:
</p><pre class="screen">
# service iptables stop
</pre><p>
If you choose to do this you should either restart the firewall when you
are done ("<strong class="userinput"><code>service iptables start</code></strong>") or reboot.
</p><p>Another alternative, for <span class="osname">CentOS</span>
and other systems, is to use the appropriate command
(e.g., <span class="command"><strong>iptables</strong></span>, <span class="command"><strong>ipfw</strong></span>, or
<span class="command"><strong>pfctl</strong></span>) to add a firewall rule to allow TCP access
to port <span class="port">18123</span>.
</p></div></li><li class="listitem"><p>You should now check that your
<span class="command"><strong>httpd</strong></span> was built properly.
First, make sure that <span class="command"><strong>test-cgi</strong></span> is executable
(a CGI that is installed by <span class="command"><strong>Apache</strong></span>):
</p><pre class="programlisting">
% chmod 0750 /usr/local/apache-dacs/cgi-bin/test-cgi
</pre><p>

And then invoke it:
</p><pre class="screen">
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/cgi-bin/test-cgi" target="_top">http://dodgers.dacstest.dss.ca:18123/cgi-bin/test-cgi</a>
</pre><p>
Look for the <code class="varname">SERVER_SOFTWARE</code> variable in its output
and ensure that its value shows the correct versions of
<span class="command"><strong>Apache</strong></span>,
<code class="function">mod_ssl</code>, and <span class="command"><strong>OpenSSL</strong></span>;
if you find something
unexpected, you probably didn't configure and/or install
<span class="command"><strong>Apache</strong></span> or <span class="command"><strong>OpenSSL</strong></span> correctly.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title">Note</h3><p>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:
</p><pre class="screen"><span class="errortext">Forbidden You don't have permission to access /cgi-bin/test-cgi on this server.</span></pre><p>
Make sure to follow the <span class="command"><strong>Apache</strong></span> instructions for enabling
script execution (e.g., using <code class="literal">Options ExecCGI</code>),
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.
</p></div><p>
</p></li><li class="listitem"><p>You have confirmed that <span class="command"><strong>Apache</strong></span> is properly
installed, so stop the web server:
</p><pre class="programlisting">
% /usr/local/apache-dacs/bin/apachectl stop
</pre><p>
</p></li></ol></div></div><div class="refsect2"><a name="Step%203"></a><h3><span class="refsect2_spec"><a name="step_3"></a>Step 3: Build and install DACS</span></h3><p>Now it is time to build and install the <span class="command"><strong>DACS</strong></span>
utilities and web services.
Make your working directory the
<span class="directory">src</span> subdirectory
of the <span class="command"><strong>DACS</strong></span> distribution.
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Build and install <span class="command"><strong>DACS</strong></span>
web services and utilities.
You must use <span class="command"><strong>gmake</strong></span>, the GNU Make utility.
Adjust the paths specified for <span class="command"><strong>Expat</strong></span>,
<span class="command"><strong>Apache</strong></span>, and <span class="command"><strong>OpenSSL</strong></span> as necessary.
The <span class="command"><strong>DACS</strong></span> 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 <span class="username">root</span>.
</p><pre class="programlisting">
% ./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
</pre><p>
If all goes well:
</p><pre class="programlisting">
% gmake install
</pre><p>
You can ignore any warnings about ACLs.
</p><p>You will be prompted for the user id and group id
to be used for <span class="command"><strong>DACS</strong></span> files and directories.
The group id you give should match the value you used for
<span class="command"><strong>Apache's</strong></span> <span class="property">Group</span> directive
(that is, the value of <code class="varname">$dacsgroup</code>).
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 <span class="username">root</span>.
You will need to do <strong class="userinput"><code>gmake install</code></strong> as
<span class="username">root</span>
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:
</p><pre class="programlisting">
% conftools/setaccess-sh reset
</pre><p>
and try <strong class="userinput"><code>gmake install</code></strong> again.
</p></li></ol></div></div><div class="refsect2"><a name="Step%204"></a><h3><span class="refsect2_spec"><a name="step_4"></a>Step 4: DACS-enable Apache</span></h3><p>We'll continue by installing the
<a class="ulink" href="http://dacs.dss.ca/man/mod_auth_dacs.html" target="_top"><code class="function">mod_auth_dacs</code></a>
module for <span class="command"><strong>Apache</strong></span>.
Make your working directory the
<span class="directory">apache</span> subdirectory
of the <span class="command"><strong>DACS</strong></span> distribution.
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Compile and install the <code class="function">mod_auth_dacs</code>
module.
As earlier, you will need to do <strong class="userinput"><code>gmake install</code></strong> as
<span class="username">root</span>
if your account has insufficient privileges to
set the user and group ids that you specify.
</p><pre class="programlisting">
% gmake tag
% gmake install
</pre><p>
If this succeeds, your <span class="command"><strong>Apache</strong></span>
<a class="ulink" href="file:///usr/local/apache-dacs/conf/httpd.conf" target="_top"><code class="filename">httpd.conf</code></a>
file should now contain the following directive:
</p><pre class="programlisting">
LoadModule auth_dacs_module modules/mod_auth_dacs.so
</pre><p>
Please check that this is so.
If you cannot find that directive, add it manually near the part of
<code class="filename">httpd.conf</code> that talks about the
<a class="ulink" href="http://httpd.apache.org/docs-2.2/mod/mod_so.html#loadmodule" target="_top"><span class="property">LoadModule</span></a> directive.
</p></li><li class="listitem"><p>Start <span class="command"><strong>Apache</strong></span> again
(as <span class="username">root</span>):</p><p>
</p><pre class="programlisting">
# /usr/local/apache-dacs/bin/apachectl start
</pre><p>
and take another look at the <code class="varname">SERVER_SOFTWARE</code> variable:
</p><pre class="screen">
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/cgi-bin/test-cgi" target="_top">http://dodgers.dacstest.dss.ca:18123/cgi-bin/test-cgi</a>
</pre><p>
</p><p>The <code class="varname">SERVER_SOFTWARE</code> variable ought to look the same
as before, except it should now also mention
<code class="function">mod_auth_dacs</code>.
</p><p>Congratulations - you are now running a <span class="command"><strong>DACS</strong></span>-enabled
web server!
<span class="command"><strong>DACS</strong></span> is not configured to do anything at the moment,
mind you, but your web server is now capable of
<span class="command"><strong>DACS</strong></span>-wrapping web services.
You should be able to view the <span class="command"><strong>DACS</strong></span> manual pages
served from the web server you just installed:
</p><pre class="screen">
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/man" target="_top">http://dodgers.dacstest.dss.ca:18123/man</a>
</pre><p>
</p></li></ol></div></div><div class="refsect2"><a name="Step%205"></a><h3><span class="refsect2_spec"><a name="step_5"></a>Step 5: Do basic DACS configuration</span></h3><p>Although your <span class="command"><strong>Apache</strong></span> is now
<span class="command"><strong>DACS</strong></span>-enabled,
a little more configuration of both <span class="command"><strong>DACS</strong></span> and
<span class="command"><strong>Apache</strong></span>
are necessary before you can do anything interesting.
We'll continue by working with the <span class="command"><strong>DACS</strong></span> configuration
(see
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/man/dacs.conf.5.html" target="_top">dacs.conf(5)</a>).
</p><p>We begin this step by defining a new <span class="command"><strong>DACS</strong></span> federation
that consists of one jurisdiction.
We will call the new federation <code class="literal">DACSTEST</code> and associate it
with the domain name
<span class="domainname">dacstest.dss.ca</span>.
We will call our jurisdiction <code class="literal">LA</code>.
Incidentally, the names that we are using in this tutorial for our
federation and jurisdiction
("<code class="literal">DACSTEST</code>", "<code class="literal">LA</code>", and
"<span class="domainname">dacstest.dss.ca</span>")
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
(<span class="domainname">dodgers.dacstest.dss.ca</span>)
is only special in that it is a subdomain of
<span class="domainname">dacstest.dss.ca</span>; this must
be the case for all jurisdictions in our example federation.
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security1"></a>Security</h3><p>All of the files and directories that we create in this and
future steps must be readable by <span class="command"><strong>DACS</strong></span> web services.
This means that they must have their group ownership set to
<code class="varname">$dacsgroup</code> and have group read and write permissions,
as discussed earlier.
</p></div><p><a name="var-defs"></a>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
<span class="directory">/usr/local/dacs/federations</span> will be
referred to as <code class="literal">$feds</code> and the pathname
<code class="literal">$feds/dacstest.dss.ca/LA</code> will be
<code class="literal">$la</code>.
You may find it useful at this time to define the following variables in
your shell using the particular syntax it prefers
(we use <span class="command"><strong>tcsh</strong></span>):
</p><pre class="programlisting">
% set dacs=/usr/local/dacs
% set bin=$dacs/bin
% set feds=$dacs/federations
% set la=$feds/dacstest.dss.ca/LA
</pre><p>
If you are using a compatible shell, such as <span class="command"><strong>csh</strong></span>,
you will then be able to copy and paste command lines and other
text that follows in the tutorial.
</p><div class="tip" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="tip22"></a>Tip</h3><p>At this point you can
use the
<a class="ulink" href="dacsinit.1.html" target="_top">dacsinit(1)</a> program,
found in the distribution's
<span class="directory">src</span> directory,
to perform the operations in this step for you.
By default,
the program uses the default paths that were established when
<span class="command"><strong>DACS</strong></span> was built and the example paths used in this step.
When prompted, simply use the <span class="command"><strong>dacsinit</strong></span> default values
(just hit <span class="keycap"><strong>Return</strong></span>/<span class="keycap"><strong>Enter</strong></span>),
which should result in the same configuration as you
would obtain by manually following the directions in this step.
</p><p>You can also use <span class="command"><strong>dacsinit</strong></span> 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
<a class="ulink" href="dacs.install.7.html#initial_config" target="_top">Initial Configuration</a>.
</p></div><p>Although you can get away with having a single
<span class="command"><strong>DACS</strong></span> configuration file on a host, we recommend
a hierarchical organization.
The file <code class="filename">site.conf</code>, 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 <code class="filename">dacs.conf</code> can be used
on a per-jurisdiction, per-federation, or per-host basis; that is, each
jurisdiction on a host can have its own <code class="filename">dacs.conf</code>,
or all (or some) of the jurisdictions on a host can share a
<code class="filename">dacs.conf</code>, or everything can just be lumped into one
<code class="filename">dacs.conf</code>.
It's entirely up to you.
</p><p>When <span class="command"><strong>configure</strong></span> is run to build
<span class="command"><strong>DACS</strong></span>,
you can specify default locations for various configuration files,
including <code class="filename">site.conf</code> and <code class="filename">dacs.conf</code>.
We did not change the defaults when we built <span class="command"><strong>DACS</strong></span> above,
so our examples will use the default paths.
</p><div class="tip" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="tip1"></a>Tip</h3><p>We recommend that
you always use the
<code class="filename">site.conf-std</code> that comes with your <span class="command"><strong>DACS</strong></span>
distribution as your <code class="filename">site.conf</code> file and that you do not
make any modifications to it, instead putting customizations in your
<code class="filename">dacs.conf</code> file.
This will make upgrades easier and less error-prone. 
</p></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Proceed by installing the default site configuration file
as <code class="filename">$feds/site.conf</code> (recall that we defined the
shell variables <a class="ulink" href="#var-defs" target="_top">earlier</a>, and that you may have
to be <span class="username">root</span> to be able to
install correctly):
</p><pre class="programlisting">
% install -c -g $dacsgroup -m 0640 $feds/site.conf-std $feds/site.conf
</pre><p>

</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note5"></a>Note</h3><p>If the
<span class="command"><strong>install</strong></span> command is unavailable
on your system, you can use <code class="filename">src/conftools/install-sh</code>
relative to your <span class="command"><strong>DACS</strong></span> distribution directory.
Or just use <span class="command"><strong>cp</strong></span> (or <span class="command"><strong>mkdir</strong></span>),
<span class="command"><strong>chgrp</strong></span>, and <span class="command"><strong>chmod</strong></span>.
</p></div><p>

</p></li><li class="listitem"><p>Since we are not using SSL in this tutorial,
edit <code class="filename">$feds/site.conf</code>
and change the value of the
<a class="ulink" href="dacs.conf.5.html#SECURE_MODE" target="_top"><span class="property">SECURE_MODE</span></a>
directive to "<code class="literal">off</code>".
For production use, the directive's value should always
be "<code class="literal">on</code>":
</p><pre class="programlisting">
SECURE_MODE "off"
</pre><p>

</p></li><li class="listitem"><p>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.
</p><pre class="programlisting">
% install -c -g $dacsgroup -m 0660 /dev/null $feds/dacs.conf
</pre><p>
</p></li><li class="listitem"><p>We will create a directory where most of the files
associated with our new federation will live:
</p><pre class="programlisting">
% install -d -g $dacsgroup -m 0770 $feds/dacstest.dss.ca
</pre><p>
</p></li><li class="listitem"><p>And a subdirectory within it where most of the files
associated with our new jurisdiction will live:
</p><pre class="programlisting">
% install -d -g $dacsgroup -m 0770 $la
</pre><p>
</p></li><li class="listitem"><p>Create a directory where we will put access control rules
(also called <em class="firstterm">ACLs</em>,
<em class="firstterm">access control lists</em>, or simply
<em class="firstterm">rules</em>)
for our jurisdiction, and we also need an empty revocation file:
</p><pre class="programlisting">
% install -d -g $dacsgroup -m 0770 $la/acls
% install -c -g $dacsgroup -m 0660 /dev/null $la/acls/revocations
</pre><p>
</p></li><li class="listitem"><p>Create directories where we will put group definitions
for our jurisdiction and define the membership of our federation:
</p><pre class="programlisting">
% 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
</pre><p>
Paste the following text into the
<code class="filename">$la/groups/DACS/jurisdictions.grp</code> file:
</p><pre class="programlisting">
&lt;groups xmlns="http://dss.ca/dacs/v1.4"&gt;
 &lt;group_definition jurisdiction="LA" name="jurisdictions" 
     mod_date="Tue, 14-Jun-2005 16:06:00 GMT" type="public"&gt;
   &lt;group_member jurisdiction="LA" name="LA Jurisdiction" type="meta" 
     alt_name="Test Jurisdiction for the LA Dodgers" 
     dacs_url="http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs"
     authenticates="yes" prompts="no"/&gt;
 &lt;/group_definition&gt;
&lt;/groups&gt;
</pre><p>
(Remember to change <span class="port">18123</span> if you are
using a different port.)
The purpose of <code class="filename">jurisdictions.grp</code> is to provide
<span class="command"><strong>DACS</strong></span> with information about the jurisdictions in this
federation.
All jurisdictions in a federation should use identical
<code class="filename">jurisdictions.grp</code>
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,
<code class="filename">jurisdictions.grp</code> would ordinarily be updated everywhere
in your federation.
For instance, if you were to add a jurisdiction to your federation,
you should add another <code class="literal">group_member</code> element to the
<code class="literal">group_definition</code> that describes the new jurisdiction,
and then copy the updated <code class="filename">jurisdictions.grp</code> file
to each jurisdiction.
Please see <a class="ulink" href="dacs.groups.5.html#dacs_metadata" target="_top">dacs.groups(5)</a>
for additional information.
</p></li><li class="listitem"><p>We need some basic configuration directives
for the jurisdiction <code class="literal">LA</code>.
Paste the following text into the <code class="filename">$feds/dacs.conf</code> file:
</p><pre class="programlisting">
&lt;Configuration xmlns="http://dss.ca/dacs/v1.4"&gt;

 &lt;Default&gt;
   FEDERATION_DOMAIN "dacstest.dss.ca"
   FEDERATION_NAME "DACSTEST"
   LOG_LEVEL "info"
 &lt;/Default&gt;

 &lt;Jurisdiction uri="dodgers.dacstest.dss.ca"&gt;
   JURISDICTION_NAME "LA"
 &lt;/Jurisdiction&gt;

&lt;/Configuration&gt;
</pre><p>
</p></li><li class="listitem"><p>And let's make this the default configuration
file for <span class="command"><strong>DACS</strong></span>
jurisdictions at this site:
</p><pre class="programlisting">
% rm -f $la/dacs.conf
% ln -s $feds/dacs.conf $la/dacs.conf
</pre><p>
</p></li><li class="listitem"><p>Now, let's ask <span class="command"><strong>DACS</strong></span> to display
its configuration by running the
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/man/dacsconf.1.html" target="_top"><span class="command"><strong>dacsconf(1)</strong></span></a> utility:
</p><pre class="programlisting">
% $bin/dacsconf -uj LA -q
</pre><p>
This configuration is the result of merging the contents of
<code class="filename">$la/dacs.conf</code> (which points to
<code class="filename">$feds/dacs.conf</code>) and
<code class="filename">$feds/site.conf</code>, with directives in the former file
overriding directives in the latter.
</p></li><li class="listitem"><p>We must create encryption keys for this federation
using the
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/man/dacskey.1.html" target="_top"><span class="command"><strong>dacskey(1)</strong></span></a>
utility:
</p><pre class="programlisting">
% 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
</pre><p>
We could not do this until after the jurisdiction had been configured
because <span class="command"><strong>dacskey</strong></span> needs to look
at <code class="filename">dacs.conf</code>.

</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security2"></a>Security</h3><p><span class="emphasis"><em>The federation key file must be kept secret</em></span>.
Any person or process that can read the federation key file can
create <span class="command"><strong>DACS</strong></span> identities.
It should be readable <span class="emphasis"><em>only</em></span> by its owner
and <span class="command"><strong>DACS</strong></span> and <span class="emphasis"><em>not</em></span>
readable by anyone else.
</p></div><p>
</p></li><li class="listitem"><p>Similarly, we should create encryption keys for our
jurisdiction:
</p><pre class="programlisting">
% install -c -g $dacsgroup -m 0640 /dev/null $la/jurisdiction_keyfile
% $bin/dacskey -uj LA -q $la/jurisdiction_keyfile
% ls -l $la/jurisdiction_keyfile
</pre><p>
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.
</p></li><li class="listitem"><p>Make sure that all of the files and directories
starting with <span class="directory">/usr/local/dacs</span>
have appropriate permissions, as discussed earlier.
</p></li></ol></div><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note6"></a>Note</h3><p>If you
modify <code class="filename">httpd.conf</code> you must
restart <span class="command"><strong>Apache</strong></span> for the changes to take effect.
If you modify <code class="filename">dacs.conf</code>,
<code class="filename">site.conf</code>, or any other
<span class="command"><strong>DACS</strong></span> configuration file, the changes take effect immediately
and do not require restarting <span class="command"><strong>Apache</strong></span>.
</p></div></div><div class="refsect2"><a name="Step%206"></a><h3><span class="refsect2_spec"><a name="step_6"></a>Step 6: Do basic Apache configuration for DACS</span></h3><p>Your <span class="command"><strong>Apache</strong></span> is now <span class="command"><strong>DACS</strong></span>-enabled and
we've configured <span class="command"><strong>DACS</strong></span>.
Before we can do anything interesting we must make some changes to
the <span class="command"><strong>Apache</strong></span> configuration.
We will begin by <span class="command"><strong>DACS</strong></span>-wrapping <span class="command"><strong>DACS</strong></span>
web services, which is required.
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Edit
<code class="filename">/usr/local/apache-dacs/conf/httpd.conf</code> and
locate the
<a class="ulink" href="http://httpd.apache.org/docs-2.2/mod/core.html#virtualhost" target="_top"><span class="property">VirtualHost</span></a>
section that you added earlier.
Inside that <span class="property">VirtualHost</span> section and near its end,
add the following text (remember to adjust paths as necessary):
</p><pre class="programlisting">
AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs "-t -v"
SetDACSAuthMethod dacs-acs external
SetDACSAuthConf dacs-acs "/usr/local/dacs/federations/dacs.conf"

&lt;Location /cgi-bin/dacs&gt;
  Require valid-user
# Note: For Apache 2.4, instead use:
# Require dacs-authz
  Options ExecCGI
  AuthType DACS
  AuthDACS dacs-acs
&lt;/Location&gt;
</pre><p>
These directives configure the virtual host to <span class="command"><strong>DACS</strong></span>-wrap
the contents of all URLs that fall under the
<span class="path">/cgi-bin/dacs</span> namespace.
The first three directives tell
<code class="function">mod_auth_dacs</code>
where to find the external
<span class="command"><strong>DACS</strong></span> access control program
(<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/man/dacs_acs.8.html" target="_top"><span class="command"><strong>dacs_acs(8)</strong></span></a>)
and the <span class="command"><strong>DACS</strong></span> configuration file.
</p></li><li class="listitem"><p>Start (or restart) <span class="command"><strong>Apache</strong></span> so that it
uses its new configuration
(as <span class="username">root</span>):
</p><pre class="programlisting">
# /usr/local/apache-dacs/bin/apachectl restart
</pre><p>
<span class="command"><strong>DACS</strong></span> should now be enforcing access control on the
<span class="path">/cgi-bin/dacs</span> part of the
server's URL space.
</p></li><li class="listitem"><p>Check that you can still access <span class="command"><strong>test-cgi</strong></span>
(which you have not <span class="command"><strong>DACS</strong></span>-wrapped):
</p><pre class="screen">
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/cgi-bin/test-cgi" target="_top">http://dodgers.dacstest.dss.ca:18123/cgi-bin/test-cgi</a>
</pre><p>
</p></li><li class="listitem"><p>Now, let's see what happens when we try to access
<span class="command"><strong>dacs_prenv</strong></span>:
</p><pre class="screen">
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_prenv?FORMAT=html" target="_top">http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_prenv</a>
</pre><p>
Apache should produce a "<code class="literal">403 Forbidden</code>" error,
which causes <span class="command"><strong>DACS</strong></span> to display an "Access Denied by DACS"
page (actually, it is the contents of the file
<code class="filename">/usr/local/dacs/www/handlers/acs_failed.html</code>,
which is set by the
<a class="ulink" href="dacs.conf.5.html#ACS_ERROR_HANDLER" target="_top"><span class="property">ACS_ERROR_HANDLER</span></a>
directive in <code class="filename">site.conf</code>).
This happens because the default rules do not grant access to
<span class="command"><strong>dacs_prenv</strong></span>, so all access will be denied.
</p></li><li class="listitem"><p>To finish up this step, let's add a rule that will
grant everyone access to <span class="command"><strong>dacs_prenv</strong></span>.
Create <code class="filename">$la/acls/acl-tutorial.0</code> with
appropriate permissions:
</p><pre class="programlisting">
% install -c -g $dacsgroup -m 0660 /dev/null $la/acls/acl-tutorial.0
</pre><p>
and then paste the following text into it:
</p><pre class="programlisting">
&lt;acl_rule status="enabled"&gt;
  &lt;services&gt;
    &lt;service url_expr='"${Conf::dacs_cgi_bin_prefix}/dacs_prenv${Conf::dacs_cgi_bin_suffix}"'/&gt;
    &lt;service url_expr='"${Conf::dacs_cgi_bin_prefix}/dacs_version${Conf::dacs_cgi_bin_suffix}"'/&gt;
  &lt;/services&gt;

  &lt;rule order="allow,deny"&gt;
    &lt;allow&gt;
      user("any")
    &lt;/allow&gt;
  &lt;/rule&gt;
&lt;/acl_rule&gt;
</pre><p>
</p><p>Whenever you add or change an access rule, you must rebuild the rule index
for the jurisdiction:
</p><pre class="programlisting">
% $bin/dacsacl -uj LA -q -build
% chgrp $dacsgroup $la/acls/INDEX
</pre><p>
It's currently only really necessary to run <span class="command"><strong>dacsacl</strong></span> if you
add a rule or modify any part of a rule's <code class="literal">services</code>
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.
</p><p>This time <span class="command"><strong>dacs_prenv</strong></span> should work because
our new rule grants access to everyone.
Try it:
</p><pre class="screen">
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_prenv?FORMAT=html" target="_top">http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_prenv</a>
</pre><p>
This output includes some new environment variables that are passed to all
<span class="command"><strong>DACS</strong></span>-wrapped programs.
These variables begin with "<code class="literal">DACS_</code>", such as
<code class="envar">DACS_VERSION</code> - see
<a class="ulink" href="dacs_acs.8.html#exported_envars" target="_top">dacs_acs(8)</a> for
additional information.
</p></li></ol></div></div><div class="refsect2"><a name="Step%207"></a><h3><span class="refsect2_spec"><a name="step_7"></a>Step 7: Test basic DACS services</span></h3><p>There's still not too much you can do at this point, but there
are a few <span class="command"><strong>DACS</strong></span> services that you can try.
If one of these requests fails,
take a look at the <span class="command"><strong>DACS</strong></span> log files in the
<span class="directory">/usr/local/dacs/logs</span> directory for clues.
The most likely cause is incorrect permissions on a file or directory,
or possibly you made an editing mistake.
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>The
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/man/dacs_version.8.html" target="_top">dacs_version(8)</a>
web service displays
various version information, naturally enough:
</p><pre class="screen">
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_version" target="_top">http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_version</a>
</pre><p>
</p></li><li class="listitem"><p>The <a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/man/dacs_list_jurisdictions.8.html" target="_top">dacs_list_jurisdictions(8)</a>
web service displays information about jurisdictions:
</p><pre class="screen">
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_list_jurisdictions" target="_top">http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_list_jurisdictions</a>
</pre><p>
You may recognize some of this material from the
<code class="filename">jurisdictions.grp</code> file.
</p></li><li class="listitem"><p>We saw the <span class="command"><strong>conf</strong></span> utility earlier.
We can get the same information from a web service:
</p><pre class="screen">
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_conf" target="_top">http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_conf</a>
</pre><p>
Ooops!  You should have been denied access to this web service.
If you examine the default ACL
(see <a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/man/dacs.acls.5.html" target="_top">dacs.acls(5)</a>)
for this web service, which can be found in
<code class="filename">/usr/local/dacs/acls/acl-conf.0</code>, you might suspect
that access to <span class="command"><strong>dacs_conf</strong></span>
will only be granted to identities that satisfy the expression
"<code class="literal">dacs_admin()</code>"
(see <a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/man/dacs.exprs.5.html" target="_top">dacs.exprs(5)</a>).
And since you have not signed on to obtain a <span class="command"><strong>DACS</strong></span> identity,
the ACL should deny access.
After we do a little more <span class="command"><strong>DACS</strong></span> configuration work
in the next step, we will give this another try.
</p></li></ol></div></div><div class="refsect2"><a name="Step%208"></a><h3><span class="refsect2_spec"><a name="step_8"></a>Step 8: Try DACS authentication</span></h3><p>It is possible to create accounts or identities specifically for
<span class="command"><strong>DACS</strong></span> users.
These identities are managed by the
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/man/dacspasswd.1.html" target="_top">dacspasswd(1)</a> utility
(there are user accounts managed by other <span class="command"><strong>DACS</strong></span>
commands, but we will not discuss them here).
Similar to <span class="command"><strong>Apache's</strong></span>
<a class="ulink" href="http://httpd.apache.org/docs-2.2/programs/htpasswd.html" target="_top">htpasswd</a> 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 <span class="command"><strong>DACS</strong></span> identity named
"<span class="username">root</span>" that has no relationship to
a Unix system's superuser - perhaps you are creating a
<span class="command"><strong>DACS</strong></span> account for actor
<a class="ulink" href="http://us.imdb.com/name/nm0740535/" target="_top">Stephen Root</a>.
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>We begin this step by creating an empty password file
for <span class="command"><strong>dacspasswd</strong></span> (to ensure correct permissions).
Then we create a
<span class="command"><strong>DACS</strong></span> account for username "<code class="literal">sandy</code>".
</p><pre class="programlisting">
% install -c -g $dacsgroup -m 0660 /dev/null $la/passwd
% $bin/dacspasswd -uj LA -q -a sandy
</pre><p>
You will be prompted for a password to assign to <code class="literal">sandy's</code>
account.
Choose any password you like as long as it is
at least six characters long.
You can change <code class="literal">sandy's</code> password
by running this command again.
</p></li><li class="listitem"><p>Next, we edit
<code class="filename">$la/dacs.conf</code> and add the following
text in the <code class="literal">Jurisdiction</code> section for
<code class="literal">dodgers.dacstest.dss.ca</code>:
</p><pre class="programlisting">
&lt;Auth id="passwd"&gt;
   URL \
"http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/local_passwd_authenticate"
   STYLE "pass"
   CONTROL "sufficient"
 &lt;/Auth&gt;
</pre><p>
This configuration enables authentication
(see <a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/man/dacs_authenticate.8.html" target="_top">dacs_authenticate(8)</a>)
for accounts managed by
the <span class="command"><strong>dacspasswd</strong></span> utility.
Check again that all files starting with
<span class="directory">/usr/local/dacs</span>
have appropriate permissions, as discussed earlier.
</p></li><li class="listitem"><p>We should now be able to authenticate ("login") as
<code class="literal">sandy</code> by providing the password you set up earlier.
If successful, your browser will be sent credentials (in an HTTP cookie)
for the identity <span class="command"><strong>DACS</strong></span> calls <code class="literal">LA:sandy</code>.
Note that the cookies <span class="command"><strong>DACS</strong></span> 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.
</p><p><span class="command"><strong>DACS</strong></span> comes with examples of simple HTML login
pages with which you can authenticate:
</p><pre class="screen">
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/examples/login.html" target="_top">http://dodgers.dacstest.dss.ca:18123/examples/login.html</a>
</pre><p>
Your browser must have JavaScript enabled to use this page.
Select the jurisdiction (<code class="literal">LA</code>),
enter the username (<code class="literal">sandy</code>) and password,
and then click "Login".
If all is well, you should see the "DACS Authentication Succeeded" page,
which is the contents of
<code class="filename">/usr/local/dacs/www/handlers/auth_ok.html</code>.
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.
</p></li><li class="listitem"><p>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
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_current_credentials" target="_top">dacs_current_credentials</a>)
or another to visit a page that will allow you to signout
(<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/man/dacs_signout.8.html" target="_top">dacs_signout(8)</a>) from all or some identities
(you can also
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_signout" target="_top">invoke dacs_signout directly</a> to signout from all identities).
If you signout, there will be a link that you can follow to login again.
</p></li><li class="listitem"><p>Now use <span class="command"><strong>dacspasswd</strong></span> to create another
account:
</p><pre class="programlisting">
% $bin/dacspasswd -uj LA -q -a don
</pre><p>
If you are curious, you can take a peek at the password file,
which we have configured to be <code class="filename">$la/passwd</code>.
</p><p>You can now authenticate as <code class="literal">sandy</code> or
<code class="literal">don</code>.
You can have more than one identity active at the same time
(i.e., you could be signed on as both <code class="literal">sandy</code>
<span class="emphasis"><em>and</em></span> <code class="literal">don</code>), but this is
disallowed by default;
see
<a class="ulink" href="dacs.conf.5.html#ACS_CREDENTIALS_LIMIT" target="_top"><span class="property">ACS_CREDENTIALS_LIMIT</span></a> and
<a class="ulink" href="dacs.conf.5.html#AUTH_SINGLE_COOKIE" target="_top"><span class="property">AUTH_SINGLE_COOKIE</span></a>.
</p></li><li class="listitem"><p>Now that you're able to authenticate, let's have
another try at running <span class="command"><strong>dacs_conf</strong></span> (recall you were not
granted access to it earlier).
We must first make one of the identities that you have created a
<span class="command"><strong>DACS</strong></span> administrator identity.
Edit <code class="filename">$la/dacs.conf</code> and add the following
text in the <code class="literal">Jurisdiction</code> section for
<span class="domainname">dodgers.dacstest.dss.ca</span>
(but <span class="emphasis"><em>not</em></span> within the <code class="literal">Auth</code> section):
</p><pre class="programlisting">
ADMIN_IDENTITY "LA:sandy"
</pre><p>
As you might assume, this confers special privileges to
<code class="literal">LA:sandy</code>.
</p><p>Authenticate as <code class="literal">sandy</code> using the
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/examples/login.html" target="_top">login
page</a>
and then try this link again
(it should work this time):
</p><pre class="screen">
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_conf" target="_top">http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_conf</a>
</pre><p>
</p><p>If you
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/examples/signout.html" target="_top">signout</a> as <code class="literal">sandy</code>, then
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/examples/login.html" target="_top">authenticate</a>
as <code class="literal">don</code>, and try
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_conf" target="_top">http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_conf</a>
again, you should be denied access.
</p></li><li class="listitem"><p>In an earlier step, you created an ACL
(<code class="filename">$la/acls/acl-tutorial.0</code>) that grants access to
<span class="command"><strong>dacs_prenv</strong></span> to
any user, whether authenticated or not.
Edit that rule and replace:
</p><pre class="programlisting">
user("any")
</pre><p>
with:
</p><pre class="programlisting">
user("auth")
</pre><p>
Try invoking
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_prenv" target="_top">dacs_prenv</a>
when you are not authenticated - you should be denied access.
Now authenticate and try
<a class="ulink" href="http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_prenv" target="_top">dacs_prenv</a>
again - it should work.
Edit the rule again and replace:
</p><pre class="programlisting">
user("auth")
</pre><p>
with:
</p><pre class="programlisting">
user("LA:don")
</pre><p>
Now you should only be granted access if you've authenticated as the
<span class="command"><strong>DACS</strong></span> username <code class="literal">LA:don</code>.
</p></li></ol></div></div><div class="refsect2"><a name="Step%209"></a><h3><span class="refsect2_spec"><a name="step_9"></a>Step 9: DACS-wrapping a web service</span></h3><p>To use <span class="command"><strong>DACS</strong></span> to control access to a resource,
there are just a few things you need to do:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Make the URL space in which the resource lies
within the scope of a
<a class="ulink" href="http://httpd.apache.org/docs-2.2/mod/core.html#location" target="_top"><span class="property">Location</span></a>
directive for the
<span class="property">VirtualHost</span> that corresponds to the
<span class="command"><strong>DACS</strong></span> jurisdiction responsible for the resource.
</p></li><li class="listitem"><p>Make an appropriate <span class="command"><strong>DACS</strong></span>
access control rule for the jurisdiction responsible for the
URL space in which the resource lies.
</p></li></ul></div><p>
Basically, you have to configure <span class="command"><strong>Apache</strong></span> to
allow <span class="command"><strong>DACS</strong></span> to perform access control for the resource,
and you have to configure <span class="command"><strong>DACS</strong></span> 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 <span class="path">/images</span> in the URL space,
related applications are collected somewhere
under <span class="path">/cgi-bin</span>, and so on) and because
ACLs can be written with wildcard patterns that will match everything
"under" a given URL space prefix.
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security3"></a>Security</h3><p>It is important to verify that all resources that you intend to be
<span class="command"><strong>DACS</strong></span>-wrapped really are access controlled and that
<span class="command"><strong>DACS</strong></span> cannot be bypassed
(e.g., by using different URLs for the same resource).
For instance, despite many improvements,
getting <span class="command"><strong>Apache's</strong></span>
<a class="ulink" href="http://httpd.apache.org/docs/2.2/vhosts/" target="_top">Virtual Hosts</a>
configured exactly as you require can be challenging - make sure that
security cannot be bypassed through selection of a particular hostname or
port number.
</p><p>Also, note that <span class="command"><strong>DACS</strong></span> 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 <span class="command"><strong>DACS</strong></span>-wrapped.
</p></div></div><div class="refsect2"><a name="Step%2010"></a><h3><span class="refsect2_spec"><a name="step_10"></a>Step 10: What's next?</span></h3><p>Having successfully completed all of the previous steps,
you should have a feel for some of the things that
you can do with <span class="command"><strong>DACS</strong></span>.
Of course, there's much more to <span class="command"><strong>DACS</strong></span>
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):
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Add a <span class="command"><strong>DACS</strong></span>-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
<code class="literal">LA</code> are files in the
<span class="directory">$la/acls</span> directory.
Review
<a class="ulink" href="dacs.acls.5.html" target="_top">dacs.acls(5)</a>
before beginning.
</p></li><li class="listitem"><p>Assign a few roles to <span class="command"><strong>DACS</strong></span> user
<code class="literal">sandy</code> 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
"<code class="literal">students</code>", some to "<code class="literal">staff</code>", and some
to "<code class="literal">faculty</code>", and then write rules that reference
those roles rather than individual <span class="command"><strong>DACS</strong></span> 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.
</p><p>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 <span class="command"><strong>DACS</strong></span> will look for roles in the file
<code class="filename">$la/roles</code>.
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:
</p><pre class="programlisting">
sandy:pitchers,retired-players
don:pitchers,retired-players
eric:pitchers,active-players
cesar:infielders,active-players
</pre><p>
The other thing you'll need is some <span class="command"><strong>DACS</strong></span>
configuration to enable roles.
Add the following to the <code class="literal">Jurisdiction</code>
section of <code class="filename">dacs.conf</code>:
</p><pre class="programlisting">
&lt;Roles id="roles"&gt;
  URL "http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/local_roles"
&lt;/Roles&gt;
</pre><p>
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
"<code class="literal">pitchers</code>" by using the predicate
(see
<a class="ulink" href="dacs.exprs.5.html" target="_top">dacs.exprs(5)</a>):
</p><pre class="programlisting">
user("%LA:pitchers")
</pre><p>
Or you can create a rule that will grant access only if the user
has the roles "<code class="literal">active-players</code>" <span class="emphasis"><em>and</em></span>
"<code class="literal">pitchers</code>"; use the predicate:
</p><pre class="programlisting">
user("%LA:pitchers") and user("%LA:active-players")
</pre><p>
</p></li><li class="listitem"><p>If you create a <span class="command"><strong>DACS</strong></span> account for a
username that
corresponds to a user on your system, you can configure
<span class="command"><strong>DACS</strong></span> to assign roles to that user based on the
Unix groups that she belongs to.
This is very easy to do: instead of using <span class="command"><strong>local_roles</strong></span>
as in the example above, use <span class="command"><strong>local_unix_roles</strong></span> instead.
If you create a <span class="command"><strong>DACS</strong></span> account for
<code class="literal">alice</code>, for example, and the account
"<code class="literal">alice</code>" has group membership on your system
(see group(5)),
then <code class="literal">alice</code> would authenticate using her
<span class="command"><strong>DACS</strong></span> password and be assigned roles from her
Unix group membership.
</p><p>Instead of using a <span class="command"><strong>DACS</strong></span> account to
authenticate <code class="literal">alice</code>, you can easily
configure <span class="command"><strong>DACS</strong></span>
to use <code class="literal">alice's</code> Unix password.
The <span class="command"><strong>DACS</strong></span> module <span class="command"><strong>local_unix_authenticate</strong></span>,
which must be installed set-uid
<span class="username">root</span> so that it can
access passwords, provides this functionality.
</p></li><li class="listitem"><p>Add a <span class="command"><strong>DACS</strong></span> jurisdiction
named <code class="literal">NY</code>
(<span class="domainname">yankees.dacstest.dss.ca</span>)
on the same host where you configured
<span class="domainname">dodgers.dacstest.dss.ca</span>.
You do not have to configure authentication at the new jurisdiction.
Notice that you can authenticate at
<span class="domainname">dodgers.dacstest.dss.ca</span>
and then access resources at
<span class="domainname">yankees.dacstest.dss.ca</span>.
This is "single sign-on".
</p></li><li class="listitem"><p>Run <span class="command"><strong>DACS</strong></span> on an additional host.
The procedure is basically the same as what you already did in this tutorial.
Name the jurisdiction
<code class="literal">BOSTON</code> and assign it the domain name
<span class="domainname">redsox.dacstest.dss.ca</span>.
You won't be able to use the IP address
<span class="ipaddress">127.0.0.1</span> for this; you'll
have to alias the domain names to the IP addresses of real interfaces
and make the same changes to <code class="filename">/etc/hosts</code> on both hosts.
You'll also have to use the identical <code class="filename">federation_keyfile</code>
on both hosts (simply copy the file you've already made).
</p></li><li class="listitem"><p>Configure a different (or additional) authentication
method for your jurisdiction.
See <a class="ulink" href="dacs_authenticate.8.html" target="_top">dacs_authenticate(8)</a>.
For the <code class="literal">password</code> style of authentication,
you might try the NTLM authentication method.
For a bit more of a challenge, see if you can make the
<code class="literal">expr</code> or <code class="literal">cert</code>
style of authentication work.
</p></li></ul></div></div><div class="refsect2"><a name="Step%2011"></a><h3><span class="refsect2_spec"><a name="step_11"></a>Step 11: Clean up</span></h3><p>If you are done, you may want to do some clean up now.
First, stop <span class="command"><strong>Apache</strong></span>:
</p><pre class="programlisting">
# /usr/local/apache-dacs/bin/apachectl stop
</pre><p>
Next, delete
<span class="domainname">dodgers.dacstest.dss.ca</span> and
any other domain names you created for this exercise
from <code class="filename">/etc/hosts</code>.
Delete any groups you created.
Remove <span class="directory">/usr/local/apache-dacs</span>,
<span class="directory">/usr/local/dacs</span>,
and everything underneath them.
</p></div><div class="refsect2"><a name="idm916"></a><h3>Troubleshooting</h3><p>The first thing to do if you encounter a problem is to
check that you've got the latest version of <span class="command"><strong>DACS</strong></span>; a
newer version might fix your problem.
Also, visit the
<a class="ulink" href="http://dacs.dss.ca/download.html" target="_top">Post-Release
Notes</a> area for your release
in case a newer edition of this document is available or a
bug fix has been posted.
</p><p>By default, the <span class="command"><strong>DACS</strong></span> log files are put in the
<span class="directory">/usr/local/dacs/logs</span> 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 <span class="command"><strong>DACS</strong></span>
<a class="ulink" href="dacs.conf.5.html#LOG_LEVEL" target="_top"><span class="property">LOG_LEVEL</span></a>
and
<a class="ulink" href="dacs.conf.5.html#LOG_FILTER" target="_top"><span class="property">LOG_FILTER</span></a>
directives in effect, log files can quickly become big.
It is safe to delete them or truncate them at any time.
</p><p>In the event of problems, you should also take a look at the <span class="command"><strong>Apache</strong></span> logs
(in <span class="directory">/usr/local/apache-dacs/logs</span>).
</p><p>There are five main sources of problems:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Typos (you got the spelling or punctuation incorrect,
or didn't paste text correctly),
</p></li><li class="listitem"><p>File permissions are incorrect
(<span class="command"><strong>DACS</strong></span> cannot read or write its files or directories),
</p></li><li class="listitem"><p>You didn't follow the instructions correctly
(you skipped something or misunderstood something),
</p></li><li class="listitem"><p>You ran into unexpected platform dependencies, or
</p></li><li class="listitem"><p>We goofed.
</p></li></ol></div><p>

If you're sure the problem is either of the last two types,
please <a class="ulink" href="http://www.dss.ca/contactus.html" target="_top">contact us</a>.
and tell us what happened.
Be sure to mention which steps succeeded and which one failed.
</p></div></div><div class="refsect1"><a name="idm946"></a><h2>SEE ALSO</h2><p>
<a class="ulink" href="dacs.1.html" target="_top">dacs(1)</a>,
<a class="ulink" href="dacsinit.1.html" target="_top">dacsinit(1)</a>,
<a class="ulink" href="dacs.readme.7.html" target="_top">dacs.readme(7)</a>,
<a class="ulink" href="dacs.install.7.html" target="_top">dacs.install(7)</a>
</p></div><div class="refsect1"><a name="idm953"></a><h2>AUTHOR</h2><p>Distributed Systems Software
(<a class="ulink" href="http://www.dss.ca" target="_top">www.dss.ca</a>)
</p></div><div class="refsect1"><a name="idm957"></a><h2>COPYING</h2><p>Copyright  2003-2015 Distributed Systems Software.
See the
<a class="ulink" href="../misc/LICENSE" target="_top"><code class="filename">LICENSE</code></a>
file that accompanies the distribution
for licensing information.
</p></div>
<!-- Generated from   $Id: dacs.quick.7.xml 2816 2015-07-22 21:52:26Z brachman $ -->
<table width="100%"><tr>
<td align="left">
<b>DACS Version 1.4.38a</b></td>
<td align="center">
<b> 2-Jun-2017</b></td>
<td align="right">
<b>DACS.QUICK(7)</b></td>
</tr></table>
<hr><p>
<!-- Begin font size selector -->
<table width="100%"><tr><td align="left">
<span class="set_font"><a href="index.html" title="Table of Contents">Table of Contents</a></span></td>
<td align="center"><span class="logo"><a href="http://www.dss.ca"><img src="/css/images/dss-long-14y.png" title="Distributed Systems Software, Inc."></a></span></td>
<td width="5%" align="right">
<div class="fontsize_label" title="Font size selector">Font:</div>
</td>
<td width="10%" align="left">
<!-- NB: must set both left margin and padding to work in all browsers-->
<!-- The onFocus code eliminates annoying post-click decoration -->
<ul id="fontsizecontainer" class="size02">
 <li><a href="javascript:setFont('0');" onFocus="if(this.blur)this.blur()" title="Smallest text size [0]"><span>Z</span></a></li>
 <li><a href="javascript:setFont('1');" onFocus="if(this.blur)this.blur()" title="Medium text size [1]"><span>Z</span></a></li>
 <li><a href="JavaScript:setFont('2');" onFocus="if(this.blur)this.blur()" title="Large text size [2]"><span>Z</span></a></li>
 <li><a href="JavaScript:setFont('3');" onFocus="if(this.blur)this.blur()" title="Largest text size [3]"><span>Z</span></a></li>
</ul>
</td>
<td width="3%" align="center">
<span class="set_font"><a href="javascript:setFont('-');" onFocus="if(this.blur)this.blur()" title="Decrease current font size">&#8722;&#8722;</a></span>
</td>
<td width="3%" align="center">
<span class="set_font"><a href="javascript:setFontConfig();" onFocus="if(this.blur)this.blur()" title="Remember current font size">Set</a></span>
</td>
<td width="3%" align="center">
<span class="set_font"><a href="javascript:setFont('+');" onFocus="if(this.blur)this.blur()" title="Increase current font size">++</a></span>
</td></tr></table>
<!-- End font size selector -->
<script language="javascript" type="text/javascript">
doFontConfig();</script>
</p><small><p><b>  $Id: dacs.quick.7.xml 2816 2015-07-22 21:52:26Z brachman $</b></p></small>
</div></body></html>
dacs-examples 1.4.38a-2 / usr / share / doc / dacs-examples / man / dacs.quick.7.html
