IP Tables State (iptstate)
Copyright (C) 2002 - 2007 Phil Dibowitz
This software is provided 'as-is', without any express or
implied warranty. In no event will the authors be held
liable for any damages arising from the use of this software.
Permission is granted to anyone to use this software for any
purpose, including commercial applications, and to alter it
and redistribute it freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you
must not claim that you wrote the original software. If you use
this software in a product, an acknowledgment in the product
documentation would be appreciated but is not required.
2. Altered source versions must be plainly marked as such, and
must not be misrepresented as being the original software.
3. This notice may not be removed or altered from any source
NOTE: If you are planning on packaging and/or submitting my
software for/to a Linux Distribution, EMAIL ME FIRST!!! See CONTRIB.
1. WHAT IS IP TABLES STATE?
IP Tables State (iptstate) was originally written to implement
the "state top" feature of IP Filter (see "The Idea" below) in
IP Tables. "State top" displays the states held by your stateful
firewall in a top-like manner.
Since IP Tables doesn't have a built in way to easily display
this information even once, an option was added to just have it
display the state table once.
- Top-like realtime state table information
- Sorting by any field
- Reversible sorting
- Single display of state table
- Customizable refresh rate
- Display filtering
- Open Source (specifically I'm using the zlib license)
- much more...
Make sure you have some version of curses installed (for most users
this is probably ncurses). Note that if you are using vendor packages
you will most likely need the packaged with '-dev' on the end of of
it (i.e. ncurses-dev).
Starting with version 2.2.0 you also need libnetfilter_conntrack version
0.0.50 or later. If you do not have libnetfilter_conntrack you can compile
iptstate to use /proc/net/ip_conntrack (what it did prior to 2.2.0) instead.
To do this, modify the Makefile and switch the LIBS and CPPFLAGS lines with
the commented-out ones. Note that this backwards compatibility is temporary
and will be removed in future versions.
The quick version:
For most people the following should do all you need:
make install <--- this must be done as root
The long version:
The program is only one c++ source file, so the compile
is very simple. For this reason there is no config file.
The defaults in the Makefile should be fine, but if you
want to change something you can change where iptstate
gets installed by changing the "SBIN" variable in your
environment. I can't imagine a reason but if you have
'install' installed in a weird place change the INSTALL
variable in your environment. Other than that nothing
should need tweaking. Obviously advanced users may wish
to do other stuff, but we'll leave that as an excersize
to the reader.
The compiling should be as simple as running 'make.'
If this doesn't work, feel free to drop me an email,
BUT MAKE SURE you put "IPTSTATE:" in the subject. In the
email include: Distribution, kernel version, make version,
gcc version, libc version, and the error messages.
Package maintainers may wish to override CXXFLAGS, and can
do so like so:
# CXXFLAGS=-O3 make
and/or use "make strip" which will build iptstate and then
If you get errors like:
iptstate.cc:286: passing `in_addr *' as argument
1 of `gethostbyaddr(const char *, size_t, int)'
then you need to upgrade your glibc. This is an important
thing to keep up-to-date anyway.
IPTState installs in /usr/sbin. This is because it should
be a utility for the superuser. You need root access
(or CAP_NET_ADMIN) for iptstate to get the data it needs anyway.
Installing should be as simple as 'make install' as root. If this
fails, feel free to do:
# cp iptstate /usr/sbin/iptstate
# chmod 755 /usr/sbin/iptstate
# chown root:bin /usr/sbin/iptstate
# cp iptstate.8 /usr/share/man/man8/iptstate.8
# chmod 444 /usr/share/man/man1/iptstate.8
And that should do it. If 'make install' fails feel free
to drop me an email provided you put "IPTSTATE:" in the
subject. Please see the BUGS file on how to send proper
IPTables State is extremely simple to use. Most of the time
what you'll want is just the command 'iptstate' as root. This
will launch you into the 'statetop' mode. In here, your state
table is being sorted by Source IP. To change the sorting, on
the fly, type 'b.' This will rotate through the various sorting
possibilities. You can quit by typing 'q.' You can also change
the sorting with the -b ("sort BY") option. The -b option takes
d (Destination IP), D (Destination Port), S (Source IP), p
(protocol), s (state), and t (TTL) as it's possible options.
To sort by Source IP, just don't specify -b.
You can also change the refresh rate of the statetop by -R
followed by an integer. The integer represents the refresh rate
To get help, hit 'h' from withint iptstate, or run iptstate
with the '--help' option.
To get a quick look at what's going across your firewall, try
iptstate -1. This is "single run" mode. It will just print out
your state table at the moment you requested it. This is where
-b comes in handy. Again, the default sort is by Source IP.
NOTE WELL: This is not meant to be a comprehensive guide. There
are many other features - check the man page, the -h option,
and the interactive help page within iptstate for more
information. But this should give you the basics.
5. DESIRED FEATURES
There is a list of features I plan and don't plan to implement
in the WISHLIST file.
6. THE IDEA
The idea of statetop comes from IP Filter by Darren Reed.
This package's main purpose is to provide a state-top type
interface for IP Tables. I've added in the "single run"
option since there's no nice way to do that with IP Tables
7. THE AUTHOR
IPTState was written by me, Phil Dibowitz. I am a Senior UNIX
Systems Administrator at Ticketmaster maintaining the web
infrastructure. Additionally, I maintain the FAQ for IP Filter,
run the MSS Initiative, document IP Filter, and do other open-source
work. For more info on me, check out http://www.phildev.net/
phil AT ipom DOT com