NAME

       dacsvfs - access objects through the DACS virtual filestore

SYNOPSIS

       dacsvfs [dacsoptions[1]] [item_type | vfs_uri | enabled] [-F sep] [op [arg...]]

DESCRIPTION

       This program is part of the DACS suite.

       The dacsvfs utility is an interface to the DACS virtual filestore. It provides a way to
       examine, change, and delete items independently of how and where they are stored. See
       dacs.vfs(5)[2] and the VFS[3] directive for additional information.

       To perform a virtual filestore operation, either an item_type or a URI argument must be
       provided to identify the filestore. The former is used to find the applicable VFS[3]
       directive that has been configured for the specified jurisdiction (see dacs.conf(5)[4]).

       As a special case, the word enabled can be specified; a list of enabled store names is
       printed to stdout and the program terminates:

           % dacsvfs -q -uj SomeJurisdiction enabled

       This program is also available as a DACS web service, dacs_vfs(8)[5].

           Security
           Only the DACS administrator should be able to successfully run this program. Because
           DACS 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.

OPTIONS

       -F sep
           Sets the field separator character to sep. The default is a colon. This is used by the
           load and dump operations.

       If present, the op 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 "help" for assistance). The following operations are available:

       delete [key]
           Delete the item, or the item identified by key.

       dump
           Write to stdout the contents of the filestore as key, followed by the field separator
           character, followed by value, one pair per line.

       edit [key]
           Interactively edit the item, or the value of the item identified by key. When
           available, the environment variable EDITOR 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.

       exists [key]
           Test if the item, or the item identified by key, exists. The outcome is reported to
           stdout.

       get [key]
           Retrieve the item, or the value of the item identified by key. If successful, the
           result is printed to stdout.

       getsize [key]
           Determine the size of the item, or the size of the value of the item identified by
           key. If successful, the result is printed to stdout.

       help
           Prints a usage summary to stderr.

       list
           Lists the names of all items (or keys) associated with the item_type.

       load
           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 key do a put operation with the specified value. This is intended
           to be a quick way to initialize a filestore or make many changes.

       put [key]
           Replace the item, or the value of the item identified by key. The value is read from
           the standard input.

       putval key value
           Replace the item, or the value of the item identified by key, and set it to value.

       rename [oldkey] newkey
           Rename the item, or the value of the item identified by oldkey to newkey.

       update [key]
           This is a synonym for the edit operation.

EXAMPLES

       To store the DTDs used by DACS in a database rather than in a collection of files, you
       must configure an appropriate VFS directive and copy the files from the DACS distribution
       into the database. Because it is read-only, this database can be shared by all federations
       and jurisdictions on the host.

       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 (DACS 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:

           [dtds]dacs-db:/usr/local/dacs/federations/dtds.db

       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 DACS distribution, and replacing
       example.com with the URI of a DACS jurisdiction on your host, execute:

           #! /bin/sh

           for i in *.dtd
           do
             dacsvfs -u example.com -q \
                 '[dtds]dacs-db:/usr/local/dacs/federations/dtds.db' put $i < $i
           done

       To configure DACS to use the database, a VFS directive must be put in an appropriate place
       in dacs.conf so that it overrides the current configuration:

           VFS "[dtds]dacs-db:/usr/local/dacs/federations/dtds.db"

       To list the contents of the database you can do:

           % dacsvfs -u example.com -q \
               '[dtds]dacs-db:/usr/local/dacs/federations/dtds.db' list

       or since the VFS directive has been configured, simply:

           % dacsvfs -u example.com -q dtds list

       If you omit the -q flag, various debugging output will appear, including some feedback
       that your new database is actually being used by DACS.

           Note
           If you copy any DACS resources, such as its DTDs, remember that when you upgrade your
           DACS software you'll need to make new copies because these resources may have changed.

       Other resources used by DACS 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 dacscheck(1)[6]) as follows:

           bobo:users
           auggie:admin,users
           harley:guest

       then the following command initializes or updates a database from that file:

           % dacsvfs -u example.com -q -F ":" \
               '[myroles]dacs-db:/usr/local/myapp/roles.db' < /tmp/roles

       The URI [myroles]dacs-db:/usr/local/myapp/roles.db can then be used with dacscheck.

DIAGNOSTICS

       The program exits 0 if everything was fine, 1 if an error occurred.

BUGS

       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).

SEE ALSO

       dacs_vfs(8)[5], dacs.conf(5)[4]

AUTHOR

       Distributed Systems Software (www.dss.ca[7])

COPYING

       Copyright2003-2012 Distributed Systems Software. See the LICENSE[8] file that accompanies
       the distribution for licensing information.

NOTES

        1. dacsoptions
           http://dacs.dss.ca/man/dacs.1.html#dacsoptions

        2. dacs.vfs(5)
           http://dacs.dss.ca/man/dacs.vfs.5.html

        3. VFS
           http://dacs.dss.ca/man/dacs.conf.5.html#VFS

        4. dacs.conf(5)
           http://dacs.dss.ca/man/dacs.conf.5.html

        5. dacs_vfs(8)
           http://dacs.dss.ca/man/dacs_vfs.8.html

        6. dacscheck(1)
           http://dacs.dss.ca/man/dacscheck.1.html

        7. www.dss.ca
           http://www.dss.ca

        8. LICENSE
           http://dacs.dss.ca/man/../misc/LICENSE