dacs

DACS(1)                      DACS Commands Manual                      DACS(1)



NAME
       dacs - a distributed access control system

SYNOPSIS
       dacs [-v | --verbose] [--dumpenv] [--license] [--version]

       dacs dacs-command [dacsoptions[1]] [...]

       dacs-command [-u uri-prefix | -uj jurisdiction-name | -un |
                    -up jurisdiction-name | -us] [-c dacs.conf]
                    [-sc site.conf] [-ll logging-level] [-format fmt] [-q]
                    [-t] [-Dname=value]
                    [-v | --verbose] [--dumpenv] [--enable-dump] [--license]
                    [--std] [--version]

DESCRIPTION
       This program is part of the DACS suite.

       DACS is a general-purpose, Web-based authentication and access control
       system. It provides single sign-on functionality and flexible access
       control to content and services provided by web servers.  DACS consists
       of an Apache module (mod_auth_dacs[2]) through which Apache
       communicates with DACS to make access control decisions, a suite of CGI
       programs that provide DACS web services, and a collection of utility
       commands that provide various support and administrative functions for
       DACS. Some of these utilities, such as dacshttp(1)[3] and
       sslclient(1)[4], are completely general-purpose.

       The DACS access control engine and authentication components can also
       be used from the command line, within a CGI environment or completely
       independently of the Web.

       For important information about DACS, including installation
       instructions, please see dacs.readme(7)[5] and dacs.install(7)[6].

   About DACS
           NO WARRANTY
           This software is provided by Dss "as is" and any express or implied
           warranties, including, but not limited to, the implied warranties
           of merchantability, fitness for a particular purpose, or
           non-infringement, are disclaimed. In no event shall Dss be liable
           for any direct, indirect, incidental, special, exemplary, or
           consequential damages (including, but not limited to, procurement
           of substitute goods or services; loss of use, data, or profits; or
           business interruption) however caused and on any theory of
           liability, whether in contract, strict liability, or tort
           (including negligence or otherwise) arising in any way out of the
           use of this software, even if advised of the possibility of such
           damage.

       By convention, the names of all DACS web services begin with the prefix
       "dacs_" (e.g., dacs_conf). Starting with release 1.4.17, all commands
       that implement DACS functionality begin with the prefix "dacs" (e.g.,
       dacsconf). Many DACS web services have command analogues. The names of
       web services that are used internally by DACS (i.e., they are never
       called directly by users) begin with "local_" (e.g.,
       local_passwd_authenticate). General-purpose web services and commands
       do not follow a naming convention, other than not using any of the
       previously mentioned prefixes.

       The document type definitions (DTDs) that are maintained in the dtd-xsd
       directory are used to document file formats or describe the arguments
       to a DACS web service or its reply. In the current implementation,
       these DTD files are not used during XML validation. Attributes of type
       CDATA may have additional constraints on their values; consult the
       relevant documentation. The files are technically not valid DTDs,
       because they lack a document type declaration (DOCTYPE); an appropriate
       DOCTYPE is generated programmatically at the time a DTD is emitted.

           Important
           DACS does not prevent certain kinds of attacks against web sites,
           such as Denial of service attacks[7], Cross-site scripting (XSS)[8]
           or Cross-site request forgery (CSRF)[9]. When combined with
           appropriate web site protective measures, however, DACS does
           provide mechanisms to make these types of attacks more difficult.

   About the Manual Pages
       The technical documentation for DACS consists of a set of manual pages.
       In the HTML collection, an index page[10] includes a table of contents,
       links to special annotations within the technical documentation, and
       lists of variables, configuration directives, and XML Document Type
       Definitions.

           Tip
           Each HTML manual page contains a font size selection tool near its
           bottom. If JavaScript is enabled, the currently selected font size
           can be changed and a global preference set. To choose a font size
           for the current page, click on one of the four boxes. To make the
           current selection your preference across manual pages, site visits,
           and browser sessions, click on the "set" button, which will set an
           HTTP cookie. If a preference has not been set in this way (i.e.,
           there is no cookie) and a manual page is visited with the query
           parameter DACSMANFONT set to 0, 1, 2, or 3 (representing smallest
           to largest point sizes), the corresponding font will be selected
           and the preference automatically set (if a preference has been set,
           the parameter is ignored).

       Areas of the documentation labeled "Security" discuss important
       security considerations; please pay special attention to them. Areas
       labeled "Tip" provide pointers to time-saving (and sometimes
       aggravation-reducing) techniques and recommended practices.

       In pathnames and URLs that appear in examples, the text "..."
       represents text that has been omitted because it is not relevant to the
       discussion at hand, or which may vary depending on configuration
       details, such as where something has been installed (e.g.,
       .../dacs/bin/dacshttp).

       Unless otherwise stated, URLs used in examples are fictitious and most
       likely will not work. The reserved domain name example.com is often
       used (RFC 2606[11]).

       In instructions and examples, a '%' is generally used to signify a
       command line prompt:

           % date
           Sun Apr  1 15:33:11 PDT 2007

       Sometimes another character is used to signify a prompt, however, such
       as when demonstrating the interactive mode of dacsexpr(1)[12]:

           > 1 + 1
           2

       An extended form of BNF notation[13] is used to describe syntax
       concisely. We hope it is both understandable and familiar, but some
       inconsistencies and ambiguities may occur throughout the documentation;
       this is being improved slowly. A term in a production may include a
       regular expression type specification, with '+' meaning one or more
       occurrences of the term, and '*' zero or more occurrences. Any one of a
       set of characters is specified within square brackets, and a range of
       consecutive characters (in ASCII code sequence) is separated by a
       hyphen (e.g., [A-Za-z0-9\-_]+ means "one or more alphabetic characters,
       digits, hyphens, or underscores"). In other contexts, square brackets
       indicate an optional term. Single and double quotes specify literal
       characters. Note that XML DTDs use their own syntax, which is somewhat
       different, and in some cases grammars followed in relevant RFCs are
       respected for clarity or in examples.

   Key Concepts
       Some of the key concepts used throughout the DACS documentation are
       defined in this section.

       account
           A persistent record that associates an identity (or username) with
           state information about the account (such as whether the account is
           enabled or disabled), information that is required to authenticate
           the identity (such as a digest of a password string), and possibly
           other sign-on related information. Note that DACS identities do not
           necessarily have a corresponding account.  DACS does not provide
           mechanisms to administer "foreign" account types; for instance,
           although it can authenticate against them, it cannot create or list
           Unix or Windows accounts.

       authentication
           The procedure by which a person or program obtains credentials that
           represent a DACS identity, usually by asserting a DACS username
           that represents an identity and providing information that only
           that identity is likely to know or possess. After successful
           authentication, a person or program is said to have authenticated.
           DACS can interface with a wide variety of authentication methods
           and provides some of its own; new methods can easily be added.

       authorization
           The procedure that determines, in a particular context, whether a
           request for a given resource or object should be allowed. If an
           identity is authorized to perform a certain operation on the
           object, access is granted, otherwise it is denied. Access control
           rules are one method of describing which identity or identities
           should be granted - or denied - access to a particular resource.
           Coarse-grained access control involves making a high-level decision
           of whether access to an object should be granted; this is usually
           an all-or-nothing decision. Fine-grained access control is used
           within a program to decide whether access to a lower-level resource
           (some data, an administrative function, a menu) should be granted.

           Note that unlike some systems, DACS does not predetermine which
           resources a particular user (identity) can and cannot access; that
           is, an administrator does not make a list of what rights each user
           has. Authorization is always determined by rule evaluation, in real
           time, when a user requests a resource. The only exemptions to this
           are some optional features: Authorization Caching[14] and
           Rlinks[15].

       credentials
           If authentication is successful, DACS returns information that can
           be used in subsequent operations to represent the authenticated
           identity. Credentials contain information about the identity, such
           as its name, and meta information, such as the time at which the
           credentials expire and become invalid. Credentials are protected
           cryptographically so that they are difficult to forge or alter.
           They must be kept secret, so that the identity cannot be used by
           anyone other than its owner, and must accompany a request made to a
           server so that DACS knows who is making the request. The particular
           mechanism used for this is not important provided credentials
           cannot be copied and reused; transporting credentials using the
           payload of an HTTP cookie over an SSL connection is typical,
           although sending credentials as the value of an HTTP extension
           header is another possibility.

           Although there is no specific limit on the size of credentials as
           far as DACS is concerned, since they can be encapsulated within an
           HTTP cookie and returned to a browser, constraints on cookies
           imposed by browsers should be carefully considered.

           Any jurisdiction can understand credentials produced by any other
           jurisdiction within the same federation. Therefore, a user only
           needs to be authenticated once to access web services at any
           jurisdiction using that identity.

           Note that in DACS, credentials do not give their owner any rights
           or convey any authorization; DACS is not a capability-based
           system[16]. Credentials simply represent a DACS identity.

           Refer to dacs_authenticate(8)[17] for details.

       current request
           The event that has triggered the authorization check being
           processed by dacs_acs(8)[18] is referred to as the current request.
           For a request for a DACS-wrapped web resource, this will be the
           HTTP request that is received by the web server for the resource.
           In situations where dacs_acs is not involved, such as when
           dacscheck(1)[19] or dacsexpr(1)[12] are used, the current request
           and its context are specified by command line arguments or are
           obtained from the execution environment[20].

           dacs_acs uses ${DACS::URI} as the path component of the current
           request. It is obtained from Apache's uri element of the current
           request_rec. This is the string that is used to match against
           access control rules.

           Other DACS components determine the current HTTP request by
           examining several environment variables: HTTP_HOST (or SERVER_NAME
           and SERVER_PORT), REQUEST_URI, QUERY_STRING, and HTTPS.

           The value of ${DACS::URI} and the path component of
           ${Env::REQUEST_URI} are not necessarily the same. After an internal
           redirect, for example, the latter's value is from the original URL,
           while the former's is from the target of the redirection.

           The current request string is important because it may be used to
           determine the current federation[21] and current jurisdiction[22],
           and because it is used when searching for the access control rule
           to apply to the request.

       DACS
           Consisting of CGI-based web services, an Apache 2.0/2.2 module, and
           a collection of utilities, DACS provides authentication and
           authorization functionality. Transparent, coarse-grained role-based
           access control is available for web resources.

           Programmatic, general-purpose role-based access control is
           available for virtually any program (using dacscheck(1)[19]). This
           is completely decoupled from Apache.

       DACS administrator
           An individual (or individuals) responsible for managing the
           operation of DACS is called a DACS administrator (sometimes just
           "the administrator"). This individual is not necessarily a system
           administrator (e.g., superuser or root), although a small number of
           optional components of DACS must execute as user or group root. The
           DACS administrator need not be an Apache administrator; once Apache
           has been configured for DACS it typically requires very few
           modifications thereafter. The DACS administrator is responsible for
           configuring and testing DACS (probably installing and upgrading it,
           too), managing user accounts and access control rules, safeguarding
           security, backing up configuration and data files, and so on. The
           design of DACS allows some delegation of responsibility, largely
           based on file permissions. When invoked as a web service, each of
           the identities configured as a ADMIN_IDENTITY[23] is effectively a
           DACS administrator; in this context, the system superuser has no
           significance.

       DACS identity
           Each authenticated user is assigned a name that consists of the
           name of the authenticating jurisdiction, its federation name, and a
           username. Each of these naming components must be syntactically
           correct. In some contexts the federation name is implicit;
           sometimes the jurisdiction name is also implicit. Entities such as
           individuals (people, but also programs, devices, etc.),
           federations, jurisdictions, and groups have names. It is the
           responsibility of jurisdictions to authenticate users. The syntax,
           meanings, and uniqueness of names is also a jurisdictional issue,
           and perhaps a federation-wide issue as well.

           Each real world entity typically has a unique DACS identity, but
           this is left up to authenticating jurisdictions. Two or more
           identities are distinct if they do not refer to the same real world
           individual.  Federated identity or single sign-on (SSO) is the
           ability to recognize a user identity across jurisdictions and even
           across federations.

               Important
               Keep in mind that regardless of the authentication method and
               account information used, two identical usernames (relative to
               the same jurisdiction and taking into account NAME_COMPARE[24])
               are implicitly assumed to refer to the same identity by DACS.
               For instance, someone who authenticated as auggie by providing
               the correct Unix password is virtually indistinguishable from
               someone who authenticated as auggie using an Information Card.
               User credentials include information about the authentication
               method involved in their creation and the user()[25] function
               can be used to obtain this information, but it would be unwise
               to base identities on this. It is strongly advised that a new
               DACS jurisdiction carefully develop an extensible plan for user
               naming.

       DACS-wrapped
           A web resource is said to be DACS-wrapped if the web server
           responsible for the resource calls DACS (more specifically,
           dacs_acs(8)[18]) to make an access control decision whenever it
           receives a request for the resource.

       federation
           A DACS federation consists of one or more jurisdictions. The
           jurisdictions comprising a federation coordinate information
           sharing through light-weight business practices implemented as a
           requirement of membership in a DACS federation; in other words, the
           members of a federation typically agree to observe certain rules of
           conduct to preserve overall security and so that users can obtain
           maximum benefit. A federation consisting of just one jurisdiction
           is not unusual.

       item type
           An item type is a name that maps to a VFS[26] (virtual filestore)
           specification that configures how and where data is stored. The
           level of indirection that they provide means that access control
           rules, for example, can be configured to be in regular files, a
           Berkeley DB database, a remote database accessed by HTTP, and so on
           - all that is required is that the item type acls be properly
           configured. Some item types (like acls) are reserved and have
           special meaning to DACS, while others can be used by a DACS
           administrator for other purposes. An item type name is case
           sensitive and consists of alphanumerics, hyphens, and underscores,
           but must begin with an alphabetic character.

       jurisdiction
           A DACS jurisdiction is an autonomous administrative entity that
           authenticates its users, provides web services, or both. It may
           correspond to an organization, department, web server, or virtual
           host. Jurisdictions are sometimes created simply as an
           administrative convenience. Each jurisdiction is assigned a unique
           name within a federation.

           A user's home jurisdiction is a jurisdiction that can authenticate
           that user. In situations where a user has multiple credentials
           obtained from different jurisdictions, the effective home
           jurisdiction for a request depends on which credentials are
           selected during authorization processing. Configuration directives
           are available to restrict the number of sets of credentials that
           may accompany a request.

       user agent
           A user agent is client-side software that interacts with other
           software (a server application, typically) on behalf of a user. A
           user is often a person but can also be software. A web browser,
           which is used to interact with a web server, is an example of a
           user agent.

   Naming
       DACS needs to name a variety of things so that they can be referred to
       in expressions, access control rules, configuration directives, and so
       on. While the URI syntax is used to name some kinds of objects within
       DACS, DACS also has its own concise naming schemes.

           Note
           The terms current federation (current jurisdiction) and this
           federation (this jurisdiction) are used in the documentation to
           refer to the federation (jurisdiction) associated with the
           configuration context in effect while DACS processes a request.

           In general, the federation-name component of a name is optional; if
           absent, the current federation is assumed. Similarly, the
           jurisdiction-name may be elided and the current jurisdiction is
           implied.

       Federations
           Syntax:

               federation-name::

           Example:

               DEMO::

           The federation-name (usually obtained from a FEDERATION_NAME[27]
           configuration directive) must begin with an alphabetic character
           and is followed by zero or more alphanumerics, hyphens, and
           underscores. A federation-name is ordinarily treated case
           sensitively (but see the NAME_COMPARE[24] configuration directive
           and the user()[25] function for alternate behaviours). There is no
           a priori limit on its length.

           The FEDERATION_DOMAIN[28] directive specifies the domain name
           suffix common to all jurisdictions in a federation.

       Jurisdictions
           Syntax:

               [[federation-name:: | [::]] jurisdiction-name:

           Examples:

               DEMO::DSS:
               ::DSS:
               DSS:

           The jurisdiction-name (usually obtained from a
           JURISDICTION_NAME[29] configuration directive) must begin with an
           alphabetic character and is followed by zero or more alphanumerics,
           hyphens, and underscores. A jurisdiction-name is ordinarily treated
           case sensitively (but see the NAME_COMPARE[24] configuration
           directive and the user()[25] function for alternate behaviours).
           There is no a priori limit on its length.

       Users
           Syntax:

               [[[federation-name:: | [::]] jurisdiction-name]:username

           Examples:

               DEMO::DSS:auggie
               ::DSS:auggie
               DSS:auggie
               :auggie

           A full DACS identity includes a federation name component and a
           jurisdiction name component, in addition to the username. It is
           provided to DACS-wrapped programs as the value of the
           DACS_IDENTITY[30] environment variable.

           The username component, which is available to CGI programs as the
           value of the DACS_USERNAME[31] environment variable, consists of
           one or more ASCII characters from the set of upper and lower case
           alphabetics, digits, and the following punctuation characters:

               ! # $ % & ' - . ; ? @ [ ^ _ ` { }

           All characters having a value less than 041 (octal) or greater than
           0176 (octal) are invalid, as are the following characters:

               * , : + ( ) ~ < > = | \ / "


               Notes
               •   In addition to the alphanumeric characters, RFC 2396[32]
                   allows only the following characters ("pchar") to appear in
                   the path component of a URI:

                       - _ . ! ~ * ' ( ) % : @ & = + $ ,


               •   Some valid email addresses are not valid DACS usernames.
                   For example, *bob*@example.com, "(bob)"@example.com, and
                   \(bob\)@example.com are valid mailbox names as defined by
                   RFC 822[33] (Appendix D) and discussed in RFC 3696[34]
                   (Section 3), but both are invalid as DACS usernames. Unless
                   quoted, the local-part component of an email address, which
                   precedes the "@" character in the addr-spec, may not
                   contain any of:

                       ( ) <  > @ , ; : \ " . [ ]

                   Additionally, the space and all US-ASCII control characters
                   (octets 0 - 31) and DEL (127) are disallowed. Without
                   quotes, the local-part may consist of any combination of
                   alphabetics, digits, or any of the following characters:

                       ! # $ % & ' * + - / = ?  ^ _ ` . { | } ~

                   A period (".") may be used, but may not start or end the
                   local-part, nor may two or more consecutive periods appear.
                   Within double quotes, any ASCII character may appear if
                   properly quoted (e.g., Auggie."
                   ".O."\'".Doggie@example.com). The maximum length of the
                   local-part is 64 characters, and the maximum length of the
                   domain component that appears after the "@" character is
                   255 characters.

                   There is currently no way to "quote" a DACS username, so
                   some safe encoding method or transformation must be applied
                   to these names.

               •   DACS may create identities for internal use having username
                   components that include characters that are normally
                   invalid.

               •   A username is case sensitive (but see the NAME_COMPARE[24]
                   configuration directive and the user()[25] function for
                   alternate behaviours). There is no a priori limit on its
                   length.

               •   The recommended practice is for jurisdictions to map their
                   DACS usernames to lower case during the authentication
                   procedure where possible and when the mappings are unique.
                   The EXIT*[35] directive may be used for this purpose.

       Groups
           Syntax:

               [[federation-name:: | [::]] %[jurisdiction-name]:groupname

           A groupname must begin with an alphabetic character and may be
           followed by any number of alphanumeric, hyphen ("-"), and
           underscore ("_") characters.

           Examples:

               %DEMO::DSS:friends
               %::DSS:friends
               %DSS:friends
               %:friends


       Roles and Role Descriptors
           Syntax:

               Role-Descriptor -> Empty-String | Role-List

               Role-List       -> Role | Role "," Role-List

               Role            -> Basic-Role | Composite-Role

               Basic-Role      -> [A-Za-z0-9\-_]+
               Composite-Role  -> Basic-Role "/" Basic-Role | Basic-Role "/" Composite-Role

               Empty-String    -> ""

           A role descriptor string (also called a role string or a role
           descriptor) consists of a comma separated list of roles. The name
           of a role (a Basic-Role) is constructed from upper and lower case
           letters, digits, hyphens, and underscores. A Composite-Role is
           constructed from two or more Basic-Role terms, separated by a slash
           character. Here are three examples of a role descriptor:

               admin,wheel,root
               admin/hardware
               networks/programming,computer-science/systems/Project_X


               Note
               A role descriptor string contains no white space characters and
               may not begin or end with a comma or slash character. Two or
               more consecutive commas are illegal, as are two or more
               consecutive slashes.
           The setvar()[36] function can be used to separate a composite role
           into its basic roles.

           Please refer to dacs.groups(5)[37] for additional information.

       Concise User Syntax
           Syntax:

               ident     -> '{' kwv-list '}' | user
               kwv-list  -> kwv [',' kwv]*
               kwv       -> kwv-user | kwv-group | kwv-attr | kwv-ip | kwv-expires
               kwv-user    -> 'u=' [Q] user [Q]
               kwv-group   -> 'g=' [Q] groups [Q]
               kwv-attr    -> 'a=' [Q] attr [Q]
               kwv-expires -> 'e=' [Q] expires [Q]
               kwv-ip      -> 'ip=' [Q] ip-addr [Q]

               user      -> simple-name | DACS-identity
               groups    -> group [',' group]*
               group     -> groupname | role-descriptor
               attr      -> any-alphabetic
               ip-addr   -> any-IP-addr
               expires   -> +rel-secs | date

           where:

           •   Q is an optional (matched) quote character;

           •   whitespace may optionally precede most tokens;

           •   a DACS-identity is a full or abbreviated DACS identity[38]

           •   a simple-name is the username component of a DACS identity
               (i.e., without any colons); consequently in this context a
               "special" name, such as auth, is treated as :auth

           •   role-descriptor must be a valid DACS role string and groupname
               must be a valid DACS group name (see dacs_authenticate(8)[39]
               and dacs.groups(5)[40]);

           •   an IP address is expressed in the Internet standard numeric dot
               notation (e.g., 10.0.0.1); and

           •   the lifetime of credentials derived from the identity can be
               expressed either as a given number of seconds (e.g, "e=+3600")
               or a given date in one of the following formats (see
               strptime(3)[41]):

                   %a, %d-%b-%Y %H:%M:%S GMT
                   %d-%b-%Y
                   %b %d, %Y
                   %b %d
                   %Y-%m-%dT%H:%M:%SZ

               When necessary, dates are interpreted relative to the current
               time or date. The lifetime is converted to its canonical form,
               which is the absolute time and date in seconds since the Epoch,
               based on the jurisdiction's clock. A date in the past can be
               specified; this might be useful for testing, for instance. If
               the identity is not used to create credentials, the expiry date
               is ignored, although it must be syntactically correct.

           •   the only supported attribute value is "a", which means that the
               identity should be treated as an ADMIN_IDENTITY[23] (refer to
               the -admin flag of dacscheck(1)[19]).

           A name expressed in the concise syntax, gives a username and,
           optionally, roles and attributes for the identity. It is used by
           dacscheck(1)[19], for instance.

   The dacs Utility
       DACS utility commands are usually installed as separate binaries, but
       DACS can (also or instead) be built with most of them combined into a
       single binary that is installed as dacs. The various utility programs
       may then be run as:

           % dacs dacs-command [dacsoptions] [command-options]

       For example:

           % dacs dacskey -u foo.myfed.com outfile

       Running the dacs utility without arguments will show the list of
       available sub-commands.

   Start-up Processing
       Most DACS programs perform the following actions when they start:

        1. Determine the "mode" in which they should operate; for example, if
           the REMOTE_ADDR environment variable is present, programs will in
           general assume they should run as a web application rather than as
           a utility command

        2. Process a standard set of command line arguments (dacsoptions[42])

        3. Set the process umask to 007 to disallow world access for any
           created files

        4. Disable a core dump so that sensitive information cannot be
           revealed by examining them (but see --enable-dump[43])

        5. Refuse to operate if any configuration file cannot be found or has
           an error

        6. For web services, make the DACS home directory the current working
           directory

        7. If "secure mode" has been enabled, web services will only process
           HTTPS requests

        8. Verify that the version required by a request is compatible with
           the version of DACS receiving the request

        9. Process any program-specific command line arguments.

       DACS programs make an effort to destroy sensitive information (such as
       passwords) as soon as it is no longer needed and not to write
       potentially sensitive information to log files unless specifically
       configured to do so.

   Internals
       Some DACS components may call other components using HTTP (possibly
       over SSL, depending on configuration). For example, authentication
       modules may be invoked as web services by dacs_authenticate(8)[39]. In
       all cases, these "internal" HTTP calls may not result in a redirection,
       such as through a 302 Found status code. Although this can sometimes be
       an inconvenience, it is, in part, a security measure.

           Tip
           When debugging a problem that may involve an internal HTTP request
           (especially related to authentication), verify that DACS is not
           receiving a redirect. Internal HTTP requests may also fail
           mysteriously because of incorrect or incomplete configuration of
           SSL parameters. Internal HTTP requests over SSL use
           sslclient(1)[4], as does the dacshttp(1)[3] command. If you suspect
           that an https-schemed URL may not be working, debug the problem
           using sslclient and then dacshttp.

       To maintain data consistency, DACS creates exclusive locks using the
       fcntl(2)[44] system call on files written in the directory configured
       through the TEMP_DIRECTORY[45] directive.

   Logging
       Most DACS services and utilities write various kinds of messages to one
       or more log files. These messages can be invaluable when trying to
       figure out what DACS is doing, for security audits, or to see which
       DACS-wrapped resources are being accessed and in what ways.

       Please refer to dacs.conf(5)[46] for information about configuration
       directives related to logging. An assortment of command line flags,
       described below, are also related to logging.

           NoteDACS can emit log messages before configuration processing is
               complete and configuration directives associated with logging
               are not in effect during this startup interval.

           •   Because mod_auth_dacs[2] is an Apache module, the Apache
               logging directives apply to it (and not the DACS directives)
               and its log messages are written to Apache log files.

           •   Log files can quickly become large, especially when the logging
               level is set to debug or trace levels. Consider daily rotation
               or truncation.

           •   The text of a log message may occasionally span several lines.

       The default value of the LOG_FORMAT[47] directive, which controls the
       appearance of log messages, is defined in include/local.h as
       LOG_FORMAT_DEFAULT_WEB for DACS web services and LOG_FORMAT_DEFAULT_CMD
       for everything else. Here is a typical log message:

           [Wed Jul 12 12:37:09 2006] [trace] [83648,1060,-] [dacs_acs:"acslib"] Allow
           clause grants access

       Audit-Class Log Messages
           In the case of audit-class messages, a string within parentheses
           may sometimes follow an identity, as in the examples below. This
           string, called a tracker, associates log messages with a particular
           origin and can be used to trace a user's sequence of service
           requests using log messages throughout a federation. This can be
           useful when debugging, looking for security problems, or forensic
           analysis.

           For an unauthenticated user, the tracker can only be derived
           heuristically, from elements of the execution context. The user's
           IP address, user agent string, and SSL client certificate, when
           available, are used. If two of these tracker strings differ, the
           requests are typically coming from different hosts, browsers, or
           users, but this is not necessarily always the case. Similarly, if
           the same tracker string is associated with two log messages, the
           service requests are not necessarily being issued by the same user.

           For an authenticated user, the tracker string consists of the
           heuristically-derived string, followed by a comma, followed by a
           string uniquely associated with the user's credentials. This
           tracker has a high probability of being unique and having a
           one-to-one mapping with a particular user.

           Consider these (condensed) log file entries:

               [Wed Jul 12 15:56:24 2006] [notice] [83963,1067,A] [dacs_acs:"authlib"]
                *** Access granted to unauthenticated user (7vJLWzv5) from 10.0.0.124
                for /cgi-bin/dacs/dacs_current_credentials

               [Wed Jul 12 15:56:27 2006] [notice] [83965,1073,A] [dacs_acs:"authlib"]
                *** Access granted to unauthenticated user (7vJLWzv5) from 10.0.0.124
                for /cgi-bin/dacs/dacs_authenticate

               [Wed Jul 12 15:56:27 2006] [debug] [83966,172,A] [dacs_authenticate:"authlib"]
                Authentication succeeded for HOME:bobo (7vJLWzv5,wA/Pudyp3f0)

               [Wed Jul 12 15:56:30 2006] [notice] [83973,1078,A] [dacs_acs:"authlib"]
                *** Access granted to DSS::HOME:bobo (7vJLWzv5,wA/Pudyp3f0)
                from 10.0.0.124 for /cgi-bin/dacs/dacs_current_credentials

           In the first two of the log messages above, the tracker 7vJLWzv5
           appears, meaning that the two requests probably came from the same
           (unauthenticated) user. With the third log message, the user has
           been authenticated and the tracker 7vJLWzv5,wA/Pudyp3f0 is used.
           Because these trackers all share the same prefix, the first two
           requests probably also came from someone who authenticated as
           DSS::HOME:bobo. The last request, for
           /cgi-bin/dacs/dacs_current_credentials, definitely came from that
           user. If this user were to signout and then issue more service
           requests anywhere in the federation DSS, each log message would
           contain the tracker 7vJLWzv5.

               Security
               Tracking the requests of anonymous users reliably is difficult
               to do well. A cookie-based approach may do better in some
               situations but has its own drawbacks (such as being totally
               ineffective when the user has disabled cookies).

   Tracking User Activity
       DACS includes a feature, enabled as a build-time option (see
       dacs.install(7)[48]), whereby a jurisdiction can track the activity of
       all of its users (i.e., those users that authenticate at the
       jurisdiction). Each successful authentication event, explicit signout
       event, and user-submitted web service request event can be recorded at
       the user's home jurisdiction in the format defined by
       dacs_user_info.dtd[49]. This information can be valuable for getting a
       better understanding of what is happening in a federation, including
       helping to diagnose performance and security issues. It is the basis of
       features like displays of recent account activity, and it might also be
       used to create new capabilities, such as a concurrent login limit or an
       adaptive authentication component to implement layered authentication
       or risk-based authentication.

       To specify where and how a home jurisdiction should maintain these
       records, the user_info item type must be defined at that jurisdiction;
       if it is not defined, no records will be written at that jurisdiction,
       although the jurisdiction will still try to send event records to other
       jurisdictions. For maximum benefit, the feature should be enabled at
       all jurisdictions in a federation since all user activity throughout
       the federation can then be logged.

       If a jurisdiction wants to monitor the activity of its users at other
       jurisdictions, it must allow those jurisdictions to invoke its
       dacs_vfs(8)[50] service by adding an appropriate access control rule.

           Security
           It is critical for any such rule to require the dacs_admin()[51]
           predicate.

           Note
           •   The dacs_admin(8)[52] tools provides an interface to these
               records. It should eventually be extended to collect and
               organize records found at all jurisdictions in a federation to
               facilitate analysis. Because they are text files with a
               relatively simple format, administrators should not find it
               difficult to apply common text processing tools or write short,
               custom programs for this purpose. Commands analogous to
               last(1)[53], who(1)[54], and sa(8)[55] are being considered.

           •   Each jurisdiction should write records to its own place (i.e.,
               jurisdictions should not share the same VFS object for
               user_info).

           •   This database will grow indefinitely; an administrator is
               responsible for rotating or truncating it. If previous and
               active sign on information is important (see
               dacs_current_credentials(8)[56]), prune only the request
               records (i.e., the acs elements). Another acceptable method is
               to discard (or archive) some proportion of older records (say,
               half) and keep some of the newer records.

           •   The data format is subject to change.

           •   A directive to enable or disable this feature at run-time may
               be added.

           •   Internal administrative events are not recorded.

           •   Because logging off (via dacs_signout(8)[57]) is optional, the
               end of a session can sometimes only be inferred or approximated
               from the expiry of credentials or the time of the last recorded
               event.

OPTIONS
       DACS programs and web services get much of their run-time configuration
       information by reading configuration files and examining environment
       variables. Some configuration information can be provided at
       compile-time. Several command line flags may be used to override
       default behaviour.

           Note
           •   All dacsoptions flags are processed left-to-right and must
               appear before any command-specific flag or argument. The first
               flag or argument that is not recognized as one of the
               dacsoptions terminates the list.

           •   The most important dacsoptions are those that specify the
               location of configuration files and identify the jurisdiction
               section to use within a configuration file. Depending on the
               program and how it is used, configuration information may not
               be needed, may be optional, or may be required.

           •   At most one of the command line flags to select a jurisdiction
               section can be specified. Refer to dacs.conf(5)[46] for
               additional information on the configuration file and
               configuration processing.

       Many DACS utilities recognize the following standard options, which are
       called dacsoptions:

       -c dacs.conf
           This tells DACS where it can find a configuration file for the
           jurisdiction on whose behalf it is acting. If this argument is not
           present, depending on how it was built, DACS may either try to use
           a compile-time specified file or it will try to use the value of
           the environment variable DACS_CONF[58]. For details, refer to
           Locating dacs.conf and site.conf[59].

       -Dname=value
           The effect of this flag is to define variable name (which must be
           syntactically valid) in the DACS namespace to have the value value.
           Any quotes around value are retained, provided the shell has not
           already stripped them off. This flag may be repeated. These
           variables can subsequently be tested during configuration
           processing and rule processing; for example, the value of a
           configuration directive might depend on the value of a dacsoptions
           flag. Defining a name that happens to correspond to a dacsoptions
           flag has no effect other than to create the variable.

           All dacsoptions flags (excluding this one) are automatically added
           to the DACS namespace as they are processed. A flag that is a
           "singleton" (e.g., -q) is initially assigned a value of one and is
           incremented on each subsequent appearance. A flag of the form
           -flagvalue is equivalent to -D-flag=value. Unused flags are
           undefined; if -q is not given, ${DACS::-q} will not be defined. For
           those flags that have synonyms, a variable for each synonym is
           created. If the name is used, explicitly or implicitly, later
           values replace earlier ones.

           For example, if the dacsoptions are:

               -c www.example.com -v --verbose -Dfoo="baz" -ll debug -D-ll=trace

           then variables will be defined as follows:

               ${DACS::-c} is "www.example.com"
               ${DACS::-v} is "2"
               ${DACS::--verbose} is "2"
               ${DACS::foo} is "\"baz\""
               ${DACS::-ll} is "trace"

           The debugging level will be debug and not trace.

       --dumpenv
           Print all environment variables to stdout and then exit
           immediately.

       --enable-dump
           By default, DACS web services and most commands disable core dump
           generation as a security precaution. Because a core dump can be
           useful when debugging, this flag allows it to be created. As
           programs that are allowed to produce a core dump must change to the
           DACS_HOME directory, core dumps will be written there. Use this
           flag with care.

       -format fmt
           The output format is set to fmt, which is one of the following
           keywords (case insensitive): file, html, json, php, plain, text,
           xml, xmldtd, xmlsimple, or xmlschema. Not all output formats are
           supported by all programs. This flag overrides any FORMAT[60]
           argument to a web service, which in turn overrides a program's
           default format. The default format depends on the particular
           program and way it is invoked. For additional information, refer to
           the description of the FORMAT argument[60].

       -ll logging-level
           The logging level is set to log-level, which is one of the keywords
           recognized by the LOG_FILTER[61] directive.

       --license
           Print the license for DACS to stdout and then exit immediately.

       -q
           Be quiet. This is equivalent to setting the logging level to warn.

       -sc site.conf
           This tells DACS that it can find a configuration file for the
           jurisdiction on whose behalf it is acting. If this argument is not
           present, depending on how it was built, DACS may either try to use
           a compile-time specified file or it will try to use the value of
           the environment variable DACS_CONF[58]. For details, refer to
           Locating dacs.conf and site.conf[59].

       --std
           This flags the end of the common arguments. The next command line
           argument, if any, is specific to the program.

       -t
           Emit tracing information. This is equivalent to setting the logging
           level to trace. (Also see debug_dacs[62].)

       -u config-uri
           This instructs DACS to use config-uri to select the jurisdiction
           section to use in the configuration file. For details, refer to The
           Jurisdiction Section[63].

       -uj jurisdiction-name
           This instructs DACS to use the jurisdiction name jurisdiction-name
           to select the jurisdiction section to use in the configuration
           file. For details, refer to The Jurisdiction Section[63].

       -un
           This instructs DACS not to process site.conf or dacs.conf. This may
           only be used with a small number of commands, such as
           dacsacl(1)[64] and sslclient(1)[4].

       -up jurisdiction-name
           NOT IMPLEMENTED. This instructs DACS to use the jurisdiction name
           jurisdiction-name to select the jurisdiction section to use in the
           configuration file and tells it that the web server is acting as a
           forward proxy; that is, jurisdiction-name does not necessarily
           "own" the requested URL. For details, refer to The Jurisdiction
           Section[63].

       -us
           This instructs DACS to use the one-and-only jurisdiction section
           that appears in the configuration file. That is, the configuration
           file must contain exactly one jurisdiction section and that is the
           one that should be used. For details, refer to The Jurisdiction
           Section[63].

       -v
       --verbose
           Be more verbose, relative to the current logging level. This flag
           may be repeated.

       --version
           Print version information to stderr immediately and then exit. If
           -v appeared earlier on the command line, also print version
           information for each DACS source code file in this program.

               Note
               Complete version information is available only for statically
               linked programs. Also see dacsversion(1)[65] and
               dacs_version(8)[66].

           Tip
           If no command line flag is given to specify the jurisdiction
           section, the value of the environment variable DEFAULT_JURISDICTION
           will be used as if given with the -uj flag. This can be
           particularly useful when a host has only one jurisdiction
           configured because it makes it unnecessary to always specify the
           jurisdiction for DACS commands.

ENVIRONMENT
       SERVER_NAME, SERVER_PORT, REQUEST_URI
           May be used to determine the applicable jurisdiction.

FILES
       dacs.conf

       site.conf

SEE ALSO
       DACS manual pages[67], dacs_admin(8)[52], dacs.install(7)[6],
       dacs.readme(7)[5]

BUGS
       There should be some assistance for administering user activity
       records[68].

AUTHOR
       Distributed Systems Software (www.dss.ca[69])

COPYING
       Copyright2003-2013 Distributed Systems Software. See the LICENSE[70]
       file that accompanies the distribution for licensing information.

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

        2. mod_auth_dacs
           http://dacs.dss.ca/man/mod_auth_dacs.html

        3. dacshttp(1)
           http://dacs.dss.ca/man/dacshttp.1.html

        4. sslclient(1)
           http://dacs.dss.ca/man/sslclient.1.html

        5. dacs.readme(7)
           http://dacs.dss.ca/man/dacs.readme.7.html

        6. dacs.install(7)
           http://dacs.dss.ca/man/dacs.install.7.html

        7. Denial of service attacks
           http://en.wikipedia.org/wiki/Denial-of-service_attack

        8. Cross-site scripting (XSS)
           http://en.wikipedia.org/wiki/Cross-site_scripting

        9. Cross-site request forgery (CSRF)
           http://en.wikipedia.org/wiki/Cross-site_request_forgery

       10. index page
           http://dacs.dss.ca/man/index.html

       11. RFC 2606
           http://www.rfc-editor.org/rfc/rfc2606.txt

       12. dacsexpr(1)
           http://dacs.dss.ca/man/dacsexpr.1.html

       13. BNF notation
           http://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form

       14. Authorization Caching
           http://dacs.dss.ca/man/dacs_acs.8.html#authorization_caching

       15. Rlinks
           http://dacs.dss.ca/man/dacs_acs.8.html#rlinks

       16. capability-based system
           http://en.wikipedia.org/wiki/Capabilities

       17. dacs_authenticate(8)
           http://dacs.dss.ca/man/dacs_authenticate.8.html#credentials

       18. dacs_acs(8)
           http://dacs.dss.ca/man/dacs_acs.8.html

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

       20. execution environment
           http://www.freebsd.org/cgi/man.cgi?query=environ&apropos=0&sektion=7&manpath=FreeBSD+9.1-RELEASE&format=html

       21. current federation
           http://dacs.dss.ca/man/#current_federation

       22. current jurisdiction
           http://dacs.dss.ca/man/#current_jurisdiction

       23. ADMIN_IDENTITY
           http://dacs.dss.ca/man/dacs.conf.5.html#ADMIN_IDENTITY

       24. NAME_COMPARE
           http://dacs.dss.ca/man/dacs.conf.5.html#NAME_COMPARE

       25. user()
           http://dacs.dss.ca/man/dacs.exprs.5.html#user

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

       27. FEDERATION_NAME
           http://dacs.dss.ca/man/dacs.conf.5.html#FEDERATION_NAME

       28. FEDERATION_DOMAIN
           http://dacs.dss.ca/man/dacs.conf.5.html#FEDERATION_DOMAIN

       29. JURISDICTION_NAME
           http://dacs.dss.ca/man/dacs.conf.5.html#JURISDICTION_NAME

       30. DACS_IDENTITY
           http://dacs.dss.ca/man/dacs_acs.8.html#var_env_dacs_identity

       31. DACS_USERNAME
           http://dacs.dss.ca/man/dacs_acs.8.html#var_env_dacs_username

       32. RFC 2396
           http://www.rfc-editor.org/rfc/rfc2396.txt

       33. RFC 822
           http://www.rfc-editor.org/rfc/rfc822.txt

       34. RFC 3696
           http://www.rfc-editor.org/rfc/rfc3696.txt

       35. EXIT*
           http://dacs.dss.ca/man/dacs_authenticate.8.html#auth_directive_index

       36. setvar()
           http://dacs.dss.ca/man/dacs.exprs.5.html#setvar

       37. dacs.groups(5)
           http://dacs.dss.ca/man/dacs.groups.5.html#roles

       38. DACS identity
           http://dacs.dss.ca/man/#dacs_identity

       39. dacs_authenticate(8)
           http://dacs.dss.ca/man/dacs_authenticate.8.html

       40. dacs.groups(5)
           http://dacs.dss.ca/man/dacs.groups.5.html

       41. strptime(3)
           http://www.freebsd.org/cgi/man.cgi?query=strptime&apropos=0&sektion=3&manpath=FreeBSD+9.1-RELEASE&format=html

       42. dacsoptions
           http://dacs.dss.ca/man/#dacsoptions

       43. --enable-dump
           http://dacs.dss.ca/man/#enable-dump-arg

       44. fcntl(2)
           http://www.freebsd.org/cgi/man.cgi?query=fcntl&apropos=0&sektion=2&manpath=FreeBSD+9.1-RELEASE&format=html

       45. TEMP_DIRECTORY
           http://dacs.dss.ca/man/dacs.conf.5.html#TEMP_DIRECTORY

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

       47. LOG_FORMAT
           http://dacs.dss.ca/man/dacs.conf.5.html#LOG_FORMAT

       48. dacs.install(7)
           http://dacs.dss.ca/man/dacs.install.7.html#configure_options

       49. dacs_user_info.dtd
           http://dacs.dss.ca/man/../dtd-xsd/dacs_user_info.dtd

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

       51. dacs_admin()
           http://dacs.dss.ca/man/dacs.exprs.5.html#DACS_ADMIN

       52. dacs_admin(8)
           http://dacs.dss.ca/man/dacs_admin.8.html

       53. last(1)
           http://www.freebsd.org/cgi/man.cgi?query=last&apropos=0&sektion=1&manpath=FreeBSD+9.1-RELEASE&format=html

       54. who(1)
           http://www.freebsd.org/cgi/man.cgi?query=who&apropos=0&sektion=1&manpath=FreeBSD+9.1-RELEASE&format=html

       55. sa(8)
           http://www.freebsd.org/cgi/man.cgi?query=sa&apropos=0&sektion=8&manpath=FreeBSD+9.1-RELEASE&format=html

       56. dacs_current_credentials(8)
           http://dacs.dss.ca/man/dacs_current_credentials.8.html

       57. dacs_signout(8)
           http://dacs.dss.ca/man/dacs_signout.8.html

       58. DACS_CONF
           http://dacs.dss.ca/man/dacs_acs.8.html#var_env_dacs_conf

       59. Locating dacs.conf and site.conf
           http://dacs.dss.ca/man/dacs.conf.5.html#locating_dacs.conf

       60. FORMAT
           http://dacs.dss.ca/man/dacs.services.8.html#FORMAT

       61. LOG_FILTER
           http://dacs.dss.ca/man/dacs.conf.5.html#logging_levels

       62. debug_dacs
           http://dacs.dss.ca/man/dacs_acs.8.html#debug_dacs

       63. The Jurisdiction Section
           http://dacs.dss.ca/man/dacs.conf.5.html#jurisdiction_section

       64. dacsacl(1)
           http://dacs.dss.ca/man/dacsacl.1.html

       65. dacsversion(1)
           http://dacs.dss.ca/man/dacsversion.1.html

       66. dacs_version(8)
           http://dacs.dss.ca/man/dacs_version.8.html

       67. DACS manual pages
           http://dacs.dss.ca/man/../man/index.html

       68. user activity records
           http://dacs.dss.ca/man/#tracking_user_activity

       69. www.dss.ca
           http://www.dss.ca

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



DACS 1.4.28b                      02/04/2014                           DACS(1)