Introduction

Cyclades-Serial-Client is a free open source Virtual serial port redirector for Linux which supports the RFC-2217 COM Port Control Telnet extention, making it compatible with NetModem Server. The client creates a pseudo TTY port in Linux, which redirects to a Terminal Server or a Modem Server over a network. When used with NetModem Server, it attaches to the next available modem in a pool of modems, allowing linux applications dialout/dialin access to the modem(s) over the network.

Cyclades-Serial-Client is included in software repositories for many Linux distributions including Ubuntu, Fedora, Debain, OpenSuse, Lucid, Mint, and Boss. Installers are provided for both 32-bit and 64-bit environments.

By installing both Cyclades-Serial-Client and a modem terminal emulator such as Minicom, Linux users are provided dialout access to analog or digital modems which are physically attached to a Windows PC running NetModem Server. The modem server can manage a pool of up to 256 modems, commonly 2, 4 or 8 modems using standard RJ45 telephone connectors for smaller applications, and up to 256 modems per server when using T1 phone lines for enterprise applications.

Installing Cyclades-Serial-Client

Cyclades-Serial-Client can be downloaded and installed from most Linux software repositories by using the following command line:
sudo apt-get install cyclades-serial-client

sudo is needed to grant root access to the apt-get installer program, and will prompt you for your administraor credentials.

apt-get will download and install the current available version of cyclades-serial-client software from your configured software repository. It will select the proper 32-bit or 64-bit installer, matching the OS its installing to.

Configuring Cyclades-Serial-Client

Once Cyclades-Serial-Client is installed, you can optionally edit the configuration file named cyclades-devices with a text editor.
To view the help file use: "man cyclades-devices".
The configuration file is usually located in /etc/, so to edit the file using gedit you could use this command line:
sudo gedit /etc/cyclades-devices

The cyclades-devices configuration file uses the following format:
device:rastype:rasname:physport:type:options

device = local device name, starting with a "/dev/" prefix.
rastype = "prts" or "path" can be used
rasname = IP Address of the NetModem Server
physport = must be "1"
type = must be "rtelnet" for remote telnet
options = this can be left blank

Here is an example of a cyclades-devices configuration file:
/dev/ptyp0:prts:192.168.1.100:1:

The config is file can also contain comments, which are lines beginning with a # character.

Pseudo device names work best: /dev/ptypX where X is a value between 0-9 or A-Z.
Any non-standard pseudo device name such as /dev/modem can be used with Minicom, but such names may fail to be accessible by some other serial communication applications. Therefore we recommend using a valid pseudo device name such as: /dev/ptyp0


The Client includes two executables:

cyclades-serial-cli - The virtual COM port redirector client
cyclades-serial-client - The client status/manager tool

The cyclades-serial-cli program is designed to be run from init, so that is is loaded during boot up. However doing so will cause it to continuously hold one of the modems open in NetModem Server, so it is recomended to run this from a terminal console instead where it can easily be controlled (ie: stopped by pressing Ctrl-C). This is done using the -x command line parameter from a Terminal.

Open a Terminal and type the following command line:
sudo cyclades-ser-cli -p 5999 -m 1 -x /dev/ptyp0 192.168.1.100 1

Subsitute the above IP address with the actual IP address (or hostname) of the NetModem Server PC.

The most common parameters used are defined below:
-p 5999 [This must be one less then the NetModem Server TCP Port]
-m 1     [Causes the client to ignore the Carrier Detection signal]
-x         [Causes the client to run in forground Console mode when started from a Terminal]
/dev/ptyp0 [This overrides the device name in the configuration file]
192.168.1.100 [The IP address (or hostname) of the Modem Server]
1          [This should always be 1. A 0 setting will select TCP port 23]

You should see the following:

The client is now running, redirecting data between the pseudo TTY named /dev/ptyp0 on the Linux box and a physical modem device on the NetModem Modem Server software running on a Windows PC.

The client also connects to the current Terminals pseudo terminal device, usually named /dev/pts/1 or /dev/pts/2. This is not a modem or serial device and should not be used in Minicom.

It is important to use the -p parameter to specify a value that is one less then the TCP port on the NetModem Server. NetModem Server defaults to using TCP port 6000, in which case -p 5999 should always be used in the client's command line.

It is also important to use the -m 1 parameter to instruct the client to ignore the Device Carrier Detection (commonly called the CD or DCD line). This is due to a bug in cyclades-ser-cli that causes it to detach the pseudo TTY from the telnet/socket connection as soon as the modem server reports that the DCD line is low(set to zero).
This prevents the applications from "hanging up" or knowing when the modem has been disconnected, but Minicom will still show the user a "NO CARRIER" message to indicate the disconnection. A hangup can be achived by closing/restarting cyclades-ser-cli .

Once the cyclades-serl-cli program is running, you can optionally change the permissions of the pseudo TTY port (virtual serial port) it creates, using the chmod command from another Terminal or a script. This will allow Minicom to access the port without needing to elevate the users access using using Sudo when running Minicom. For example:
sudo chmod og=rw /dev/ptyp0

This gives everyone read and write access to the named pseudo TTY device (a virtual serial port) created by the client.

As with any serial device, only one user can open a device at any given time. You can use multiple instances of cyclades-serial-client to create additional pseudo TTY devices so that other users or applications can be connected to other modems/devices on the Server at the same time, limited only to the number of shared modems/devices on the Server.

To stop the client and to release the modem back to the servers pool you can press Ctrl-C in the cyclades-ser-cli Terminal window, or the program can be sent a SIGTERM by any other means.


The cyclades-serial-client program is a client status/manager tool which can monitor and control the status of each cyclades-ser-cli that is defined in the cyclades-devices file. However, this tool does not appear to function with non cyclades devices.

The tool must be involked with one of the following commands: start, stop, restart, or status, and optionally a second parameter can be passed with the specific device name to control such as /dev/ptyp0 or if the second parameter is not passed then the requested action will be performed on all the devices defined in cyclades-devices.

• No automated credential handling. If the modem server requires user authentication, the user can manually enter their username and password into Minicom.
  
  
• No support for multiple pools. The Cyclades-Serial-Client will always connect to the first modem pool defined in NetModem Server, on the next available COM port found in this modem pool.
  
  
• No SSL/TLS Encryption support. It may be possible using SSLTunnel, but this is not suggested or supported by PC Micro staff.
  
  
• No Carrier Detect (DCD) signal. This is due to a bug in the current version of cyclades-ser-cli requiring the -m 1 parameter to ignore this signal.
  
  
• No ability to connect to the modem on the server ONLY while the pseudo TTY device is held open. This means that one of the devices\modems on the NetModem Server will be held open the entire time that cyclades-ser-cli is running. Press Ctrl-C to exit cyclades-serl-cli and release the modem device back to the NetModem Server modem pool.