PLId to Port Mapping
PLId to Port Mapping enables fixed Reality port numbers to be allocated to incoming terminal connections using their PLIds (Physical Location Identifiers), so that whenever a user logs in at a particular terminal, the same port number is allocated each time. The allocated port number will be unique and consistent.
Before connecting to the database, Reality requests its PLId from the host Session Manager (smanager), then performs a look-up in a 'PLId to Port' mapping file called devices. If the PLId matches a valid entry in the devices file, the corresponding port number is allocated to the terminal connection. Provided that the Reality process is not a background server, this port number is then requested when making the connection to the Reality database. If the PLId does not exist in the devices file or the port is already in use, the next available virtual port number is allocated (note that you can prevent a virtual port being allocated if the port is in use by using the NOVIRT
The devices file is also used:
-
To determine the PLId for background processes which are started on a particular port number (e.g. TIPHs and LOGONs).
-
By TCL commands, such as LOGON, and PH-START, which reference a port number. It is used to look up the PLId associated with the specified port number and determine the identity of the UNIX device file for that port number.
PLId to Port mapping is enabled by creating and configuring the devices file as described below.
Setting Up the Devices File
The PLId to Port mapping facility is automatically enabled by the presence of the devices file in the Reality database configs directory, or globally in $REALROOT/files. Reality looks in the configs directory first and then in $REALROOT/files, using the first devices file it finds. If no devices file is found, or if the file contains no valid entries, Reality will assign virtual port numbers to all connections.
The devices file can contain two types of lines: Comment lines and Data lines.
-
Comment lines are blank or have a '#' as their first non-blank character. These lines are ignored.
-
Data lines have the format:
PLIdSpec BasePort {Keywords} {#Comment}
where:
PLIdSpec is either a single PLid or a range of PLids (with the range in brackets).
BasePort is the port number assigned to the PLid or to the first PLid in the range (subsequent port numbers are offset from this number according to the position in the range of the PLid).
Keywords and a trailing comment (following a '#' character) are optional.
PLId and Port Specifications
There are two supported formats of Data line with differing PLId and port/PC session specifications.
-
Exact Match - for example:
UNIX-0-console 0 # Console
NT-0-con 0 # Console
These examples both specify a single PLId that maps to a single port number. The PLId must match exactly.
-
PLId Range - for example:
UNIX-0-tty[01-03] 1 # Moto V3 (Ports 1 to 3)
This example specifies a range of PLIds from UNIX-0-tty01 to UNIX-0-tty03 which are mapped onto ports in the range 1 to 3. The port number specified is used for the first PLId in the range and subsequent PLIds are assigned increasing port numbers according to their position in the range.
INET-192.67.50.5-[01-99] 1 # Telnet (Ports 1 to 99)
This example specifies a range of PLIds from INET-192.67.50.5-01 to
INET-192.67.50.5-99 which are mapped to ports or PC session numbers in the range 1 to 99. The port/session number specified is used for the first PLId in the range and subsequent PLIds are assigned increasing numbers according to their position in the range.In this format the range specified in brackets must be a numeric range with no gaps and must be at the right hand end of the PLId specification. The numbers specified may be in decimal (default), or hexadecimal (indicated by the HEX keyword), and may be of fixed or variable length as appropriate to the PLId format.
Keywords
The optional keywords field may contain one or more keywords (separated by spaces) which have two main uses.
-
To describe the format of the final part of the PLId and control the conversion between PLId format and relative port number. These keywords are named according to the format they describe.
-
To specify attributes associated with the PLId. They are named according to the attribute they specify.
The current list of valid keywords is:
DEC Specifies that the PLId range is given in decimal numbers. This is the default and need not be specified explicitly.
HEX Specifies that the PLId range is given in hexadecimal numbers.
NOVIRT Specifies that if the port is already in use, a connection should fail rather than assign a virtual port to this PLId.
OPEN Specifies a port or range of ports that can be used by any PLid. These ports can only be used by using the reality command's -t option to specify the required port or allocating them as TIPH ports with the PH-ALLOCATE TCL command.
PRIV Specifies 'Privileged ports' that may use reserved licences. See the topic Reserved Licences.
RANGE Specifies that a range of port numbers specified with the OPEN keyword should permit logon to the first free port in the range. If two users both specify the same port, they will be allocated different ports within the range defined.
Note
-
This functionality must be enabled by setting the PortRange database configuration parameter.
-
If you create or change a devices file entry that includes the RANGE keyword, your changes will not take effect until you either shut down the database (using killreal -d) or run user exit U37C5 from a Proc or DataBasic program.
UHEX Specifies that the PLId range is given in upper-case hexadecimal numbers.
If no keyword is specified to define the algorithm for converting between PLIds and relative port numbers, the final part of the PLId is assumed to be a decimal number.
Examples
Some example devices file entries are shown below. A template file called devices.tmpl is available in $REALROOT/files.
Note
These examples show a wider variety of PLId types than would normally be found in a single system.
UNIX
# # Example devices file entries # UNIX-0-console 0 # Console UNIX-0-tty[01-03] 1 # Moto V3 (Ports 1 to 3) UNIX-0-tty[11-99] 11 # Moto V3 (Ports 11 to 99) UNIX-0-tty0[00-3f] 100 HEX # Moto V3 (Ports 100 to 163) UNIX-0-tty1[00-3f] 164 HEX # Moto V3 (Ports 164 to 227) UNIX-0-tty2[00-3f] 228 HEX # Moto V3 (Ports 228 to 291) UNIX-0-tty3[00-3f] 292 HEX # Moto V3 (Ports 292 to 355) UNIX-0-term[0-199] 0 NOVIRT # Moto V4 (Ports 0 to 199) UNIX-0-rt00[01-20] 201 HEX # ANNEX (Ports 201 TO 232) inet-192.67.50.5-[0-31] 300 # Telnet (Ports 300 to 331) TNET-00802D0045C6-[1-32] 351 # Telnet (Ports 351 to 382) [1-5] 15 OPEN RANGE NOVIRT # Opens ports 15 to 19 for logon to next free port
Windows
NT-0-con 0 # Console
INET-192.67.50.5-[01-03] 1 # Telnet (Ports 1 to 3)
INET-190.67.50.5-[11-99] 11 # Telnet (Ports 11 to 99)
INET-192.67.50.5-[0-31] 300 # Telnet (Ports 300 to 331)
INET-170.88.0C.40-[00-67] 228 # Telnet (Ports 228 to 295)
INET-98.72.0C.0C-[2] 100 # Telnet (PC Session No. 2, port 100)
INET-98.72.0C.0C-[00-28] 164 # Telnet (PC Session Nos. 00 to 28, ports 164 to 192)
INET-75.67.50.05-[00-32] 292 # Telnet (PC Session Nos. 00 to 32, ports 292 to 324)
TNET-00802D0045C6-[1-32] 351 # Telnet (Ports 351 to 382)
Checking the Devices File for Errors
For the PLId to Port mapping software to operate correctly, the mapping information in the devices file must be formatted correctly and PLId/port identities must be within defined limits. The validity of the information in the devices file can be checked by running the chkdev utility.