#
# $Id: README,v 1.7 2005/08/17 10:25:40 evertonm Exp $
#

INTRODUCTION

	nepim stands for network pipemeter, a tool for measuring
	available bandwidth between hosts. nepim is also useful to
	generate network traffic for testing purposes.

	nepim operates in client/server mode, is able to handle
	multiple parallel traffic streams, reports periodic partial
	statistics along the testing, and supports IPv6.

LICENSE

	nepim - network pipemeter
	Copyright (C) 2005 Everton da Silva Marques

        nepim is free software; you can redistribute it and/or modify
        it under the terms of the GNU General Public License as
        published by the Free Software Foundation; either version 2,
        or (at your option) any later version.

        nepim is distributed in the hope that it will be useful, but
        WITHOUT ANY WARRANTY; without even the implied warranty of
        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
        GNU General Public License for more details.

        You should have received a copy of the GNU General Public
        License along with nepim; see the file COPYING.  If not, write
        to the Free Software Foundation, Inc., 59 Temple Place - Suite
        330, Boston, MA 02111-1307, USA.

HOME SITE

	nepim lives at Savannah:

	http://www.nongnu.org/nepim/

REQUIREMENTS

        nepim depends on Liboop (1.0 or higher), available at:

        http://liboop.org/

	If you need another source, you may try the original tarball
	distributed from Debian repository:

	http://ftp.debian.org/debian/pool/main/libo/liboop/liboop_1.0.orig.tar.gz

BUILDING

	nepim has been tested under Linux/i686 and Solaris8/sparc,
	though it should work under other platforms as well. If you
	manage to build nepim for different systems, please send the
	patch.

	Before compiling nepim, install Liboop on your system.

	Then type:

	$ cd src
	$ make

	If you have Liboop installed on a special location, pass it to
	the make, as in the following example:

	$ cd src
	$ make OOP_BASE=/usr/local/oop

	Afterwards copy the 'nepim' binary to your system's proper
        filesystem location. For instance:

	$ cp nepim /usr/local/bin

	If you face trouble compiling, try tweaking the
	Makefile. Otherwise, post your problem at nepim support site.

BASIC USAGE

	Starting the server:

	$ nepim

	Starting the client:

	$ nepim -c 10.10.10.10 -d

	Display brief help about command line options:

	$ nepim -h

EXAMPLE

	Running nepim in server mode at the server host:

	server$ nepim
	running TCP listener socket on 0.0.0.0,1234
	could not create TCP listener socket on ::,1234
	FIXME: server.c spawn_udp_listener: 0.0.0.0
	FIXME: server.c spawn_udp_listener: ::

	Running nepim in client mode at the client host:

	client$ nepim -c 10.10.10.10 -d
	TCP socket solving 10.10.10.10,1234
	TCP socket trying 10.10.10.10,1234
	3: TCP socket connected to 10.10.10.10,1234
	3: greetings sent to 10.10.10.10,1234
	3: partial 2/10 kbps_recv=2780.85 kbps_sent=2505.92
	3: partial 4/10 kbps_recv=3465.14 kbps_sent=2162.69
	3: partial 6/10 kbps_recv=2454.27 kbps_sent=2818.05
	3: partial 8/10 kbps_recv=2653.17 kbps_sent=3407.87
	3: total 10/10 kbps_recv=2827.94 kbps_sent=2663.87
	client$

USAGE HINTS

	* nepim runs single-threaded and should impose very light
	burden on your CPU. Unless, of course, your testing hosts have
	relatively high network bandwidth compared to low CPU power.

	* One single server can service multiple clients
	simultaneously.

	* As of nepim 0.11, one single client can interact
	simultaneously with multiple servers. For instance, suppose
	you want to test, from a single client, two remote servers,
	one located at 10.0.0.1,2000 and another at 192.168.0.1,3000:

		nepim -c 10.0.0.1,2000/192.168.0.1,3000

	* The server listens to both TCP and UDP sockets. The client
	by default uses TCP sockets. Use the "-u" client option to
	switch the client operation to UDP.

	* By default, only the server sends traffic towards the
	client. Use the "-s" client option to reverse the behavior,
	then only the client will send traffic. Use the "-d" client
	option to make both client and server to send traffic.

	* Use the "-r" client option to establish an upper bit rate
	limit. Without this option, nepim always tries to send as fast
	as possible. Please notice the rate is specifieed in bps (bits
	per seconds); for instance, the following example states a
	rate limit of 100.000 bps:

		nepim -c 10.0.0.1 -r 100000

	* Use the "-n" client option to run multiple parallel traffic
	streams.

	* Use the "-b" server option to make the server to listen on
	specific local addresses.

	* Use the "-6" option to disable IPv6 support.

			      -- END --

