null-modem-ppp

Name

null-modem-ppp — Used to setup a PPP connection over a direct serial connection.

Synopsis

null-modem-ppp -t TEXT | --tty TEXT [ --start [true]|false ] [ --kill [true]|false ] [ --status [true]|false ] [ -l TEXT | --local-ip TEXT ] [ -r TEXT | --remote-ip TEXT ] [ -m TEXT | --netmask TEXT ] [ --speed TEXT ] [ -o TEXT | --options TEXT ] [ --test-remote [true]|false ] [ --template [true]|false ] [ --sysv-script [true]|false ] [ -h [true]|false | --help [true]|false ] [ -H [true]|false | --help-long [true]|false ] [ -v [true]|false | --verbose [true]|false ] [ --version [true]|false ]

Description

The null-modem-ppp script is intended to simplify the process of setting up a PPP link between two systems using a serial line as its connection. This script has been successfully used to connect Linux systems (tested on Fedora Core 2 and Fedora Core 3 distributions). To make use of this script, you will need to determine the following:

  • The serial port to be used (like /dev/ttyS0). You may omit the /dev/ if desired - we treat ttyS0 the same as /dev/ttyS0).

  • The baud rate to use for the connection (like 19200).

  • The IP address that the local system will use for the PPP connection (like 172.18.1.31).

  • The IP address that the remote end of the PPP connection will be known as (like 172.18.1.32).

Once your determined the information, you will need to enter it in the configuration file associated with the serial port. For example, one would create the configuration file /etc/sysconfig/null-modem-ppp.ttyS0 for the serial port associated with the /dev/ttyS0 device.

You may also specify options on the command line, but this becomes a bit tedious. Any command line specified options will take precedence over the options specified in the configuration file.

If things don't go well, try running it again with the --verbose option.

If you use this script on both machines involved in the PPP connection, you will need to reverse the local and remote IP addresses used.

Creating a Configuration File

There are MANY options which this command accepts. As opposed to typing them on the command line each time, it is recommended that you use the --template option to generate a configuration file and then edit the values in this configuration file. The following demonstrates how one can accomplish this:

[root@probe #] null-modem-ppp -t ttyS0 --template > /etc/sysconfig/null-modem-ppp.ttyS0
[root@probe #] vi /etc/sysconfig/null-modem-ppp.ttyS0
[root@probe #]

Starting the PPP Link

To bring up the PPP link, at a minimum, you will need to specify a serial device to use. For example, the following should start up the PPP link using serial port /dev/ttyS0 at a baud rate of 19200 and configure the IP address of both the local and remote ends of the connection:

[root@probe #] null-modem-ppp --tty ttyS0 --start \
--speed 19200 --local-ip 172.18.1.32 --remote-ip 172.18.1.31 \
-v --test-remote
Checking for config file: /etc/sysconfig/null-modem-ppp.ttyS0
Checking to see if PPP is up for 172.18.1.32 is in use...
Getting current list of PPP interfaces...
  
Starting up the PPP daemon via:
  /usr/sbin/pppd /dev/ttyS0 19200 172.18.1.32:172.18.1.31 netmask 255.255.255.0 lock crtscts noauth asyncmap 0 connect '/usr/sbin/chat '\'\'' '\'\'
Waiting for PPP link to come up.....
Configuring the PPP interface ppp0 via:
  /sbin/ifconfig ppp0 up 172.18.1.32
Adding route to 172.18.1.31 via:
  /sbin/route add 172.18.1.31 metric 1 ppp0
Verifying remote end of connection (ping 172.18.1.31)...
  successful in attempt to ping 172.18.1.31
[root@probe #]

However, it becomes cumbersome to type in so many parameters on the command line. It is easier to create a configuration file and edit the associated settings. Assuming that the configuration file for ttyS0 exists (/etc/sysconfig/null-modem-ppp.ttyS0), you can start the PPP connection via:

[root@probe #] null-modem-ppp --tty ttyS0 --start
[root@probe #]

Note

The second example does not produce any output as the verbose (-v) option was omitted. Most likely you will want to include the verbose option when invoking the script by hand.

Note

This does not bring up the PPP connection on the remote machine. If the PPP connection doesn't come up within a reasonable amount of time on the remote end, then the pppd daemon will terminate.

Getting PPP Link Status

Use the --status option to get information about the PPP link. You may want to include the --test-remote option as well to verify that the remote end of the PPP connection is up as well.

[root@probe #] null-modem-ppp -t ttyS0 --status -v
Loading config file: /etc/sysconfig/null-modem-ppp.ttyS0
Checking to see if ttyS0 is up...
  ppp0 is up
Verifying route entry for 172.18.1.31...
  found route entry for 172.18.1.31 over ppp0
Verifying local end of connection (ping 172.18.1.32)...
  successful in attempt to ping 172.18.1.32
[root@probe #] null-modem-ppp -t ttyS0 --status --test-remote -v
Checking for config file: /etc/sysconfig/null-modem-ppp.ttyS0
Loading config file: /etc/sysconfig/null-modem-ppp.ttyS0
Checking to see if ttyS0 is up...
  ppp0 is up
Verifying route entry for 172.18.1.31...
  found route entry for 172.18.1.31 over ppp0
Verifying local end of connection (ping 172.18.1.32)...
  successful in attempt to ping 172.18.1.32
Verifying remote end of connection (ping 172.18.1.31)...
  successful in attempt to ping 172.18.1.31
[root@probe #]

Note

It has been my experience to see the pppd daemon die when the pppd daemon on the remote end of the connection terminates. This does not appear to be a problem if the serial cable is disconnected and then reconnected, but only if the remote pppd terminates normally.

Killing the PPP Link

This script can also be used to kill the PPP connection. The following demonstrates how one would kill the PPP on serial device /dev/ttyS0:

[root@probe #] null-modem-ppp --tty ttyS0 --kill -v
Checking for config file: /etc/sysconfig/null-modem-ppp.ttyS0
Loading config file: /etc/sysconfig/null-modem-ppp.ttyS0
Searching for pid of PPP using:
  ps -e | grep ttyS0
Killing pppd (23460) associated with /dev/ttyS0...
[root@probe #]

If you don't specify the serial device on the command line, we will use the value found in the associated configuration file.

Note

When you kill the pppd daemon in this manner, it will likely kill the pppd daemon running on the remote machine as well.

Creating A SYSV Script

If you are familiar with the SYSV start/stop scripts found in the /etc/rc.d/init.d directory, you may find it useful to create a script for each PPP interface you plan to use. To do this, you MUST have a configuration file associated with the PPP connection. For example /etc/sysconfig/null-modem-ppp.ttyS0 for the /dev/ttyS0 serial port. The following demonstrates how one uses the --sysv-script option to generate the script for the ttyS0 interface:

[root@probe #] null-modem-ppp -t ttyS0 --sysv-script \
>| /etc/rc.d/init.d/ttyS0
[root@probe #] chmod +x /etc/rc.d/init.d/ttyS0
[root@probe #]

Once you create the script, you should be able to start, stop and check the status of the PPP connection as shown below:

[root@probe #] /etc/rc.d/init.d/ttyS0 start
Starting ttyS0:                                            [  OK  ]
[root@probe #] /etc/rc.d/init.d/ttyS0 status
ttyS0 is running...
[root@probe #] /etc/rc.d/init.d/ttyS0 condrestart
Stopping ttyS0:                                            [  OK  ]
Starting ttyS0:                                            [  OK  ]
[root@probe #] /etc/rc.d/init.d/ttyS0 status
ttyS0 is running...
[root@probe #] /etc/rc.d/init.d/ttyS0 stop
Stopping ttyS0:                                            [  OK  ]
[root@probe #] /etc/rc.d/init.d/ttyS0 condrestart

[root@probe #] /etc/rc.d/init.d/ttyS0 status
ttyS0 is stopped
[root@probe #] /etc/rc.d/init.d/ttyS0 stopn
Stopping ttyS0:                                            [FAILED]
[root@probe #]

Finally, you should be able to use the chkconfig command to enable or disable the PPP connection at boot time.

[root@probe #] chkconfig --list ttyS0
service ttyS0 supports chkconfig, but is not referenced in any runlevel (run 'chkconfig --add ttyS0')
[root@probe #] chkconfig --add ttyS0
[root@probe #] chkconfig --list ttyS0
ttyS0           0:off   1:off   2:on    3:on    4:on    5:on    6:off
[root@probe #] chkconfig ttyS0 off
[root@probe #] chkconfig --list ttyS0
ttyS0           0:off   1:off   2:off   3:off   4:off   5:off   6:off
[root@probe #] chkconfig --del ttyS0
[root@probe #]

Keeping a Link Up Forever

The original purpose of creating this helper script for serial based PPP links was to provide a mechanism for a unmanned sensor to maintain a network connection to a central location (command center). In this situation, you want the remote sensor to make every attempt possible to maintain (or establish) a PPP connection back to the server. The following script does this by first testing the PPP connection (making sure it can ping the server). If the PPP connection appears to be down, it then tries to kill the connection and then restart it.

#!/bin/bash

#
# Loop through each configured PPP connection
#
for f in /etc/sysconfig/null-modem-ppp.*; do
  TTY="${f//\/etc\/sysconfig\/null-modem-ppp./}"
  if ! null-modem-ppp --tty ${TTY} --status --test-remote >/dev/null 2>&1; then
    logger -t "${TTY}" "PPP link was down - unable to ping remote end - restarting"

    # prefer sysv script start/stop if available
    if [ -x /etc/rc.d/init.d/${TTY} ]; then
      if /etc/rc.d/init.d/${TTY} restart >/dev/null 2>&1; then
        logger -t "ttyS0" "PPP link was restarted"
      else
        logger -t "ttyS0" "Attempt to restart PPP link FAILED"
      fi
    else
      null-modem-ppp --tty ${TTY} --kill >/dev/null 2>&1
      if null-modem-ppp --tty ${TTY} --start --verbose >| /var/log/${TTY} 2>&1; then
        logger -t "ttyS0" "PPP link was restarted"
      else
        logger -t "ttyS0" "Attempt to restart PPP link FAILED"
      fi
    fi
  fi
done

The above script only tries one time to restart each of the PPP links which it finds to be down. It is recommended that the script be invoked by crond at periodic intervals. Assuming that the above script is saved as /usr/sbin/null-modem-ppp-check, one should be able to run it every 20 minutes using the following crontab entry:

[root@probe #] crontab -e
# Check PPP links at 7, 27 and 47 minutes past each hour (every 20 
# minutes)
7,27,47 * * * * /usr/sbin/null-modem-ppp-check
crontab: installing new crontab
[root@probe #]

Options

The following command line options are available:

-t TEXT | --tty TEXT

This parameter is required and specifies the character device that represents the serial port to use. Typically this will resemble /dev/ttyS0 or /dev/ttyUSB0. You may omit the /dev/ path from your device name (we treat ttyS0 the same as /dev/ttyS0)

[--start [true]|false]

This needs to be specified on the command line if you want to bring the PPP connection up. It will first verify that the connection is not already up. It then starts the pppd, configures the network interface and adds a route between the local machine and the remote end of the connection.

[--kill [true]|false]

If this option is specified, then the pppd process which is associated with the serial port of the PPP connection will be killed. The process is located through the serial port associated with the connection (as specified by the --tty DEVICE command line option, or through the value of the TTY environment variable found in the configuration file).

[--status [true]|false]

It will verify that the PPP connection is up. It will verify that there is a route to the remote end of the connection configured. It will verify that the IP address of the local end of the connection is reachable. It will not check the remote end of the connection unless you include the --test-remote option.

[-l TEXT] | [--local-ip TEXT]

This parameter allows one to set the IP address of the local end of the PPP connection. The default value is 172.18.1.31 if omitted.

[-r TEXT] | [--remote-ip TEXT]

This parameter allows one to set the IP address of the remote end of the PPP connection. The default value is 172.18.1.32 if omitted. You will want to ping this address after running the script to verify that you can communicate with the remote host.

[-m TEXT] | [--netmask TEXT]

This parameter allows one to specify the network mask for the PPP connection. It MUST include both the source and remote IP address. The default value is 255.255.255.0 if omitted.

[--speed TEXT]

This parameter allows one to specify the baud rate to use over the serial port. The default value is 19200 if omitted.

[-o TEXT] | [--options TEXT]

You should not need to adjust this parameter if you are truly using a direct serial connection between your NST probe and the PPP server. However, if your connection requires some special settings, you may replace our default values of lock crtscts detach idle 30 noauth asyncmap 0 with the values you require (this is best done in the configuration file).

[--test-remote [true]|false]

This option can be used when one uses the script to setup a PPP connection, or when one is using the --status option to check the state of the connection. When this option is specified (or set to true), we will attempt to ping the IP address of the remote end of the connection one time to verify that the PPP connection has been established.

[--template [true]|false]

When you specify this option, null-modem-ppp will print out a template configuration file for the PPP connection. You can save this as /etc/sysconfig/null-modem-ppp.ttyS0 (change ttyS0 to match the tty you plan to use) and then edit the configuration file. This reduces the number of parameters you must specify on the command line.

[--sysv-script [true]|false]

When you specify this option, null-modem-ppp will print out a standard SYSV start/stop script which can be copied to the /etc/rc.d/init.d directory and used to control the PPP link. It is recommended to name the script such that it matches the name of the tty device the PPP connection is associated with.

[-h [true]|false] | [--help [true]|false]

When this option is specified, null-modem-ppp will display a short one line description of null-modem-ppp, followed by a short description of each of the supported command line options. After displaying this information null-modem-ppp will terminate.

[-H [true]|false] | [--help-long [true]|false]

This option will attempt to pull up additional null-modem-ppp documentation within a text based web browser. You can force which browser we use setting the environment variable TEXTBROWSER, otherwise, we will search for some common ones.

[-v [true]|false] | [--verbose [true]|false]

When you set this option to true, null-modem-ppp will produce additional output. This is typically used for diagnostic purposes to help track down when things go wrong.

[--version [true]|false]

If this option is specified, the version number of the script is displayed.

Files

/etc/sysconfig/null-modem-ppp.DEVICE

When run, we will check for the existance of this file and (where DEVICE is replaced by the base name of the tty device). For example, if you run null-modem-ppp -t /dev/ttyS1 we will look for /etc/sysconfig/null-modem-ppp.ttyS1.