# Compaq TCP/IP Services for OpenVMS
Management

Previous | Contents | Index

# Chapter 19
Configuring XDMCP-Compatible X Displays

The X Window System, developed by the Massachusetts Institute of Technology, is a network-based graphics window system based on the client/server application model. The X protocol, through which the client and server communicate, runs on UNIX domain sockets, TCP/IP, or DECnet. This means that an X display on one system can display information output from an application running on another system in the network.

An X display is a graphic output device that is known by The X Display Manager (XDM), such as:

- An X terminal
- A workstation that has the X Window System software installed and configured
- A PC running Windows or Windows NT and some X Window System software, such as eXcursion or Exceed

This chapter reviews key concepts, discusses how to configure an XDMCP-compatible X display using the TCP/IP Services XDM server, and covers the following topics:

- XDMCP queries ( Section 19.2)
- XDM configuration files ( Section 19.3)
- XDM log files( Section 19.4)
- XDM server startup and shutdown ( Section 19.5)
- Configuring the XDM server( Section 19.6)
- Configuring other X displays ( Section 19.7)

# 19.1 Key Concepts

The X Display Manager (XDM) is an X client that manages the login process of a user's X window session. XDM is responsible for displaying a login screen on a display specified by an X server, establishing an X window session, and running scripts that start other X clients. When the user logs out of the X session, XDM is responsible for closing all connections and resetting the terminal for the next user session.

An earlier version of XDM had limitations that were resolved with the introduction of the XDM Control Protocol (XDMCP). Before XDMCP, XDM used the XSERVERS file to keep track of the X terminals for which it managed the login process. At startup, XDM initialized all X terminals listed in the XSERVERS file. If the X terminal was turned off and then on again, XDM had no way of knowing that a new login process should be initiated at the X terminal. To reinitialize the X terminal, the XDM process had to be restarted. This problem was solved through the development of the XDM Control Protocol.

Now, because of XDMCP, XDM can listen for management requests from X terminals as well as use the XSERVERS file for the X terminals that were not XDMCP compatible. Most X terminals today are XDMCP compatible.

The TCP/IP Services implementation of XDM is based on the X11R6.1 release from X Consortium.

# 19.2 XDMCP Queries

XDMCP provides the following methods to query XDM for service:

- Direct
  X terminals, configured for the direct request method, send a connection request to a specific host.
- Broadcast
  X terminals, configured for a broadcast request, send out a general query to ask for service from all nodes running XDM. A list of the responding nodes is then presented to the user for selection by the client software.
- Indirect
  An indirect request is used to relay a request for service from one XDM node to another.

The TCP/IP Services implementation of XDM does not support the indirect query with a chooser box supported by some other XDM servers.

An authentication protocol is supported for all three types of requests.

# 19.3 XDM Configuration Files

If the files are present, XDM uses the following files to configure the X display environment:

- Master configuration (XDM_CONFIG.CONF)
- Servers (XSERVERS.TXT)
- Access (XACCESS.TXT)
- Keys (XDM_KEYS.TXT)
- Session (XDM_XSESSION.COM)

After installing XDM, you can use the TCP/IP Services-supplied configuration templates located in SYS$SPECIFIC:[TCPIP$XDM] to create the configuration files. The default directory location of the configuration and template files is the SYS$SPECIFIC:[TCPIP$XDM] directory.

## 19.3.1 Master Configuration File

The master configuration file, which is an optional file, specifies the location and file names of the other configuration files used to control the operation of XDM.

Example 19-1 shows the contents of the default configuration template file (XDM_CONFIG.TEMPLATE) supplied with XDM:

Example 19-1 XDM_CONFIG.TEMPLATE File

    !
    ! Default SYS$SPECIFIC:[TCPIP$XDM]XDM_CONFIG.CONF file
    !
    DisplayManager.keyFile:            SYS$SPECIFIC:[TCPIP$XDM]XDM_KEYS.TXT
    DisplayManager.servers:            SYS$SPECIFIC:[TCPIP$XDM]XSERVERS.TXT
    DisplayManager.accessFile:         SYS$SPECIFIC:[TCPIP$XDM]XACCESS.TXT
    DisplayManager*RemoveDomainname:   true

Each noncomment line in the file must consist of a keyword and value pair. TCP/IP Services supports the following keywords:

    $ TYPE SYS$SPECIFIC:[TCPIP$XDM]XDM_CONFIG.TEMPLATE
    !
    ! Default SYS$SPECIFIC:[TCPIP$XDM]XDM_CONFIG.CONF file
    !
    DisplayManager.keyFile:            SYS$SPECIFIC:[TCPIP$XDM]XDM_KEYS.TXT
    DisplayManager.servers:            SYS$SPECIFIC:[TCPIP$XDM]XSERVERS.TXT
    DisplayManager.accessFile:         SYS$SPECIFIC:[TCPIP$XDM]XACCESS.TXT
    DisplayManager*RemoveDomainname:   true

The file specification for the master configuration file is:

    SYS$SPECIFIC:[TCPIP$XDM]XDM_CONFIG.CONF

XDM uses the `DisplayManager*RemoveDomainname:` value when computing the display name for XDMCP clients. BIND, when performing a host name lookup creates a fully qualified host name for the X terminal. When this keyword is set to TRUE, XDM removes the domain name portion of the host name if it is the same as the local host domain. The default value of `DisplayManager*RemoveDomainname:` is TRUE.

## 19.3.2 XACCESS.TXT File

The XACCESS.TXT file, a required file, allows or restricts access to remote X servers. If the XACCESS.TXT file is not present, the system restricts all remote X server access. You use this file to control the way XDM responds to broadcast, direct, and indirect requests from X servers.

The default file specification for the XACCESS.TXT configuration file is:

    SYS$SPECIFIC:[TCPIP$XDM]XACCESS.TXT

If you choose to use another file name or directory location, you can override the default by adding a line in the XDM_CONFIG.CONF file similar to the following:

    DisplayManager.accessFile:  WORK1$:[XDM]XACCESS.TXT

Example 19-2 shows a sample XACCESS.TXT configuration file:

Example 19-2 XACCESS.TXT File

    # $XConsortium: Xaccess,v 1.5 91/08/26 11:52:51 rws Exp $
    #
    # Access control file for XDMCP connections
    #
    # To control Direct and Broadcast access:
    #
    #       pattern
    #
    # To control Indirect queries:
    #
    #       pattern         list of hostnames and/or macros ...
    #
    # To define macros:
    #
    #       %name           list of hosts ...
    #
    # The first form tells xdm which displays to respond to itself.
    # The second form tells xdm to forward indirect queries from hosts matching
    # the specified pattern to the indicated list of hosts.
    #
    # In all cases, xdm uses the first entry which matches the terminal;
    # for IndirectQuery messages only entries with right hand sides can
    # match, for Direct and Broadcast Query messages, only entries without
    # right hand sides can match.
    #

    *               #any host can get a login window

    #
    # To hardwire a specific terminal to a specific host, you can
    # leave the terminal sending indirect queries to this host, and
    # use an entry of the form:
    #

    #terminal-a     host-a

Allowing Direct Access

To allow access, add a line to the XACCESS.TXT file with the host name, as shown in the following example:

    condor.compaq.com

Denying Access

To restrict access, add a line to the XACCESS.TXT file with the host name, preceded by an exclamation point, as shown in the following example:

    !rufus.compaq.com

You can use the question mark (?) and the asterisk (*) wildcard characters to specify host names that vary with one character or more than one character.

Allowing Indirect Access

To allow indirect access, add a line to the XACCESS.TXT file similar to the following line:

    rufus.compaq.com     richard.compaq.com henry.compaq.com william.compaq.com

## 19.3.3 XSERVERS.TXT File

The XSERVERS.TXT file was originally used to specify all X servers to be managed by XDM. However, since the introduction of XDMCP, there is no need to specify X servers that are XDMCP compatible in this file.

This file now specifies the X servers that do not support XDMCP. Unlike other XDM implementations, this file is not used to specify XDM support for the local display server.

The default file specification for the XSERVERS.TXT file is:

    SYS$SPECIFIC:[TCPIP$XDM]XSERVERS.TXT

If you choose to use a different name and directory location, you can override the default by adding a line to the XDM_CONFIG.CONF file similar to the following line:

    DisplayManager.servers:  WORK1$:[XDM]XSERVERS.TXT

Example 19-3 shows a sample XSERVERS.TXT configuration file:

Example 19-3 XSERVERS.TXT File

    $ TYPE XSERVERS.TXT
    #
    #
    # This file can be used to support X terminals which do not support XDMCP.
    #
    # For each terminal, add a line that consists of
    #     DisplayName:0 foreign
    #
    # Where DisplayName is a IP name.
    #
    rufus.compaq.com:0 foreign

The word foreign in the previous example indicates that the X server is running on another machine.

## 19.3.4 XDM_KEYS.TXT File

The XDM_KEYS.TXT file provides XDM-AUTHENTICATION-1 style XDMCP authentication. This optional file contains key ID and key value pairs for use with X terminals that support or require XDM authorization.

Each noncomment line in the XDM_KEYS.TXT file contains a display ID and a key value. The file is used when a request containing a display ID key is received from an X terminal. The corresponding key value is encrypted and returned to the X terminal. If the key value in the configuration file matches the key value specified by the X terminal's control information, the session is allowed.

The default file specification for the XDM_KEYS.TXT files is:

    SYS$SPECIFIC:[TCPIP$XDM]XDM_KEYS.TXT

If you choose to use a different name and directory location, you can override the default by adding a line to the XDM_CONFIG.CONF file similar to the following line:

    DisplayManager.keyFile:  WORK1$:[XDM]XDM_KEYS.TXT

Example 19-4 shows a sample XDM_KEYS.TXT configuration file:

Example 19-4 XDM_KEYS.TXT

    #
    # Security Key File
    #
    #  Excursion Display ID                 Excursion Cookie:
    #
    test123456                              123457
    #
    #  Exceed Display ID:                   Exceed Key:
    #
    HCLpcXserver:629409365                  1234568
    #

## 19.3.5 XDM_XSESSION.COM File

The XDM_XSESSION.COM file is an optional command procedure file that specifies the type of X window that XDM displays after a user has successfully logged in.

XDM's default operation is to create a Common Desktop Environment (CDE) using the commands from the SYS$SYSTEM:TCPIP$XDM_XSESSION.COM file:

    $ DEFINE DECW$DISPLAY "''p1'"
    $ DEFINE display      "''p1'"
    $ @CDE$PATH:XSESSION.COM

At present, CDE is only available on Alpha systems in version 1.2-4 or later of DWMOTIF, and not at all on VAX systems. If the CDE command procedure XSESSION.COM is not found on the system, XDM will look for the DECwindows Desktop Session Manager startup command procedure, DECW$STARTSM.COM to initiate the session using the commands:

    $ SET DISPLAY/CREATE/NODE=nodename/TRANSPORT=TCPIP
    $ @SYS$MANAGER:DECW$STARTSM.COM

Before executing either of these command procedures, XDM looks for an XDM_XSESSION.COM file in the user's SYS$LOGIN directory. If found, XDM executes the file. Users can create a DECterm by adding the following DCL commands to their XDM_XSESSION.COM file:

    $ SET PROC/PRIV=SYSNAM
    $ SET DISPLAY/CREATE/NODE=workstation_display/TRANSPORT=TCPIP -
    _$ /EXECUTIVE_MODE
    $ CREATE/TERMINAL/WAIT/WINDOW_ATTRIBUTES=(ICON=nodename, -
    _$  TITLE=window_title)

For a complete description of the CREATE and SET DISPLAY commands and their qualifiers, use the DCL command HELP at the OpenVMS system prompt.

# 19.4 XDM Log Files

XDM maintains three log files to record XDM server and client activity:

- XDM server log file
- X terminal process log file
- User process log file

Table 19-1 lists the XDM log files and their OpenVMS directory locations.

Table 19-1 XDM Log Files
Process | File Name | Location
--- | --- | ---
XDM server | TCPIP$XDM_RUN.LOG | SYS$SPECIFIC:[TCPIP$XDM]
X terminal | xterm_name_domain.COM | SYS$SPECIFIC:[TCPIP$XDM.WORK]
| xterm_name_domain.ERR | SYS$SPECIFIC:[TCPIP$XDM.WORK]
| xterm_name_domain.OUT | SYS$SPECIFIC:[TCPIP$XDM.WORK]
User | xterm_name_domain.LOG | SYS$LOGIN

# 19.5 XDM Server Startup and Shutdown

The XDM server can be shut down and started independently from the rest of the TCP/IP Services software. This is useful when you change parameters or logical names that require the service to be restarted.

The following files are provided:

- SYS$STARTUP:TCPIP$XDM_STARTUP.COM allows you to start up the XDM service.
- SYS$STARTUP:TCPIP$XDM_SHUTDOWN.COM allows you to shut down the XDM service.

To preserve site-specific parameter settings and commands, create the following files. These files are not overwritten when you reinstall TCP/IP Services:

- SYS$STARTUP:TCPIP$XDM_SYSTARTUP.COM can be used as a repository for site-specific definitions and parameters to be invoked when XDM is started.
- SYS$STARTUP:TCPIP$XDM_SYSHUTDOWN.COM can be used as a repository for site-specific definitions and parameters to be invoked when XDM is shut down.

# 19.6 Configuring the XDM Server

To configure your XDM server, you need to:

- Run SYS$MANAGER:TCPIP$CONFIG to create the default directories and a user ID for the XDM component. The configuration procedure checks to see whether the following DECwindows components are installed:
  - SYS$COMMON:[SYSLIB]DECW$XLIBSHR.EXE
  - SYS$COMMON:[SYSLIB]DECW$XTLIBSHRR5.EXE
  - SYS$COMMON:[SYSLIB]DECW$TRANSPORT_COMMON.EXE (VAX only)
  If the DECwindows components are not found, TCPIP$CONFIG notifies you and gives you the option of configuring XDM, with the assumption that before you attempt to activate XDM you will install the DECwindows components. TCPIP$CONFIG notifies you of this situation with the following prompt:

          XDM requires DECwindows components that are not installed.
          Attempts to activate XDM will fail.

         Type C to continue with XDM configuration, or E to exit [ E ]:

- If necessary, use the template files located in SYS$SPECIFIC:[TCPIP$XDM] to create an XDM_CONFIG.CONF, XSERVERS.TXT, XACCESS.TXT, and XDM_KEYS.TXT file. These files are not required unless you want to:
  - Configure a non-XDMCP X display
  - Restrict access to a remote X server
  - Provide XDMCP authentication
  - Change the way XDM computes the display name for XDMCP clients.
- Run SYS$MANAGER:TCPIP$CONFIG to enable XDM.

## 19.6.1 Ensuring XDM Is Enabled and Running

To make sure that the XDM service is enabled and that the XDM process is running, enter the following TCPIP command:

    $ TCPIP SHOW SERVICE XDM

    Service             Port  Proto    Process          Address            State

    XDM                  177  UDP      TCPIP$XDM        0.0.0.0             Enabled

# 19.7 Configuring Other X Displays

If you have an X terminal that does not support the XDMCP protocol, you can manage this terminal by using an XSERVERS.TXT configuration file. See Section 19.3.3 for information about how to create the configuration file.

If you are running Compaq eXcursion, refer to the Compaq PATHWORKS 32 eXcursion User's Guide for configuration information. For all other X servers, refer to the third-party X Window System software documentation for information about how to configure their product.

Previous | Next | Contents | Index