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 firstname.lastname@example.org . 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.