set sharing
Purpose
Configures or displays the port sharing feature. A Digi device enabled for port sharing allows more than one client to open a serial port through RealPort, reverse Telnet, reverse SSH, or connect.
All clients that share a port will read the same data from the serial port; the data is duplicated and sent to each client. All clients that share a port will have the data they write merged and sent out the serial port. The serial port parameters, such as baud rate and flow control, can either be shared by all clients or be controlled exclusively from the Digi device alone.
If there is only one client, RealPort, reverse Telnet, reverse SSH, and connect will work properly.
Port sharing is available on select products only
Port sharing is supported on select Digi products only. To determine whether this command and the port sharing feature are supported on a product, enter help set ?. If sharing is displayed in the returned list, this command is supported.
About flow control on shared ports
All open shared ports share the same underlying input data buffers, so they must remain roughly in sync in the input data stream. For example, if one client stops reading data, the other clients sharing that same physical port can only read one buffer full of data ahead before they must wait for the first client to catch up.
To overcome this limitation that all clients must remain roughly in sync when reading data, a user-configurable timeout can be set by the set sharing timeout option. If one client is waiting for the other clients to read, it only has to wait until the timeout expires and then it will be allowed to continue reading. The other clients, that is, the clients that are not reading data, will lose data from the time the timeout expires until they begin reading again. This timeout will not be set by default.
Considerations and cautions for port sharing
CAUTION! There are several caveats when using port sharing:
- When clients send data to the ports, their data will be intermixed; that is, there is no synchronization of the data. If two clients send data at the same time, the data from one client might appear in the middle of the other client's data.
- If one client stops reading data, the input will be flow-controlled for all clients. Clients can only be able to read data at the rate of the slowest client. (There is a timeout to override this, as described above.)
- Incoming opens, persistent opens, and immediate opens may not behave as expected when multiple clients are opening the port at the same time.
- The modem control lines are not dropped until all clients have closed the port.
- When multiple clients share control of the serial port options, such as baud rate, data size, parity, or flow control, the last options set take effect. The serial port options could be changed unexpectedly by another client. This could leave the RealPort driver confused about the correct serial port settings. Different RealPort drivers might react differently to these unexpected changes in serial port settings.
Configure Serial Port Settings
- Certain applications disable flow control temporarily to drain the serial port when a connection is closed, if hardware flow control is enabled and other applications are sending/receiving data during this time serial overflow errors may occur.
- When multiple clients share control of the serial port options, and a new client opens a port, that new client might momentarily set the options to default values before the application can set the options correctly. This might momentarily disrupt communication with the other clients. Depending on the operating system used by the client, it is possible to set the default serial port options to match the options required by the application, and there will be no disruption.
- When multiple clients share control of the serial-port options, some serial-port options, such as case conversion, carriage return, or new line mapping, might be handled on the client system. Therefore, these options would apply to the client that set these options only.
- When the Digi device exclusively controls the serial port settings, any attempt to change the serial port settings from a client are silently ignored. The client believes the settings have been changed, when in fact they have not. The only way to change the serial port settings is through the command line on the Digi device or through the web UI.
- With reverse Telnet, reverse SSH, and connect, it is possible for a single client machine to open a single shared port multiple times by using multiple telnet or ssh sessions. However, with RealPort, it is not possible for a single client machine to open the same RealPort multiple times and use port sharing. Windows simply prevents one machine from opening a RealPort more than once. Unix does allow a single machine to open a RealPort more than once, but the sharing is happening on that Unix machine, not on the Digi device. Unix sharing does merge data written to the port and shares control of the port. However, it does not duplicate the incoming data to all programs that have opened the same RealPort. Instead, the incoming data is arbitrarily divided among the programs. It is possible for one machine to use port sharing with RealPort, but only by configuring the RealPort driver multiple times for the same Digi device.
- Windows RealPort explicitly forces DTR and RTS to drop when it closes.
Required permissions
For Digi products with two or more users, permissions must be set to set permissions s-sharing=read to display settings, and set permissions s-sharing=rw to display and configure settings. See set permissions for details on setting user permissions for commands.
Syntax
Configure port sharing
set sharing
[port=range]
[clients=maxiumn clients]
[control={shared|exclusive}]
[timeout=timeout]
[wrpolicy={all|first}]
Display current port-sharing settings
set sharing
Or:
show sharing
Options
port=range
Used to specify the serial port.
Note This is optional on a single-port device.
clients=maximum clients
The maximum number of clients that are allowed to share the port. Setting this value to 1 means that port sharing is off; that is, only one client can open the port. Setting this value to 2 means that port sharing is on; that is, the port is enabled to be shared. The maximum value allowed is 32. There is a slight performance penalty if port sharing is on, even if only one client is using ports. Therefore, this value should be set to 1, unless port sharing is needed. The default is 1.
control={shared|exclusive}
Specifies whether control should be shared by all clients, or controlled exclusively by the Digi device.
shared
All clients share control of the serial-port parameters, such as baud rate, data bits, parity, or flow control. Any changes made to these parameters by one client affects all clients.
exclusive
The serial port parameters can only be set from the command line or web UI of the device itself. Any attempt by the clients to change serial-port parameters through RealPort will be silently ignored.
The default is shared.
timeout=timeout
The flow-control timeout, specified in 1/10ths of a second. This parameter specifies how long a fast client waits for a slower client that has flow-controlled the port (see About flow control on shared ports for more information). After this timeout expires, the faster client is allowed to read ahead in the data stream, and the slower client begins to lose data. A value of 0 means there is no timeout; the faster client will wait forever if necessary for the slower client and never timeout. A value of 1 means the faster client waits only 1/10 of a second for a slower client; which means essentially no waiting. The maximum value is 6000. The default is 0.
wrpolicy={all|first}
Specifies who can transmit on a serial port.
all
Everyone can transmit on the serial port.
first
Only the first module to open the port is allowed to write to the device.
Examples
Display and change port-sharing settings
This example shows using show sharing and set sharing to display port-sharing settings, configure settings, and display changed settings.
#> show sharing Port Sharing Configuration : port# clients(max) clients(cur) control timeout wrpolicy 1 4 0 shared 0 all
Port-sharing parameters are displayed in four columns. current clients shows how many clients are currently sharing the port. The max clients, control, and timeout columns show the values set by the clients, control, and timeout options.
Next, a set sharing command is issued to change port-sharing parameters:
#> set sharing clients=4 control=exclusive timeout=600
#> show sharing
Port Sharing Configuration :
port# clients(max) clients(cur) control timeout wrpolicy
1 4 0 shared 0 all
#> set sharing clients=1
Warning: Some changes will not take effect until the ports are closed.
#> set sharing
current max
tty clients clients control timeout
1 2 1 shared 100
2 0 4 exclusive 600
At this point, the two clients disconnect from port 1 and a new client connects to port 2.
#> show sharing Port Sharing Configuration : port# clients(max) clients(cur) control timeout wrpolicy 1 4 0 shared 0 all
The warning message indicates that until the two clients disconnect from port 1, the clients value cannot be reduced to 1.
PDF
