The MultiNet X11-Gateway program provides X (X Window System) connectivity between a DECnet-only host and an IP-only host by a MultiNet node as an application gateway. The X11-Gateway is bidirectional; it functions as a gateway from a DECnet-only X client to an IP-only X server, or vice versa.
The gateway node requires MultiNet and DECnet software only. There is no requirement for the gateway to be running any X software. The gateway software can support multiple X Windows connections simultaneously.
Before configuring the X11-Gateway, be sure you understand the following terms:
|
Client |
The node executing the X application |
|
Gateway |
The node connected to an IP network and a DECnet network. Information from the client on one network is passed through the gateway to the server on the other network. |
|
Server |
The node running the X server software. (Typically a host with a mouse, keyboard, and at least one bit-mapped screen.) |
|
Server number |
A unique number identifying the X11-Gateway to MultiNet, DECnet, and the X software on the client and server nodes. Each configured gateway is assigned a unique server number by the system manager. |
To avoid conflicts with current and future versions of DECwindows software, use numbers beginning with 10 and increment for each new gateway. For example, assign the number 10 to the first X11-Gateway, the number 11 to the second, and so on. As you remove X11-Gateways from the system, you can reuse their server numbers.
To configure the X11-Gateway host to allow an IP client access to a DECnet server:
1. Choose an X11-Gateway server number between 10 and 999.
2. Create a TCP port number by adding 6000 to the server number. For example, if the server number is 13, the TCP port number is 6013. TCP port 6000 is used by DECwindows servers. Select port numbers starting at 6010 to avoid conflicts with DECwindows.
3. Add the X11-Gateway service to the list of TCP/IP services using the Server Configuration Utility (SERVER-CONFIG). Information about using this utility and its commands is provided in Chapter 12.
The prefix X11-GATEWAYxxx is added to the name of the service you install; xxx is the server number you selected in Step 1. For example, for server number 10, the service you add using SERVER-CONFIG is X11-GATEWAY10. SERVER-CONFIG provides the X11-GATEWAY13 service, but the number 13 has no significance; this service is provided only as an example. You can use this service or any number of your choice between 10 and 999. If you chose 13 as the server number in Step 1, you can enable the existing X11-GATEWAY13 service using SERVER-CONFIG. There is no need to add this service, as it has already been added it. The following example adds an X11-Gateway server number of 12.
$ MULTINET
CONFIGURE/SERVER
MultiNet Server Configuration Utility 5.6
[Reading in configuration from MULTINET:SERVICES.MASTER_SERVER]
SERVER-CONFIG>ADD X11-GATEWAY12
[Adding new configuration entry for service "X11-GATEWAY12"]
Protocol: [TCP] RETURN
TCP Port number: 6012
Program to run: MULTINET:X11-GATEWAY.EXE
[Added service X11-GATEWAY12 to configuration]
[Selected service is now X11-GATEWAY12]
SERVER-CONFIG>RESTART
Configuration modified, do you want to save it first ? [YES] RETURN
[Writing configuration to
MULTINET_COMMON_ROOT:[MULTINET]SERVICES.MASTER_SERVER]
%RUN-S-PROC_ID, identification of created process is 20E0026B
SERVER-CONFIG>EXIT
4. Define the X11-Gateway logical names. The X11-Gateway accepts connections from the IP network and routes the X protocol requests to a specific DECnet X server. Specify the server using the following logical names:
MULTINET_XGATEWAY_TCPIP_server_number_HOSTNAME
Specifies the DECnet host name. This logical name must be defined, but do not include the colons from the DECnet host name.
MULTINET_XGATEWAY_TCPIP_server_number_SERVER
The X server number of the node where the X client application is displayed. Most hosts run one X server, which is designated as server 0 (zero). This logical name is optional if the DECnet X server number is zero. The X11-Gateway assumes a DECnet X server number of zero if you do not define this logical. You should define the logical if the DECnet X server number is not zero.
In the following example, the X11-Gateway server number is 12. The X11-Gateway accepts connections from the IP network and gateways them to X server 1 on the DECnet node BRONX. Assign values to these logical names using commands like the following examples:
$ DEFINE/SYSTEM/EXEC
MULTINET_XGATEWAY_TCPIP_12_HOSTNAME BRONX
$ DEFINE/SYSTEM/EXEC MULTINET_XGATEWAY_TCPIP_12_SERVER
1
Insert these logical name definitions in the system startup procedure so they are invoked after the DECnet and MultiNet startup procedures execute.
To bring up the X application on the IP-client-to-DECnet-server configuration:
1. On the DECnet server, authorize DECnet connections from user SYSTEM on the gateway node. If the MULTINET_SERVER process on the gateway node has been started under a user name other than SYSTEM, that user should also be authorized. A less secure, but more reliable, method is to authorize the "*" user. See the X11-Gateway Security section.
On UNIX systems, use the xhost command to provide connection authorization. On ULTRIX or OpenVMS, use the Session Manager.
2. On the IP client, set the display variable to point to the X11-Gateway host. Use the X11-Gateway server number for the display server number.
On UNIX systems, use the setenv command to modify the DISPLAY environment. On OpenVMS systems, use the SET DISPLAY command.
3. On the IP client, start the X application.
For example:
· The IP X client node is the UNIX node pelham.example.com. The X11-Gateway node is metro.example.com (TCP/IP) and METRO:: (DECnet). The X11-Gateway server number is 12. BRONX:: is an OpenVMS DECnet X server.
· On the BRONX:: node, the user authorizes protocol DECNET, node METRO, and user "*" using the Security pull-down menu in the Session Manager.
· On the pelham.example.com UNIX node, the user runs setenv to set the DISPLAY environment variable to the value amtrak.flowers.com:12.1. The user can then invoke an X application.
· The X application appears on the BRONX:: node.
To configure the X11-Gateway to allow a DECnet client access to an IP server:
1. Choose an X11-Gateway server number as described in Allowing an IP Client to Access a DECnet Server.
2. Add the X11-Gateway to the list of DECnet objects. The object name for the X11-Gateway has the value X$Xserver_number. For example, for a server number of 17, set the object with this command:
$ RUN
SYS$SYSTEM:NCP
NCP> DEFINE OBJECT X$X17 NUMBER 0 FILE
MULTINET:X11-GATEWAY.EXE
NCP> SET OBJECT X$X17 NUMBER 0 FILE MULTINET:X11-GATEWAY.EXE
If the DECnet default account is disabled, the command should include a valid USERNAME and PASSWORD on the gateway system. In this example the X11-Gateway server number is 17:
$ RUN
SYS$SYSTEM:NCP
NCP> DEFINE OBJECT X$X17 NUMBER 0 FILE -
_ MULTINET:X11-GATEWAY.EXE USER SYSTEM PASS systempassword
NCP> SET OBJECT X$X17 NUMBER 0 FILE MULTINET:X11-GATEWAY.EXE -
_ USER SYSTEM PASS systempassword
3. Define the logical names. The X11-Gateway accepts connections from the DECnet network and directs X protocol requests to a specific IP X server. Specify the server is using the following logical names:
MULTINET_XGATEWAY_DECNET_server_number_HOSTNAME
Specifies the IP X server host name. You must define this logical name.
MULTINET_XGATEWAY_DECNET_server_number_SERVER
Specifies the X server number, which is typically set at 0 (zero) to indicate that a single server is being used. If a second server is in use, set this value to 1, and so on. If this logical name is not defined, the default value is 0. For example, the X11-Gateway server number is 17. The X11-Gateway accepts connections from the DECnet network and directs them to X server number 1 on the IP node englewood-nj.example.com. The logical names are then defined as:
$ DEFINE/SYSTEM/EXEC
MULTINET_XGATEWAY_DECNET_17_HOSTNAME -
_$ ENGLEWOOD-NJ.EXAMPLE.COM
$ DEFINE/SYSTEM/EXEC
MULTINET_XGATEWAY_DECNET_17_SERVER 1
Insert these logical name definitions into the system startup procedure so the definitions occur after the invocation of the DECnet and MultiNet startup procedures.
To bring up the X application on the DECnet-client-to-IP-server configuration:
1. On the IP server, authorize IP connections from the gateway node. X-over-IP does not provide user name information. If a user name is required as part of the authorization (for example, on OpenVMS) use a "*" value. Connection authorization is usually accomplished with the xhost command on UNIX systems, or with the OpenVMS or ULTRIX Session Manager.
2. On the DECnet client, set the display variable to point to the X11-Gateway host. The X11-Gateway server number should be used for the display server number. On UNIX hosts (including ULTRIX) use the setenv command; on OpenVMS systems, use the SET DISPLAY command.
3. On the DECnet client, execute the X Windows application.
For example:
· The DECnet X client is an OpenVMS node METRO::. The X11-Gateway node is DENISE:: (DECnet) and DENISE.EXAMPLE.COM (TCP/IP). The X11-Gateway server number is 17. The IP X server is the UNIX host englewood-nj.example.com.
· On englewood-nj the user authorizes node denise.example.com by entering the command:
% xhost +denise.example.com
· On METRO, the user issues the command:
$ SET DISPLAY/CREATE/NODE=DENISE/TRANS=DECNET/SERVER=17
· The user can then invoke an X application, which appears on the englewood-nj server.
The X11-Gateway node does not attempt to restrict connections it receives from the network. As a result, any node or user on the client side of the gateway can access the server, essentially allowing a client user to monitor all activity on the X server via the X11-Gateway.
For IP-client-to-DECnet-server connections, you can reduce risk by using the ACCEPT-HOSTS/ACCEPT-NETS capabilities of the MultiNet master server on the gateway host. For more information, see Chapter 12.
For DECnet-client-to-IP-server connections, your risk can be reduced by using the NCP utility to limit access to the gateway host.
Process Software does not recommend running the X11-Gateway on untrusted networks unless other restrictions have been imposed by the system manager.
The best programs for testing client-to-gateway to server connectivity are based on the Xlib routines (as opposed to widget toolkits).
The ICO program is available on most X implementations (for example, /usr/bin/X11/ico or DECW$EXAMPLES:ICO) and works well for debugging problems. The ICO program opens a window and causes an icosahedron to bounce around the window. When this program works, X works as well. Exit the OpenVMS version of this program by pressing Ctrl/Y in the window from which you invoked ICO. You can also use the MultiNet X11DEBUG command to debug OpenVMS IP client problems.
The table below lists error values from the ERRNO.H file.
|
Error |
Value |
Description |
|
ENETUNREACH |
51 |
The IP network you are trying to contact is currently unreachable. |
|
ECONNRESET |
54 |
The connection was reset by the remote node. This typically occurs when the remote host has rebooted and the local host attempts to transmit on a stale connection. |
|
ETIMEDOUT |
60 |
The connection timed out during the open. |
|
ECONNREFUSED |
61 |
The connection was refused. This occurs when a connection is attempted to a nonexistent server process. |
|
EHOSTUNREACH |
65 |
There is no route to the host you are trying to contact. |
The X11-Gateway node transmits NETWORK class operator messages when an error is encountered. You can change the level of information supplied by X11-Gateway messages by defining the logical name MULTINET_XGATEWAY_DEBUG_LEVEL in the system table. Set this value to:
· 0 - to receive fatal errors
· 1 - for debugging messages
· 2 - for informational messages
For example, to select debug level 1:
$ DEFINE/SYSTEM/EXEC
MULTINET_XGATEWAY_DEBUG_LEVEL 1
$ @MULTINET:START_SERVER
If the logical name does not exist, the DEBUG level defaults to a value of zero. All error messages from the X11-Gateway are prefixed with Xgateway:. The errno values can be translated by examining ERRNO.H Error Values, or by consulting ERRNO.H in the MultiNet Programmer’s Guide. Status values are OpenVMS error values that you can examine using the command WRITE SYS$OUTPUT F$MESSAGE(Status).