/sys$common/syshlp/HELPLIB.HLB  —  XAUTH
    Invokes the X Authority utility (xauth) that enables you to
    manage the contents of one or more X authority files. The X
    authority file contains information used to authorize client
    connections to the X display server.

    This utility is typically used to extract authorization records
    from one system and combine them with the records on another
    system, such as when granting access to additional users or
    enabling remote logins. The actual record entries vary depending
    on the authentication scheme currently in use.

    In contrast to other X Window System utilities that are available
    with DECwindows Motif, xauth is included as a part of OpenVMS
    Alpha and OpenVMS I64 operating systems. The xauth commands are
    case-insensitive and available directly from the DCL command
    line, xauth command line, or from a batch file.

    Format:

    XAUTH [-f authfile] [-options...] [command]

1  –  Options

1.1  –  -f_authfile

    Specifies the name of the X authority file. Version numbers
    are not allowed. If a display device is specified on the
    command line, xauth will use the X authority file referenced
    by the display device. Otherwise, xauth will use the default X
    authority file used by client applications. This file is the X
    authority file referenced by the DECW$DISPLAY display device, the
    DECW$XAUTHORITY logical, or SYS$LOGIN:DECW$XAUTHORITY.DECW$XAUTH.

1.2  –  -q

    Specifies that xauth operate in quiet mode. Status messages are
    not displayed. This is the default setting if the output from
    xauth is not directed to a terminal.

1.3  –  -v

    Specifies that xauth operate in verbose mode. Status messages are
    printed. This is the default setting if the output from xauth is
    directed to a terminal.

1.4  –  -i

    Specifies that xauth ignore file locks. Normally, xauth will
    refuse to read or edit any files that have been locked by another
    program (such as, by another instance of xauth) and not timed
    out.

1.5  –  -b

    Specifies that xauth break file locks before proceeding. Use this
    option only to clean up stale locks.

1.6  –  -n

    Specifies that xauth not interpret the host name when the list
    command is used. Instead, xauth displays the literal value as it
    appears in the X authority file.

2  –  Commands

2.1  –  ADD

    Adds or replaces the specified entries.

2.2  –  EXTRACT

    Extracts and writes the specified entries to a new X authority
    file.

2.3  –  EXIT

    Saves and closes the file and exits the xauth utility. (Available
    from the xauth command line only.)

2.4  –  REMOVE

    Deletes the specified entries.

2.5  –  MERGE

    Appends entries from another X authority file.

2.6  –  NEXTRACT

    Extracts the specified entries in numerical format.

2.7  –  NMERGE

    Merges the specified entries presented in numerical format.

2.8  –  LIST

    Displays a listing of entries in the X authority file.

2.9  –  NLIST

    Displays a listing of entries in numerical format.

2.10  –  GENERATE

    Used to generate a new authorization key. Requires that
    DECwindows Motif for OpenVMS be installed and the SECURITY
    extension be enabled on the X display server.

    The generate command creates a key that applies to all entries
    with a matching IPv4 or IPv6 host address. It is not limited to
    the IP address of the host used to connect to the display server.

2.11  –  HELP

    Displays information about the parameters and options for this
    utility. Subtopic help is also available by typing a question
    mark (?) at the command prompt.

2.12  –  INFO

    Provides a brief overview of the X authority file.

2.13  –  QUIT

    Closes the xauth utility without applying any changes. (Available
    from the xauth command line only.)

2.14  –  SOURCE

    Runs xauth commands from a command file.

3  –  X Authority Files

    The X authority file is a binary data file that contains
    information used to authorize connections to the X server on a
    system running DECwindows Motif Version 1.3 or higher.

    Each time a client application attempts to connect to an X
    server system that uses an authorization protocol, it references
    the current X authority file to determine the appropriate
    authorization key to apply in order to authenticate the
    connection. Each authorization key consists of the protocol name
    and token, which can be one of the following depending on the
    protocol in use:

    o  MIT-MAGIC-COOKIE-1 + random numeric code

    o  MIT-KERBEROS-5 + encrypted string (cached separately)

    By default, an X authority file is created automatically the
    first time a user logs into a desktop on a system configured
    for MIT-MAGIC-COOKIE-1 or MIT-KERBEROS-5 authentication.
    The file is stored in that user's OpenVMS login directory
    (SYS$LOGIN:DECW$XAUTHORITY.DECW$XAUTH). Each time the user
    subsequently logs into a desktop on that system, a new
    authorization key is generated, passed to the X server, and
    written to the user's X authority file. This key controls access
    to the X server during the DECwindows Motif session.

    A separate X authority file can be manually defined on a server
    level (using the DECW$SERVER_XAUTHORITY symbol) for those client
    applications that require access to the X server outside of the
    normal DECwindows Motif login process.

    If the SECURITY extension is enabled, authorization keys can also
    be manually generated. Manually-generated keys can be used to
    further restrict server access. The generated key is stored in
    the X authority file on the client system overwriting any value
    already present for the specified display server. The key can be
    distributed to different client systems to allow connections
    to a specific server and can be revoked to stop subsequent
    connections.

    Generated keys are assigned an authorization ID that associates
    the key with the user who generated the key. As a result, only
    the user who generated the key can revoke the key.

3.1  –  Format of File Entries

    Each entry in an X authority file corresponds to a particular X
    display server and is composed of three main components:

    display-name protocol token

3.1.1  –  display-name

    Identifies the name of the X display to which you are authorizing
    access. The display name follows the supported display name
    format:

    [transport/]host:[:]server[.screen]

    This format enables you to use a single X authority file to
    grant varying levels of access to different X display servers
    and connection families.

    For example, the following entries grant access to the local
    display server on node HUBBUB and the remote display server on
    node ZEPHYR via the DECnet transport:

 local/HUBBUB:0 MIT-MAGIC-COOKIE-1 cfcc5ef98f9718f90154f355c0ae9f62
 decnet/ZEPHYR::0 MIT-MAGIC-COOKIE-1 cfcc5ef98f9718f90154f355c0ae9f62

    o  [transport/]
       Identifies the network transport used to connect to an X
       display server. See the DECwindows Motif documentation for
       a list of the supported transport values. If a transport value
       is not specified, the default value is interpreted from the
       format of the remaining portions of the display-name entry,
       for example:

          Host address and one colon (116.94.24.187:0) (TCP/IP)
          Two colons (::0 or ZEPHYR::0) (DECnet)
          No host name or address and one colon (:0) (local)

    o  host[:]
       Identifies the name of the host system where the X display
       server is located. A value of 0 is interpreted as the local
       host, which is the default. The type of host is determined
       by the transport value. See the DECwindows documentation for
       examples of valid host name and address formats.

    o  :server
       Identifies the server. This value is required and must be
       preceded by a single colon (:). Typically the value for a
       single-server system is :0. If you are specifying a display
       on a multi-server system (such as when using a proxy server),
       additional values may apply depending on the number of servers
       in the configuration. If you have specified a display device
       (with the SET DISPLAY command), the server portion of the
       entry is assumed from the device specification.

    o  [.screen]
       Identifies the screen. On OpenVMS Alpha and OpenVMS I64
       systems, the screen value is not held in the X authority file
       and is ignored when included in a command. All screens on a
       single server have the same authorization.

3.1.2  –  protocol

    Indicates the authentication protocol in use. Valid values are
    MIT-MAGIC-COOKIE-1 and MIT-KERBEROS-5.

3.1.3  –  token

    A random alphanumeric string that functions as a password
    authorizing a server connection. The format of the token depends
    on the authorization scheme in use. MIT-MAGIC-COOKIE-1 uses a
    128-bit string known as a magic cookie. MIT-KERBEROS-5 uses an
    encrypted string to authorize server connections. This string
    is stored separately. The token entry in the X authority file
    represents the encoded location of the Kerberos keytab file and
    associated principal name, which is referenced by the server to
    locate the encrypted string.

3.2  –  Specifying an X Authority File

    By default, the X authority file referenced by client
    applications and the xauth utility is defined as
    SYS$LOGIN:DECW$XAUTHORITY.DECW$XAUTH. You can override this
    default and specify an alternate X authority file in either of
    the following ways:

    o  You can create alternate X authority files and switch between
       them using the DECW$XAUTHORITY logical. For example, the
       following command changes the X authority file in use for
       the current DECwindows Motif session to UNTRUSTED.DECW$AUTH:

       $  DEFINE DECW$XAUTHORITY-
       _$ SYS$MANAGER:[SYSMGR]UNTRUSTED.DECW$XAUTH

       The logical definition remains in use until it is
       redefined or an alternate value is specified using the SET
       DISPLAY/XAUTHORITY command.

    o  If a display device is used to create a client connection to
       an X server, you can specify an alternate X authority file
       using the SET DISPLAY/CREATE/XAUTHORITY command. Note that the
       file specified on this command line overrides both the default
       and any file referenced by the DECW$XAUTHORITY logical.

4  –  Entering Commands

    You can choose to enter commands interactively from DCL, or enter
    the utility and issue commands from the xauth command line.

    Note that SYS$LOGIN:DECW$XAUTHORITY.DECW$XAUTH is the default X
    authority file. If you want to work with an alternate file, use
    the -f option on the command line to specify the filename, as
    follows:

    $ XAUTH -f SYS$SYSROOT:[SYSMGR]UNTRUSTED.DECW$XAUTH
    Using authority file SYS$SYSROOT:[SYSMGR]UNTRUSTED.DECW$XAUTH

    xauth>

    Tips and Shortcuts

    o  If you are working with an X authority file other than the
       default, and plan to enter a series of commands, use the XAUTH
       -f command to enter the utility; then issue the subsequent
       commands from the utility command line. Otherwise, you will
       need to reenter the fully-qualified filename with each xauth
       command issued from the DCL command line.

    o  When adding a file entry, you can specify a period (.) in
       place of the value MIT-MAGIC-COOKIE-1. The period is replaced
       by the name of the authentication protocol.

5  –  IPv6 Considerations

    Note that xauth interprets certain transport values slightly
    different than in most other DECwindows Motif interfaces. xauth
    Transport Actions describes how xauth interprets each transport.

    Table 1 xauth Transport Actions

    With this
    Transport
    Value...        xauth Commands Affect...

    INET            All entries in the X authority file whose
                    host address matches any of the IPv4 addresses
                    associated with the same TCP/IP host.
    INET6           All entries in the X authority file whose host
                    address matches any of the IPv4 or IPv6 addresses
                    associated the same TCP/IP host.
    TCPIP or TCP    All entries in the X authority file as if INET
                    or INET6 had been specified, depending on the
                    setting of DECW$IPV6_SUPPORT.

6  –  Accessing Help

    To display a brief list of the available xauth commands or a
    summary of their function, issue either the XAUTH ? or XAUTH HELP
    command.

7  –  Creating a File

    Use the XAUTH -f ADD command to manually create an X authority
    file. You must manually create an X authority file for the
    server when enabling authentication outside of a DECwindows
    Motif session. You can also choose to create additional user X
    authority files to store alternate authentication settings, such
    as for authorizing untrusted network connections.

    An X authority file name can consist of any characters currently
    supported by OpenVMS; however, the file extension is restricted
    to a maximum of 37 characters and version numbers are not
    allowed.

    The -f option specifies the name of the X authority file, and
    the ADD command creates the file by adding an entry. If you do
    not enter a fully-qualified filename, the new X authority file is
    written to the current directory by default.

    For example, the following command creates a new X authority file
    UNTRUSTED.DECW$XAUTH to be used to authorize untrusted network
    connections:

    $ XAUTH -f UNTRUSTED.DECW$XAUTH ADD :0 .
    cfcc5ef98f9718f90154f355c0ae9f62

8  –  Displaying File Information

    To assist with debugging file access and write issues, xauth
    includes a command that displays summary information about
    a particular X authority file. Use the XAUTH INFO command to
    display information about an X authority file, such as the
    current lock status and change history.

    For example, the following command displays summary information
    about the X authority file UNTRUSTED.DECW$XAUTH:

    $  XAUTH -f SYS$SYSROOT:[SYSMGR]UNTRUSTED.DECW$XAUTH INFO
    Authority file:      SYS$SYSROOT:[SYSMGR]UNTRUSTED.DECW$XAUTH
    File new:            no
    File locked:         yes
    Number of entries:   2
    Changes honored:     yes
    Changes made:        no
    Current input:       command line

9  –  Viewing and Editing File Entries

    Each X authority file assumes the default protections of the
    account and directory in which it resides. If you have the
    appropriate privileges, you can view or edit the contents of
    an X authority file. To ensure the appropriate level of security,
    access to this file is typically limited to either the local
    SYSTEM account, the file owner, or both.

                                   NOTE

       When an X authority file is open for viewing or editing,
       one or more lock files are created by adding -L or -C to the
       file extension (such as, *.DECW$XAUTH-C). This renders the
       X authority file locked from further use. When the file is
       closed, the lock is subsequently removed, and the lock files
       deleted.

       If a DECwindows Motif session is terminated abruptly, one
       or more locked files can remain. Use the XAUTH command with
       options -b or -i to either break or ignore the locks and
       gain access to the file.

9.1  –  Displaying File Entries

    Use the XAUTH LIST command to display the contents of an X
    authority file.

    For example, the following XAUTH command displays the entries in
    the X authority file UNTRUSTED.DECW$XAUTH:

    $  XAUTH -f UNTRUSTED.DECW$XAUTH LIST
    local/ZEPHYR:0  MIT-MAGIC-COOKIE-1  cfcc5ef98f9718f90154f355c0ae9f62
    decnet/ZEPHYR::0  MIT-MAGIC-COOKIE-1  cfcc5ef98f9718f90154f355c0ae9f62
    116.94.24.187:0  MIT-MAGIC-COOKIE-1  cfcc5ef98f9718f90154f355c0ae9f62

                                   NOTE

       TCP/IP is considered the default transport for X authority
       file entries. As a result, the transport portion of the
       display name is assumed and not displayed for entries that
       use the TCP/IP transport.

    To limit the list to entries related to a particular display,
    enter the display name at the end of the XAUTH LIST command, as
    follows:

    $ XAUTH -f UNTRUSTED.DECW$XAUTH LIST ZEPHYR::0
    decnet/ZEPHYR::0  MIT-MAGIC-COOKIE-1  cfcc5ef98f9718f90154f355c0ae9f62

    With the TCPIP transport, multiple addresses may correspond to
    the same display name. When displaying X authority file entries,
    it may be difficult to distinguish which entry applies to which
    address. To differentiate the entries, use the -n qualifier to
    list them in numeric format, as follows:

    $ XAUTH LIST
    test13_2:0  MIT-MAGIC-COOKIE-1  12
    test13_2:0  MIT-MAGIC-COOKIE-1  23
    $ XAUTH -n LIST
    #0006#fe800000000000000200f8fffe101905#:0  MIT-MAGIC-COOKIE-1  12
    #0000#c0a70209#:0  MIT-MAGIC-COOKIE-1  23

9.2  –  Adding and Removing File Entries

    Use the XAUTH ADD and XAUTH REMOVE commands to add entries to or
    delete entries from an X authority file.

    If you have created a display device (using the SET DISPLAY
    command), you can specify the device name on the xauth command
    line to insert or remove entries related to the display device.
    Typically, the X authority file entry for a display device
    corresponds to the display server specified by the SET DISPLAY
    command. However, if the SET DISPLAY command specifies that
    a proxy server be used, the file entry pertains to that proxy
    server.

    For example, the following X authority file has a single
    entry for the LOCAL transport on node ZEPHYR. To use the same
    authorization key for the DECnet transport and to specify
    that Kerberos be used when connecting to remote node HUBBUB,
    you could add the following entries to the X authority file
    UNTRUSTED.DECW$XAUTH:

    $  XAUTH -f UNTRUSTED.DECW$XAUTH
    Using authority file untrusted.decw$xauth

    xauth>  LIST
    local/ZEPHYR:0  MIT-MAGIC-COOKIE-1  cfcc5ef98f9718f90154f355c0ae9f62

    xauth>  ADD ::0 . cfcc5ef98f9718f90154f355c0ae9f62
    xauth>  ADD HUBBUB::0 MIT-KERBEROS-5 ""

    xauth>  LIST
    local/ZEPHYR:0  MIT-MAGIC-COOKIE-1  cfcc5ef98f9718f90154f355c0ae9f62
    decnet/ZEPHYR::0  MIT-MAGIC-COOKIE-1  cfcc5ef98f9718f90154f355c0ae9f62
    decnet/HUBBUB::0  MIT-KERBEROS-5

    xauth> EXIT
    Writing X authority file untrusted.decw$xauth

    Client applications running on systems in the same cluster
    share a single X authority file. As a result, in cluster
    configurations, adding an entry for the DECnet transport to the
    local system grants client applications running on other nodes in
    the cluster access to that system.

    To discontinue remote access to HUBBUB, you could use the XAUTH
    REMOVE command to remove the entry, as follows:

    $  XAUTH -f UNTRUSTED.DECW$XAUTH
    Using authority file untrusted.decw$xauth

    xauth> REMOVE HUBBUB::0
    1 entries removed

    xauth> LIST
    local/ZEPHYR:0  MIT-MAGIC-COOKIE-1  cfcc5ef98f9718f90154f355c0ae9f62
    decnet/ZEPHYR::0  MIT-MAGIC-COOKIE-1  cfcc5ef98f9718f90154f355c0ae9f62

    xauth> EXIT
    Writing X authority file untrusted.decw$xauth

9.3  –  Copying Entries Between Files

    Use one or more of the following XAUTH commands to copy entries
    for a particular display from one X authority file to another.

    This enables you to use an existing entry to grant another user
    access to a particular display or to obtain access to a remote
    host from the current display device.

    o  EXTRACT - Creates a new X authority file whose entries match
       those in the original file.

    o  MERGE - Appends the contents of one file to another, replacing
       entries for the same display name or adding entries for
       different names.

    o  NEXTRACT and NMERGE - These commands are designed to be used
       with the PIPE command. NEXTRACT extracts file entries in a
       text format that can then be used as input for the NMERGE
       command.

       For example, the following command extracts the X
       authority file entry for the local transport from the file
       UNTRUSTED.DECW$XAUTH and adds it to a new X authority file
       NEW_XAUTHORITY.DECW$XAUTH:

       $  PIPE XAUTH -f UNTRUSTED.DECW$XAUTH NEXTRACT SYS$OUTPUT :0 | -
       _$ XAUTH -f NEW_XAUTHORITY.DECW$XAUTH NMERGE SYS$INPUT

    These commands can also be used with the rsh command to
    copy entries from an X authority file on an OpenVMS host to
    an X authority file on a remote UNIX system. For example,
    the following command extracts the entry for TCP/IP access
    (TCPIP/0:0) and adds it to the current file for user SMITH on
    the remote UNIX system FLOPSY:

    $  PIPE XAUTH -f UNTRUSTED.DECW$XAUTH NEXTRACT TCPIP/0:0 | -
    _$ rsh/user=smith/password=secret flopsy "xauth nmerge -"

                                   NOTE

       When using the PIPE and XAUTH commands to pass information
       to a UNIX host, you must press Ctrl/C to terminate the
       connection to the UNIX host and return control to OpenVMS.

10  –  Generating Authorization Keys

    When the SECURITY extension is enabled on an X display server,
    you can generate additional authorization keys. Generated keys
    enable you to further manage server access and control the type
    of operations performed over the connection. For example, you
    can revoke a generated key at will, set it to expire after a
    certain time period, or use it to further grant or restrict the
    operations (at the X atom level) that can be performed over the
    connection.

    Use the XAUTH GENERATE command to produce a new authorization
    key. Note that the generated key overwrites any existing key for
    the current session. To preserve the existing key, specify an
    alternate X authority file on the XAUTH command line.

    For example, the following commands specify the alternate X
    authority file UNTRUSTED.DECW$XAUTH, generate and display a new
    key for the local display, and write the generated key to the
    alternate file:

    $  XAUTH -f UNTRUSTED.DECW$XAUTH
    Using authority file untrusted.decw$xauth

    xauth> LIST :0
    local/ZEPHYR:0  MIT-MAGIC-COOKIE-1  cfcc5ef98f9718f90154f355c0ae9f62

    xauth> GENERATE :0

    xauth> LIST :0
    local/ZEPHYR:0  MIT-MAGIC-COOKIE-1  cfcc4ff77f3709c46222c355f0ea1c93

    xauth> EXIT
    Writing X authority file untrusted.decw$xauth
Close Help