NETCOUNT(1)

NAME
netcount - display summaries on network traffic over PPP connections

SYNOPSIS
netcount [ -a, --all ] [ -B, --bytes-limit count ] [ -b, --begin datespec ] [ -c, --columns wbls ] [ -D, --deadline day ] [ -e, --end datespec ] [ -f, --read-file fname ] [ -h, --help ] [ -i, --binary ] [ -L, --time-limit length ] [ -l, --logfiles pattern ] [ -R, --rx-limit count ] [ -o, --round-up ] [ -r, --records chdDmMt ] [ -s, --speed-unit ] [ -T, --tx-limitcount ] [ -t, --time-unit ] [ -u, --bytes-unit bkMG ] [ -v, --verbose drfs ] [ -W, --config-filefname ] [ -w, --write-config ] [ datespec ]

netcount-upd up | down | snap | reset

DESCRIPTION
This man page documents netcount, a tool for printing statistics on the traffic via ppp network lines. ( netcount-upd is a small script called from other programs, such as cron and pppd, which writes the logfiles netcount bases its summaries on. It is not intended to be called from the command line except for debugging purposes. netcount-upd is not described in further detail here.)

netcount takes several command line options. (There is an EXAMPLES section at the end of this man page. For a quick start, you may want to skip there and to return later for more details.)

netcount's command line options may be optionally followed by a date specification datespec which describes the date the listing starts at. If no date specification is entered, the one used when the last -w option was given is taken. Use netcount -h to see its current setting.

ENTERING DATE VALUES
Date values can be entered in several ways. netcount accepts all date formats which are accepted by the GNU date utility command. In fact, it delegates date interpretation to the date command if the syntax does not conform to netcount's own format conventions. It adds one keyword to date's set of recognized words: start, which is replaced by the starting date of the current monthly accounting period. A brief summarization of this syntax follows:

    •   Use keywords like january, jan, feb, sun, wednesday, first (first day of month), start (start of accounting period), now, today, yesterday, last (e.g. "last tuesday"), and numeric dates in several formats, e.g. "2003-06-23", "6/23/03", "23 Jun 2003", "23 jun 03", "june 23, 03", "23jun03" (the year may be omitted; the current year is taken in this case) to describe a specific day of the year.

    •   Use one or several "relative items" to specify a time displacement. Keywords are day(s), week(s), fortnight, month(s), year(s). They may optionally preceded by a signed number. You can use the word ago instead of the minus sign. If used alone, like "2 days ago", they reference an offset from today's date, else (as in "03 June -2 weeks") an offset from the date named before.

    •   Examples: This leads to specifications as "last monday -1 week" for the monday before the last, "2 weeks ago" for the last 14 days, "start 2 months ago" or "start -2 months" meaning the current accounting period and the two before it, "1 day 3 weeks ago", for 22 days ago, or, meaning the same, "yesterday -3 weeks", "yesterday 3 weeks ago" or simply "-22 days".

    •   Note: It must be stressed that no space is allowed between the sign and the number if you use a signed displacement. I don't know the reason for this, it's just how the date utility works. You should also avoid having both ago and the minus sign in one specification or using ago more than once in a specification.

If a date specification contains spaces, it must be quoted if it is an argument to the -b and -e options to prevent it from being splitted by the shell. The quotes are not necessary if the specification is - as usual - the command line argument (the last item on the command line) (which, like -b, also means a begin specification). If the date command line argument starts with a signed negative number, this is considered part of the argument, not part of the options despite the leading dash.

A second syntax is available which was the only one in earlier versions of netcount:

    In this form, the date is composed of the year (which may be expressed in as many digits as you want or left out), followed by a hyphen (which cannot be omitted), the optional month (1 or 2 digits), and optionally a hyphen and the day (1 or 2 digits).

    That sounds more complicated than it is: express the date as year-month-day. You can omit any part except for the dash preceding the month. When omitting parts, netcount will insert appropriate defaults. Valid datespec examples are: 2002-3-12, 2003-03, -03-12 (for March, 12, in the current year), -03 (for March of the current year), -- for the current year, month and day.

OPTIONS
netcount has several options, which determine the way it displays its information and set other aspects of its operation. Of major importance are the -c and -r options. They determine which columns and which types of records (rows) to print out. In contrast, upper case short options are only useful if you want to use the accounting features (percentage display). If you're a flat rate user, you can ignore them completely.

-a, --all
    display all records, independent of date. Default is to display the current monthly accounting period (default: the calendar month, see -D) and the period before.

-b, --begin datespec
    The date the listing starts at (default: current and previous monthly period). This option exists for compatibility reasons and will be used for other purposes in the near future. Its use is deprecated. Starting date entry is now done by naming it as last item on the command line, i.e. as command line argument, not as an option. Note that if datespec contains spaces, it must be enclosed in quotes to prevent the shell from splitting it.

-B, --bytes-limit count
    defines the amount of traffic (sum of tx and rx bytes) that is considered as being 100% for the daily percentage and monthly percentage display (D and M arguments to the -r, --record option). For the daily amount, count is divided by the number of days in the current monthly accounting period.

    There are three options to set the traffic reference amount: -B, -R, and -T (--bytes-limit, --rx-limit and --tx-limit). -B is useful when displaying Tx and Rx bytes together (see the s argument to the -c option), -R and -T if they are displayed separately. If one of the three values is missing, it is computed from the others. If Rx and Tx values are displayed separately but only -B is given, the percentage shows only the value for the sum of both. And, finally, if only -R or only -T is given the column for the other value is left empty.

    count is an integer or fractional number, optionally followed by k, kB, ki, kiB, M, MB, Mi, MiB, G, GB, Gi or GiB (case insensitive) to indicate the respective unit.

    Setting count to 0 will disable the corresponding option. Note that you must explicitly set it to 0 if it is defined in the configuration file and you want to disable it.

-c, --columns cspec
    Use this option to determine which columns to display. cspec is one or more of w, b, t, l, and s to select display of day of week, byte count, transmission speed, length of connection, and separating Rx and Tx data, respectively.

    Note that using the -c, --columns option replaces the default setting (as opposed to appending to it). The default setting is determined by the configuration file and is displayed by netcount -h.

-D, --deadline day_of_month
    Set the day the monthly accounting period ends at. This is useful for cases when your monthly accounting period ends at some day during the month. If day_of_month is greater than the number of days of the current month, the last day of the month is taken.

    The default for day_of_month is determined by the configuration file (usually 31, i.e. the accounting period ends at month boundaries).

    The monthly summarization record is only shown when using the m argument to the -r option (see below for details) and is labeled with year and month of the day the period ends.

    Note that only the records which fall into the current begin/end criteria are summarized. So the fist monthly record shown does not necessarily comprise a full accounting period. The default begin/end setting however is to display all records falling into the current and the previous monthly accounting period.

-e, --end datespec
    determines the ending date of screen output (default: today). datespec is as described above in the "ENTERING DATE VALUES" section. If omitted, screen output ends at the latest log entry. Note that if datespec contains spaces, it must be enclosed in quotes to prevent the shell from splitting it.

-f, --read-file fname
    read configuration from fname after the default files are read in. The default files are /etc/netcountrc, then ~/.netcountrc. Settings in fname override those from the default files.

-h, --help
    displays a help message showing the defaults determined by the configuration file.

-i, --binary
    toggle unit for displaying byte counts and transfer speeds from multiples of 10**3 (e.g., MB) to multiples of 2**10 (e.g., MiB). See also the -s or --byte-unit and -s or --speed-unit options. The default is determined by the config file and displayed using netcount -h.

-L, --time-limit secs
    defines the duration of time that is considered as being 100% for the daily percentage and monthly percentage display (D and M arguments to the -r, --record option). For the daily amount, count is divided by the number of days in the current monthly accounting period.

    The time is given in minutes or hours if followed by m or h (case insensitive), in seconds if the unit is omitted.

-l, --logfiles globspec
    Specify a shell wildcard pattern for the name of the logfile(s) where netcount-upd wrote its output to. This is useful for showing logs from a remote computer. The default is displayed using netcount -h and can be changed in the configuration file.

-o, --round-up
    Most providers round up to the next full minute of connection time when the link is closed. This option mimics this behavior. Note that the seconds display for hourly, daily and monthly records will not necessarily show up as zero if rounding up is enabled. Values other than 0 can occur if a connection persisted during the start or end of the corresponding period since rounding up occurs at termination, not at time stamps in between.

-R, --rx-limit count
    defines the amount of Rx traffic (download) that is considered as being 100% for the daily percentage and monthly percentage display (D and M arguments to the -r, --record option). For the daily amount, count is divided by the number of days in the current monthly accounting period. See under -B for a description of percentage values.

-r, --records rspec
    Select record type. rspec is one or more of c, h, d, D, m, M and t, which select per call records, per hour records, per day records, per day percentage, per month records, per month percentage, and a totals line, respectively. The default is preset by the configuration file and shown by the -h option. Note that giving the -r option temporarily replaces the default setting (as opposed to appending to it). Note also that the monthly records summarize the displayed lines of the month, which may differ from the total traffic of the month due to begin/end criteria. The time span of a month must not necessarily be the calendar month but may be changed by the -D resp. --deadline option.

    Using the h argument without c is possibly only useful for special applications (e.g., visualization). It presents hourly slices comprised of one record for each hour during which a connection existed, with the time shown being that of the first connection during this hour (or, if it persisted from the previous hour, the time when cron called netcount-upd) and the length being the sum of all uptimes of this hour.

    Using the c argument without h shows one line for each connection. The line is assigned to the day when the connections is complete; its date column refers to when the connection has begun which is not necessarily the same. If a connection spans more than one day, the daily summary will reflect the part(s) which fell into the respective day(s), while the connection record is shown later at the day the connection finished (since its totals are not known before).

    Using c and h together will show one record at each full hour a connection was active plus one record for each connection at the time when the connection has started and ended. In other words: You see the full connection, plus subdivisions at each full hour. The traffic and time figures represent the difference to the previous record (hourly or per-call - whatever might have been output before). This is done so in order not to list the same data twice.

    D and M show percentage lines. The 100% reference points are set by the -B, -T, -R and -L options. For the daily percentage (D), reference values are divided by the number of days in the current monthly accounting period. For the monthly record, the first column shows how many percent of the monthly period have passed, followed by the associated traffic and time percentages.

    It is not useful to use the D and M arguments to the -r option without defining at least one of the -B, -R, -T or -L options, since you will get a line with all values left out.

-s, --speed-unit sspec
    select the unit transfer speeds are displayed in. sspec may be one of k and M for kB/s or MB/s. The default is determined by the configuration file and displayed using netcount -h.

-T, --tx-limit count
    defines the amount of Tx traffic (upload) that is considered as being 100% for the daily percentage and monthly percentage display (D and M arguments to the -r, --record option). For the daily amount, count is divided by the number of days in the current monthly accounting period. See under -B for a description of percentage values.

-t, --time-unit size-spec
    determines the way time ranges are displayed. size-spec is one of h, m, s for an "hh:mm:ss", "mm:ss" or "sss" display of time values. The default is determined by the configuration file and shown by netcount -h.

-u, --bytes-unit size-spec
    determines the unit traffic bytes are displayed in. size-spec is one of k, M, G for kilobytes, megabytes or gigabytes, respectively. See the -i, --binary options for binary units. The default is determined by the configuration file and displayed by netcount -h.

-v, --verbose debug-spec
    This option is for debugging purposes only. debug-spec is one or more of d, r, f, s which turn on date, per-record (from the netcount-upd log), file-I/O and state debugging.

-V, --version
    shows the netcount program version.

-W, --write-file fname
    write current active settings to the configuration file named by fname. Using "-" for fname means standard output. See the following section on configuration file(s) for details about them.

-w, --write-config
    make current configuration permanent by writing the settings to the user configuration file. This is the same as issuing a netcount -W ~/.netcountc command. See the following section on configuration file(s) for details about them.

CONFIGURATION FILES
Configuration files are used to store your default settings so you don't need to re-type them any time you start netcount.

At startup, netcount reads in two configuration files: /etc/netcountrc and ~/.netcountrc, in that order. They need not exist; if one or both of them are not found, no error is raised.

You can have more than one configuration using the -f, --filename command line option.

/etc/netcountrc is used for system-wide defaults and ~/.netcountrc for user defaults. The user defaults override the system defaults, since they are read in later, overwriting the system wide settings.

Using netcount -W - shows a list of all available sections, options and their current settings. The configuration option names correspond to the long command line option names as are described in the section above. Options may be left out in the configuration file; a builtin default is taken in this case.

Usually, there is rarely any need to deal with configuration files directly by editing them. Use netcount -h to see the current settings. Play around with the command line options until the display you are getting suits your needs, then append a -w to write the settings to your user configuration file. Copy ~/.netcountrc to /etc/netcountrc if you want to make these defaults system wide.

Note that writing a new configuration file is done after interpreting the current defaults, which includes reading the old ones. If there are fatal errors with the old version, it is advisable to remove the file before calling netcount to write the new one. (In most error cases, however, it will be sufficient to issue a netcount -w to write a new configuration file with the illegal options removed.)

EXAMPLES
The following examples are meant to give a starting point in using netcount's command line. You need to have at least some connection data available to use them. You may want to pick one that comes nearest to your needs, make it permanent by adding the -w option and modify it further. If you want to know the stored (or - at first start - built-in) defaults, netcount -h displays a short line-up of the available options along with their current settings.

There are two options which define the overall appearance: -r, which determines the records (rows) to print and -c to choose from different columns. They both take a set of characters as argument which determine the individual elements to print. Note that every time you use -R and -c on the command line, you start out with a fresh (empty) set which overwrites the stored defaults (as opposed to appending to them).

Initially, you won't have too many log file entries, so you may want do display all:

    netcount -rcht

prints one line for every call (c) and every connection hour (h), plus a totals line (t). Later, to give a more concise overview,

    netcount -rd

summarizes your connections on a per day basis (d) without listing the individual calls.

Add -w to one of the command lines above to make netcount remember the -r settings. Now let's combine them with a specification of the columns to list:

    netcount -cbl

prints the two details which may later appear on your invoice: byte count (b) and transmission length (l).

    netcount -cwbtl

adds day of week (w) and transmission speed (both directions) (t). Finally, use

    netcount -cbtls

to separate (s) upload and download in the byte count and speed displays.

Now, let's assume that you are charged for a period ending on the 14th of every month. The line

    netcount -D 14 -w

makes netcount aware of this, and adding m to the -r option causes netcount to print a corresponding summary record:

    netcount -rdm

Say your monthly connection time limit is 100 hours,

    netcount -L 100h -w

and/or your traffic (sum of up- and download) is limited to 5 GB/month,

    netcount -B 5G -w

then you can have netcount display which percentage of your accounting period has passed, which percentage of traffic you've used up until now and which percentage of total connection time is over:

    netcount -rdmM -cbl

Of course, you can omit the -cbl if you've installed defaults as described above. Assuming you have done so, you can also have a look at what your daily use is with respect to a daily limit calculated from the monthly limits:

    netcount -rdD

Some providers use different limits for up- and download; see -T and -R for details.

What is left out here are details on how to specify date limits. This becomes increasingly important as your logs grow and is detailed (including several examples) in the section ENTERING DATE VALUES at the beginning of this man page.

FILES

All distributions:
    /usr/local/bin/netcount
    /usr/local/bin/netcount.py
    /usr/local/bin/netcount-upd
    /usr/share/man/man1/netcount.1.gz
    /etc/netcountrc
    ~/.netcountrc
    /var/log/netcount/

Distribution-dependent files. Pretty much confusion out there...:

Debian:
    /etc/cron.d/netcount
    /etc/ppp/ip-down.d/10netcount
    /etc/ppp/ip-up.d/10netcount
    /etc/init.d/netcount

RedHat:
    /etc/cron.hourly/netcount
    /etc/ppp/ip-down.local
    /etc/ppp/ip-up.local
    /etc/rc.d/rc.local

SuSE:
    /etc/cron.hourly/netcount
    /etc/ppp/ip-down.local
    /etc/ppp/ip-up.local
    /etc/init.d/boot.local

Mandrake and Slackware:
    /etc/cron.hourly/netcount
    /etc/ppp/ip-down
    /etc/ppp/ip-up
    /etc/rc.d/rc.local

CAVEATS
netcount cannot be used if you are running more than one PPP connection in parallel. Any connection status change while this condition exists is flagged as an error.

netcount relies upon the timely execution of the ip-up and ip-down scripts by pppd. If netcount seems to ignore a hang-up after going online followed immediately by hanging up or terminating pppd, this is usually caused by a hanging process run by ip-up, which in turn delays execution of ip-down. This usually only causes netcount to become aware of the hangup somewhat later than normal, but becomes a problem if for whatever reason another pppd is started (whose data will conflict with those of the ip-up/down script of the current one). One possible cure for this is to start the offending process in the background.

It is an error to have more than one pppd running at the same time, because there will be two competing counter values in the ip-down script. Unfortunately, there is not much netcount can do about this situation than to have netcount-upd log an error message which is then shown by netcount. The resulting traffic figures will most probably be incorrect.

KNOWN BUGS
There currently is an unsettled issue with the pppd in Debian unstable (package ppp, version 2.4.2+20040428-5). The behaviour of two environment variables on which netcount relies upon (BYTES_SENT and BYTES_RECEIVED) has changed without providing any means for programs using them to recognize which behaviour to expect. For now, you should stick witch the ppp versions found in the stable or testing distribution.

SEE ALSO
nstat(1), onlinecalc(1), pppd(8), pon(1), poff(1), logrotate(8)

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