.\" 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_admin
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 08/23/2020
.\"    Manual: DACS Web Services Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "DACS_ADMIN" "8" "08/23/2020" "DACS 1.4.40" "DACS Web Services 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"
dacs_admin \- \fBDACS\fR administration service
.SH "SYNOPSIS"
.HP \w'\fBdacs_admin\fR\ 'u
\fBdacs_admin\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR]
.SH "DESCRIPTION"
.PP
This program is part of the
\fBDACS\fR
suite\&.
.PP
The
\fBdacs_admin\fR
web service is a tool for administering various
\fBDACS\fR
resources at a jurisdiction\&. Providing both a browser\-based interface and a simple,
\m[blue]\fBREST\-oriented\fR\m[]\&\s-2\u[2]\d\s+2
HTTP interface that can be used by middleware, scripts, and web browsers,
\fBdacs_admin\fR
allows inspection (and sometimes modification) of a jurisdiction\*(Aqs access control rules, configuration directives, group definitions,
\fBDACS\fR
user accounts, revocation list, version information, authorization cache,
\fBDACS\fR
log files, user tracking records, and more\&. An administrator can manage a different jurisdiction simply by aiming a browser or other HTTP client at that jurisdiction\*(Aqs
\fBdacs_admin\fR
web service\&.
.PP
Probably the best way to understand the tool is to simply use it interactively to browse through a jurisdiction\*(Aqs resources\&.
.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
This web service provides a way to view and change security\-related
\fBDACS\fR
configuration,
\fBDACS\fR
passwords, and so on\&. The default access control rule denies all access to the web service \- you must add a custom rule to enable access\&. All functionality should be restricted to an
\m[blue]\fBADMIN_IDENTITY\fR\m[]\&\s-2\u[3]\d\s+2\&.
.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
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Some features of this program may require JavaScript to be enabled in the browser\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBdacs_admin\fR
will eventually unify and replace several existing different
\fBDACS\fR
administrative web services\&. It may also include federation\-wide functions, such as the capability of adding a new jurisdiction\&.
.RE
.sp .5v
.RE
.SS "Web Service Arguments"
.PP
The following web service argument is always recognized:
.PP
\fIFORMAT\fR
.RS 4
By default, output is emitted in HTML\&. Several varieties of XML output can be selected, however, using the
\fIFORMAT\fR
argument (please refer to
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[4]\d\s+2)\&.
.RE
.SS "Resources and Methods"
.PP
The interface provided by
\fBdacs_admin\fR
allows various
\fBDACS\fR
resources to be examined and modified using standard HTTP methods (see
\m[blue]\fBRFC 2616\fR\m[]\&\s-2\u[5]\d\s+2)\&. Not all
\fBDACS\fR
resources may be accessible using
\fBdacs_admin\fR
and not all methods may be valid for some resources\&.
.PP
In keeping with the REST architectural style, every persistent resource is identified by a URI (\m[blue]\fBRFC 2396\fR\m[]\&\s-2\u[6]\d\s+2
and
\m[blue]\fBRFC 3986\fR\m[]\&\s-2\u[7]\d\s+2)\&. Invoking the
GET
method on
https://www\&.example\&.com/cgi\-bin/dacs/dacs_admin, for example, will (assuming appropriate configuration and permission) return a list of root\-level resources managed by
\fBdacs_admin\fR\&.
.PP
Invoking the
GET
method on a resource either returns a listing (by default, formatted as an HTML list or table) or an unadorned value (by default, formatted as an HTML encoded string)\&. For instance, this URL might return a list of configuration directives and their current values:
.sp
.if n \{\
.RS 4
.\}
.nf
https://www\&.example\&.com/cgi\-bin/dacs/dacs_admin/conf/current
.fi
.if n \{\
.RE
.\}
.sp
while this URL might return the current value of a particular configuration directive:
.sp
.if n \{\
.RS 4
.\}
.nf
https://www\&.example\&.com/cgi\-bin/dacs/dacs_admin/conf/current/AUTH_SUCCESS
.fi
.if n \{\
.RE
.\}
.PP
The functionality of
\fBdacs_admin\fR
is described in terms of resources and methods supported on those resources\&. Depending on the particular service request, the result consists of an HTTP status code (usually "\fB200\fR OK", "\fB201\fR Created", "\fB400\fR Bad Request", or "\fB404\fR Not Found"), and possibly an HTML or XML document (selectable)\&. The XML document is described by
\m[blue]\fBdacs_admin\&.dtd\fR\m[]\&\s-2\u[8]\d\s+2\&.
.PP
Arguments are passed in the
query
part of a URI\&. Unrecognized and context\-inappropriate arguments are silently ignored\&.
.SH "OPTIONS"
.PP
Only the standard
\m[blue]\fB\fIdacsoptions\fR\fR\m[]\&\s-2\u[1]\d\s+2
command line arguments are recognized\&.
.SH "FILES"
.PP
\m[blue]\fBdacs_admin\&.css\fR\m[]\&\s-2\u[9]\d\s+2
.SH "DIAGNOSTICS"
.PP
The program exits
0
if everything was fine,
1
if an error occurred\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacsacl(1)\fR\m[]\&\s-2\u[10]\d\s+2,
\m[blue]\fBdacspasswd(1)\fR\m[]\&\s-2\u[11]\d\s+2,
\m[blue]\fBdacs\&.acls(5)\fR\m[]\&\s-2\u[12]\d\s+2,
\m[blue]\fBdacs_conf(8)\fR\m[]\&\s-2\u[13]\d\s+2,
\m[blue]\fBdacs_group(8)\fR\m[]\&\s-2\u[14]\d\s+2,
\m[blue]\fBdacs_list_jurisdictions(8)\fR\m[]\&\s-2\u[15]\d\s+2,
\m[blue]\fBdacs_passwd(8)\fR\m[]\&\s-2\u[16]\d\s+2,
\m[blue]\fBdacs_version(8)\fR\m[]\&\s-2\u[17]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[18]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2014 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[19]\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
REST-oriented
.RS 4
\%https://code.google.com/p/implementing-rest/
.RE
.IP " 3." 4
ADMIN_IDENTITY
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#ADMIN_IDENTITY
.RE
.IP " 4." 4
dacs(1)
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html
.RE
.IP " 5." 4
RFC 2616
.RS 4
\%http://www.rfc-editor.org/rfc/rfc2616.txt
.RE
.IP " 6." 4
RFC 2396
.RS 4
\%http://www.rfc-editor.org/rfc/rfc2396.txt
.RE
.IP " 7." 4
RFC 3986
.RS 4
\%http://www.rfc-editor.org/rfc/rfc3986.txt
.RE
.IP " 8." 4
dacs_admin.dtd
.RS 4
\%http://dacs.dss.ca/man/../dtd-xsd/dacs_admin.dtd
.RE
.IP " 9." 4
dacs_admin.css
.RS 4
\%http://dacs.dss.ca/man//css/dacs_admin.css
.RE
.IP "10." 4
dacsacl(1)
.RS 4
\%http://dacs.dss.ca/man/dacsacl.1.html
.RE
.IP "11." 4
dacspasswd(1)
.RS 4
\%http://dacs.dss.ca/man/dacspasswd.1.html
.RE
.IP "12." 4
dacs.acls(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.acls.5.html
.RE
.IP "13." 4
dacs_conf(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_conf.8.html
.RE
.IP "14." 4
dacs_group(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_group.8.html
.RE
.IP "15." 4
dacs_list_jurisdictions(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_list_jurisdictions.8.html
.RE
.IP "16." 4
dacs_passwd(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_passwd.8.html
.RE
.IP "17." 4
dacs_version(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_version.8.html
.RE
.IP "18." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "19." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE