DACS(1)                       DACS Commands Manual                       DACS(1)

       dacs - a distributed access control system

       dacs [-v | --verbose] [--checkdigest digest-desc] [--dumpenv]
            [--digests [digest-name]] [--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]
                    [-v | --verbose] [--checkdigest digest-desc]
                    [--digests [digest-name]] [--dumpenv] [--enable-dump]
                    [--license] [--std] [--version]

       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.

           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 is provided as a set of manual
       pages. From XML source files, HTML, nroff/troff, and nroff output
       collections are generated during the installation procedure. 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.

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

           The output of man(1)[11] for these manual pages is likely to contain
           ANSI escape sequences (e.g., for bold face mark up). For these pages
           to be rendered in a terminal window as intended, the pager used for
           this purpose may need to be given an appropriate flag, such as -R for

       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[13]).

       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)[14]:

           > 1 + 1

       An extended form of BNF notation[15] 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.

           A record, usually persistent, that associates an identity (or
           username) with state information (such as whether authentication 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.  DACS does not provide mechanisms
           to administer "foreign" account types. For instance, although it can
           authenticate against them, DACS cannot create, modify, delete, or
           list Unix or Windows accounts. Note that DACS identities do not
           necessarily have a corresponding account.

           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.

           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[16] and Rlinks[17].

           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/TLS 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[18].
           Credentials simply represent a DACS identity.

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

       current request
           The event that has triggered the authorization check being processed
           by dacs_acs(8)[20] 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)[21] or dacsexpr(1)[14] are used, the current request and
           its context are specified by command line arguments or are obtained
           from the execution environment[22].

           dacs_acs uses ${DACS::URI} as the path component of the current
           request. It is obtained from the uri element of the current
           request_rec within httpd. 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

           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[23] and current jurisdiction[24],
           and because it is used when searching for the access control rule to
           apply to the request.

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

           Programmatic, general-purpose access control is available for
           virtually any program (using dacscheck(1)[21]). 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[25] is effectively a DACS
           administrator; in this context, the system superuser has no

       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

               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[26])
               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()[27] 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

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

           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

       item type
           An item type is a name that maps to a VFS[28] (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

           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

           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.

       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.

           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





           The federation-name (usually obtained from a FEDERATION_NAME[29]
           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[26] configuration directive and the user()[27] function
           for alternate behaviours). There is no a priori limit on its length.

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


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



           The jurisdiction-name (usually obtained from a JURISDICTION_NAME[31]
           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[26] configuration directive and the user()[27]
           function for alternate behaviours). There is no a priori limit on its


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



           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[32] environment variable.

           The username component, which is available to CGI programs as the
           value of the DACS_USERNAME[33] 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:

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

               •   It is a goal to liberally accept usernames because different
                   platforms and even different platform versions and flavours
                   allow various username syntaxes. Nevertheless, administrators
                   should be careful if punctuation characters are permitted in
                   usernames as this could lead to subtle problems if those
                   characters appear in URLs, access control rules, or HTTP
                   cookies. The compile-time symbol JURISDICTION_NAME_SEP_CHAR,
                   which is a colon by default, is disallowed in usernames (and
                   this symbol should probably never be redefined).

               •   In addition to the alphanumeric characters, RFC 2396[34]
                   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[35] (Appendix D) and discussed in RFC 3696[36] (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[26]
                   configuration directive and the user()[27] function for
                   alternate behaviours). There is no a priori limit on its

               •   The usernames auth and unauth are perfectly valid. Refer to
                   the user()[27] function for additional information.

               •   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*[37] directive may be used for this purpose.


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



       Roles and Role Descriptors

               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:


               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
           The setvar()[38] function can be used to separate a composite role
           into its basic roles.

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

       Concise User 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


           •   Q is an optional (matched) quote character;

           •   whitespace may optionally precede most tokens;

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

           •   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)[41] and

           •   an IP address is expressed in the Internet standard numeric dot
               notation (e.g.,; 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

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

               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[25] (refer to the
               -admin flag of dacscheck(1)[21]).

           A name expressed in the concise syntax, gives a username and,
           optionally, roles and attributes for the identity. It is used by
           dacscheck(1)[21], 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 license
           % dacs dacskey -u j1.example.com outfile
           % dacs checkdigest "pbkdf2[a=sha256,count=4098, dklen=20]"
           % dacs checkdigest 14

       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[44])

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

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

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

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

        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

       Some DACS components may call other components using HTTP (possibly over
       SSL/TLS, depending on configuration). For example, authentication modules
       may be invoked as web services by dacs_authenticate(8)[41]. 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.

           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/TLS parameters. Internal HTTP requests over SSL/TLS 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)[46] system call on files written in the directory configured
       through the TEMP_DIRECTORY[47] directive.

       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)[48] 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 (see --enab

           •   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

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

       The default value of the LOG_FORMAT[50] directive, which controls the
       appearance of log messages, is defined in include/local.h as
       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
                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
                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 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.

               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)[51]), 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[52]. This information can be valuable for better
       understanding what is happening throughout 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; 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)[53] service by adding an appropriate access control rule.

           It is critical for any such rule to require the dacs_admin()[54]

           •   Because the records are currently not keyed, at present only the
               file item type is supported for this purpose. A configuration
               directive similar to the following would be used:

                   VFS "[user_info]file://${Conf::FEDERATIONS_ROOT}/${Conf::FEDERATION_DOMAIN}/${Conf::JURISDICTION_NAME}/user_info"

           •   The dacs_admin(8)[55] 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)[56], who(1)[57], and
               sa(8)[58] are being considered.

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

           •   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)[59]), 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

           •   Internal administrative events are not recorded.

           •   Because signing off (via dacs_signout(8)[60]) 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

       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

           •   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)[48] 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[61]. For details, refer to Locating
           dacs.conf and site.conf[62].

           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

           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.

       --checkdigest digest-desc
           Validate the syntax of digest descriptor digest-desc, as it might
           appear as the value of the PASSWORD_DIGEST[63] directive. In addition
           to the digest name, the given argument names and values are checked.
           A numeric algorithm identifier can be given as a synonym for the
           algorithm name. The descriptor is printed in canonical form.

       --digests [digest-name]
           With no digest-name, list information about all available
           cryptographic digest algorithms, otherwise only digest-name. The
           information includes:

           •   the canonical name for the digest

           •   the digest's block size, in bytes ("bsize"),

           •   the digest size, in bytes ("dsize"),

           •   the internal password algorithm identifier ("alg", an unsigned
               integer), and

           •   its attributes: whether the algorithm can be used with
               PASSWORD_DIGEST[63] ("Password"), HMAC constructs ("HMAC"),
               digital signatures ("Sign"), scrypt ("scrypt"), PBKDF2
               ("PBKDF2"), if it requires parameters ("Parameters"), whether it
               produces a variable-length digest ("Varlen"), and its
               implementation ("OpenSSL", "DACS", or "System").

           A digest size of zero also indicates that there is a variable-length
           output, which may depend on any of the arguments to the digest
           function. After printing to stdout, the program exits immediately.
           For convenience, --digest is a synonym.

           Print all environment variables to stdout and then exit immediately.

           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, xmlschema, uri, or url. Not all output formats are
           supported by all programs. This flag overrides any FORMAT[64]
           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[64].

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

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

           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[61]. For details, refer to Locating
           dacs.conf and site.conf[62].

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

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

       -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[67].

       -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[67].

           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)[68]
           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

           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

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

           Print version information to stderr immediately and then exit. If the
           -v (--verbose) flag appeared earlier on the command line, also print
           version information for each DACS source code file used by this
           program that was compiled with a recognized revision identifier
           string. This information can be helpful when debugging suspected
           build problems.

               Complete version information is available only for statically
               linked programs. Also see dacsversion(1)[69] and

           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.

           May be used to determine the applicable jurisdiction.



       DACS manual pages[71], dacs_admin(8)[55], dacs.install(7)[6],
       dacs.readme(7)[5], dacs.services(8)[72]

       Whether using DACS, Apache, or both for authentication and authorization,
       always test that resources are being protected according to your
       requirements. This is especially important when upgrading or
       reconfiguring DACS or Apache.

       Compatibility and interoperability with Apache
       authentication/authorization features and configuration may change as
       Apache evolves. For a particular set of DACS-wrapped resources (e.g.,
       URLs in the scope of a given Location section), it is easiest, safest,
       and most predictable if as much as possible is delegated to DACS rather
       than combining DACS with Apache authentication/authorization modules and
       directives beyond the minimal configuration. Non-minimal combinations may
       cause DACS or Apache to function incorrectly, so they should be avoided
       or used with care. This is particularly important with respect to Apache
       2.4, which has greatly expanded the number of directives associated with
       authentication and authorization.

       There should be some assistance for administering user activity

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

       Copyright © 2003-2018 Distributed Systems Software. See the LICENSE[75]
       file that accompanies the distribution for licensing information.

        1. dacsoptions

        2. mod_auth_dacs

        3. dacshttp(1)

        4. sslclient(1)

        5. dacs.readme(7)

        6. dacs.install(7)

        7. Denial of service attacks

        8. Cross-site scripting (XSS)

        9. Cross-site request forgery (CSRF)

       10. index page

       11. man(1)

       12. less(1)

       13. RFC 2606

       14. dacsexpr(1)

       15. BNF notation

       16. Authorization Caching

       17. Rlinks

       18. capability-based system

       19. dacs_authenticate(8)

       20. dacs_acs(8)

       21. dacscheck(1)

       22. execution environment

       23. current federation

       24. current jurisdiction


       26. NAME_COMPARE

       27. user()

       28. VFS




       32. DACS_IDENTITY

       33. DACS_USERNAME

       34. RFC 2396

       35. RFC 822

       36. RFC 3696

       37. EXIT*

       38. setvar()

       39. dacs.groups(5)

       40. DACS identity

       41. dacs_authenticate(8)

       42. dacs.groups(5)

       43. strptime(3)

       44. dacsoptions

       45. --enable-dump

       46. fcntl(2)


       48. dacs.conf(5)

       49. --enab le-hush-startup-logging

       50. LOG_FORMAT

       51. dacs.install(7)

       52. dacs_user_info.dtd

       53. dacs_vfs(8)

       54. dacs_admin()

       55. dacs_admin(8)

       56. last(1)

       57. who(1)

       58. sa(8)

       59. dacs_current_credentials(8)

       60. dacs_signout(8)

       61. DACS_CONF

       62. Locating dacs.conf and site.conf


       64. FORMAT

       65. LOG_FILTER

       66. debug_dacs

       67. The Jurisdiction Section

       68. dacsacl(1)

       69. dacsversion(1)

       70. dacs_version(8)

       71. DACS manual pages

       72. dacs.services(8)

       73. user activity records

       74. www.dss.ca

       75. LICENSE

DACS 1.4.40                        02/19/2019                            DACS(1)