.\" 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: dacsacl
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 08/23/2020
.\"    Manual: DACS Commands Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "DACSACL" "1" "08/23/2020" "DACS 1.4.40" "DACS Commands Manual"
.\" -----------------------------------------------------------------
.\" * 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"
dacsacl \- list, check, or re\-index access control rules
.SH "SYNOPSIS"
.HP \w'\fBdacsacl\fR\ 'u
\fBdacsacl\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR] [\fB\-build\fR | \fB\-nobuild\fR] [\fB\-vfs\ \fR\fB\fIvfs_uri\fR\fR] [...] [\fIop\-spec\fR] [\fIacl\-name\fR...]
.SH "DESCRIPTION"
.PP
This program is part of the
\fBDACS\fR
suite\&.
.PP
The
\fBdacsacl\fR
utility performs administrative functions related to access control, such as:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
validating the syntax of ACL files (parsing the XML and
\fBDACS\fR
expressions);
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
checking that the revocation list (VFS type
revocations) exists and performing a syntax check on it;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
creating an index (a directory data structure, as an XML file) of access control files; and
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
listing and deleting access tokens in the authorization cache (refer to
\m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[2]\d\s+2)\&.
.RE
.PP
Please refer to
\m[blue]\fBdacs\&.acls(5)\fR\m[]\&\s-2\u[3]\d\s+2
for details about how access control rule files are named\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBImportant\fR
.ps -1
.br
.PP
Version
1\&.4\&.21
introduced important changes to the way
\fBDACS\fR
processes access control files, introducing incompatibilities with earlier releases\&. Please pay special attention to the
\fB\-convert\fR
and
\fB\-build\fR
flags\&.
.PP
Most importantly, after adding, deleting, or editing an access control file the ACL index must be regenerated\&. This can be done simply by running
\fBdacsacl\fR
with no arguments\&.
.sp .5v
.RE
.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
.PP
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
So that it can be run as part of the installation procedure,
\fBdacsacl\fR
does not require
dacs\&.conf
to exist\&. If it does exist, however, it must be readable and syntactically correct\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The program emits a warning message if it finds different ACL files that contain identical
url_pattern
(or
url_expr) attributes\&. It does not detect pairs of these attributes that are equivalent, however; in general, it is not possible to do so because the actual specifications used to match against a service request are not known until run time\&. Two or more
service
elements should never apply to the same service request (other than through wildcard matching) and the result of authorization testing with such rules is indeterminate\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The
\m[blue]\fBdacs_admin(8)\fR\m[]\&\s-2\u[4]\d\s+2
web service provides some of the same functionality as
\fBdacsacl\fR\&.
.RE
.sp .5v
.RE
.SH "OPTIONS"
.PP
In addition to the standard
\m[blue]\fB\fIdacsoptions\fR\fR\m[]\&\s-2\u[1]\d\s+2,
\fBdacsacl\fR
recognizes these options:
.PP
.PP
\fB\-build\fR
.RS 4
Index rebuilding is done by default with most modes of operation, but it can be explicitly requested with this flag\&. If the flag is given, it is not an error if an index file does not exist (as when initially creating an index)\&.
.RE
.PP
\fB\-nobuild\fR
.RS 4
Suppress index rebuilding\&.
.RE
.PP
\fB\-vfs \fR\fB\fIvfs_uri\fR\fR
.RS 4
This flag, which may be repeated, causes
\fIvfs_uri\fR
to be defined as if by a
\m[blue]\fBVFS\fR\m[]\&\s-2\u[5]\d\s+2
directive, overriding any existing definition\&. This can be used to specify an alternate location for the item types
acls
or
dacs_acls, for instance\&. As a special case, if
acls
(dacs_acls) is defined using this flag but not
dacs_acls
(acls), then only the former\*(Aqs index will be rebuilt\&.
.sp
This option can be useful in conjunction with the
\fB\m[blue]\fB\-un\fR\m[]\&\s-2\u[1]\d\s+2\fR
flag so that indexes can be generated before a jurisdiction has been configured\&.
.RE
.PP
The optional
\fIop\-spec\fR
describes one of the following operations:
.PP
\fB\-convert\fR
.RS 4
This flag is used to convert from the older rule processing scheme (pre\-1\&.4\&.21) to the current scheme\&. It should only be needed by installations that are using custom rules (i\&.e\&., those other than the standard rules for
\fBDACS\fR
web pages and web services)\&. Note that in some cases (described below) conversion is not fully automated, so the administrator may need to do some additional work\&.
.RE
.PP
\fB\-\-\fR
.RS 4
This flag is a no\-op that is used to prevent any following argument from being interpreted as a flag or operation\&.
.RE
.PP
\fB\-f\fR \fIfile\fR [...]
.RS 4
Each
\fIfile\fR
argument is the pathname of an ACL file or a directory containing ACL files\&. Since ACL files can be organized using a directory structure, directories are checked recursively\&.
.RE
.PP
\fB\-l\fR
.RS 4
List the full URI of each access control rule in the virtual filestore for item types
acls
and
dacs_acls\&. No error checking is performed\&.
.RE
.PP
\fB\-s\fR
.RS 4
List the name (sans prefixes) of each access control rule in the virtual filestore for item types
acls
and
dacs_acls\&. No error checking is performed\&.
.RE
.PP
\fB\-tc\fR
.RS 4
Clean up the authorization cache by deleting expired or otherwise invalid entries\&. Note: since there may not be any concurrency control in effect, this should probably not be done while
\fBDACS\fR
could be writing to the file\&.
.RE
.PP
\fB\-td\fR # \&.\&.\&.
.RS 4
Delete one or more authorization cache entries by giving their integer listing number (starting at
1, as produced by the
\fB\-tl\fR
flag)\&. Note: since there may not be any concurrency control in effect, this should probably not be done while
\fBDACS\fR
could be writing to the file\&.
.RE
.PP
\fB\-tl\fR
.RS 4
List the entries in the authorization cache\&.
.RE
.PP
\fB\-tt\fR
.RS 4
Truncate the authorization cache, effectively deleting everything in the cache\&. This is not currently implemented; in the meantime, simply delete the file or database, or copy
/dev/null
to it\&.
.RE
.PP
If one or more
\fIacl\-name\fR
arguments appear they are interpreted as ACL files accessed through
\fBDACS\*(Aqs\fR
virtual filestore using item types
acls
and
dacs_acls
(both are checked)\&. The applicable
\fBDACS\fR
configuration for the item type determines how an
\fIacl\-name\fR
will be accessed\&. Note that
\fIacl\-name\fR
must be the actual filename\&.
.PP
If no
\fIop\-spec\fR
or
\fIacl\-name\fR
is specified,
\fBdacsacl\fR
will examine all currently indexed ACL files configured for the appropriate
\fBDACS\fR
jurisdiction\&.
.SH "EXAMPLES"
.PP
The following command checks all of the access control rules belonging to the jurisdiction associated with
dss\&.example\&.com:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsacl \-u dss\&.example\&.com \-v
Checking: /usr/local/dacs/federations/dss/acls/acl\&.2
Checking: /usr/local/dacs/federations/dss/acls/acl\&.3
Checking: /usr/local/dacs/federations/dss/acls/acl\&.4
Checking: /usr/local/dacs/acls/acl\-auth\&.0
(Note: duplicate keys for "acl\-auth\&.0" and "acl\-conf\&.0")
Checking: /usr/local/dacs/acls/acl\-conf\&.0
(Note: duplicate keys for "acl\-conf\&.0" and "acl\-dacs\&.0")
Checking: /usr/local/dacs/acls/acl\-dacs\&.0
(Note: duplicate keys for "acl\-dacs\&.0" and "acl\-passwd\&.0")
Checking: /usr/local/dacs/acls/acl\-passwd\&.0
(Note: duplicate keys for "acl\-passwd\&.0" and "acl\-stddocs\&.0")
Checking: /usr/local/dacs/acls/acl\-stddocs\&.0
Updated rule: [acls]dacs\-fs:/usr/local/dacs/conf/acls/acl\-abc\&.0
Updated rule: [acls]dacs\-fs:/usr/local/dacs/conf/acls/acl\-accounts\&.0
\&.\&.\&.
Built index for "acls": 44 rules
Updated rule: [dacs_acls]dacs\-fs:/usr/local/dacs/acls/acl\-admin\&.0
Updated rule: [dacs_acls]dacs\-fs:/usr/local/dacs/acls/acl\-auth\-agent\&.0
\&.\&.\&.
Built index for "dacs_acls": 14 rules
58 ACL files were checked (OK)
.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
.PP
While it is not an error for access control rules to have the same numeric suffix, because the suffix partly determines the order in which roles are processed, using equal suffix values accidentally may have unintended results\&.
.sp .5v
.RE
.PP
The following command checks only one access control rule belonging to the jurisdiction associated with
dss\&.example\&.com:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsacl \-u dss\&.example\&.com \-v acl\&.2
Checking: /usr/local/dacs/federations/dss/acls/acl\&.2
1 ACL file was checked (OK)
.fi
.if n \{\
.RE
.\}
.PP
In general, to validate and index a set of rules placed in the directory
/tmp/rules:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsacl \-un \-q \-build \-vfs "[dacs_acls]file:///tmp/rules"
.fi
.if n \{\
.RE
.\}
.sp
.SH "DIAGNOSTICS"
.PP
The program exits
0
if everything was fine,
1
if an error occurred\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacsvfs(1)\fR\m[]\&\s-2\u[6]\d\s+2,
\m[blue]\fBdacs\&.acls(5)\fR\m[]\&\s-2\u[3]\d\s+2,
\m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[7]\d\s+2,
\m[blue]\fBdacs_admin(8)\fR\m[]\&\s-2\u[4]\d\s+2,
\m[blue]\fBdacs_vfs(8)\fR\m[]\&\s-2\u[8]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[9]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2016 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[10]\d\s+2
file that accompanies the distribution for licensing information\&.
.SH "NOTES"
.IP " 1." 4
dacsoptions
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#dacsoptions
.RE
.IP " 2." 4
dacs_acs(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html#authorization_caching
.RE
.IP " 3." 4
dacs.acls(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.acls.5.html
.RE
.IP " 4." 4
dacs_admin(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_admin.8.html
.RE
.IP " 5." 4
VFS
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#VFS
.RE
.IP " 6." 4
dacsvfs(1)
.RS 4
\%http://dacs.dss.ca/man/dacsvfs.1.html
.RE
.IP " 7." 4
dacs_acs(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html
.RE
.IP " 8." 4
dacs_vfs(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_vfs.8.html
.RE
.IP " 9." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "10." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE