phrelay

Support remote connectivity with phindows and phditto clients

Syntax:

phrelay [-eGx] [-b number] [-D debugfile] [-g port]
        [-k delay,interval,retry] [-V...]

Runs on:

Neutrino

Options:

-b number

Set the number of messages buffered to allow write-ahead draws to Phindows or phditto. The actual number used is the lesser of this option and the -N option of Phindows or phditto. The default value is 20. Use a lower value to save memory at the expense of throughput, or, if memory isn't an issue, a higher value to gain some additional throughput performance. Adjusting this setting has the most effect when end-to-end response time is slow compared with throughput, such as over a modem or when there are many network hops between the local and remote ends.

-D debugfile

The file or device to which to send the debugging information specified by the -V option.

-e

Don't allow unencrypted connections. If this option is specified, the Phindows connection must provide a valid private key with the -K option, or the connection is refused. Without this option, Phindows can connect without encryption. For more information, see the Encryption section below.

-G

When phrelay isn't started automatically by inetd, you can start with this option to force phrelay to listen to socket port 4868.

-g port

This is the same as -G, but you specify the port.

-k delay,interval,retry

The keepalive delay (in seconds), interval (in seconds), and retry count. This option determines how long phrelay will stay alive when a network connection to a client has failed (for example, if a network cable is unplugged). The default setting is 20,5,3.

-V...

Be verbose. Add more V's for greater verbosity. Output is sent to the file or device you specify in the -D option that's required if you specify -V.

-x

Embed color palette information into the data stream. This option works around a problem where some applications with many small graphics may have incorrect palette tags, and therefore are displayed incorrectly on the client screen. If small graphics (such as on buttons) appear correctly, you don't need to use this option.

Description:

The phrelay utility supports remote user interface clients on other nodes.

Remote connectivity via modem

When you specify a modem (using the -m option to phditto or phindows), the remote client first acts as a simple text terminal emulator so you can interact with the modem, dial up a remote QNX machine, and log in.

Once you're logged in, you can start a Photon session by entering the following command:

exec /usr/bin/phrelay

The remote client synchronizes with phrelay and starts to function as a Photon graphics terminal.

Remote connectivity via TCP/IP

When you specify a TCP/IP connection (using the -t option to phditto or phindows), the inetd program running on the remote QNX host automatically launches phrelay for you, provided phrelay and inetd have been configured properly (see below).

Configuring for TCP/IP

There are several configuration issues that need to be taken care of before you can use phrelay over TCP/IP.

First, the QNX host must have TCP/IP installed and running. In addition, inetd must be running with the following items specified in the inetd configuration file /etc/inetd.conf:

phrelay stream tcp nowait root /usr/bin/phrelay phrelay

The file /etc/services file must include the following line (it's in the default file):

phrelay 4868/tcp

These two entries cause inetd to listen for incoming requests to establish a new Photon session. When a request is detected (from a remote phindows or phditto client), inetd automatically establishes a full TCP/IP connection and launch phrelay on that connection. The remote phindows or phditto client is then fully connected to a local Photon session.

Connecting using a serial port

You can use phrelay to connect a machine running phindows (on Windows) or phditto (on Neutrino) to a Neutrino self-hosted development machine acting as a target via the machines' serial ports.

Example serial connection

Use a null modem cable to connect COM1 on a Windows or Neutrino development host to /dev/ser1 on a QNX6 development machine acting as a target. Here are two similar procedures that can be used to connect phditto/phindows to phrelay:

1. On the target run on -t/dev/ser1 ksh
2. On the host run phditto -m/dev/ser1 or phindows -mcom1
3. In the phditto/phindows window, get the ksh prompt and then run stty +raw +echoe +echoke +echoctl +imaxbel +onlcr </dev/ser1
4. In the phditto/phindows window, run the following as root: phrelay -x

You should see the phrelay connect sequence automatically resume. Another way to connect to the target is as follows:

1. On the target, add /dev/ser1 to the list in /etc/config/ttys, and then as root restart or run tinit.
2. On the host run phditto -m/dev/ser1 or phindows -mcom1
3. In the phditto/phindows window, get the “login” prompt, log in, and then run: stty +raw +echoe +echoke +echoctl +imaxbel +onlcr </dev/ser1
4. In the phditto/phindows window run the following as root: phrelay -x

Using predefined Photon services

The -s command-line option of phditto and phindows is provided to simplify the task of creating shortcuts to Photon applications within the MS-Windows desktop.

By using the -s option, you can create an icon or shortcut on the MS-Windows desktop to start up a Photon application automatically (within a private phindows session). With proper specification of the remote Window Manager options, it's possible to make that Photon application look like it's a native MS-Windows application.

When phrelay runs on the QNX host machine, it looks up the Photon service specified with the -s parameter in a configuration file (/etc/config/phrelay[.node]). If a matching service is found, then phrelay launches the specified Photon command instead of the default Photon desktop. You can specify optional window-manager options, but the default mode is to start the remote Photon application so that it looks and behaves as if it were a native MS-Windows application.

The phditto/phindows -U option is often used with the -s option to specify a QNX userid to use when running the remote Photon command. If no userid is given, and the phrelay service doesn't specify a default userid, then Photon pops up the QNX Photon Login dialog requesting the QNX userid before proceeding. By specifying a userid with the -U option, you can avoid this login dialog.

For example, if a MS-Windows shortcut were created as follows:

phindows -tx.x.x.x -svpoker -Ujoe

where the IP address x.x.x.x specified the TCP/IP address of QNX node 2, and the phrelay configuration file on node 2 (/etc/config/phrelay.2) contained the following line:

vpoker % /usr/photon/bin/vpoker

then Joe could directly launch a Photon vpoker session (running as QNX userid joe) on his MS-Windows desktop by clicking on the shortcut icon.

phrelay configuration file format

The phrelay utility processes requests for service according to the contents of a configuration file. If phrelay is running on QNX node n, then the file /etc/config/phrelay.n is used. If this file doesn't exist, then the default file /etc/config/phrelay is used.

The format of each service entry in the phrelay configuration file is as follows:

service user [-W pwm_options] command

where:

service is the symbolic name of the Photon service (matches the -s phindows or phditto parameter).

user defines how to process userids that may be specified on the phindows or phditto command line (-U option).

user can be one of:

userid

QNX userid (if no -U). Prompt for password if required.

userid:password

QNX userid and password (if no -U).

%

Prompt for user/password (if no -U).

?

Always prompt for user/password (ignore -U).

!

Fail (if no -U).

=userid

Force this userid (ignore -U).

=userid:password

Force this userid and password (ignore -U).

pwm_options can be one or more of the following Photon Window Manager options:

P

Disable Taskbar, console switching, and keyboard.

W

Disable Workspace menu.

R remote_option

Remote Window Manager options, where remote_option can be one or more of:

b

Remove Photon Window Manager borders.

c

Close Window Manager when program terminates.

f

Fit. Make application always fit in phditto/phindows window. This is the same as both s and l options combined.

l

Continually resize the application to fit the phditto/phindows window.

m

Initially resize application to fit in phditto/phindows window.

r

Initially resize phditto/phindows window to fit application.

s

Continually resize the phditto/phindows window to fit the application.

t

Send Window title to phditto/phindows.

The default Window Manager options are PWRcbtfr.

command is the Photon command to launch instead of the default command, which starts the Photon desktop.

Data compression options

The phrelay utility supports one of three data compression options that the client can request:

• Byte-Pair Encoding — (BPE) performs the best data compression and is recommended for all serial connections. Although BPE is inexpensive to decode (both in memory and CPU usage), it does require a fair amount of CPU on the host QNX machine. When link speeds are low (such as with modem links), the extra cost in CPU on the sending side is well worth the tradeoff.
• Run Length Limited — (RLL) provides good data compression. Although not as highly compressed as BPE, RLL encoding is both quick to decode and encode. RLL encoding is recommended for network TCP/IP connections because it places less CPU load on the QNX host, yet provides fair compression.
• None — With data compression turned off, Photon draw events are transmitted “as is.” This might make sense if the connection bandwidth is very high (say 100Mb Ethernet), making the extra processing time involved in data compression an unnecessary step.

Data caching options

The phrelay utility makes very extensive use of data caching techniques to minimize the amount of data that needs to be transmitted from the host to the client machine. Thanks to this intensive data caching, phditto/phindows can operate over modem-link speeds as low as 9600 baud.

Most “large” static data objects in Photon are “tagged” with a unique 32-bit ID (tag). Tagged objects include bitmap data, image data, and color palettes. These objects are generally tagged when first created by the Photon program developers. This process is accomplished automatically by the Photon development tools, so the program developer is, for the most part, not even aware that this is taking place.

Photon passes these tags along with the data objects as they flow through the Photon event space. The end result is that Photon graphics drivers (such as phrelay) almost always have available a small, unique, precalculated tag to identify the larger Photon graphical objects.

Encryption

The phrelay utility supports encrypted connections with Phindows versions 3.09 and later.

When Phindows requests an encrypted connection (by specifying a key using the -K commandline option), phrelay looks for a matching key in the /etc/config/phkeys file. Each line of the file has this format:

*|user private_key

Keys can be up to 31 characters long.

The line that starts with the * character applies to connections that don't specify a Photon service and user ID. For Phindows connections that specify a service (-s), a user ID can also be specified using -U. In this case, phrelay finds the user in the /etc/config/phkeys, and checks that the specified key matches the key sent by Phindows. If a matching key isn't found, phrelay doesn't allow the connection, and Phindows displays a “Error: Permission problem on host” message.

Security

Both Phindows and phditto allow a user to connect to an existing Photon session, which displays the contents of the Photon session on the remote client's screen. You can disable this option by creating an /etc/system/config/noditto file on your target. When this file exists, remote clients can still connect to your target machine using their own private Photon session, but they can't view an already running Photon session.

Examples:

From a remote phindows or phditto session, type:

exec /usr/bin/phrelay

See also:

phditto, phrelaycfg

Using the Photon microGUI in the Neutrino User's Guide