PacketProxy v.0.71 README By Daniel Stoedle, daniels@cs.uit.no Last updated 30. June 2008. License changed on November 7. 2007 to the BSD license. BUILD INSTRUCTIONS ------------------ Just cd into the src-directory and type 'make' to compile and link the PacketProxy software. You'll end up with an executable called pproxy in the current directory. To install, run 'make install' as root. This will copy PacketProxy to your /usr/local/bin directory. (Note: You do *not* need to be root in order to use PacketProxy -- installing it is just for convenience, not a requirement.) USAGE SUMMARY ------------- pproxy -d -p [-l ] [-m ] [-a ] [-f ] [-v ] -d: Destination address, a hostname or an IP address. -p: The destination port number, to which packets will be redirected. -l: The port on which PacketProxy will listen for incoming connections (1999). -m: The maximum number of threads PacketProxy will ever spawn simultaneously (10). -a: Enable authentication, using provided filename to screen incoming connections. -f: Log file -v: Verbosity level (-1 to 4, where -1 is no output, and 4 is all output) USAGE ----- PacketProxy is very simple to use. It requires two command line switches: ./pproxy -d -p This will forward any incoming TCP connection to localhost on port 1999 to the supplied host and port. Running in this configuration, PacketProxy supports up to 10 simultaneous connections (this can be changed -- see below). In addition, you may supply the port on which PacketProxy listens to with the -l flag. You may also specify the maximum number of threads PacketProxy will ever use at once -- this is useful to prevent someone DoS'ing your proxy :) The maximum number of threads defaults to 10, but can be changed with the -m flag. For example, to have PacketProxy redirect packets to the web-server at www.apple.com, you can start PacketProxy with the following options: ./pproxy -d www.apple.com -p 80 Assuming you started PacketProxy on your own machine, you should now be able to browse www.apple.com by entering the following URL in your webbrowser: localhost:1999 The number following the hostname specifies PacketProxy's listening port. SECURITY -------- PacketProxy supports a simple, IP-based form of authentication, to prevent it from forwarding connections from hosts you do not trust. To enable this feature, you will need to create an authentication configuration file. The format of this file is very simple; any line beginning with an H indicates a trusted hostname, and any line beginning with I indicates a trusted IP address. You may also supply an IP mask with IP-lines, to trust entire subnets (this does not work with hostnames!). Finally, anything following a hash (#) is ignored, allowing you to comment your files. An example configuration file would look like this: # Sample authentication configuration for PacketProxy # Allow port forwarding from www.apple.com: H www.apple.com # Allow ports to be forwarded from clients connecting from localhost: I 127.0.0.1 # And finally, allow anyone in the 192.168-subnet to get their connections forwarded: I 192.168.0.0 255.255.0.0 Now, to make PacketProxy use your configuration file, start pproxy with the -a flag, specifying the filename following the -a: ./pproxy -d www.slashdot.org -p 80 -a auth_conf LOGGING AND VERBOSITY --------------------- You can control PacketProxy's verbosity level by specifying it with the -v flag. Valid values are in the range -1 to 4, where the amount of output is as indicated below: -1: No output 0: Only errors are logged 1: Error messages and info messages are logged 2: Display events, in addition to output from levels 0 and 1 3: Be even more verbose 4: Show debug messages as well The default verbosity level is 1. A logfile may be specified using the -f switch -- this will suppress output to standard out, and instead save it to the specified file. TO DO ----- Features that I might implement include a global or per thread bandwidth cap, and some sort of simple UDP packet forwarding. UDP packet forwarding will require the use of a set of static forwarding rules, and will not be as transparent to the client applications using PacketProxy. CONTACT ------- I'd be grateful for any feedback you may have -- send it to me here: daniels@stud.cs.uit.no. Bugs, questions, suggestions, criticism and compliments are all welcome. VERSION HISTORY --------------- I've not been very good keeping a version history, but I'll do that starting with 0.71. * 0.71 - 30. June 2008: Incorporated a bugfix from Michael Demmer, fixing an issue with incorrect thread counts. * 0.70 - sometime a long time ago: Previous stable release. LICENSE ------- PacketProxy is licensed under the BSD-license: Copyright (c) 2002-2008, Daniel Stoedle , Yellow Lemon Software. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. - Neither the name of Yellow Lemon Software nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.