.\" 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.vfs
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 08/23/2020
.\"    Manual: DACS Formats Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "DACS\&.VFS" "5" "08/23/2020" "DACS 1.4.40" "DACS Formats 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.vfs \- the \fBDACS\fR virtual filestore
.SH "DESCRIPTION"
.PP
These files are part of the
\fBDACS\fR
suite\&.
.PP
The virtual filestore provides flexible ways for
\fBDACS\fR
and software built on top of
\fBDACS\fR
to obtain information regardless of how or where the information is stored\&. The
\fBDACS\fR
core accesses (almost) all configuration information through the virtual filestore layer, allowing information to be more easily shared and maintained, secured, or organized for better performance\&.
.PP
Sometimes it is easiest to store information in a regular file initially, where it can be modified using an ordinary text editor, but after some growth a database might improve performance\&. In some situations, accessing the information remotely, via HTTP, makes administration more convenient or is more secure\&. A goal of the virtual filestore is to make data storage alternatives easier to specify and change\&.
.SS "The vfs_uri and Item Types"
.PP
Many
\fBDACS\fR
components need to access data to perform their function\&. The documentation for a component will specify a reserved, case\-sensitive name called an
item type
for each data set that it may use\&. For example,
\m[blue]\fBdacspasswd(1)\fR\m[]\&\s-2\u[1]\d\s+2
identifies the account information that it manages by the name
passwds\&.
.PP
Item types start with an alphabetic character followed by zero or more alphanumerics, hyphens, and underscores\&. Item types used by
\fBDACS\fR
are always completely lower case\&. Some other item types used by
\fBDACS\fR
are
federation_keys
and
jurisdiction_keys
(used by
\m[blue]\fBdacskey(1)\fR\m[]\&\s-2\u[2]\d\s+2
and others), and
revocations
(used by
\m[blue]\fBdacs\&.acls(5)\fR\m[]\&\s-2\u[3]\d\s+2
and others)\&. The
\m[blue]\fBdacsconf(1)\fR\m[]\&\s-2\u[4]\d\s+2
command can list all reserved item types\&.
.PP
The
\m[blue]\fBVFS\fR\m[]\&\s-2\u[5]\d\s+2
directive is used to specify the mapping from an item type to a
vfs_uri, which describes where and how the information is stored\&. Some commands and functions take a
vfs_uri
as an argument to provide a default or override a default\&. A
vfs_uri
has the following syntax:
.sp
.if n \{\
.RS 4
.\}
.nf
vfs_uri \-> [ \*(Aq[\*(Aq \fIitem_type\fR \*(Aq]\*(Aq ] \fIURI\fR
.fi
.if n \{\
.RE
.\}
.sp
The general form of the URI syntax is (see
\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):
.sp
.if n \{\
.RS 4
.\}
.nf
\fIscheme\fR : [ // \fIauthority\fR] [\fIpath\fR] [\fIquery\fR] [\fIfragment\fR]
.fi
.if n \{\
.RE
.\}
.PP
The distribution\*(Aqs
conf/site\&.conf\-std
file (by default installed as
/usr/local/dacs/federations/site\&.conf; see
\m[blue]\fBdacs\&.install(7)\fR\m[]\&\s-2\u[8]\d\s+2) specifies defaults for many item types\&. For example, it defines the "roles file" (item type
roles; see
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[9]\d\s+2) as:
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[roles]dacs\-kwv\-fs:${Conf::FEDERATIONS_ROOT}/${Conf::FEDERATION_DOMAIN}/${Conf::JURISDICTION_NAME}/roles"
.fi
.if n \{\
.RE
.\}
.sp
For the hypothetical federation domain
example\&.com
and jurisdiction
J1, by default this would resolve to a file,
/usr/local/dacs/federations/example\&.com/J1/roles\&. That file might consist of entries like:
.sp
.if n \{\
.RS 4
.\}
.nf
julia:project1/dacs,admin,horses
sara:project2/dacs,project1/dacs,lps
sam:project2/dacs,project1/dacs
admin:root,project2/admin
.fi
.if n \{\
.RE
.\}
.PP
The default location of the
\fBDACS\fR
XML DTDs (item type
dtds) is defined as:
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[dtds]dacs\-fs:${Conf::DACS_HOME}/www/dtd\-xsd"
.fi
.if n \{\
.RE
.\}
.sp
By default, this would resolve to the directory
/usr/local/dacs/www/dtd\-xsd\&.
.PP
Refer to the
\m[blue]\fBVFS\fR\m[]\&\s-2\u[5]\d\s+2
directive for additional detail\&.
.SS "Virtual Filestore Details"
.PP
Each virtual filestore instance contains either an uninterpreted sequence of bytes (e\&.g\&., a Unix file or the output of a program) or an object that contains zero or more items, each of which is associated with a key (i\&.e\&., the name of an item relative in its virtual filestore context) and has an uninterpreted sequence of bytes as its value (e\&.g\&., a database file, a Unix file containing lines having a particular keyword/value structure, or a directory containing regular files)\&.
.PP
For maximum portability, a key should be composed of characters from the
\m[blue]\fBPortable Filename Character Set\fR\m[]\&\s-2\u[10]\d\s+2: any alphanumeric character, period, hyphen, or underscore\&. The true limitation on the character set depends on the underlying storage scheme and URI syntax constraints\&. There is no
\fIa priori\fR
limit on naming context or key length\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacsvfs(1)\fR\m[]\&\s-2\u[11]\d\s+2,
\m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[12]\d\s+2,
\m[blue]\fBdacs\&.install(7)\fR\m[]\&\s-2\u[8]\d\s+2,
\m[blue]\fBdacs_vfs(8)\fR\m[]\&\s-2\u[13]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[14]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2015 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[15]\d\s+2
file that accompanies the distribution for licensing information\&.
.SH "NOTES"
.IP " 1." 4
dacspasswd(1)
.RS 4
\%http://dacs.dss.ca/man/dacspasswd.1.html
.RE
.IP " 2." 4
dacskey(1)
.RS 4
\%http://dacs.dss.ca/man/dacskey.1.html
.RE
.IP " 3." 4
dacs.acls(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.acls.5.html
.RE
.IP " 4." 4
dacsconf(1)
.RS 4
\%http://dacs.dss.ca/man/dacsconf.1.html
.RE
.IP " 5." 4
VFS
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#VFS
.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.install(7)
.RS 4
\%http://dacs.dss.ca/man/dacs.install.7.html
.RE
.IP " 9." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#local_roles
.RE
.IP "10." 4
Portable Filename Character Set
.RS 4
\%http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap03.html#tag_03_276
.RE
.IP "11." 4
dacsvfs(1)
.RS 4
\%http://dacs.dss.ca/man/dacsvfs.1.html
.RE
.IP "12." 4
dacs.conf(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html
.RE
.IP "13." 4
dacs_vfs(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_vfs.8.html
.RE
.IP "14." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "15." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE