.\" 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: dacsvfs
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 02/19/2019
.\"    Manual: DACS Commands Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "DACSVFS" "1" "02/19/2019" "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"
dacsvfs \- access objects through the \fBDACS\fR virtual filestore
.SH "SYNOPSIS"
.HP \w'\fBdacsvfs\fR\ 'u
\fBdacsvfs\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR] [\fIitem_type\fR\ |\ \fIvfs_uri\fR\ |\ enabled] [\fB\-F\ \fR\fB\fIsep\fR\fR] [\fIop\fR\ [\fIarg\fR...]] 
.SH "DESCRIPTION"
.PP
This program is part of the
\fBDACS\fR
suite\&.
.PP
The
\fBdacsvfs\fR
utility is an interface to the
\fBDACS\fR
virtual filestore\&. It provides a way to examine, change, and delete items independently of how and where they are stored\&. See
\m[blue]\fBdacs\&.vfs(5)\fR\m[]\&\s-2\u[2]\d\s+2
and the
\m[blue]\fBVFS\fR\m[]\&\s-2\u[3]\d\s+2
directive for additional information\&.
.PP
To perform a virtual filestore operation, either an
\fIitem_type\fR
or a URI argument must be provided to identify the filestore\&. The former is used to find the applicable
\m[blue]\fBVFS\fR\m[]\&\s-2\u[3]\d\s+2
directive that has been configured for the specified jurisdiction (see
\m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[4]\d\s+2)\&.
.PP
As a special case, the word
\fBenabled\fR
can be specified; a list of enabled store names is printed to
stdout
and the program terminates:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsvfs \-q \-uj SomeJurisdiction enabled
.fi
.if n \{\
.RE
.\}
.PP
This program is also available as a
\fBDACS\fR
web service,
\m[blue]\fBdacs_vfs(8)\fR\m[]\&\s-2\u[5]\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
\fBSecurity\fR
.ps -1
.br
.PP
Only the
\fBDACS\fR
administrator should be able to successfully run this program\&. Because
\fBDACS\fR
keys and configuration files must be limited to the administrator, this will normally be the case, but a careful administrator will deny access to all other users\&.
.sp .5v
.RE
.SH "OPTIONS"
.PP
\fB\-F \fR\fB\fIsep\fR\fR
.RS 4
Sets the field separator character to
\fIsep\fR\&. The default is a colon\&. This is used by the
load
and
dump
operations\&.
.RE
.PP
If present, the
\fIop\fR
argument specifies the operation to be performed on the filestore\&. If it is omitted, the program enters interactive mode where most of the same operations are available (type "\fBhelp\fR" for assistance)\&. The following operations are available:
.PP
delete [\fIkey\fR]
.RS 4
Delete the item, or the item identified by
\fIkey\fR\&.
.RE
.PP
dump
.RS 4
Write to
stdout
the contents of the filestore as
\fIkey\fR, followed by the field separator character, followed by
\fIvalue\fR, one pair per line\&.
.RE
.PP
edit [\fIkey\fR]
.RS 4
Interactively edit the item, or the value of the item identified by
\fIkey\fR\&. When available, the environment variable
\fBEDITOR\fR
is used to determine which editor to use, otherwise a default editor specified at compile time is used\&. After editing, the user is asked for confirmation\&. If the operation is not aborted, the item or its value will be updated\&.
.RE
.PP
exists [\fIkey\fR]
.RS 4
Test if the item, or the item identified by
\fIkey\fR, exists\&. The outcome is reported to
stdout\&.
.RE
.PP
get [\fIkey\fR]
.RS 4
Retrieve the item, or the value of the item identified by
\fIkey\fR\&. If successful, the result is printed to
stdout\&.
.RE
.PP
getsize [\fIkey\fR]
.RS 4
Determine the size of the item, or the size of the value of the item identified by
\fIkey\fR\&. If successful, the result is printed to
stdout\&.
.RE
.PP
help
.RS 4
Prints a usage summary to
stderr\&.
.RE
.PP
list
.RS 4
Lists the names of all items (or keys) associated with the
\fIitem_type\fR\&.
.RE
.PP
load
.RS 4
Read key/value pairs from
stdin, one pair per line\&. The end of the key is denoted by the field separator character, which may be repeated\&. Whitespace may appear on either side of the field separator character (unless the field separator is a whitespace character)\&. For each
\fIkey\fR
do a
put
operation with the specified
\fIvalue\fR\&. This is intended to be a quick way to initialize a filestore or make many changes\&.
.RE
.PP
put [\fIkey\fR]
.RS 4
Replace the item, or the value of the item identified by
\fIkey\fR\&. The value is read from the standard input\&.
.RE
.PP
putval \fIkey\fR \fIvalue\fR
.RS 4
Replace the item, or the value of the item identified by
\fIkey\fR, and set it to
\fIvalue\fR\&.
.RE
.PP
rename [\fIoldkey\fR] \fInewkey\fR
.RS 4
Rename the item, or the value of the item identified by
\fIoldkey\fR
to
\fInewkey\fR\&.
.RE
.PP
update [\fIkey\fR]
.RS 4
This is a synonym for the
edit
operation\&.
.RE
.SH "EXAMPLES"
.PP
To store the DTDs used by
\fBDACS\fR
in a database rather than in a collection of files, you must configure an appropriate
VFS
directive and copy the files from the
\fBDACS\fR
distribution into the database\&. Because it is read\-only, this database can be shared by all federations and jurisdictions on the host\&.
.PP
The first step is to select the type of database to use and decide where to put it\&. This example will use a Berkeley DB database (\fBDACS\fR
must have been built with support for whichever database is used) and put it in
/usr/local/dacs/federations/dtds\&.db\&. The URI to express this in the
VFS
syntax looks like this:
.sp
.if n \{\
.RS 4
.\}
.nf
[dtds]dacs\-db:/usr/local/dacs/federations/dtds\&.db
.fi
.if n \{\
.RE
.\}
.PP
The next step is to create the database and load it with the DTDs\&. A simple shell script makes this easy to do\&. From the
dtd\-xsd
directory of the
\fBDACS\fR
distribution, and replacing
example\&.com
with the URI of a
\fBDACS\fR
jurisdiction on your host, execute:
.sp
.if n \{\
.RS 4
.\}
.nf
#! /bin/sh

for i in *\&.dtd
do
  dacsvfs \-u example\&.com \-q \e
      \*(Aq[dtds]dacs\-db:/usr/local/dacs/federations/dtds\&.db\*(Aq put $i < $i
done
.fi
.if n \{\
.RE
.\}
.PP
To configure
\fBDACS\fR
to use the database, a
VFS
directive must be put in an appropriate place in
dacs\&.conf
so that it overrides the current configuration:
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[dtds]dacs\-db:/usr/local/dacs/federations/dtds\&.db"
.fi
.if n \{\
.RE
.\}
.sp
To list the contents of the database you can do:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsvfs \-u example\&.com \-q \e
    \*(Aq[dtds]dacs\-db:/usr/local/dacs/federations/dtds\&.db\*(Aq list
.fi
.if n \{\
.RE
.\}
.sp
or since the
VFS
directive has been configured, simply:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsvfs \-u example\&.com \-q dtds list
.fi
.if n \{\
.RE
.\}
.sp
If you omit the
\fB\-q\fR
flag, various debugging output will appear, including some feedback that your new database is actually being used by
\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
If you copy any
\fBDACS\fR
resources, such as its DTDs, remember that when you upgrade your
\fBDACS\fR
software you\*(Aqll need to make new copies because these resources may have changed\&.
.sp .5v
.RE
.PP
Other resources used by
\fBDACS\fR
would be configured similarly\&. The
load
and
dump
operations can be particularly useful for this\&. If the file
/tmp/roles
associates roles with identities (e\&.g\&., as used by
\m[blue]\fBdacscheck(1)\fR\m[]\&\s-2\u[6]\d\s+2) as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
bobo:users
auggie:admin,users
harley:guest
.fi
.if n \{\
.RE
.\}
.sp
then the following command initializes or updates a database from that file:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsvfs \-u example\&.com \-q \-F ":" \e
    \*(Aq[myroles]dacs\-db:/usr/local/myapp/roles\&.db\*(Aq < /tmp/roles
.fi
.if n \{\
.RE
.\}
.sp
The URI
[myroles]dacs\-db:/usr/local/myapp/roles\&.db
can then be used with
\fBdacscheck\fR\&.
.SH "DIAGNOSTICS"
.PP
The program exits
0
if everything was fine,
1
if an error occurred\&.
.SH "BUGS"
.PP
There should be a caching mechanism that could be used with expensive storage types (i\&.e\&., those that are relatively slow to access, such as the
http
scheme)\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacs_vfs(8)\fR\m[]\&\s-2\u[5]\d\s+2,
\m[blue]\fBdacs\&.conf(5)\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[7]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2012 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[8]\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.vfs(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.vfs.5.html
.RE
.IP " 3." 4
VFS
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#VFS
.RE
.IP " 4." 4
dacs.conf(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html
.RE
.IP " 5." 4
dacs_vfs(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_vfs.8.html
.RE
.IP " 6." 4
dacscheck(1)
.RS 4
\%http://dacs.dss.ca/man/dacscheck.1.html
.RE
.IP " 7." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP " 8." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE