nwload

NAME
SYNOPSIS
DESCRIPTION
PULLDOWN MENU
COMMAND LINE OPTIONS
CONFIGURATION FILE
CAVEATS
AUTHOR
SEE ALSO

NAME

nwload − graphically display network load

SYNOPSIS

nwload [ -b, --bits-p-s ] [ -B, --bytes-p-s ] [ -d, --device dev ] [ -f, --full-scale bps ] [ -g, -geometry, --geometry gspec ] [ -h, --help ] [ -i, --no-grid ] [ -l, --flat-grid ] [ -m, --remember-geometry ] [ -n, --not ] [ -r, --sample-rate sec ] [ -R, --rx-on-top ] [ -s, --sticky ] [ -T, --top-invert ] [ -V, --version ] [ -x, --x-grid sec ] [ -y, --y-grid bps ]

DESCRIPTION

nwload is a graphical X display utility which monitors network activity. It can be used to monitor any network device (i.e., any of the devices whose byte counts are accessible through the Linux /proc/net/dev interface), for example eth0, eth1,... ippp0,... and ppp0, ppp1... devices. The display adapts to any window size; it scales accordingly and may be resized while running. Rx (incoming) traffic is displayed in cyan, while tx (outgoing) traffic uses yellow. When started, the window begins to fill from the left, scrolling to the left when the right border is reached. The display is configurable in many ways by command line options as well as by an option pull-down menu and its submenus.

PULLDOWN MENU

The pull-down menu is accessed by clicking the left mouse button while the mouse cursor is over the nwload window. This menu also shows the current display parameters. The menu choices and their meanings are as follows, from top to bottom:

Cancel

Exit the menu without changing anything.

Sticky

Checkbox. When this option is checked, nwload’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"). This option effectively bypasses the window manager. A facility to manage the window in this mode is provided: You can move it around the screen by dragging it with the left mouse button at any point except the window’s lower right corner, and you can resize it by dragging it at the lower right corner.

Rx on top

Checkbox. Usually, Tx traffic is displayed on top of Rx traffic. Checking this box reverses the order. Rx traffic stays cyan and Tx traffic stays yellow.

Invert top

Checkbox. Whatever is selected with "Rx on top" as being on top, grows from the upper boundary downwards if this setting is checked. Otherwise the two (Rx and Tx) will stack one above the other.

Numeric speed display

Submenu. This leads to a submenu where you can check one of "None", "bits per second", or "Bytes per second". If checking one of the "per second" options, the sum of rx and tx traffic will be displayed in the upper left corner of nwload’s window. (If you change any display parameters while numeric speed display is on, the next number will not appear before the next value becomes available, i.e. not before the end of the current sample period.) Bytes per second are displayed using a "B" suffix, while bits per second use "b" (lower case).

Grid appearance

Submenu. Select from "3D", "Flat", or "None".

X grid spacing

Submenu. Select from different values for the time (X, vertical) grid. Besides the predefined values, you can introduce a custom choice with the −x option, which will be displayed at the bottom of the submenu.

Each displayed traffic value has a timestamp of its own. If you select a grid setting of e.g. 1 minute, the X grid will mark each sample taken at the system time’s full minute, scrolling left when the graph scrolls left (it stays on the marked sample).

Improper X grid values values lead to a display filled with vertical grid lines or no X grid lines at all, but otherwise do not affect nwload’s operation.

X sample rate

Submenu. X resolution is determined by the X sample rate: the display advances by one pixel for each sample. Any change in sample rate will affect the displayed values starting at the current time (X) position, not those before. This will be reflected in differing X grid spacings for old and new values after changing sample rate. Changing X sample rate will always take effect immediately and affect all following displayed samples. You can add a customary value to the predefined values using the −r option.

Y grid spacing

Submenu. Set the Y (speed, horizontal) grid. Improper values lead to a display filled with horizontal grid lines or no horizontal grid lines at all, but do not affect operation.

Y full scale

Submenu. A wide range of values to select from are provided in two submenus. The first menu offers some of the more widely used bit rates, while the second, which is selected with the "other..." entry in the first and has the same layout as "Y grid spacing" above, allows more detailed control using bit/s or Byte/s units. The entire window is rescaled according to the new setting without loss of resolution. You most probably want to change the Y grid spacing value after doing a change here. You can add a customary value to the bit rate selection by specifying it with the −x command line option.

Device to monitor

Submenu. Select the device. The devices which are running at the time this menu is called are offered, plus the device(s) named using the −d command line option. Changing the device causes the display to start over with an empty graph. If there are previously saved X and Y parameters for the new device, they take effect immediately, else the old values continue to be used.

Remember size & position on save

Checkbox. When a "Save settings" is done while this box is checked, nwload will save its size and position in addition to the other settings. Next time it is started, it will occupy the same location and size as at the time the save was done. If this box is not checked, it will start with a default size in a position determined by the window manager. Checking or unchecking this item doesn’t do the actual save, so you might want to execute "Save settings" next.

Save settings

Command. Save all settings from the settings menu. Global settings are: Sticky, Rx on Top, Invert top, Grid appearance, Device to monitor and Remember size & position. They are saved in one global file. Device specific settings are the X and the Y settings. On startup, nwload reads in the global settings if they exist, followed by the device specific settings (for the device named by the global settings). They latter are written to a file named after the device they belong to (see the section titled CONFIGURATION FILE below). Every time you change the device, the device specific settings for the new device are read in if there are saved settings for it.

Quit nwload

Command. Exit immediately.

COMMAND LINE OPTIONS

The command line options provide the same functionality as the pull-down menu, plus some extra functions.

-n, --not

This inverts the sense of the next command line option. Its main purpose is to override options from the saved settings. It is only useful for boolean options (options which take no argument(s)). For other options, a preceding −n, −−not is flagged as an error. This option always only takes effect on the command line option immediately following it.

-b, --bits-ps

-B, --bytes-ps

Display the sum of rx and tx bytes in either bits/s or Bytes/s format. The corresponding number appears in the upper left corner of nwload’s window. This may be switched off by prepending either of the two options with −n (It doesn’t matter which one of both was set).

-d, --device device[,device..]

Arguments to this command line options are one or more device names, separated by commas. The first name determines the device which is monitored at startup, and it and the following ones, if any, are added to nwload’s device list when selecting "Device to monitor" from the pull-down menu. By itself, nwload only knows about the devices which are running when the device selection submenu is called. This command extends the list. Its arguments are saved when selecting "Save settings" from the pull-down menu so they must be entered only once and stay in effect for all following invocations. Default on first startup is "ppp0". Call nwload with an empty list as argument, i.e. nwload -d "" to reset the list and then select "Save settings".

-f, --full-scale float

Set full scale speed. float is any floating point number, e.g. 1000, 1000.0, 1e3 all mean the same. Unit is bits/s by default, but the number may immediately be followed by b, kb, Mb to indicate bits/s, 10**3 bits/s or 10**6 bits/s. They also may be followed by B, kB, MB (note: case matters) to indicate the respective Byte/s units.

If the number provided this way is not already part of the menu of predefined full scale values, it is appended as additional choice at its bottom.

-g, -geometry, --geometry gspec

Specify initial size and/or placement. gspec takes the form of a standard X geometry specification, see man X(1) for details. Examples are "200x100" for a size specification, "+300+100" for a placement specification and "200x100-100-200" for a specification of both size and placement. See also the -m, --remember-geometry option.

-h, --help

Display a help message.

-i, --3d-grid

-l, --flat-grid

Specify grid layout. If both options are given, the later one wins. Inverting (by prepending one of -n, --not ) any of these option prevents any grid from appearing.

-m, --remember-geometry

When doing a "Save settings" from the settings pull-down menu, also save position and size. This is the same as checking "Remember size & positions on save" in the pull-down. It is not useful to set or reset this option without actually doing the save with the pull-down menu, since it won’t have any other effect but extending the save operation.

-r, --sample-rate sec

Set sample rate to sec. sec is an integer or floating point value which is measured in seconds by default. It may be optionally followed by ms, s or min to indicate milliseconds, seconds, or minutes. The display advances one pixel per sample, so the sample rate also determines the X resolution. You can change this value at any time later using the option menu (item "X sample rate"). If the sec value differs from the standard values offered by this menu, it is added as an additional menu item at its bottom.

-R, --rx-on-top

Display Rx data (cyan) on top of Tx data (yellow). This is the same as the "Rx on top" pull-down menu setting.

-s, --sticky

Make window sticky. Remove decoration and stay on top an all workspaces. This is the same as the "Sticky" setting from the pull-down menu.

-T, --top-invert

Let the top graph grow from the top of the window downwards (instead of stacking upon the lower graph). This is the same as the "Invert top" pull-down menu item.

-V, --version

Display nwload’s version string.

-x, --x-grid float

Set the horizontal grid spacing. float is any valid floating point value. It is measured in seconds but may optionally be followed by ms, s or min to indicate milliseconds, seconds, or minutes. This is the same as selecting "X grid spacing" from the pull-down menu, but you can specify any value you like. Note that it is not too difficult to enter a X grid spacing / X resolution combination which leads to the entire background being filled with grid lines since their spacing is the same or less as the X resolution. This won’t impair nwload’s operation.

-y, --y-grid float

Set the vertical grid spacing. float is any valid floating point value. By default it is measured in bits/s, but the floating point number may immediately be followed by b, kb, Mb to indicate bits/s, 10**3 bits/s or 10**6 bits/s. It also may be followed by B, kB, MB (note: case matters) to indicate the respective Byte/s units. This is the same as "Y grid spacing" from the pull-down menu, but you can specify any value you like. Note that it is not too difficult to enter a Y grid spacing / Y full scale combination which leads to the entire background being filled with grid lines. This won’t impair nwload’s operation.

CONFIGURATION FILE

You can save nwload’s settings by checking "Save settings" from the pull-down menu. If there are saved settings, they are loaded when nwload starts. Command line options can be used to override them. The settings are saved in two parts: the global and the device-specific ones. Device specific settings are X grid spacing, X sample rate, Y grid spacing and Y full scale. When you change the device, nwload looks if you have saved settings for the new device and loads them if they can be found. If you never saved while this device was selected, the current values stay in effect.

Normally, you won’t have to deal with the configuration files directly. Their names are: ~/.nwloadrc for all global settings and ~/.nwloadrc.device for device specific settings (device is replaced by the actual device name). Data is stored into these files in the form

<long-option-name> = <value>

with the angle bracket expressions replaced by the actual long option names (without preceding dashes) and their values. For boolean options, the value is either 0 or 1.

Global settings are: sticky, top-invert, rx-on-top, bits-p-s, no-grid, device, remember-geometry. There is an additional entry which has no corresponding command line option, active-device, for the device currently monitored. This also determines the suffix of the device-specific configuration file. If the -m, --remember-geometry option is set, there is one more additional entry: geometry, with an X geometry specification as its argument.

Device-specific settings are: x-grid, y-grid, full-scale, and sample-rate.

Invalid options and syntax errors print an error message on stdout indicating option and argument, but are otherwise ignored.

CAVEATS

Traffic exceeding 4 GBytes (32 Gbits) per X sample rate (i.e., per pixel) will not display correctly. Below this limit, a /proc/net/dev counter overflow is recognized and handled as it should be.

Mouse selection of submenus while near the right screen edge is somewhat inconvenient. If your window is placed there, click and release as usual to reach the menu, but keep your mouse button pressed after selecting one of the submenus, else what happens to be under the mouse cursor in the newly appearing submenu is selected instantaneously. This is a Tk restriction and I know of no way to circumvent this.

When the window is in sticky mode and the Y grid spacing, the second Y full scale or the device menu is selected, the main window temporarily "unsticks". This is done so in order not to allow the nwload main window to cover part of the menu by staying on top of it.

AUTHOR

nwload is written by Heike C. Zimmerer <hcz@hczim.de> and published under the terms of the GPL (GNU Public License), version 2.

SEE ALSO

gkrellm(1), procmeter3(1), xisdnload(1)