INTRODUCTION
TO PORTMAPPING:
Portmapping configuration
allows
administrators to customize how the CommPortIdentifier list is populated, and
therefore
which devices
are available to applications. Through
the portmap.conf file
the administrator can create descriptive aliases to replace default
names that are otherwise assigned to ports. Portmapping is an
implementation specific feature that is not defined in the API.
Currently this portmapping scheme it is only offered in Sun's
implementation of javax.comm for Solaris and Linux. It is
possible that at some point a Java Specification Request (JSR) can be
created to expand the CommAPI to allow a pluggable portmapping strategy
in a future release.
The portmap.conf file consists of lines. Each non-commented line is referred to as a portmapping entry. One of the more powerful types of portmapping entry is the Automatic Logical Name (ALN), which is a shorthand notation used to refer to ports on USB-to-Serial converters (AKA 'dongles') that can be connected to Sun Rays to provide them RS-232 interfaces. ALNs allow the administrator to refer to a dongle's ports without having to specify the filesystem-specific path to the device, and without having to create softlinks in the filesystem. Besides making configuration much simpler, ALNs also make DTU replacement easier. Other portmap entries are provided to allow server ports to be visible in Sun Ray sessions, as by default a Sun Ray can only see ports on connected dongles, and only via the port's default name. The format of portmap.conf has changed substantially in version 3.0. In previous releases, the portmapping configuration file was called portmap.properties, however starting javax.comm 3.0 it is called portmap.conf. All of the previous portmapping functionality has been subsumed into the new feature set and is now embodied in the DTU Assigned portmap entry type. Each portmap entry type in portmap.conf has a disposition, syntax and privilege. These qualities describe how a portmap entry is identified, under which circumstances such an entry will be active, and when the represented port is visible to the application. Generally when a portmap entry is active (ie. meets all criteria to enable it), the alias provided for the represented port will be offered in the port list instead of a physical path or default name for the port. There are two broad catagories of portmap file entries: session dependent, and session independent. These refer to whether a rule applies to a Sun Ray sessions or not. Session dependent entries are active only if the javax.comm JVM is running in a SunRay session, otherwise session independent entries are activated. Therefore, if javax.comm is not running in a Sun Ray environment, session dependent entries have no function. The following types of processes are not considered Sun Ray sessions:
DEFAULT BEHAVIOR: If portmap.conf
is
not present, cannot be located, is empty, or contains unusable
information, javax.comm uses
a default portmapping strategy. Default behavior differs
depending upon whether javax.comm is
run in a Sun Ray session or not. If the JVM is running outside of
a Sun Ray session, the locations searched for comm. port devices are
specified in the platform-specific javax.comm.properties
file. That required configuration file is distributed with
defaults port paths setup to locate commonly used ports for the
represented platform. (This is a new feature in the Sun
distribution as of javax.comm 3.0).
Note: See the comments in javax.comm.properties file if you need to modify, add or delete port paths to javax.comm for any reason. Default behavior when the JVM is running in a Sun Ray session is to list all the ports on all dongles attached to the current Sun Ray. Default Port Names: If no portmap entry exists to override the default name assigned to ports, the default name is used. Default port names are the names given to CommPortIdentifiers, and are created differently by javax.comm depending on whether the port is on the server chassis (or serial port expansion card plugged into a server bus), or if the port is on a dongle attached to a Sun Ray. The default name used for server ports is the full device path to the port device node. The name given to Sun Ray dongle ports is the final namespace element in the dongle device path, which is typically the dongle's vendor name as represented to the filesystem by the dongle driver. LOCATING portmap.conf: When the CommPortIdentifiers.getPortIdentifiers()
method is initially invoked by the application, javax.comm
first attempts to locate and parse a file called portmap.conf
.
Note: In previous releases portmap.conf was called portmap.properties. An example of this portmap.conf can be found here In javax.comm 3.0 the following
search order is used to locate portmap.conf
(If the search fails,
default portmapping is used): 1. Current directory. 2. Each directory in ${java.classpath} (ie. $CLASSPATH or -classpath setting). 3. <java installation dir>/lib. 4. <java installation dir>/jre/lib. NOTE: <java installation dir> refers to the directory the JVM is launched from. It is not necessarily the value of $JAVA_HOME. PARSING portmap.conf: If portmap.conf is located, it's contents will modify portmapping behavior accordingly. During parsing of portmap.conf, any text that is commented with '#' is ignored. A comment begins as soon as a '#' character is encountered and remains in effect until the end of the line. Blank lines are ignored. This document describes the format and action of each type of portmap entry allowed. Parsing errors are not displayed by default. Each rejected line in portmap.conf is silently discarded, unless the administrator enables the debugging option to log portmap parsing errors. Please see this usage example (PDF) of portmap.conf for more information. DEBUGGING the portmapping configuration file: The debug_portmap property is used to enable logging of portmap.conf errors when launching the JVM. Example: $ java -Ddebug_portmap myTargetApplicationClassFile When debug_portmap is enabled, portmapping errors and portmap path translation during CommPort.open() are displayed on stderr. An even more informative dump is enabled with -Ddebug_portmap=all, which additionally displays how successfully parsed entries were interpreted. ALNs (Automatic Logical Names): The purpose of an ALN is to be able to refer to a port on a dongle without the application or administrator ever needing to know the device path in the filesystem. ALNs are designed to greatly simplify configuration, and make Sun Ray (DTU) replacement very easy. When ALNs are used, all that is required to swap out a DTU is to update the Terminal ID in the corresponding DTU Alias entry in portmap.conf. ALNs are automatic in the sense that they are automatically translated into the full path of the of dongle port by javax.comm when when getCommPortIdentifer() or getCommPortIdentifiers() are called. portmap.conf is loaded only once and parsed when javax.comm is loaded. If portmap.conf is modified, the JVM must be re-started for the changes to take effect. Examples of ALNs:
utcom1 - Refers to the first serial port on the target dongle. utcom2 - Refers to the 2nd serial port on the target dongle. ... utcom<n> - Refers to the nth serial port on the target dongle. utprt1 - Refers to the first parallel port on the target dongle. utprt2 - Refers to the 2nd parallel port on the target dongle.
...
utprt<n> - Refers to the nth parallel port on the target dongle. Summary of portmap.conf entry types:
|
Syntax:
|
<alias>
= <Terminal ID>
<alias> = <DTU Mac Addr> |
Disposition: | Session
Independent |
Privilege: | None
|
Examples: | Teller1
=
02:5f:39:93:ab:92 Kiosk = IEEE802.5abc2309fc29 |
A DTU must be given a name
in order to
make reference it in portmap.conf,
and after the alias is assigned, all references to th Sun Ray DTU must
thereafter made using its alias.
The reason for thes restriction is to enforce the policy of clarity, simplicity and ease of DTU replacement. DERIVING TERMINAL ID: Chord method:
The easiest way to derive the MAC address of a Sun Ray DTU, which is used on Sun Ray to form the terminal ID, is to press the 'chord' (three buttons) simultaneously. The 'chord' is comprised of the leftmost three buttons in a row of four buttons above the numeric keypad. These three buttons are mute, volume +, and volume -, respectively (each has an icon of a speaker device). Directory lookup method: An alternative way to determine the MAC address of a DTU is to login on the DTU and type at the shell prompt echo $DISPLAY (using only the part of the number that precedes the dot. For example DISPLAY = :21.0 meands the display number is '21'. Assuming the display number is 21, the following will display the terminal ID: % ls -l /tmp/SUNWut/sessions/21/unit This will display a link to a path whose final path element is the DTU terminal ID |
Syntax: | <alias> = DTU Alias : <physical path to server port> |
Disposition: | Session
Dependent |
Privilege: | None |
Examples: | Central
Printer = Joes_SunRay:/dev/term/a |
DTU Assigned aliases allow the
administrator to make a server port to show up in the CommPortIdentifier
list of a specific DTU, and only
on the specified DTU. By default server ports are not available to Sun Ray session. DTU Assigned aliases are NOT the recommended method for referring to dongle ports as that requires cluttering the environment with device links which are difficult to administer and maintain. The preferred way to configure dongle ports is with Session Local ALNs, and DTU Specific ALNs. DTU Assigned aliases enable applications running on a Sun Rays to access a devices connected to a server port as if the devices were physically connected to a Sun Ray dongle port. |
Syntax: | <alias> = * : <physical path to server port> |
Disposition: | Session
Dependent |
Privilege: | None |
Examples: | Central_Logger
=
*:/dev/term/a shared_printer = *:/dev/ecpp0 |
Globally
Visible aliases allow the
administrator to make a server port to show up in the CommPortIdentifier
list within sessions running on all Sun Ray DTUs. In all other
ways, Globally Visible
aliases are identical to DTU Assigned
aliases. Globally Visible aliases are called 'Session Dependent' because, even though they are visible to all Sun Ray sessions, the alias is not active unless inside a Sun Ray session. To provide an alias that goes into effect for a port outside of a Sun Ray session, use a Path Alias. |
Syntax: | <alias> = <filesystem path to comm. port> |
Disposition: | Session
Independent |
Privilege: | None
|
Examples: | Central_Logger
= /dev/term/a shared_printer = /dev/ecpp0 |
Path Aliases
allows descriptive
names to be
given to device paths that javax.comm
locates during its default device search. The alias is offered in
lieu of the path
name, and applies only to applications running on a workstation
or server. They Path Aliases do not appear in Sun Ray
sessions. The
proper way to use an alias to be seen in a Sun
Ray session is with a DTU Assigned entry
or a Globally Visible
entry. A Path Alias cannot be used to refer to arbitrary devices. The mechanism used to define new devices for javax.comm to be aware of is by adding them to the javax.comm.properties file. The format of that file is described in the comments of the one that comes with the distribution. |
Syntax: | [hide]
<filesystem path to comm. port> |
Disposition: | Session
Independent |
Privilege: | None |
Examples:
|
[hide]
/dev/term/a [hide] /dev/cua/b |
Hidden aliases are
kept them from appearing in the CommPortIdentifier list.
This type of portmap entry is similar to path alias, except that rather
than providing a different name for a device the device is not
shown. |
Syntax: | <alias>
= ALN |
Session
Dependent |
|
Privilege: | None |
Examples: |
local_printer = utprt1 cashdrawer = utcom1 |
A Session
Local ALN provides an abbreviated way to access ports on a
dongle connected
to the local DTU. If the session migrates
to a new DTU, the ALN will refer to the corresponding port on
the dongle of the new DTU, if any. This eliminates the need
for the administrator to create device links in order to be able to
access
Sun Ray dongle ports, or have to specify device paths to dongle ports
in portmap.conf. By connecting peripherals to dongles consistently among DTUs, the administrator can simplify the application. For example, if it is known that a printer is physically connected to the 1st serial port of the the on each Sun Ray, and a cash drawer on the 2nd port, then by assigning corresponding logical names to utcom1 and utcom2, respectively, the application can refer to those logical names and know that it is communicating with a printer or cash drawer without having to consider which Sun Ray the application's Sun Ray session is running on. If a Session Local ALN portmap entry refers to a valid port on a supported dongle, the alias appears in the port list when getCommPortIdentifiers() is called, in place of default name of the dongle port. Each Session Local ALN is referred to by the administrator according to the port it represents on the dongle). For example, utcom1 refers to the 1st serial port on the dongle, utcom2 refers to the 2nd port on the dongle, and so on. Similarly, utprt1 refers to the first parallel port. If the ALN port number exceeds the number of ports on the first dongle found connected to the DTU, for example, referring to port #5 on a 4-port dongle, the ALN reference will 'spill over' to the next dongle, that is, if any other dongle are connected to the Sun Ray, and would refer to the first port on the subsequent dongle. This is because the ALN port number reference is really just an index into the list of device links in the Sun Ray device directory. Hotdesking: Session Local
ALNs always follow the session and are not tied to a
specific device. DTU
Specific ALNs
are used to alternatively refer to dongles on specific DTUS as though
from a bird's eye view.
When a session moves to a new DTU (that kind of session migration is known as hotdesking in Sun Ray terminology), javax.comm throws an exception for any ports opened on the previous DTU. Once the session has migrated to the new DTU, the next time comm. ports are enumerated by the application, the logical names specificed in those ALN entries in portmap.conf will then map to corresponding port on the dongle on the new DTU, and those ports will need to be openned in order to use. There are two types of the
Session Local ALN, to accommodate different application strategies. |
Syntax: | <alias> = DTU Alias : ALN Note: The syntax of this entry looks similar to the DTU Assigned alias, but each serves an entirely different purpose. This type of definition refers to Sun Ray dongle ports and always ends in utcom1, utcom2, utprt1, etc... A DTU Assigned alias always ends in a device path, such as /dev/term/a. |
Disposition: | Session
Independent |
Privilege: | root |
Examples: |
hallway_printer = hallway_dtu:utprt2 retina_scanner = entrance:utcom1 |
The purpose of the DTU Specific ALN is to access a dongle port on an arbitrary Sun Ray DTU, without the administrator needing to know, nor having directly refer to the the dongle port's filesystem device path. Root privilege is required to view ports on other DTUs. Without root privilege, Sun Ray devices is only accessible from sessions running on the DTUs devices are locally attached to. DTU Specific ALNs are provided primarily to provide a means for daemons (running as root) to be able access devices on any Sun Ray, requiring minimal configuration effort. A DTU Specific ALN is used to make a static reference to a particular serial port on a specific Sun Ray, regardless of whether javax.comm is run from inside or outside of a session. In contrast, Session Local ALNs always refer to the local DTU. The alias will appear in the CommPortIdentifier list only if the the target DTU is online and available, there is a compatible dongle is attached to the DTU, and the specified port is present on the dongle at the time getCommPortIdentifer() or getCommPortIdentifiers() are called. Unless debugging is enabled, erroneous or unresolvable ALN aliases are silently dropped. ALN spillover: Intuitively, utcom3 is not a valid specifier for a dongle with only 2 serial ports. On a dongle with two ports, only utcom1 and utcom2 are valid. If a dongle has two ports, a reference to utcom3 'spills over' to the next dongle if another dongle is attached to the DTU. That is, if there are subsequent dongles attached, thst spillover will refer to the first available port on the subsequent dongle. If there are no additional dongles, the reference to utcom3 is silently discarded as an error. Consider a case where two 2-port dongles are attached to one Sun Ray; utcom4 would refer to the 2nd port on the 2nd dongle. The problem with using 'spill over' is in determining which dongle is dongle 1, and which is dongle 2, as the order of enumeration is not obvious unless the USB connector and hub enumeration order is carefully analyzed by the administrator. For that reason, and the fact that unwary user's might move the USB conectors, the multi-dongle per DTU scenario is probably best avoided. ALNs work by indexing into the list of files in the Sun Ray device directories. The order in which the dongles are listed is based on dongle type and to which USB ports/hubs the dongles are connected. Therefore, the easiest way to guarantee a 1:1 mapping between ALNs and dongle ports, is to ensure that one dongle is ever attached to a given DTU and that the dongle has sufficient number of ports. In other words, if 4 ports are needed, get a 4-port dongle; if 7-ports are needed, use an 8-port dongle. If multiple dongles are used, great care needs to be taken to determine the enumeration order and keep the hardware and portmap.conf file in sync with one another. Therefore multiple dongles per DTU is not in the spirit of ALNs. |