======================================================================== * README ======================================================================== IP Tables State (iptstate) Copyright (C) 2002 - 2005 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 distribution. ----------------------------------- NOTE: If you are planning on packaging and/or submitting my software for/to a Linux Distribution, EMAIL ME FIRST!!! IPTState Version 1.4 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. Features include: - Top-like realtime state table information - Sorting by any field - Reversible sorting - Single display of state table - Customizable refresh rate - Open Source (specifically I'm using the zlib license) 2. PRE-INSTALATION 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). 3. INSTALLATION The quick version: For most people the following should do all you need: make make install The long version: Configuration 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. Compiling 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 my wish to override CXXFLAGS: # CXXFLAGS=-O2 make and/or use "make strip" which will build iptstate and then strip it. 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. Installing IPTState installs in /usr/sbin. This is because it should be a utility for the superuser. In recent versions of iptables, /proc/net/ip_conntrac is only readable by root anyway. Installing should be as simple as 'make install.' If this fails, feel free to do: # cp iptstate /usr/sbin/iptstate # chmod 755 /usr/sbin/iptstate # chown root:bin /usr/sbin/iptstate # cp man/man1/iptstate.1 /usr/share/man/man1/iptstate.1 # chmod 444 /usr/share/man/man1/iptstate.1 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 bug reports. 4. USAGE IPTables State is extremely simple to use. Most of the time what you'll want is just 'iptstate.' 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 's.' 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), 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 in seconds. To get a quick look at what's going across your firewall, try iptstate -s. 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 and the -h option 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 either. 7. THE AUTHOR IPTState was written by me, Phil Dibowitz. I am a UNIX Systems Administrator at USC maintaining, architecting, and administering infrastructure Solaris systems. 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 Dibowitz phil@ipom.com ======================================================================== * LICENSE ======================================================================== IP Tables State (iptstate) Copyright (C) 2002 - 2005 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 distribution. ----------------------------------- NOTE: If you are planning on packaging and/or submitting my software for/to a Linux Distribution, EMAIL ME FIRST!!! There is already an official maintainer for Mandrake, Debian and Gentoo, see the CONTRIB file for details. Phil Dibowitz phil@ipom.com