Provided by: dacs_1.4.28b-3ubuntu2_amd64 bug

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 -flag value 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