nstat − show status of a PPP network connection


nstat [ -b, --before secs ] [ -f, --file fnam ] [ -g, --geometry gspec ] [ -h, --help ] [ -i, --idlesecs ] [ -k, --keep ] [ -l, --loud ] [ -n, --notime ] [ -s, --sticky ] [ -u, --hard-hangup ] [ -V, --version ]


nstat is an X status display for PPP networking. It uses netcount’s logging facilities, so netcount must be installed for nstat to work.

Depending on network state, nstat shows one out of four symbolic icons:

A symbolized "X" (crossed-out) on red background if PPP networking is disabled (pppd not running),

A red-filled black circle (a symbolized "0") on yellow background if PPP is ready, but no connection has been made (depending on your pppd configuration this also means that the system is ready for automatic dialout),

A small vertical bar (a "1") on green background indicates that you are online, but there is currently no traffic through the line,

A large vertical bar on green background indicates that you are online and there is traffic going through the line.

While online, nstat shows the connection time in hh:mm:ss format. nstat can optionally hangup the line after a certain minimum idle time just before the next minute is full.

It can automatically restart pppd if it dies.

Clicking on the nstat window with the left mouse button opens an option menu. If nstat is started as root, it allows you, depending on network state, to start pppd, terminate pppd, hangup the line, exit nstat or to cancel the menu. If nstat is has not been started as root, only the exit and cancel options are available.

The start and stop pppd options call /usr/bin/pon and /usr/bin/poff without arguments (the full path is used for security reasons). See the pon(1) and poff(1) descriptions if they don’t work out as expected. (Usually, your default pppd configuration file must be named /etc/ppp/peers/provider). The hangup option by default sends pppd a hangup signal using /usr/bin/killall −HUP pppd, but may optionally (−u option) do a pppd kill followed by a start instead. The default (hangup) causes pppd to go offline without terminating. Note that pppd only survives a hangup signal if at least one of the persist or demand options in its configuration file are set.

Clicking on the nstat window using the right mouse button will (if run as root):

hang up if online,

terminate pppd if pppd is running, but not connected, and

start a new pppd if none is running.


-g, --geometry gspec

Specify window size and/or position. gspec takes the form of a standard X geometry specification; see X(1) for information. Examples are 55x55+300+20, 30x30, +150−50, for setting both size and position, size only, and position only.

-s, --sticky

With this option, nstat’s window is not decorated, it always stays on top of the other windows, and it stays in the same place when changing workspaces (it "sticks to the glass"). To achieve this is usually the window manager’s job, but this option effectively bypasses it. It is primarily provided for uses (e.g. by startup scripts) when there is no simple way of telling the window manager to do it automatically.

In this mode, you cannot resize nstat’s window; use the −g option to determine its size on startup. The window can be repositioned by moving the mouse while above the window and pressing the left mouse button.

-n, --notime

Omit the display of connection time.

-k, --keep

Keep pppd running. Respawn pppd when it dies for whatever reason (if not explicitly shut down by nstat). nstat must be run as root for this option.

-l, --loud

causes nstat to use pure red, yellow and green colors instead of the somewhat less prominent standard colors. (Just a matter of taste.)

-f, --file fnam

Check for the existence of file fnam instead of /var/log/netcount/nc-up. Do not watch /proc/net/dev for ppp0 traffic. This might be used for checking over network paths or simply to indicate the existence of any desired file. With this option only either a circle or a bar are displayed.

-i, --idle secs

This option is not especially useful except if you typically have short connection times, if you are charged for the full minute even if the minute has just started and if you want to stay online as long as possible in order to have faster response times without starting a new minute. It hangs the line up just before the end of the current connection minute if the idle time has been exhausted. When the idle time is exhausted, the color of the time display font turns from red into blue to indicate that nstat will hang up just before the end of the current minute. nstat must be run as root for this option. Default for secs is 0, i.e. disabled.

You should set pppd’s idle time in its option file (usually /etc/ppp/options or /etc/ppp/peers/provider) to a substantially higher amount of time than the argument to the −i option if you want to use this option.

The use of the −u option is highly recommended when using −i.

-b, --before secs

This number of seconds before the full minute hangup will take place (if the idle time has been exhausted before). This option takes only effect if the −i option is used. Default is 2 seconds.

-u, --hard-hangup

Use hard hangup: Hang up by killing pppd immediately followed by restarting a new one instead of the default behavior, which is to send pppd a SIGHUP signal. nstat must be run as root for this option.

This option exists because pppd occasionally seems to hang after a hangup caused by a signal. This way, you get a "fresh" pppd every time nstat hangs up either by mouse action or by the −i option.

-V, --version

Show the version number.

-h, --help

Display a command summary.


You decide if running nstat as root constitutes a security hole.

pppd occasionally seems to die unexpectedly on receiving a signal or on line events such as being disconnected. This is what the −k option is meant for.

pppd sends its parent a SIGHUP, SIGTERM or SIGINT under certain conditions, so nstat blocks these signals as soon as you start pppd from there.

As is true for netcount, nstat depends upon the timely execution of the ip-up and ip-down scripts by pppd. If nstat seems to hang after going online followed immediately by hanging up or terminating pppd, this is usually caused by a hanging process started by ip-up, which in turn delays execution of ip-down. This does not cause further harm except for nstat not updating its display before the process times out. One possible cure for this is to start the offending process in the background.

nstat and netcount cannot be used if more than one pppd is running. nstat detects this situation and aborts with an error message if any operation on pppd is requested while this condition exists.

For the same reason, you can not have more than one nstat which runs as root since this may lead to more than one pppd being automatically started. You will get an error menu giving you a chance to correct the situation if you try this.

Currently, nstat ignores X resource specifications.

There are occasional problems with pppd not dialing out even with the −u option. You need to use the "Terminate pppd" menu entry followed by the "Start pppd" menu entry (or press the right mouse button twice) to handle this. This is rare, but it may happen. The reason for this is unclear (nstat does no special things to pppd).

Times over 999:59:59 are not displayed correctly.

Being a script, it is useless to set nstat setuid root. To get root features, run it as user root.


netcount(1), gkrellm(1), procmeter3(1), pppd(8), pon(1), poff(1)


The netcount package is written by Heike C. Zimmerer <hcz@hczim.de>.