.\" Copyright (c) 2003-2012
.\" Distributed Systems Software. All rights reserved.
.\" See the file LICENSE for redistribution information.
.\" $Id: copyright-nr 2564 2012-03-02 00:17:08Z brachman $
'\" t
.\" Title: dacs.quick
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1
.\" Date: 02/19/2019
.\" Manual: DACS Miscellaneous Information Manual
.\" Source: DACS 1.4.40
.\" Language: English
.\"
.TH "DACS\&.QUICK" "7" "02/19/2019" "DACS 1.4.40" "DACS Miscellaneous Information"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
dacs.quick \- \fBDACS\fR Quick Start Tutorial
.SH "DESCRIPTION"
.PP
The purpose of
\fBDACS\fR
Quick Start is to explain, step\-by\-step, how to configure a very basic
\fBDACS\fR\-enabled web site from scratch so that you can try
\fBDACS\fR
with minimal effort\&. We hope that by performing the entire example configuration yourself, you will gain a better understanding of how
\fBDACS\fR
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
\fBDACS\fR
federation on one of your hosts\&. You will become familiar with some of the
\fBDACS\fR
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\&.
.PP
After successfully completing Quick Start, you should understand
\fBDACS\fR
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\&.
.PP
We do not provide much background or technical information about
\fBDACS\fR
here, or tell you how to set up a fully functional, production\-quality
\fBDACS\fR
system\&. You may find it worthwhile to review the
\m[blue]\fBFAQ\fR\m[]\&\s-2\u[1]\d\s+2
before beginning, but if you\*(Aqre itching to get started right away you may do so\&. For technical details, please refer to the
\m[blue]\fBmanual pages\fR\m[]\&\s-2\u[2]\d\s+2
and other documentation\&.
.PP
We assume that you\*(Aqve got some hands\-on experience configuring and using
\fBApache\fR, although Quick Start tells you exactly what to do\&.
\fITo avoid frustrating problems, we recommend that you resist the temptation to stray from the instructions except when indicated\fR\&. Experienced
\fBApache\fR
administrators may recognize the opportunity for some shortcuts, but since we\*(Aqre trying to keep things simple for a wide audience, we\*(Aqd rather not get sidetracked by mentioning them\&. Likewise, experienced
\fBDACS\fR
administrators may recognize alternative ways \- maybe even better ways \- of doing things\&. But our goal is to get beginners started quickly, so we\*(Aqll 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\&.
.PP
Perhaps it\*(Aqs just us, but despite working with
\fBApache\fR
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\&.
.PP
We\*(Aqll assume that you\*(Aqve already obtained the
\fIlatest version\fR
of
\fBDACS\fR, unpacked it, and at least skimmed through
\m[blue]\fBdacs\&.readme(7)\fR\m[]\&\s-2\u[3]\d\s+2
and
\m[blue]\fBdacs\&.install(7)\fR\m[]\&\s-2\u[4]\d\s+2\&. This document should have come from that version of
\fBDACS\fR\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
You will be installing and configuring a basic
\fBApache\fR
server (\fBhttpd\fR) 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\*(Aqs 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
\fBDACS\fR
on your own there could be unintended consequences\&. It is probably a good idea to stop
\fBApache\fR
when you are no longer using it\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.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\*(Aqs 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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
Make sure that this document came with the
\fBDACS\fR
release that you are working with\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
Depending on your environment, some tasks may need to be done as
root
(e\&.g\&., using
\fBsudo\fR)\&. In particular, editing
/etc/hosts
and
\fBDACS\fR
configuration files, setting file ownership and permissions, and the
\fBmake install\fR
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
\fBDACS\fR
web services, none of the
\fBDACS\fR
web services needs to run set\-uid or set\-gid\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 6." 4.2
.\}
Ordinarily, all
\fBDACS\fR\-related network communication
\fImust\fR
be done over SSL/TLS\&. Setting up SSL/TLS appropriately is primarily
\m[blue]\fBan Apache configuration task\fR\m[]\&\s-2\u[5]\d\s+2, 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
\fBDACS\fR
installation, we will neither use SSL/TLS in the examples nor mention SSL/TLS again\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 7." 4.2
.\}
It\*(Aqs 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
\m[blue]\fBcontact us\fR\m[]\&\s-2\u[6]\d\s+2\&. Our goal is to make it as easy as possible to get started with
\fBDACS\fR\&.
.RE
.sp .5v
.RE
.PP
Quick Start Steps:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
Step 1: Install required third\-party packages
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
Step 2: Install and configure Apache
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
Step 3: Build and install DACS
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
Step 4: DACS\-enable Apache
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
Step 5: Do basic DACS configuration
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 6." 4.2
.\}
Step 6: Do basic Apache configuration for DACS
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 7." 4.2
.\}
Step 7: Test basic DACS services
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 8.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 8." 4.2
.\}
Step 8: Try DACS authentication
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 9.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 9." 4.2
.\}
Step 9: DACS\-wrapping a web service
.RE
.sp
.RS 4
.ie n \{\
\h'-04'10.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "10." 4.2
.\}
Step 10: What\*(Aqs next?
.RE
.sp
.RS 4
.ie n \{\
\h'-04'11.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "11." 4.2
.\}
Step 11: Clean up
.RE
.SS "Step 1: Install required third\-party packages"
.PP
Obtain the versions of
\m[blue]\fBApache\fR\m[]\&\s-2\u[7]\d\s+2,
\m[blue]\fBOpenSSL\fR\m[]\&\s-2\u[8]\d\s+2, and
\m[blue]\fBExpat\fR\m[]\&\s-2\u[9]\d\s+2
that are specified in
\m[blue]\fBdacs\&.install(7)\fR\m[]\&\s-2\u[4]\d\s+2\&. If your system already has suitable versions of
\m[blue]\fBOpenSSL\fR\m[]\&\s-2\u[8]\d\s+2, and
\m[blue]\fBExpat\fR\m[]\&\s-2\u[9]\d\s+2
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
\m[blue]\fBOpenSSL\fR\m[]\&\s-2\u[10]\d\s+2
and
\m[blue]\fBExpat\fR\m[]\&\s-2\u[11]\d\s+2\&. This document assumes that
\fBApache\fR
2\&.2
is being used; you may use
2\&.4
if you are able to adapt the instructions on your own\&.
.PP
For the purposes of this exercise, those are the only third\-party packages that you need, other than
\fBgmake\fR,
\fBGCC\fR, and the usual software development tools\&. Install
\fBOpenSSL\fR
and
\fBExpat\fR
now; we will deal with
\fBApache\fR
in the next step\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
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\&.
.PP
Some administrators prefer to use a particular file extension, such as "\&.cgi", for CGI executables\&. The easiest way to make
\fBDACS\fR
accommodate this is to pass the
\fB\-\-with\-cgi\-suffix\fR
flag to
\fBconfigure\fR
(see
\m[blue]\fBdacs\&.install(7)\fR\m[]\&\s-2\u[4]\d\s+2)\&. This results in the configuration variable
\fI${Conf::dacs_cgi_bin_suffix}\fR
being set to the suffix\&. In this document, we will assume that no special file extension is required\&.
.sp .5v
.RE
.SS "Step 2: Install and configure Apache"
.PP
Because you probably do not want to use a production web server for this exercise, so that we\*(Aqre on the same page to begin with, and to make it easier for you to clean up later, we\*(Aqll build and install a fresh
\fBApache\fR
server\&. It will be best if you start from scratch by unpacking an
\fBApache\fR
distribution into a new directory, building and installing it, and then verifying that the default
\fBApache\fR
configuration works\&. We will install this
\fBApache\fR
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\&.
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
From the root of the
\fBApache\fR
distribution, you need to build
\fBApache\fR\&. Review the
\fBApache\fR
INSTALL
file\&. Unfortunately, there is no simple way to build
\fBApache\fR
that will work on all platforms, so you will need to review the
\m[blue]\fBdetailed instructions\fR\m[]\&\s-2\u[12]\d\s+2\&. Then build and install
\fBApache\fR\&.
.sp
Do not configure any
\fBApache\fR
modules or customizations\&. We want to create a vanilla web server\&. The path
/usr/local/apache\-dacs
is being used to avoid any existing
\fBApache\fR
installation; when you are finished with the tutorial, you will remove this directory\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.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
\fBhttpd\fR\&. Choose one of the following two options:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
If you are installing
\fBApache\fR
on the same machine from which you are running your web browser, edit
/etc/hosts
as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
127\&.0\&.0\&.1 localhost dodgers\&.dacstest\&.dss\&.ca
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
If you will be running your browser on a host different from where
\fBApache\fR
is running, you will need to add an alias in
/etc/hosts
for that host\*(Aqs IP address
\fIon both machines\fR\&. The entry will have the format:
.sp
.if n \{\
.RS 4
.\}
.nf
\fIhostip\fR \fIhostname\fR dodgers\&.dacstest\&.dss\&.ca
.fi
.if n \{\
.RE
.\}
.sp
For example, on my system I used:
.sp
.if n \{\
.RS 4
.\}
.nf
10\&.0\&.0\&.125 i7\&.dss\&.ca i7 dodgers\&.dacstest\&.dss\&.ca
.fi
.if n \{\
.RE
.\}
.sp
So the
\fIhostip\fR
I selected above is
10\&.0\&.0\&.125\&.
.RE
.sp
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNotes\fR
.ps -1
.br
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
If your desktop is a Windows platform rather than Unix\-based, you will need to edit
C:\eWindows\esystem32\edrivers\eetc\ehosts
or
C:\eWINNT\esystem32\edrivers\eetc\ehosts
(or similar) instead of
/etc/hosts\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
After you have completed this exercise, please remember to delete the aliases\&.
.RE
.sp .5v
.RE
To verify the change, use
\fBping\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
% ping dodgers\&.dacstest\&.dss\&.ca
.fi
.if n \{\
.RE
.\}
.sp
(You may need to run it as
/sbin/ping
or something similar on your system\&.)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
We need to make a few changes to
\fBApache\*(Aqs\fR
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
\fBDACS\fR\&. Edit
/usr/local/apache\-dacs/conf/httpd\&.conf, advance to the bottom of the file, and insert the text that appears below:
.sp
.if n \{\
.RS 4
.\}
.nf
# Permit access to the DACS documents
Options Indexes FollowSymLinks
Order allow,deny
Allow from all
# 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
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/"
.fi
.if n \{\
.RE
.\}
.sp
This
\m[blue]\fBVirtualHost\fR\m[]\&\s-2\u[13]\d\s+2
section is going to correspond to the
\fBDACS\fR
jurisdiction that we will define shortly\&. The purpose of the
\m[blue]\fBDirectory\fR\m[]\&\s-2\u[14]\d\s+2
and
\m[blue]\fBAlias\fR\m[]\&\s-2\u[15]\d\s+2
directives is to make various web resources available without having to copy them under your
\m[blue]\fBDocumentRoot\fR\m[]\&\s-2\u[16]\d\s+2\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
In our examples, we use port
18123, which we\*(Aqre guessing is unlikely to already be in use on your machine\&. If you are unlucky and it is in use,
\fBApache\fR
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
\m[blue]\fBnetstat(1)\fR\m[]\&\s-2\u[17]\d\s+2
and
\m[blue]\fBsockstat(1)\fR\m[]\&\s-2\u[18]\d\s+2
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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
If you are already running
\fBApache\fR
on port
80
(the default) or if you are not
root
whenever you run
\fBapachectl\fR
in any of the following steps, you must comment out (or delete) all
\m[blue]\fBListen\fR\m[]\&\s-2\u[19]\d\s+2
directives for port
80
in
httpd\&.conf\&. Therefore, comment out all directives that look like any of the following:
.sp
.if n \{\
.RS 4
.\}
.nf
Listen 80
Listen 0\&.0\&.0\&.0:80
Listen [::]:80
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp .5v
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
Some versions of
\fBApache\fR
do not build and enable
\m[blue]\fBmod_cgi\fR\m[]\&\s-2\u[20]\d\s+2
by default\&. We require it, so make sure that it has been done\&. Run this command;
cgi_module
should appear in the output list:
.sp
.if n \{\
.RS 4
.\}
.nf
# bin/httpd \-M
.fi
.if n \{\
.RE
.\}
.sp
The shared library
mod_cgi\&.so
should be in the
\fBApache\fR
installation\*(Aqs
modules
subdirectory or it should have been built\-in to
\fBhttpd\fR; in the former case, also check that there is a
\m[blue]\fBLoadModule\fR\m[]\&\s-2\u[21]\d\s+2
directive for it:
.sp
.if n \{\
.RS 4
.\}
.nf
LoadModule cgi_module modules/mod_cgi\&.so
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
It is good practice to run
\fBhttpd\fR
as an unprivileged user id and
\fBApache\fR
does this by default through the
\m[blue]\fBUser\fR\m[]\&\s-2\u[22]\d\s+2
directive in
httpd\&.conf:
.sp
.if n \{\
.RS 4
.\}
.nf
User nobody
.fi
.if n \{\
.RE
.\}
.sp
\fBDACS\fR
web services are run as the same user id as
\fBhttpd\fR, but they must be able to read and sometimes write files within the
\fBDACS\fR
installation directory\&. These files should not be readable or writable by other processes or anyone other than a
\fBDACS\fR
administrator\&. Using
\m[blue]\fBmod_suexec\fR\m[]\&\s-2\u[23]\d\s+2
is one approach, but for the purpose of this tutorial we want to keep things simple\&. Note that setting
\m[blue]\fBUser\fR\m[]\&\s-2\u[22]\d\s+2
(or
\m[blue]\fBGroup\fR\m[]\&\s-2\u[24]\d\s+2) to
root
is not a good idea\&.
.sp
The
\fBApache\fR
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
\m[blue]\fBgroup(5)\fR\m[]\&\s-2\u[25]\d\s+2) 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
\fBDACS\fR
is installed in the next step you will be prompted for this group id and you must make the appropriate change to
httpd\&.conf:
.sp
.if n \{\
.RS 4
.\}
.nf
Group www
.fi
.if n \{\
.RE
.\}
.sp
Because we will refer to this group name often in later steps, save its name as the value of the shell variable
\fIdacsgroup\fR
(we will use
\fBcsh\fR/\fBtcsh\fR
syntax \- use the syntax preferred by your shell):
.sp
.if n \{\
.RS 4
.\}
.nf
% set dacsgroup=www
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
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
\fBgroups\fR
command\&.
.sp .5v
.RE
Change the group id of files in the
\fBApache\fR
installation directory to this group and adjust permissions (you may have to do this as
root):
.sp
.if n \{\
.RS 4
.\}
.nf
% chgrp \-R $dacsgroup /usr/local/apache\-dacs/
% chmod \-R g+w /usr/local/apache\-dacs/
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 6." 4.2
.\}
As
root, start your httpd\&.\&.\&.
.sp
.if n \{\
.RS 4
.\}
.nf
# /usr/local/apache\-dacs/bin/apachectl start
.fi
.if n \{\
.RE
.\}
.sp
The reason you must do this as
root
is because it is required by Apache\*(Aqs
\m[blue]\fBUser\fR\m[]\&\s-2\u[22]\d\s+2
and
\m[blue]\fBGroup\fR\m[]\&\s-2\u[24]\d\s+2
directives\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
On
FreeBSD,
\fBApache\fR
may produce a message like:
.sp
.if n \{\
.RS 4
.\}
.nf
Failed to enable the \*(Aqhttpready\*(Aq Accept Filter
.fi
.if n \{\
.RE
.\}
.sp
You may be able to fix this by doing (as
root):
.sp
.if n \{\
.RS 4
.\}
.nf
\fB
# kldload accf_http
\fR
.fi
.if n \{\
.RE
.\}
.sp
See
\m[blue]\fBthis\fR\m[]\&\s-2\u[26]\d\s+2\&.
.sp .5v
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 7." 4.2
.\}
Use your favourite browser (or link fetcher, such as
\fBwget\fR) to verify that
\fBApache\fR
is serving content, starting with this link:
.sp
.if n \{\
.RS 4
.\}
.nf
\m[blue]\fBhttp://dodgers\&.dacstest\&.dss\&.ca:18123\fR\m[]
.fi
.if n \{\
.RE
.\}
.sp
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)\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
It appears that
CentOS
disallows non\-localhost connection requests by default; to allow Apache to receive non\-localhost requests on
CentOS, run (as
root):
.sp
.if n \{\
.RS 4
.\}
.nf
# system\-config\-firewall
.fi
.if n \{\
.RE
.\}
.sp
(This command was named
\fBsystem\-config\-securitylevel\fR
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\&.
.sp
Another option, if it is safe to do so, is to totally disable the firewall\&. On
CentOS:
.sp
.if n \{\
.RS 4
.\}
.nf
# service iptables stop
.fi
.if n \{\
.RE
.\}
.sp
If you choose to do this you should either restart the firewall when you are done ("\fBservice iptables start\fR") or reboot\&.
.sp
Another alternative, for
CentOS
and other systems, is to use the appropriate command (e\&.g\&.,
\fBiptables\fR,
\fBipfw\fR, or
\fBpfctl\fR) to add a firewall rule to allow TCP access to port
18123\&.
.sp .5v
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 8.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 8." 4.2
.\}
You should now check that your
\fBhttpd\fR
was built properly\&. First, make sure that
\fBtest\-cgi\fR
is executable (a CGI that is installed by
\fBApache\fR):
.sp
.if n \{\
.RS 4
.\}
.nf
% chmod 0750 /usr/local/apache\-dacs/cgi\-bin/test\-cgi
.fi
.if n \{\
.RE
.\}
.sp
And then invoke it:
.sp
.if n \{\
.RS 4
.\}
.nf
\m[blue]\fBhttp://dodgers\&.dacstest\&.dss\&.ca:18123/cgi\-bin/test\-cgi\fR\m[]
.fi
.if n \{\
.RE
.\}
.sp
Look for the
\fISERVER_SOFTWARE\fR
variable in its output and ensure that its value shows the correct versions of
\fBApache\fR,
\fBmod_ssl\fR, and
\fBOpenSSL\fR; if you find something unexpected, you probably didn\*(Aqt configure and/or install
\fBApache\fR
or
\fBOpenSSL\fR
correctly\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
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:
.sp
.if n \{\
.RS 4
.\}
.nf
Forbidden You don\*(Aqt have permission to access /cgi\-bin/test\-cgi on this server\&.
.fi
.if n \{\
.RE
.\}
.sp
Make sure to follow the
\fBApache\fR
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\&.
.sp .5v
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 9.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 9." 4.2
.\}
You have confirmed that
\fBApache\fR
is properly installed, so stop the web server:
.sp
.if n \{\
.RS 4
.\}
.nf
% /usr/local/apache\-dacs/bin/apachectl stop
.fi
.if n \{\
.RE
.\}
.sp
.RE
.SS "Step 3: Build and install DACS"
.PP
Now it is time to build and install the
\fBDACS\fR
utilities and web services\&. Make your working directory the
src
subdirectory of the
\fBDACS\fR
distribution\&.
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
Build and install
\fBDACS\fR
web services and utilities\&. You must use
\fBgmake\fR, the GNU Make utility\&. Adjust the paths specified for
\fBExpat\fR,
\fBApache\fR, and
\fBOpenSSL\fR
as necessary\&. The
\fBDACS\fR
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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
% \&./configure \-\-prefix=/usr/local/dacs \e
\-\-disable\-shared \-\-enable\-static \e
\-\-enable\-passwd\-auth \-\-disable\-bdb \e
\-\-with\-apache=/usr/local/apache\-dacs \e
\-\-with\-apache\-apr=/usr/local/apache\-dacs/apr\-httpd \e
\-\-with\-expat=/usr/local/expat\-2\&.0\&.1 \e
\-\-with\-ssl=/usr/local/openssl\-1\&.0\&.1p
% gmake
.fi
.if n \{\
.RE
.\}
.sp
If all goes well:
.sp
.if n \{\
.RS 4
.\}
.nf
% gmake install
.fi
.if n \{\
.RE
.\}
.sp
You can ignore any warnings about ACLs\&.
.sp
You will be prompted for the user id and group id to be used for
\fBDACS\fR
files and directories\&. The group id you give should match the value you used for
\fBApache\*(Aqs\fR
Group
directive (that is, the value of
\fI$dacsgroup\fR)\&. 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
\fBgmake install\fR
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:
.sp
.if n \{\
.RS 4
.\}
.nf
% conftools/setaccess\-sh reset
.fi
.if n \{\
.RE
.\}
.sp
and try
\fBgmake install\fR
again\&.
.RE
.SS "Step 4: DACS\-enable Apache"
.PP
We\*(Aqll continue by installing the
\m[blue]\fB\fBmod_auth_dacs\fR\fR\m[]\&\s-2\u[27]\d\s+2
module for
\fBApache\fR\&. Make your working directory the
apache
subdirectory of the
\fBDACS\fR
distribution\&.
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
Compile and install the
\fBmod_auth_dacs\fR
module\&. As earlier, you will need to do
\fBgmake install\fR
as
root
if your account has insufficient privileges to set the user and group ids that you specify\&.
.sp
.if n \{\
.RS 4
.\}
.nf
% gmake tag
% gmake install
.fi
.if n \{\
.RE
.\}
.sp
If this succeeds, your
\fBApache\fR
\m[blue]\fBhttpd\&.conf\fR\m[]\&\s-2\u[28]\d\s+2
file should now contain the following directive:
.sp
.if n \{\
.RS 4
.\}
.nf
LoadModule auth_dacs_module modules/mod_auth_dacs\&.so
.fi
.if n \{\
.RE
.\}
.sp
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
\m[blue]\fBLoadModule\fR\m[]\&\s-2\u[21]\d\s+2
directive\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
Start
\fBApache\fR
again (as
root):
.sp
.if n \{\
.RS 4
.\}
.nf
# /usr/local/apache\-dacs/bin/apachectl start
.fi
.if n \{\
.RE
.\}
.sp
and take another look at the
\fISERVER_SOFTWARE\fR
variable:
.sp
.if n \{\
.RS 4
.\}
.nf
\m[blue]\fBhttp://dodgers\&.dacstest\&.dss\&.ca:18123/cgi\-bin/test\-cgi\fR\m[]
.fi
.if n \{\
.RE
.\}
.sp
The
\fISERVER_SOFTWARE\fR
variable ought to look the same as before, except it should now also mention
\fBmod_auth_dacs\fR\&.
.sp
Congratulations \- you are now running a
\fBDACS\fR\-enabled web server!
\fBDACS\fR
is not configured to do anything at the moment, mind you, but your web server is now capable of
\fBDACS\fR\-wrapping web services\&. You should be able to view the
\fBDACS\fR
manual pages served from the web server you just installed:
.sp
.if n \{\
.RS 4
.\}
.nf
\m[blue]\fBhttp://dodgers\&.dacstest\&.dss\&.ca:18123/man\fR\m[]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.SS "Step 5: Do basic DACS configuration"
.PP
Although your
\fBApache\fR
is now
\fBDACS\fR\-enabled, a little more configuration of both
\fBDACS\fR
and
\fBApache\fR
are necessary before you can do anything interesting\&. We\*(Aqll continue by working with the
\fBDACS\fR
configuration (see
\m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[29]\d\s+2)\&.
.PP
We begin this step by defining a new
\fBDACS\fR
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\*(Aqs 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\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.PP
All of the files and directories that we create in this and future steps must be readable by
\fBDACS\fR
web services\&. This means that they must have their group ownership set to
\fI$dacsgroup\fR
and have group read and write permissions, as discussed earlier\&.
.sp .5v
.RE
.PP
We\*(Aqre 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
\fBtcsh\fR):
.sp
.if n \{\
.RS 4
.\}
.nf
% set dacs=/usr/local/dacs
% set bin=$dacs/bin
% set feds=$dacs/federations
% set la=$feds/dacstest\&.dss\&.ca/LA
.fi
.if n \{\
.RE
.\}
.sp
If you are using a compatible shell, such as
\fBcsh\fR, you will then be able to copy and paste command lines and other text that follows in the tutorial\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
At this point you can use the
\m[blue]\fBdacsinit(1)\fR\m[]\&\s-2\u[30]\d\s+2
program, found in the distribution\*(Aqs
src
directory, to perform the operations in this step for you\&. By default, the program uses the default paths that were established when
\fBDACS\fR
was built and the example paths used in this step\&. When prompted, simply use the
\fBdacsinit\fR
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\&.
.PP
You can also use
\fBdacsinit\fR
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
\m[blue]\fBInitial Configuration\fR\m[]\&\s-2\u[31]\d\s+2\&.
.sp .5v
.RE
.PP
Although you can get away with having a single
\fBDACS\fR
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\*(Aqs entirely up to you\&.
.PP
When
\fBconfigure\fR
is run to build
\fBDACS\fR, you can specify default locations for various configuration files, including
site\&.conf
and
dacs\&.conf\&. We did not change the defaults when we built
\fBDACS\fR
above, so our examples will use the default paths\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
We recommend that you always use the
site\&.conf\-std
that comes with your
\fBDACS\fR
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\&.
.sp .5v
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
Proceed by installing the default site configuration file as
$feds/site\&.conf
(recall that we defined the shell variables
\m[blue]\fBearlier\fR\m[]\&\s-2\u[32]\d\s+2, and that you may have to be
root
to be able to install correctly):
.sp
.if n \{\
.RS 4
.\}
.nf
% install \-c \-g $dacsgroup \-m 0640 $feds/site\&.conf\-std $feds/site\&.conf
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
If the
\fBinstall\fR
command is unavailable on your system, you can use
src/conftools/install\-sh
relative to your
\fBDACS\fR
distribution directory\&. Or just use
\fBcp\fR
(or
\fBmkdir\fR),
\fBchgrp\fR, and
\fBchmod\fR\&.
.sp .5v
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
Since we are not using SSL in this tutorial, edit
$feds/site\&.conf
and change the value of the
\m[blue]\fBSECURE_MODE\fR\m[]\&\s-2\u[33]\d\s+2
directive to "off"\&. For production use, the directive\*(Aqs value should always be "on":
.sp
.if n \{\
.RS 4
.\}
.nf
SECURE_MODE "off"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
It is convenient \- though not required \- to collect the configuration directives for all jurisdictions on this host in a single file\&. It\*(Aqs not unusual for a host to be associated with just one jurisdiction (and one federation), but this is certainly not always the case\&.
.sp
.if n \{\
.RS 4
.\}
.nf
% install \-c \-g $dacsgroup \-m 0660 /dev/null $feds/dacs\&.conf
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
We will create a directory where most of the files associated with our new federation will live:
.sp
.if n \{\
.RS 4
.\}
.nf
% install \-d \-g $dacsgroup \-m 0770 $feds/dacstest\&.dss\&.ca
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
And a subdirectory within it where most of the files associated with our new jurisdiction will live:
.sp
.if n \{\
.RS 4
.\}
.nf
% install \-d \-g $dacsgroup \-m 0770 $la
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 6." 4.2
.\}
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:
.sp
.if n \{\
.RS 4
.\}
.nf
% install \-d \-g $dacsgroup \-m 0770 $la/acls
% install \-c \-g $dacsgroup \-m 0660 /dev/null $la/acls/revocations
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 7." 4.2
.\}
Create directories where we will put group definitions for our jurisdiction and define the membership of our federation:
.sp
.if n \{\
.RS 4
.\}
.nf
% 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
.fi
.if n \{\
.RE
.\}
.sp
Paste the following text into the
$la/groups/DACS/jurisdictions\&.grp
file:
.sp
.if n \{\
.RS 4
.\}
.nf
.fi
.if n \{\
.RE
.\}
.sp
(Remember to change
18123
if you are using a different port\&.) The purpose of
jurisdictions\&.grp
is to provide
\fBDACS\fR
with information about the jurisdictions in this federation\&. All jurisdictions in a federation should use identical
jurisdictions\&.grp
files\&. We\*(Aqre 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
\m[blue]\fBdacs\&.groups(5)\fR\m[]\&\s-2\u[34]\d\s+2
for additional information\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 8.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 8." 4.2
.\}
We need some basic configuration directives for the jurisdiction
LA\&. Paste the following text into the
$feds/dacs\&.conf
file:
.sp
.if n \{\
.RS 4
.\}
.nf
FEDERATION_DOMAIN "dacstest\&.dss\&.ca"
FEDERATION_NAME "DACSTEST"
LOG_LEVEL "info"
JURISDICTION_NAME "LA"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 9.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 9." 4.2
.\}
And let\*(Aqs make this the default configuration file for
\fBDACS\fR
jurisdictions at this site:
.sp
.if n \{\
.RS 4
.\}
.nf
% rm \-f $la/dacs\&.conf
% ln \-s $feds/dacs\&.conf $la/dacs\&.conf
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'10.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "10." 4.2
.\}
Now, let\*(Aqs ask
\fBDACS\fR
to display its configuration by running the
\m[blue]\fB\fBdacsconf(1)\fR\fR\m[]\&\s-2\u[35]\d\s+2
utility:
.sp
.if n \{\
.RS 4
.\}
.nf
% $bin/dacsconf \-uj LA \-q
.fi
.if n \{\
.RE
.\}
.sp
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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'11.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "11." 4.2
.\}
We must create encryption keys for this federation using the
\m[blue]\fB\fBdacskey(1)\fR\fR\m[]\&\s-2\u[36]\d\s+2
utility:
.sp
.if n \{\
.RS 4
.\}
.nf
% 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
.fi
.if n \{\
.RE
.\}
.sp
We could not do this until after the jurisdiction had been configured because
\fBdacskey\fR
needs to look at
dacs\&.conf\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
\fIThe federation key file must be kept secret\fR\&. Any person or process that can read the federation key file can create
\fBDACS\fR
identities\&. It should be readable
\fIonly\fR
by its owner and
\fBDACS\fR
and
\fInot\fR
readable by anyone else\&.
.sp .5v
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'12.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "12." 4.2
.\}
Similarly, we should create encryption keys for our jurisdiction:
.sp
.if n \{\
.RS 4
.\}
.nf
% install \-c \-g $dacsgroup \-m 0640 /dev/null $la/jurisdiction_keyfile
% $bin/dacskey \-uj LA \-q $la/jurisdiction_keyfile
% ls \-l $la/jurisdiction_keyfile
.fi
.if n \{\
.RE
.\}
.sp
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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'13.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "13." 4.2
.\}
Make sure that all of the files and directories starting with
/usr/local/dacs
have appropriate permissions, as discussed earlier\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
If you modify
httpd\&.conf
you must restart
\fBApache\fR
for the changes to take effect\&. If you modify
dacs\&.conf,
site\&.conf, or any other
\fBDACS\fR
configuration file, the changes take effect immediately and do not require restarting
\fBApache\fR\&.
.sp .5v
.RE
.SS "Step 6: Do basic Apache configuration for DACS"
.PP
Your
\fBApache\fR
is now
\fBDACS\fR\-enabled and we\*(Aqve configured
\fBDACS\fR\&. Before we can do anything interesting we must make some changes to the
\fBApache\fR
configuration\&. We will begin by
\fBDACS\fR\-wrapping
\fBDACS\fR
web services, which is required\&.
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
Edit
/usr/local/apache\-dacs/conf/httpd\&.conf
and locate the
\m[blue]\fBVirtualHost\fR\m[]\&\s-2\u[13]\d\s+2
section that you added earlier\&. Inside that
VirtualHost
section and near its end, add the following text (remember to adjust paths as necessary):
.sp
.if n \{\
.RS 4
.\}
.nf
AddDACSAuth dacs\-acs /usr/local/dacs/bin/dacs_acs "\-t \-v"
SetDACSAuthMethod dacs\-acs external
SetDACSAuthConf dacs\-acs "/usr/local/dacs/federations/dacs\&.conf"
Require valid\-user
# Note: For Apache 2\&.4, instead use:
# Require dacs\-authz
Options ExecCGI
AuthType DACS
AuthDACS dacs\-acs
.fi
.if n \{\
.RE
.\}
.sp
These directives configure the virtual host to
\fBDACS\fR\-wrap the contents of all URLs that fall under the
/cgi\-bin/dacs
namespace\&. The first three directives tell
\fBmod_auth_dacs\fR
where to find the external
\fBDACS\fR
access control program (\m[blue]\fB\fBdacs_acs(8)\fR\fR\m[]\&\s-2\u[37]\d\s+2) and the
\fBDACS\fR
configuration file\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
Start (or restart)
\fBApache\fR
so that it uses its new configuration (as
root):
.sp
.if n \{\
.RS 4
.\}
.nf
# /usr/local/apache\-dacs/bin/apachectl restart
.fi
.if n \{\
.RE
.\}
.sp
\fBDACS\fR
should now be enforcing access control on the
/cgi\-bin/dacs
part of the server\*(Aqs URL space\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
Check that you can still access
\fBtest\-cgi\fR
(which you have not
\fBDACS\fR\-wrapped):
.sp
.if n \{\
.RS 4
.\}
.nf
\m[blue]\fBhttp://dodgers\&.dacstest\&.dss\&.ca:18123/cgi\-bin/test\-cgi\fR\m[]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
Now, let\*(Aqs see what happens when we try to access
\fBdacs_prenv\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
\m[blue]\fBhttp://dodgers\&.dacstest\&.dss\&.ca:18123/cgi\-bin/dacs/dacs_prenv\fR\m[]\&\s-2\u[38]\d\s+2
.fi
.if n \{\
.RE
.\}
.sp
Apache should produce a "403 Forbidden" error, which causes
\fBDACS\fR
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
\m[blue]\fBACS_ERROR_HANDLER\fR\m[]\&\s-2\u[39]\d\s+2
directive in
site\&.conf)\&. This happens because the default rules do not grant access to
\fBdacs_prenv\fR, so all access will be denied\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
To finish up this step, let\*(Aqs add a rule that will grant everyone access to
\fBdacs_prenv\fR\&. Create
$la/acls/acl\-tutorial\&.0
with appropriate permissions:
.sp
.if n \{\
.RS 4
.\}
.nf
% install \-c \-g $dacsgroup \-m 0660 /dev/null $la/acls/acl\-tutorial\&.0
.fi
.if n \{\
.RE
.\}
.sp
and then paste the following text into it:
.sp
.if n \{\
.RS 4
.\}
.nf
user("any")
.fi
.if n \{\
.RE
.\}
.sp
Whenever you add or change an access rule, you must rebuild the rule index for the jurisdiction:
.sp
.if n \{\
.RS 4
.\}
.nf
% $bin/dacsacl \-uj LA \-q \-build
% chgrp $dacsgroup $la/acls/INDEX
.fi
.if n \{\
.RE
.\}
.sp
It\*(Aqs currently only really necessary to run
\fBdacsacl\fR
if you add a rule or modify any part of a rule\*(Aqs
services
element, but this may change in a future release so just do it always\&. We make sure that the index file\*(Aqs group ID is correct\&.
.sp
This time
\fBdacs_prenv\fR
should work because our new rule grants access to everyone\&. Try it:
.sp
.if n \{\
.RS 4
.\}
.nf
\m[blue]\fBhttp://dodgers\&.dacstest\&.dss\&.ca:18123/cgi\-bin/dacs/dacs_prenv\fR\m[]\&\s-2\u[38]\d\s+2
.fi
.if n \{\
.RE
.\}
.sp
This output includes some new environment variables that are passed to all
\fBDACS\fR\-wrapped programs\&. These variables begin with "DACS_", such as
\fBDACS_VERSION\fR
\- see
\m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[40]\d\s+2
for additional information\&.
.RE
.SS "Step 7: Test basic DACS services"
.PP
There\*(Aqs still not too much you can do at this point, but there are a few
\fBDACS\fR
services that you can try\&. If one of these requests fails, take a look at the
\fBDACS\fR
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\&.
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
The
\m[blue]\fBdacs_version(8)\fR\m[]\&\s-2\u[41]\d\s+2
web service displays various version information, naturally enough:
.sp
.if n \{\
.RS 4
.\}
.nf
\m[blue]\fBhttp://dodgers\&.dacstest\&.dss\&.ca:18123/cgi\-bin/dacs/dacs_version\fR\m[]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
The
\m[blue]\fBdacs_list_jurisdictions(8)\fR\m[]\&\s-2\u[42]\d\s+2
web service displays information about jurisdictions:
.sp
.if n \{\
.RS 4
.\}
.nf
\m[blue]\fBhttp://dodgers\&.dacstest\&.dss\&.ca:18123/cgi\-bin/dacs/dacs_list_jurisdictions\fR\m[]
.fi
.if n \{\
.RE
.\}
.sp
You may recognize some of this material from the
jurisdictions\&.grp
file\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
We saw the
\fBconf\fR
utility earlier\&. We can get the same information from a web service:
.sp
.if n \{\
.RS 4
.\}
.nf
\m[blue]\fBhttp://dodgers\&.dacstest\&.dss\&.ca:18123/cgi\-bin/dacs/dacs_conf\fR\m[]
.fi
.if n \{\
.RE
.\}
.sp
Ooops! You should have been denied access to this web service\&. If you examine the default ACL (see
\m[blue]\fBdacs\&.acls(5)\fR\m[]\&\s-2\u[43]\d\s+2) for this web service, which can be found in
/usr/local/dacs/acls/acl\-conf\&.0, you might suspect that access to
\fBdacs_conf\fR
will only be granted to identities that satisfy the expression "dacs_admin()" (see
\m[blue]\fBdacs\&.exprs(5)\fR\m[]\&\s-2\u[44]\d\s+2)\&. And since you have not signed on to obtain a
\fBDACS\fR
identity, the ACL should deny access\&. After we do a little more
\fBDACS\fR
configuration work in the next step, we will give this another try\&.
.RE
.SS "Step 8: Try DACS authentication"
.PP
It is possible to create accounts or identities specifically for
\fBDACS\fR
users\&. These identities are managed by the
\m[blue]\fBdacspasswd(1)\fR\m[]\&\s-2\u[45]\d\s+2
utility (there are user accounts managed by other
\fBDACS\fR
commands, but we will not discuss them here)\&. Similar to
\fBApache\*(Aqs\fR
\m[blue]\fBhtpasswd\fR\m[]\&\s-2\u[46]\d\s+2
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
\fBDACS\fR
identity named "root" that has no relationship to a Unix system\*(Aqs superuser \- perhaps you are creating a
\fBDACS\fR
account for actor
\m[blue]\fBStephen Root\fR\m[]\&\s-2\u[47]\d\s+2\&.
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
We begin this step by creating an empty password file for
\fBdacspasswd\fR
(to ensure correct permissions)\&. Then we create a
\fBDACS\fR
account for username "sandy"\&.
.sp
.if n \{\
.RS 4
.\}
.nf
% install \-c \-g $dacsgroup \-m 0660 /dev/null $la/passwd
% $bin/dacspasswd \-uj LA \-q \-a sandy
.fi
.if n \{\
.RE
.\}
.sp
You will be prompted for a password to assign to
sandy\*(Aqs
account\&. Choose any password you like as long as it is at least six characters long\&. You can change
sandy\*(Aqs
password by running this command again\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
Next, we edit
$la/dacs\&.conf
and add the following text in the
Jurisdiction
section for
dodgers\&.dacstest\&.dss\&.ca:
.sp
.if n \{\
.RS 4
.\}
.nf
URL \e
"http://dodgers\&.dacstest\&.dss\&.ca:18123/cgi\-bin/dacs/local_passwd_authenticate"
STYLE "pass"
CONTROL "sufficient"
.fi
.if n \{\
.RE
.\}
.sp
This configuration enables authentication (see
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[48]\d\s+2) for accounts managed by the
\fBdacspasswd\fR
utility\&. Check again that all files starting with
/usr/local/dacs
have appropriate permissions, as discussed earlier\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
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
\fBDACS\fR
calls
LA:sandy\&. Note that the cookies
\fBDACS\fR
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\&.
.sp
\fBDACS\fR
comes with examples of simple HTML login pages with which you can authenticate:
.sp
.if n \{\
.RS 4
.\}
.nf
\m[blue]\fBhttp://dodgers\&.dacstest\&.dss\&.ca:18123/examples/login\&.html\fR\m[]
.fi
.if n \{\
.RE
.\}
.sp
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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
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
\m[blue]\fBdacs_current_credentials\fR\m[]\&\s-2\u[49]\d\s+2) or another to visit a page that will allow you to signout (\m[blue]\fBdacs_signout(8)\fR\m[]\&\s-2\u[50]\d\s+2) from all or some identities (you can also
\m[blue]\fBinvoke dacs_signout directly\fR\m[]\&\s-2\u[51]\d\s+2
to signout from all identities)\&. If you signout, there will be a link that you can follow to login again\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
Now use
\fBdacspasswd\fR
to create another account:
.sp
.if n \{\
.RS 4
.\}
.nf
% $bin/dacspasswd \-uj LA \-q \-a don
.fi
.if n \{\
.RE
.\}
.sp
If you are curious, you can take a peek at the password file, which we have configured to be
$la/passwd\&.
.sp
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
\fIand\fR
don), but this is disallowed by default; see
\m[blue]\fBACS_CREDENTIALS_LIMIT\fR\m[]\&\s-2\u[52]\d\s+2
and
\m[blue]\fBAUTH_SINGLE_COOKIE\fR\m[]\&\s-2\u[53]\d\s+2\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 6." 4.2
.\}
Now that you\*(Aqre able to authenticate, let\*(Aqs have another try at running
\fBdacs_conf\fR
(recall you were not granted access to it earlier)\&. We must first make one of the identities that you have created a
\fBDACS\fR
administrator identity\&. Edit
$la/dacs\&.conf
and add the following text in the
Jurisdiction
section for
dodgers\&.dacstest\&.dss\&.ca
(but
\fInot\fR
within the
Auth
section):
.sp
.if n \{\
.RS 4
.\}
.nf
ADMIN_IDENTITY "LA:sandy"
.fi
.if n \{\
.RE
.\}
.sp
As you might assume, this confers special privileges to
LA:sandy\&.
.sp
Authenticate as
sandy
using the
\m[blue]\fBlogin page\fR\m[]
and then try this link again (it should work this time):
.sp
.if n \{\
.RS 4
.\}
.nf
\m[blue]\fBhttp://dodgers\&.dacstest\&.dss\&.ca:18123/cgi\-bin/dacs/dacs_conf\fR\m[]
.fi
.if n \{\
.RE
.\}
.sp
If you
\m[blue]\fBsignout\fR\m[]\&\s-2\u[54]\d\s+2
as
sandy, then
\m[blue]\fBauthenticate\fR\m[]
as
don, and try
\m[blue]\fBhttp://dodgers\&.dacstest\&.dss\&.ca:18123/cgi\-bin/dacs/dacs_conf\fR\m[]
again, you should be denied access\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 7." 4.2
.\}
In an earlier step, you created an ACL ($la/acls/acl\-tutorial\&.0) that grants access to
\fBdacs_prenv\fR
to any user, whether authenticated or not\&. Edit that rule and replace:
.sp
.if n \{\
.RS 4
.\}
.nf
user("any")
.fi
.if n \{\
.RE
.\}
.sp
with:
.sp
.if n \{\
.RS 4
.\}
.nf
user("auth")
.fi
.if n \{\
.RE
.\}
.sp
Try invoking
\m[blue]\fBdacs_prenv\fR\m[]\&\s-2\u[55]\d\s+2
when you are not authenticated \- you should be denied access\&. Now authenticate and try
\m[blue]\fBdacs_prenv\fR\m[]\&\s-2\u[55]\d\s+2
again \- it should work\&. Edit the rule again and replace:
.sp
.if n \{\
.RS 4
.\}
.nf
user("auth")
.fi
.if n \{\
.RE
.\}
.sp
with:
.sp
.if n \{\
.RS 4
.\}
.nf
user("LA:don")
.fi
.if n \{\
.RE
.\}
.sp
Now you should only be granted access if you\*(Aqve authenticated as the
\fBDACS\fR
username
LA:don\&.
.RE
.SS "Step 9: DACS\-wrapping a web service"
.PP
To use
\fBDACS\fR
to control access to a resource, there are just a few things you need to do:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Make the URL space in which the resource lies within the scope of a
\m[blue]\fBLocation\fR\m[]\&\s-2\u[56]\d\s+2
directive for the
VirtualHost
that corresponds to the
\fBDACS\fR
jurisdiction responsible for the resource\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Make an appropriate
\fBDACS\fR
access control rule for the jurisdiction responsible for the URL space in which the resource lies\&.
.RE
.sp
Basically, you have to configure
\fBApache\fR
to allow
\fBDACS\fR
to perform access control for the resource, and you have to configure
\fBDACS\fR
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\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.PP
It is important to verify that all resources that you intend to be
\fBDACS\fR\-wrapped really are access controlled and that
\fBDACS\fR
cannot be bypassed (e\&.g\&., by using different URLs for the same resource)\&. For instance, despite many improvements, getting
\fBApache\*(Aqs\fR
\m[blue]\fBVirtual Hosts\fR\m[]\&\s-2\u[57]\d\s+2
configured exactly as you require can be challenging \- make sure that security cannot be bypassed through selection of a particular hostname or port number\&.
.PP
Also, note that
\fBDACS\fR
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
\fBDACS\fR\-wrapped\&.
.sp .5v
.RE
.SS "Step 10: What\*(Aqs next?"
.PP
Having successfully completed all of the previous steps, you should have a feel for some of the things that you can do with
\fBDACS\fR\&. Of course, there\*(Aqs much more to
\fBDACS\fR
than what we\*(Aqve covered\&. You should be capable of using the system you\*(Aqve configured to this point to try some things on your own\&. Here are a few ideas (in order of increasing difficulty):
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Add a
\fBDACS\fR\-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
\m[blue]\fBdacs\&.acls(5)\fR\m[]\&\s-2\u[58]\d\s+2
before beginning\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Assign a few roles to
\fBDACS\fR
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
\fBDACS\fR
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\&.
.sp
Here are some hints to get you started\&. You\*(Aqll need to do two things: assign roles to users and enable roles\&. Once enabled, your
\fBDACS\fR
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:
.sp
.if n \{\
.RS 4
.\}
.nf
sandy:pitchers,retired\-players
don:pitchers,retired\-players
eric:pitchers,active\-players
cesar:infielders,active\-players
.fi
.if n \{\
.RE
.\}
.sp
The other thing you\*(Aqll need is some
\fBDACS\fR
configuration to enable roles\&. Add the following to the
Jurisdiction
section of
dacs\&.conf:
.sp
.if n \{\
.RS 4
.\}
.nf
URL "http://dodgers\&.dacstest\&.dss\&.ca:18123/cgi\-bin/dacs/local_roles"
.fi
.if n \{\
.RE
.\}
.sp
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
\m[blue]\fBdacs\&.exprs(5)\fR\m[]\&\s-2\u[59]\d\s+2):
.sp
.if n \{\
.RS 4
.\}
.nf
user("%LA:pitchers")
.fi
.if n \{\
.RE
.\}
.sp
Or you can create a rule that will grant access only if the user has the roles "active\-players"
\fIand\fR
"pitchers"; use the predicate:
.sp
.if n \{\
.RS 4
.\}
.nf
user("%LA:pitchers") and user("%LA:active\-players")
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
If you create a
\fBDACS\fR
account for a username that corresponds to a user on your system, you can configure
\fBDACS\fR
to assign roles to that user based on the Unix groups that she belongs to\&. This is very easy to do: instead of using
\fBlocal_roles\fR
as in the example above, use
\fBlocal_unix_roles\fR
instead\&. If you create a
\fBDACS\fR
account for
alice, for example, and the account "alice" has group membership on your system (see group(5)), then
alice
would authenticate using her
\fBDACS\fR
password and be assigned roles from her Unix group membership\&.
.sp
Instead of using a
\fBDACS\fR
account to authenticate
alice, you can easily configure
\fBDACS\fR
to use
alice\*(Aqs
Unix password\&. The
\fBDACS\fR
module
\fBlocal_unix_authenticate\fR, which must be installed set\-uid
root
so that it can access passwords, provides this functionality\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Add a
\fBDACS\fR
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"\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Run
\fBDACS\fR
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\*(Aqt be able to use the IP address
127\&.0\&.0\&.1
for this; you\*(Aqll 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\*(Aqll also have to use the identical
federation_keyfile
on both hosts (simply copy the file you\*(Aqve already made)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Configure a different (or additional) authentication method for your jurisdiction\&. See
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[60]\d\s+2\&. 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\&.
.RE
.SS "Step 11: Clean up"
.PP
If you are done, you may want to do some clean up now\&. First, stop
\fBApache\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
# /usr/local/apache\-dacs/bin/apachectl stop
.fi
.if n \{\
.RE
.\}
.sp
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\&.
.SS "Troubleshooting"
.PP
The first thing to do if you encounter a problem is to check that you\*(Aqve got the latest version of
\fBDACS\fR; a newer version might fix your problem\&. Also, visit the
\m[blue]\fBPost\-Release Notes\fR\m[]\&\s-2\u[61]\d\s+2
area for your release in case a newer edition of this document is available or a bug fix has been posted\&.
.PP
By default, the
\fBDACS\fR
log files are put in the
/usr/local/dacs/logs
directory\&. If you encounter any problems or just want to see what\*(Aqs going on, examine the log files in that directory\&. Depending on the
\fBDACS\fR
\m[blue]\fBLOG_LEVEL\fR\m[]\&\s-2\u[62]\d\s+2
and
\m[blue]\fBLOG_FILTER\fR\m[]\&\s-2\u[63]\d\s+2
directives in effect, log files can quickly become big\&. It is safe to delete them or truncate them at any time\&.
.PP
In the event of problems, you should also take a look at the
\fBApache\fR
logs (in
/usr/local/apache\-dacs/logs)\&.
.PP
There are five main sources of problems:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
Typos (you got the spelling or punctuation incorrect, or didn\*(Aqt paste text correctly),
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
File permissions are incorrect (\fBDACS\fR
cannot read or write its files or directories),
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
You didn\*(Aqt follow the instructions correctly (you skipped something or misunderstood something),
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
You ran into unexpected platform dependencies, or
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
We goofed\&.
.RE
.sp
If you\*(Aqre sure the problem is either of the last two types, please
\m[blue]\fBcontact us\fR\m[]\&\s-2\u[6]\d\s+2\&. and tell us what happened\&. Be sure to mention which steps succeeded and which one failed\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[64]\d\s+2,
\m[blue]\fBdacsinit(1)\fR\m[]\&\s-2\u[30]\d\s+2,
\m[blue]\fBdacs\&.readme(7)\fR\m[]\&\s-2\u[3]\d\s+2,
\m[blue]\fBdacs\&.install(7)\fR\m[]\&\s-2\u[4]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[65]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2018 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[66]\d\s+2
file that accompanies the distribution for licensing information\&.
.SH "NOTES"
.IP " 1." 4
FAQ
.RS 4
\%http://dacs.dss.ca/faq.html
.RE
.IP " 2." 4
manual pages
.RS 4
\%http://dacs.dss.ca/man
.RE
.IP " 3." 4
dacs.readme(7)
.RS 4
\%http://dacs.dss.ca/man/dacs.readme.7.html
.RE
.IP " 4." 4
dacs.install(7)
.RS 4
\%http://dacs.dss.ca/man/dacs.install.7.html
.RE
.IP " 5." 4
an Apache configuration task
.RS 4
\%http://httpd.apache.org/docs/2.4/ssl/
.RE
.IP " 6." 4
contact us
.RS 4
\%http://www.dss.ca/contactus.html
.RE
.IP " 7." 4
Apache
.RS 4
\%http://httpd.apache.org
.RE
.IP " 8." 4
OpenSSL
.RS 4
\%http://www.openssl.org
.RE
.IP " 9." 4
Expat
.RS 4
\%http://sourceforge.net/projects/expat
.RE
.IP "10." 4
OpenSSL
.RS 4
\%http://dacs.dss.ca/man/dacs.install.7.html#install-openssl
.RE
.IP "11." 4
Expat
.RS 4
\%http://dacs.dss.ca/man/dacs.install.7.html#install-expat
.RE
.IP "12." 4
detailed instructions
.RS 4
\%http://dacs.dss.ca/man/dacs.install.7.html#install-apache
.RE
.IP "13." 4
VirtualHost
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/core.html#virtualhost
.RE
.IP "14." 4
Directory
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/core.html#directory
.RE
.IP "15." 4
Alias
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mod_alias.html#alias
.RE
.IP "16." 4
DocumentRoot
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/core.html#documentroot
.RE
.IP "17." 4
netstat(1)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=netstat&apropos=0&sektion=1&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "18." 4
sockstat(1)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=sockstat&apropos=0&sektion=1&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "19." 4
Listen
.RS 4
\%http://httpd.apache.org/docs/2.0/mod/mpm_common.html#listen
.RE
.IP "20." 4
mod_cgi
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mod_cgi.html
.RE
.IP "21." 4
LoadModule
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mod_so.html#loadmodule
.RE
.IP "22." 4
User
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mpm_common.html#user
.RE
.IP "23." 4
mod_suexec
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mod_suexec.html
.RE
.IP "24." 4
Group
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mod_unixd.html#group
.RE
.IP "25." 4
group(5)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=group&apropos=0&sektion=5&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "26." 4
this
.RS 4
\%http://unix.derkeiler.com/Newsgroups/comp.unix.bsd.freebsd.misc/2005-04/0624.html
.RE
.IP "27." 4
\fBmod_auth_dacs\fR
.RS 4
\%http://dacs.dss.ca/man/mod_auth_dacs.html
.RE
.IP "28." 4
httpd.conf
.RS 4
\%file:///usr/local/apache-dacs/conf/httpd.conf
.RE
.IP "29." 4
dacs.conf(5)
.RS 4
\%http://dodgers.dacstest.dss.ca:18123/man/dacs.conf.5.html
.RE
.IP "30." 4
dacsinit(1)
.RS 4
\%http://dacs.dss.ca/man/dacsinit.1.html
.RE
.IP "31." 4
Initial Configuration
.RS 4
\%http://dacs.dss.ca/man/dacs.install.7.html#initial_config
.RE
.IP "32." 4
earlier
.RS 4
\%http://dacs.dss.ca/man/#var-defs
.RE
.IP "33." 4
SECURE_MODE
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#SECURE_MODE
.RE
.IP "34." 4
dacs.groups(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.groups.5.html#dacs_metadata
.RE
.IP "35." 4
\fBdacsconf(1)\fR
.RS 4
\%http://dodgers.dacstest.dss.ca:18123/man/dacsconf.1.html
.RE
.IP "36." 4
\fBdacskey(1)\fR
.RS 4
\%http://dodgers.dacstest.dss.ca:18123/man/dacskey.1.html
.RE
.IP "37." 4
\fBdacs_acs(8)\fR
.RS 4
\%http://dodgers.dacstest.dss.ca:18123/man/dacs_acs.8.html
.RE
.IP "38." 4
http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_prenv
.RS 4
\%http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_prenv?FORMAT=html
.RE
.IP "39." 4
ACS_ERROR_HANDLER
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#ACS_ERROR_HANDLER
.RE
.IP "40." 4
dacs_acs(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html#exported_envars
.RE
.IP "41." 4
dacs_version(8)
.RS 4
\%http://dodgers.dacstest.dss.ca:18123/man/dacs_version.8.html
.RE
.IP "42." 4
dacs_list_jurisdictions(8)
.RS 4
\%http://dodgers.dacstest.dss.ca:18123/man/dacs_list_jurisdictions.8.html
.RE
.IP "43." 4
dacs.acls(5)
.RS 4
\%http://dodgers.dacstest.dss.ca:18123/man/dacs.acls.5.html
.RE
.IP "44." 4
dacs.exprs(5)
.RS 4
\%http://dodgers.dacstest.dss.ca:18123/man/dacs.exprs.5.html
.RE
.IP "45." 4
dacspasswd(1)
.RS 4
\%http://dodgers.dacstest.dss.ca:18123/man/dacspasswd.1.html
.RE
.IP "46." 4
htpasswd
.RS 4
\%http://httpd.apache.org/docs/2.4/programs/htpasswd.html
.RE
.IP "47." 4
Stephen Root
.RS 4
\%http://us.imdb.com/name/nm0740535/
.RE
.IP "48." 4
dacs_authenticate(8)
.RS 4
\%http://dodgers.dacstest.dss.ca:18123/man/dacs_authenticate.8.html
.RE
.IP "49." 4
dacs_current_credentials
.RS 4
\%http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_current_credentials
.RE
.IP "50." 4
dacs_signout(8)
.RS 4
\%http://dodgers.dacstest.dss.ca:18123/man/dacs_signout.8.html
.RE
.IP "51." 4
invoke dacs_signout directly
.RS 4
\%http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_signout
.RE
.IP "52." 4
ACS_CREDENTIALS_LIMIT
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#ACS_CREDENTIALS_LIMIT
.RE
.IP "53." 4
AUTH_SINGLE_COOKIE
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_SINGLE_COOKIE
.RE
.IP "54." 4
signout
.RS 4
\%http://dodgers.dacstest.dss.ca:18123/examples/signout.html
.RE
.IP "55." 4
dacs_prenv
.RS 4
\%http://dodgers.dacstest.dss.ca:18123/cgi-bin/dacs/dacs_prenv
.RE
.IP "56." 4
Location
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/core.html#location
.RE
.IP "57." 4
Virtual Hosts
.RS 4
\%http://httpd.apache.org/docs/2.4/vhosts/
.RE
.IP "58." 4
dacs.acls(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.acls.5.html
.RE
.IP "59." 4
dacs.exprs(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html
.RE
.IP "60." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html
.RE
.IP "61." 4
Post-Release Notes
.RS 4
\%http://dacs.dss.ca/download.html
.RE
.IP "62." 4
LOG_LEVEL
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#LOG_LEVEL
.RE
.IP "63." 4
LOG_FILTER
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#LOG_FILTER
.RE
.IP "64." 4
dacs(1)
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html
.RE
.IP "65." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "66." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE