HP OpenVMS Systems Documentation
HP DECwindows Motif for OpenVMS
The X Authority utility (xauth) 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 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.
The command format for xauth is as follows:
$ xauth [-f authfile] [-options...] [command]
Table 2-6 defines the available options.
|-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.|
|-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.|
|-v||Specifies that xauth operate in verbose mode. Status message are printed. This is the default setting if the output from xauth is directed to a terminal.|
|-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.|
|-b||Specifies that xauth break file locks before proceeding. Use this option only to clean up stale locks.|
|-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.|
Table 2-7 defines the available commands.
|add||Adds or replaces the specified entries.|
|extract||Extracts and writes the specified entries to a new X authority file.|
|exit||Saves and closes the file and exits the xauth utility. (Available from the xauth command line only.)|
|remove||Deletes the specified entries.|
|merge||Appends entries from another X authority file.|
|nextract||Extracts the specified entries in numerical format.|
|nmerge||Merges the specified entries presented in numerical format.|
|list||Displays a listing of entries in the X authority file.|
|nlist||Displays a listing of entries in numerical format.|
|generate||Used to generate a new authorization key. Requires that DECwindows Motif 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.|
|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.|
|info||Provides a brief overview of the X authority file.|
|quit||Closes the xauth utility without applying any changes. (Available from the xauth command line only.)|
|source||Runs xauth commands from a command file.|
The X authority file is a binary data file that contains information used to authorize connections to the X display 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:
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.
22.214.171.124.1 Format of an X Authority File Entry
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
Identifies the name of the X display to which you are authorizing access. The display name follows the supported display name format described in HP DECwindows Motif for OpenVMS Management Guide:
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
Indicates the authentication protocol in use. Valid values are MIT-MAGIC-COOKIE-1 and MIT-KERBEROS-5.
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.
126.96.36.199.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:
$ DEFINE DECW$XAUTHORITY SYS$MANAGER:[SYSMGR]UNTRUSTED.DECW$XAUTH
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
Note that xauth interprets certain transport values slightly different than in most other DECwindows Motif interfaces. Table 2-8 describes how xauth interprets each transport.
|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.|
To display a brief list of the available xauth commands or a summary of
their function, issue either the XAUTH ? or XAUTH HELP command.
188.8.131.52 Creating an X Authority 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
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
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.
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.
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 184.108.40.206:0 MIT-MAGIC-COOKIE-1 cfcc5ef98f9718f90154f355c0ae9f62
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
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
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.
$ 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 -"
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.