CONTENTS
========
- Description
- Getting started
- Updating from previous versions
- Manual installation
- Installing for remote Operation
- Finals
DESCRIPTION
===========
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.
GETTING STARTED
===============
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.
1.
First, unpack the netcount-x.xx.tar.gz archive. Since you're reading
this, you obviously have done so already.
2.
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 (http://rhn.redhat.com) 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.
3.
"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.
4.
(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.
5.
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.
6.
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.
MANUAL INSTALLATION
===================
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:
netcount-cron.d
netcount-cron.hourly
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.
netcount-init.d
netcount-init
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.
10netcount-ip-down.d
netcount-ip-down-local
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.
10netcount-ip-up.d
netcount-ip-up-local
As above but called when pppd connects.
netcount-upd
Copy it to INSTALLDIR/sbin/ . INSTALLDIR is the directory you
checked when editing config.make. Do a chmod +x.
netcount
Copy it to INSTALLDIR/bin/ . Give it execute permission
(chmod +x).
nstat.py
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.
UPDATING FROM PREVIOUS VERSIONS
===============================
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/netcount.py (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.
INSTALLING FOR REMOTE OPERATION
===============================
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, netcount.py and (if not already
present) python on the machine you want to use for display (the host
machine).
Or do an automatic installation on the target machine and move
netcount and netcount.py 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.
KNOWN BUG WITH DEBIAN UNSTABLE
==============================
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.
FINALS
======
So we are through with configuring and installing netcount. I hope
you will find this package useful.
You can contact me at hcz@hczim.de .
The latest version of netcount may be found at:
http://freshmeat.net/projects/netcount
http://www.hczim.de/netcount.html
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.