#
# $Id: README,v 1.19 2006/04/03 10:47:19 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://download.ofb.net/liboop/

        http://directory.fsf.org/libs/c/liboop.html

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

        http://liboop.org/

BUILDING

        nepim has been tested under Linux, Solaris and FreeBSD, 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 against one server located at 10.10.10.10:

        $ 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
        nepim - network pipemeter - version 0.10
        server: tcp_read=32768 tcp_write=32768 udp_read=4096 udp_write=4096
        3: TCP socket listening on ::,1234(1234)
        spawn_tcp_listener: TCP listener socket failed for 0.0.0.0,1234(1234): -3
        4: UDP socket listening on ::,1234(1234)
        4: pmtud_mode=1 path_mtu=-11 ttl=64 mcast_ttl=1
        5: UDP socket listening on 0.0.0.0,1234(1234)
        5: pmtud_mode=1 path_mtu=-11 ttl=64 mcast_ttl=1
        nepim: server ready

        Running nepim in client mode at the client host:

        client$ nepim -c localhost -d -r 1000000
        nepim - network pipemeter - version 0.10
        client: tcp_read=32768 tcp_write=32768
        TCP socket solving localhost,1234
        TCP socket trying localhost,1234
        DEBUG FIXME sock.c nepim_connect_client_socket slow synchronous connect(port=1234)
        3: TCP socket connected to: host=localhost,1234 len=16 family=2 type=1 proto=6
        3: sending: hello server_send=1 bit_rate=1000000 stat_interval=2 test_duration=10 write_delay=250000 server_ka_send=0 server_ka_req=2
        3: greetings sent to localhost,1234
        3: pmtud_mode=1 path_mtu=16436 ttl=64 mcast_ttl=1
        3: part 2/10 kbps_in=1000.00 kbps_out=1000.00 rcv/s=4.00 snd/s=4.00
        3: part 4/10 kbps_in=1000.00 kbps_out=1000.00 rcv/s=4.00 snd/s=4.00
        3: part 6/10 kbps_in=1000.00 kbps_out=1000.00 rcv/s=4.00 snd/s=4.00
        3: part 8/10 kbps_in=1000.00 kbps_out=1000.00 rcv/s=4.00 snd/s=4.00
        3: avg 10/10 kbps_in=1000.00 kbps_out=1000.00 rcv/s=4.00 snd/s=4.00
        3: pmtud_mode=1 path_mtu=16436 ttl=64 mcast_ttl=1
        nepim: done
        client$ 

USAGE HINTS

        * nepim is useful to assess the throughput at the transport
        layer (TCP or UDP) as seen by applications.

        * 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 -c 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 a rate limiting option, nepim sends as fast as
        possible. See also "-R" below. Please notice the rate is
        specified in bps (bits per second); for instance, the
        following example states a rate limit of 100,000 bps (100
        Kbps):

                nepim -c 10.0.0.1 -r 100000

        * Use the "-R" client option to establish an upper "packet"
        rate limit (outbound rate limit for transport layer
        segments). Without a rate limiting option, nepim sends as fast
        as possible. If both "-r" and "-R" are given, nepim limits the
        sending rate at the lower of those bounds.

        * 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.

        * Use the "-4" option to disable IPv4 support.

        * Multicast support is special. Use the "-j" server switch to
        join a multicast group, then specify the "-M" client switch to
        enable multicast-compatible options. Example:

                server$ nepim -j ff01::1111

                client$ nepim -M -c ff01::1111 -r 100000

        * The "-k" switch provides a simple password mechanism for
        client authentication. Just use the same password at both
        sides:

                server$ nepim -k 321

                client$ nepim -k 321 -c server-hostname

	* One can specify the "-F" switch to force sending out UDP
	  packets regardless of a remote server.

		client$ nepim -F -c 1.1.1.1 -r 100000

	* The "-U" option makes the server to listen on UNIX-domain
	  stream sockets. See the example below.

		server$ nepim -U /tmp/sock1

		client$ nepim -c /tmp/sock1

                              -- END --

