- Description
 - Getting started
 - Updating from previous versions
 - Manual installation
 - Installing for remote Operation
 - Finals


Netcount is a program for logging and displaying traffic over the PPP
interface of a Linux machine.  It monitors the ppp0 interface and
prints statistics on a per-call, hourly, daily or monthly basis.

Also part of the netcount package is nstat, a small X application to
display the state of the ppp interface (off, down, off-hook/no traffic
and off-hook/traffic).  It also allows you to disconnect and terminate
pppd.  It uses the logging facilities provided by netcount.

Netcount is safe against overflow problems with the 32 Bit kernel
counters.  It samples them at regular intervals, thus getting aware of
an overflow if it happens.  The sampling interval is 1 hour by
default, but it may be changed to any other value if so desired.

At the heart of the netcount package is an executable which is also
called netcount.  It acts as the user interface to the logfiles
created by netcount-upd, a bash script.  netcount is written in
Python, which must be installed on the system.  Files for cron (to do
the sampling of the kernel network counter) and for logrotate (for
automatic logfile archiving and removal) are also provided.

There is also a small cgi script (netcount.cgi) provided by Alexander
Fedtke  which allows you to include netcount's output
into web pages.

The following prerequisites must be met for installation:

  - bash must be available, any version should do.

  - python must be installed. Usually, your distribution did so
    already.  You need at least Version 2.2.  It may be named
    /usr/bin/python, /usr/bin/python2.2, /usr/local/bin/python2.2 or
    whatever you like. Its name and location are configurable; default
    is /usr/bin/python.  For nstat (the X app) operation, Tkinter is
    also required, which might be packaged separately.

  - cron must be running

  - logrotate should be installed, but this is not mandatory

  - the commands printf, date and pidof must be available.

Any existing distribution should provide the needed facilities.  On
harddisk-less routers (such as fli4l) the need for the different
utilities may well be prohibitive, however.  But usually you have
other traffic logging abilities available on such a setup.


In nearly all cases, unpacking followed by "make install" as root is
all that is needed.  But you'd better go through the next few steps,
just in case.

  First, unpack the netcount-x.xx.tar.gz archive. Since you're reading
  this, you obviously have done so already.

  Second, check that python and logrotate are available by typing
  their name on the command line. Python might disguise as python2.2
  or python2.3. Type Ctrl-D to leave Python. Use "which python" to get
  its full path.  It usually resides in /usr/bin, but that may differ.

  If it doesn't exist, you must install it. Use your distribution's
  package manager to do so. Python 2.3 is pretty new is currently on
  beta status, so it may not be available with your distribution. Use
  python 2.2 instead. netcount works with versions from 2.2 upwards.

  If you are running Debian, and python is not installed, woody users
  please do an "apt-get install python2.2-tk" (as root).  You might as
  well run "apt-get install python2.3-tk" for the latest version if
  you are using sarge or sid.  This will install Tkinter and (as
  prerequsites) the other needed packages.

  RedHat users make sure the following packages are installed: python,
  tcl, tk, tkinter.  Use 'rpm -qi ' to see which packages
  are already installed on your system (e.g.: rpm -qi tkinter).  Use
  rpm -ihv  to install those that are missing. You'll
  find the RPM packages on your CDs, or you might choose to dowload
  then from the Red Hat Network ( or from any
  other good RPM archive.

  Other distributions: most probably, python will already be
  installed.  Else it will be available via your package manager.

  "cd" into the netcount source directory (named netcount-x.xx/ and
  created by the unpacking process).  A Makefile is provided which
  handles the Debian, RedHat/Fedora, Mandrake, Slackware, Gentoo and
  SuSE distributions.

  If you run another distribution or something goes wrong, refer to
  the chapter "Manual Installation" at the end of this document.  I'd
  appreciate if you'd drop me a line about the steps you've taken so I
  can include them for the benefit of other users.

  If you encounter problems, I'd be glad, too, to receive a mail on
  what you've discovered.  As always, don't forget to give the version
  number, the steps needed to reproduce the problem and the exact
  error messages you are getting.

  (Editing the configuration is not necessary any more for standard
  installations.)  Just run

    make install

  as root.  Make will determine the distribution from /etc/issue and
  modify and install the files as needed.

  (If you have modified /etc/issue (which is no good idea anyway) and
  removed the distribution name from there, you will get an error
  message stating that the value of DIST is undefined.  Add to the
  line above "DIST=XXX", replacing the "XXX" by either "debian",
  "redhat", "mandrake", "gentoo", or "suse" (without the
  quotes) according to the distribution you are using. Slackware users
  use "mandrake". This addition applies to the following make
  commands, too).

  Make will print some lines and return almost immediately. It
  inserts the definitions made to config.make into the separate
  components. It will then install to the appropriate places.

  Now you're done.

  If something fails, follow the instructions found under "MANUAL
  INSTALLATION". You may find that some or all of the files mentioned
  there have already been created by the installation process. Check
  them and complete the installation by adding those that are missing.

  After the installation, you may want to clean up the directory from
  intermediate files by typing

    make clean

  If at any point later you decide that you don't want the netcount
  package any more, type (as root)

    make uninstall

  to get rid of the files created by the installation process, i.e. any
  files outside the netcount source directory (where you are currently
  in). On some distributions, this will also print a message that one
  or more files cannot be removed because they may contain
  not-netcount-specific data. Edit them and remove the netcount
  part. If there is nothing in there but an accordingly marked
  netcount part, you can delete them.

  Before making changes to existing files, the Makefile does a backup
  copy to a file with the same name in the same directory and the
  suffix .backup appended. You may want to delete these files later.

  That's it.

  Type "netcount -h" or "netcount --help" to see a list of available
  options and their current defaults.  Type "netcount" without options
  and a message should appear stating that no logs are present or that
  no matching records were found.  This is no surprise, because they
  can't be there when you are starting netcount for the first time.

  You might also want to have a look at nstat by calling it with the
  command "nstat &".  If you want to use its pppd start/stop and
  hangup facilities, start it as root.  Click into its icon with mouse
  button 1 to get an option menu.

  Place a call now.  After hangup or -whatever comes first- after the
  next cron sample (around the full hour), your first entry should
  appear when typing "netcount -rch" at the shell prompt.

  If your PPP connection is already running, it may last up to two
  hours until you the first log entry pair is available.  You can
  speed up this startup process by typing (as root) "netcount-upd
  snap" twice while traffic is coming in and/or out. This will start
  and complete your first log entries.  Later on, this command will be
  rarely ever need to be entered manually, so you can forget about it
  after the installation.

  There is a section named "EXAMPLES" in netcount's man page for a
  quick start.  Using it as a starting point should get you up and
  running fast.

  When you have become more familiar with netcount and its options,
  you might want to change the default display. Have a look at the man
  page, primarily at the -c and -r options.  Play around with these
  and with the other display options.  When you've found a combination
  that suits your needs, add a "-w" to your netcount command line to
  make it permanent.


  It's not too difficult to install netcount manually. But don't
  forget to make a backup copy of any files you change, just in case.

  "cd" into the netcount source directory (named netcount-x.xx/ and
  created by the unpacking process), if you didn't so already.  In
  config.make are the definitions for user-configurable options.  Open
  config.make using your favorite text editor. The provided defaults
  should cover most installations, but carefully read the comments and
  make appropriate changes where applicable.

  If you are doing an installation for remote operation (logging is
  done on another machine than displaying), LOGPATTERN must be set to
  be the wildcard pattern from the host (where you display) to the
  target (where logging is done).  Else the default is fine.

  After editing config.make, run the command

    make files

  This creates the necessary files with some values patched in. We'll
  go through these files now:


      These two files are control files for cron. The netcount-cron.d
      version is in crontab format, while netcount-cron.hourly is a
      shell script. Only one of these is needed.

      Use the netcount-cron.d version to append to an existing cron
      table or to insert into a directory holding cron tables,
      whatever your system supports. In this case, check the contents
      and your cron man page because you may or may not need the
      "root" column in the netcount-cron.d file. Also remember that
      most crons need a trailing end-of-line in their crontab.

      Use netcount-cron.hourly if your system has a directory
      consisting of shell scripts which are executed on every
      hour. In this case you most probably will have to do a chmod +x
      on the script.


      One of these must be executed on system startup. Use the
      netcount-init.d version if your system supports a directory
      whose scripts are run on system startup. Don't forget a chmod +x
      if your system needs so.

      The netcount-init version is for appending to an existing script
      which gets executed on startup.


      One of these must be called when pppd disconnects.
      Again, the difference between these two is the way they are
      executed: 10netcount-down.d is for insertion as stand alone
      script, netcount-ip-down-local is meant for appending at an
      existing file. And remember the chmod +x.


      As above but called when pppd connects.


      Copy it to INSTALLDIR/sbin/ . INSTALLDIR is the directory you
      checked when editing config.make. Do a chmod +x.


      Copy it to INSTALLDIR/bin/ . Give it execute permission
      (chmod +x).
      Copy it to INSTALLDIR/bin/. Give it execute permission.

  This completes your manual installation. Now check your installation
  as described in step 6 above. Feel free to contact me via email if
  something fails and you can't figure it out. Don't forget to give
  the version number, the steps you've done and the exact error
  messages you're getting.


If you didn't do any changes to your old version's config.make except
for the path to the Python executable (as will be the case in the vast
majority of installations), you can start over with the fresh
distibution.  Starting with Version 0.7e, Makefile now checks for the
correct Python interpreter by itself, so you don't have to copy your
old config.make any more.

The following applies only if you've done a manual installation:

   If you already have a running manual installation, copy your
   existing config.make file to the new directory, overwriting the new
   one.  Its contents haven't radically changed. Some values have been
   dropped and there were some small comment updates.  You don't have
   to re-edit it.  Then, as root, call

      make install

   and you're done.  The DIST=XXX definition which had to be typed in
   previous versions is gone.  (You only need it in case you've removed
   the distribution info in /etc/issue.  You will get an error message if
   you've done so.  See above under "Getting started", subsection 5, for
   valid names if this is the case.)  Call netcount -V to make sure you
   have indeed the new version.  Look up the netcount and nstat man pages
   for new features.

Make will eventually inform you that you can remove
/usr/local/lib/ (or wherever your installation resides).
This can safely be done.

The syntax for entering date specifications has been expanded
considerably if you are updating from versions before 0.8.  Have a
look at the new secion entitled ENTERING DATE VALUES in the man page.
I hope you will like the new extended syntax as much as I do.


Doing the logs on a different machine than displaying is nearly the
same as the manual installation.  Install all programs but netcount on
the machine where pppd is running (the target machine).  No Python is
needed there.  Install netcount, and (if not already
present) python on the machine you want to use for display (the host

Or do an automatic installation on the target machine and move
netcount and to the host. Then run netcount -f
/path/to/the/target's/logfiles\* (note the backslash before the
asterisk to prevent the shell from expanding) to check the
installation. Use
   netcount -f /path/to/the/target's/logfiles\* -w
to make the path permanent.

You can't run nstat in remote mode since the /proc pseudo file system
is not propagated through NFS paths.  You can, however, use a subset
of nstat's functionality by using the -f option with a target path of
e.g. <$TARGET>/var/log/netcount/nc-up in the target's log directory.


The pppd in Debian unstable (package: ppp) introduces incompatible
changes to pppd's API concerning the contents of the BYTES_SENT and
BYTES_RECEIVED environment variables in ip-up/down scripts.
Unfortunately, currently there is no way of detecting which version is
actually running than asking the package manager, since (AFAIK)
nothing in the script's environment tells it what kind of data these
environment variables carry; not even the version number of pppd has
changed (just that of the package).  So far there has been no response
from the author, so a script has been added to detect and warn against
this situation and even abort the installation if the incompatible
version is used.


So we are through with configuring and installing netcount. I hope
you will find this package useful.

You can contact me at .

The latest version of netcount may be found at:

My thanks go to Guido Rossum and all the Python people.  If you are
looking for an object oriented scripting language with concise and
readable syntax and great capablities, then you might want to have a
look at Python.  Netcount once was my first project with Python (but
not for very long), and it was fun writing it.  It doesn't take a long
time to become productive with Python.