pmacct (Promiscuous mode IP Accounting package)
pmacct is Copyright (C) 2004 by Paolo Lucente

pmacctd EXAMPLES file.

(poorman's) TABLE OF CONTENTS:
I.	Configuring pmacct for compilation
II.	Brief SQL setup examples
III.	Running pmacct daemon
IV.	Running pmacct client
V.	Running logfile players 


I. Configuring pmacct for compilation
The simplest chance is to let the configure script to test default headers and libraries
locations for you without enabling any optional plugin (PostgreSQL or MySQL):
shell> ./configure

As usual, to get help and the list of available switches:
shell> ./configure --help

A pair of examples on how to configure the package to enable the support of a (1) MySQL or
a (2) PostgreSQL database; they, of course, could be enabled (3) both:
(1) shell> ./configure --enable-mysql
(2) shell> ./configure --enable-pgsql
(3) shell> ./configure --enable-mysql --enable-pgsql


II. Brief SQL setup examples
Scripts for DB setup both for a MySQL and PostgreSQL DB are in "sql" directory of distribution
tarball. Now, examples to create the database, grant default permissions. Remember to enable
the appropriate plugin at configure time.
 
IIa. MySQL examples 
shell> cd sql/
shell> mysql -u root -p < pmacct-create-db.mysql
shell> mysql -u root -p < pmacct-grant-db.mysql

Data will be available in "acct" table of "pmacct" DB.

IIb. PostgreSQL examples
Which user has to execute the following two scripts and how to autenticate with the PostgreSQL
server depends upon your current configuration. Keep in mind that both scripts need postgres
superuser permissions to execute some commands successfully:
shell> cp -p *.pgsql /tmp
shell> su - postgres
shell> psql -d template1 -f /tmp/pmacct-create-db.pgsql
shell> psql -d pmacct -f /tmp/pmacct-create-table.pgsql

Two tables will be created in the "pmacct" DB. "acct" table is the default table where data will
be written when in "frontend" mode (see "sql_data" option in CONFIG-KEYS text file; default value
is "frontend"); "acct_back" is the default table where data will be written when in "backend" mode.
A brief explanation of what frontend/backend means here: "frontend data are final, human readable
strings; backend data are integers, IP addresses represented in network byte order, etc.".


III. RUNNING PMACCTD DAEMON (pmacctd)
You can run pmacctd either with commandline options or using a configuration file. Please remember
that sample configuration files are in "examples" directory of the tarball distribution. Note that 
many new features are available only if enabling them via a configuration file. Getting rid either
of a configuration file or commandline options is mutual exclusive. To be aware of all existing
config keys, please read CONFIG-KEYS textfile. 

Show all available pmacctd commandline switches:
shell> pmacctd -h

Run pmacctd reading configuration from a specified config file (see "examples" directory for a brief
list of some common use keys inside sample config files and refer to CONFIG-KEYS textfile to learn
about available keys):
shell> pmacctd -f pmacctd.conf

Daemonize the process; listen on eth0; aggregate data with "src_host" and "dst_host" primitives; write
data in a mysql database, activating "mysql" plugin; filter traffic matching source ip network 10.0.0.0/16;
filtering option is same use as tcpdump. Please refer tcpdump's man page for examples. 
shell> pmacctd -D -c src_host,dst_host -i eth0 -P mysql src net 10.0.0.0/16

Daemonize the process; aggregate traffic statistics to show who connects where and using what service; store
data in a PostgreSQL database, activating "pgsql" plugin. Because no interface has been supplied, the default
one will be choosen for you:
shell> pmacctd -D -c src_host,dst_host,dst_port -P pgsql 

Enable debug mode; listen on interface ee1; collect stats aggregating for destinations in a memory structure
with 8 memory pools of 64Kb each (curious about memory pools ? Take a look to "Memory table plugin" section
in INTERNALS textfile):
shell> pmacctd -d -P memory -c dst_host -i ee1 -m 8 -s 65535

Daemonize the process; this time memory structure is configured to grow undefinitely in memory, allowing the
structure itself to allocate more and more memory without a pre-defined limit (-m 0); memory pools size will
be 32Kb:
shell> pmacctd -D -m 0 -s 32768 

Daemonize the process; set the number of buckets of the in-memory table at a value of 65537; having a flat table
(translates: high number of buckets) is the right way for keeping it healty when reaches large sizes (see further
details about structure of in-memory table in INTERNALS textfile, section "Memory table plugin"; this time the
traffic will get aggregated for source and destination mac addresses:
shell> pmacctd -D -b 65537 -c src_mac,dst_mac  

Run multiple instances of pmacctd (eg. to listen for traffic over multiple interfaces); each instance will have
its own in-memory table and will require an own pipe file to get queried by pmacct client. 
shell> pmacctd -D -i eth0 -m 8 -s 65535 -p /tmp/pipe.eth0 
shell> pmacctd -D -i ppp0 -m 0 -s 32768 -p /tmp/pipe.ppp0 

Run pmacctd logging what happens to syslog and using "local2" facility:
shell> pmacctd -c src_host,dst_host -S local2

NOTE: superuser privileges are needed to execute pmacctd correctly. 


IV. Running pmacct client (pmacct)
The pmacct client is used to gather data from pmacctd only when using an in-memory table. Requests and answers are
exchanged bewteen client and daemon via a pipe file so their security are strictly connected with file permissions.
Of course, when using SQL plugins you will not need pmacct client but your specific DB client program (eg. psql,
mysql) to gather data. 

Show all available pmacct client commandline switches:
shell> pmacct -h

Fetch all data in the in-memory table:
shell> pmacct -s 

Fetch all stats and use session password 'yahhuuu':
shell> pmacct -s -P "yahhuuu"

Fetch data in the in-memory table but output only source hosts, destination hosts and destination ports (maybe because
you are using this aggregation on the daemon side and you don't really want a bunch of zeroes fill the screen): 
shell> pmacct -c src_host,dst_host,dst_port -s

Fetch data for host 10.0.1.200 as destination host:
shell> pmacct -c dst_host -m 10.0.1.200

Show bandwidth wasted from www service, communicating with the daemon via /tmp/pipe.eth0 pipe file (this means daemon
is listening over that file):
shell> pmacct -c dst_port -m 80 -p /tmp/pipe.eth0 

Show ftp-data (port 20) traffic for host 10.0.1.10 connecting to host 194.119.200.100 (ahhh, our loved area). NOTE: the
order of primitives is not important; the semantic match between values supplied with "-m" option and primitives specified
with "-c" option is essential:
shell> pmacct -c src_host,dst_host,dst_port -m 10.0.1.10,194.119.200.100,20 


V. Running logfile players (pmmyplay and pmpgplay)
Examples will be shown using "pmmyplay" tool; they are same way applicable to "pmpgplay" tool. Two methods are supported
as failover action when writing to a DB: use logfiles or a backup DB. Aside from different scenarios and environments, a
brief advice is the following: using a logfile is a simple way to overcome transient failure situations that requires
human intervention while using a backup DB could ease the data merging task automation.

Display online help and available options:
shell> pmmyplay -h

Play the whole specified file, inserting elements in the DB and enabling debug:
shell> pmmyplay -d -f /tmp/pmacct-recovery.dat

Play a single (-s) element (the fifth) from the specified file (useful if, for example, a previously player execution has 
failed to write some element; all element failed to get written, if any, will be displayed over your screen):
shell> pmmyplay -o 5 -s -f /tmp/pmacct-recovery.dat

Play all elements, starting from element number six; use the supplied password to connect to the DB (useful if, for example,
during a previously player execution, SQL server has gone its way):
shell> pmmyplay -o 6 -f /tmp/pmacct-recovery.dat -p ohwhatanicepwrd

