summaryrefslogtreecommitdiff
path: root/doc/en
diff options
context:
space:
mode:
authorJakub Sławiński2005-03-15 01:22:55 +0100
committerJoshua Judson Rosen2014-07-17 21:14:58 +0200
commit1adde65db245ec1fca752cfee4c198badf40fb5f (patch)
treebba33f3b1fe7d469f9df7a89af9dac77b27fa3bb /doc/en
parentudp_patch (diff)
downloadapf-1adde65db245ec1fca752cfee4c198badf40fb5f.tar.gz
v0.6
- Fixed: default password incompatibilities from config file - Added: "client's id" option - Lightly Modified: verbose mode - Added: temporary listen ports - Fixed: bug in printing "client's id" - Added: 'dateformat' option to set format of the date in the logs - Modified: command line option and config file behaviour - Added: logging to a socket - Fixed: parsing config file - Fixed: major bug in packet buffering - Added: several clients-users in one realm - Modified: default hostname used by afserver - Modified: server listening behaviour (for clients) - Fixed: bug in checking options values - Modified: verbose mode - Modified: client initial connection to server - Added: connection time / uptime statistics - Added: first version of remote administration (statistics only) - Fixed: major bug in remove_client routine - Added: 'raclients' option - Added: use of automake/autoconf - Added: creating ~/.apf directory - Modified: the way of creating/managing keys/certificates - Added: 'dnslookups' option - Modified: usage functions - Fixed: no handling of missing 'listen' option after 'newrealm' in config file - Added: 'quit' command in remote administration mode - Modified: logging error messages during initialization - Modified: 'newrealm' changed to 'realm' in config file - Added: realm names - Modified: connection time / uptime - Added: client names / unique numbers - Added: user unique numbers - Fixed: segmentation fault after 'quit' command
Diffstat (limited to 'doc/en')
-rw-r--r--doc/en/README479
1 files changed, 479 insertions, 0 deletions
diff --git a/doc/en/README b/doc/en/README
new file mode 100644
index 0000000..0e49c3e
--- /dev/null
+++ b/doc/en/README
@@ -0,0 +1,479 @@
+AF - Active Port Forwarder 0.6 - README
+Copyright (C) 2003,2004,2005 jeremian - <jeremian [at] poczta.fm>
+=================================================================
+
+================================================================================
+
+GRAY-WORLD.NET / Active Port Forwarder
+======================================
+
+ The Active Port Forwarder program is part of the Gray-World.net projects.
+
+ Our Gray-World Team presents on the http://gray-world.net website the projects
+ and publications we are working on which are related to the NACS (Network
+ Access Control System) bypassing research field and to the computer and
+ network security topics.
+
+================================================================================
+
+=======
+SUMMARY
+=======
+
+INTRO
+
+1. INSTALLATION
+ 1.1 Instructions
+ 1.2 Required libs
+ 1.3 Tested platforms
+2. USAGE
+ 2.1 afserver
+ 2.2 afclient
+3. REMOTE ADMINISTRATION
+4. MODULES
+5. EXAMPLES
+ 5.1 tcp mode
+ 5.2 reverse udp mode
+6. BUGS/PROBLEMS
+
+NOTES
+
+THANKS
+
+================================================================================
+
+=====
+INTRO
+=====
+
+Active port forwarder is a software tool for secure port forwarding.
+It uses ssl to increase security of communication between a server and a client.
+Originally, it was developed to forward data point to point. However, the need
+for bypassing firewalls in order to connect to internally located computers
+influenced the further development of the project.
+
+AF is dedicated for people, who don't have an external ip number and want to
+make some services available across the net.
+
+Moreover, zlib is used to compress the transferred data.
+
+Using one, permanent data/control channel with flow control / packet buffering
+provides good performance and reasonably small latency.
+
+Multiple clients allow to create more sophisticated tunneling scheme.
+
+================================================================================
+
+===============
+1. INSTALLATION
+===============
+
+ 1.1 Instructions
+ ----------------
+
+1. Download the compressed sources from http://www.gray-world.net/pr_af.shtml
+2. Unpack them with tar zxvf
+3. Type "./configure"
+4. Type "make"
+5. Type "make install" while logged as root
+6. If something goes wrong - mail the author or post a message on
+ http://gray-world.net/board/
+
+ 1.2 Required libs
+ -----------------
+
+1. openssl - http://www.openssl.org/
+2. zlib - http://www.gzip.org/zlib/
+
+ 1.3 Tested platforms
+ --------------------
+
+1. Linux:
+ Gentoo, Slackware, Mandrake - built without any problems
+2. Windows:
+ win32 - cygwin version is available on the project homepage
+
+================================================================================
+
+========
+2. USAGE
+========
+
+ 2.1 afserver
+ ------------
+
+ Basic options:
+
+ -n, --hostname - it's used when creating listening sockets
+ (default: '')
+ -l, --listenport - listening port number - users connect
+ to it (default: 50127)
+ -m, --manageport - manage port number - second part of the active
+ port forwarder connects to it (default: 50126)
+ -h, --help - prints this help
+
+ Authorization:
+
+ --pass - set the password used for client identification
+ (default: no password)
+
+ Configuration:
+
+ -c, --cerfile - the name of the file with certificate
+ (default: cacert.pem)
+ -k, --keyfile - the name of the file with RSA key (default: server.rsa)
+ -f, --cfgfile - the name of the file with the configuration for the
+ active forwarder (server)
+ -D, --dateformat - format of the date printed in logs (see 'man strftime'
+ for details) (default: %d.%m.%Y %H:%M:%S)
+
+ -t, --timeout - the timeout value for the client's connection
+ (default: 5)
+ -u, --users - the amount of users allowed to use this server
+ (default: 5)
+ -C, --clients - the number of allowed clients to use this server
+ (default: 1)
+ -r, --realm - set the realm name (default: none)
+ -R, --raclients - the number of allowed clients in remote administration
+ mode to use this server (default: 1)
+ -U, --usrpcli - the number of allowed users per client (default: $users)
+ -M, --climode - strategy used for connecting users with clients
+ (default: 1)
+ Available strategies:
+ 1. fill first client before go to next
+
+ -p, --proto - type of server (tcp|udp) - for which protocol it will
+ be operating (default: tcp)
+ -b, --baseport - listenports are temporary and differ for each client
+ --nossl - ssl is not used for transferring data (but it's still
+ used to establish a connection) (default: ssl is used)
+ --nozlib - zlib is not used for compressing data (default:
+ zlib is used)
+ --dnslookups - try to obtain dns names of the computers rather than
+ their numeric IP
+
+ Logging:
+
+ -O, --heavylog - logging everything to a logfile
+ -o, --lightlog - logging some data to a logfile
+ -S, --heavysocklog - logging everything to a localport
+ -s, --lightsocklog - logging some data to a localport
+ -v, --verbose - to be verbose - program won't enter the daemon mode
+ (use several times for greater effect)
+
+ IP family:
+
+ -4, --ipv4 - use ipv4 only
+ -6, --ipv6 - use ipv6 only
+
+ 2.2 afclient
+ ------------
+
+ Basic options:
+
+ -n, --servername - where the second part of the active
+ port forwarder is running (required)
+ -m, --manageport - manage port number - server must be
+ listening on it (default: 50126)
+ -d, --hostname - the name of this host/remote host - the final
+ destination of the packets (default: the name
+ returned by hostname function)
+ -p, --portnum - the port we are forwarding connection to (required)
+ -h, --help - prints this help
+
+ Authorization:
+
+ -i, --id - send the id string to afserver
+ --pass - set the password used for client identification
+ (default: no password)
+
+ Configuration:
+
+ -k, --keyfile - the name of the file with RSA key (default: client.rsa)
+ -D, --dateformat - format of the date printed in logs (see 'man strftime'
+ for details) (default: %d.%m.%Y %H:%M:%S)
+
+ Modes:
+
+ -u, --udpmode - udp mode - client will use udp protocol to
+ communicate with the hostname
+ -U, --reverseudp - reverse udp forwarding. Udp packets will be forwarded
+ from hostname:portnum (-p) to the server name:portnum
+ (-m)
+ -r, --remoteadmin - remote administration mode. (using '-p #port' will
+ force afclient to use port rather then stdin-stdout)
+
+ Logging:
+
+ -O, --heavylog - logging everything to a logfile
+ -o, --lightlog - logging some data to a logfile
+ -S, --heavysocklog - logging everything to a localport
+ -s, --lightsocklog - logging some data to a localport
+ -v, --verbose - to be verbose - program won't enter the daemon mode
+ (use several times for greater effect)
+
+ IP family:
+
+ -4, --ipv4 - use ipv4 only
+ -6, --ipv6 - use ipv6 only
+
+ Modules:
+
+ -l, --load - load a module for user's packets filtering
+ -L, --Load - load a module for service's packets filtering
+
+================================================================================
+
+========================
+3. REMOTE ADMINISTRATION
+========================
+
+Afclient can be started in remote administration mode by '-r, --remoteadmin'
+option. Required option: '-n, --servername NAME'.
+
+After successful authorization stdin/stdout is used to communicate with user.
+All the commands parsing is done by afserver.
+
+Currently available commands are:
+
+ help
+ display help
+
+ lcmd
+ lists available commands
+
+ info
+ prints info about server
+
+ rshow
+ display realms
+
+ cshow X
+ display clients in X realm
+
+ ushow X
+ display users in X realm
+
+ quit
+ quit connection
+
+Afclient with '-p, --portnum PORT' option listens for connection from user at
+NAME:PORT. NAME is set by '-d, --hostname' option or hostname() function, when
+the option is missing.
+
+When user quits (close the connection or send 'quit' command), afclient exits.
+
+================================================================================
+
+==========
+4. MODULES
+==========
+
+Afclient can use external modules for user's packets filtering ('-l, --load')
+and service's packets filtering ('-L, --Load'). Module file has to declare three
+functions:
+
+char* info(void);
+
+ info() return values:
+ - info about module
+
+ Example:
+
+ char*
+ info(void)
+ {
+ return "Module tester v0.1";
+ }
+
+int allow(char* host, char* port);
+
+ allow() return values:
+ 0 - allow to connect
+ !0 - drop the connection
+
+ Example:
+
+ int
+ allow(char* host, char* port)
+ {
+ return 0; /* allow to connect */
+ }
+
+int filter(char* host, unsigned char* message, int* length);
+
+ filter() return values:
+ 0 - allow to transfer
+ 1 - drop the packet
+ 2 - drop the connection
+ 3 - release the module
+ 4 - drop the packet and release the module
+ 5 - drop the connection and release the module
+
+ Example:
+
+ int
+ filter(char* host, unsigned char* message, int* length)
+ {
+ int i;
+ for (i = 1; i < *length; ++i) {
+ if (message[i-1] == 'M') {
+ if (message[i] == '1') {
+ return 1; /* ignored */
+ }
+ if (message[i] == '2') {
+ return 2; /* dropped */
+ }
+ if (message[i] == '3') {
+ return 3; /* release */
+ }
+ if (message[i] == '4') {
+ return 4; /* ignored + release */
+ }
+ if (message[i] == '5') {
+ return 5; /* dropped + release */
+ }
+ }
+ }
+ return 0; /* allow to transfer */
+ }
+
+Modules have to be compiled with '-fPIC -shared' options.
+
+================================================================================
+
+===========
+5. EXAMPLES
+===========
+
+ 5.1 tcp mode
+ ------------
+
+ local network |FireWall| Internet
+ ||
+ || User 1
+ || /(tcp)
+ AF Client <---Encrypted/Compressed channel---> AF Server
+ / || | \(tcp)
+ /(tcp) || (tcp)| User 2
+ / || \
+ Http server || User 3
+ ||
+
+
+The use of it is extremely simple. Let's suppose we want to create a http server
+on our computer and we are behind a masquerade or a firewall:
+
+1) We have to find some machine on the net with an external ip and a shell
+ account.
+
+2) Use "make" to compile everything on that machine. (you can freely remove the
+ afclient and client.rsa files)
+
+3) You can edit the config file or just type from the console (to use the config
+ type -f <cfgfile>) :
+ $ ./afserver
+ This will work, if you want to use default values:
+ - hostname will be taken from hostname function (it would be ideally, if
+ there is appropriate registration in /etc/hosts)
+ - server will be listening for users on port 50127
+ - server will be listening for client on port 50126
+ - server will be for maximum 5 users
+ - server will forward tcp packets
+ - there will be no logging and no verbose messages
+ - there will be no password identification
+ - ip protocol family will be unspecified
+
+4) We use "make" on our machine (we can delete everything apart from afclient
+ and client.rsa)
+
+5) We are typing from the console:
+ $ ./afclient -n <name of the server> -p 80
+ Where <name of the server> is a string like : 'bastion.univ.gda.pl' or
+ '153.19.7.200'
+
+6) We can now enter with a web-browser to: <name of the server>:50127 and we
+ will enter to our computer in the fact.
+
+ 5.2 reverse udp mode
+ --------------------
+
+ local network |FireWall| Internet
+ || (udp)
+ || User 1-------AF Client
+ || /(tcp)
+ AF Client <---Encrypted/Compressed channel---> AF Server
+ / || |
+ /(udp) || (tcp)|
+ / || /
+ Game server || AF Client-------User 2
+ || (udp)
+
+
+Let's see how to use af to forward udp packets. Suppose we want to create a game
+server on our computer (udp port 27960 on our machine):
+
+1) - 4) is the same like in example 1. (but we add option: -p udp)
+
+5) We are typing from the console:
+ $ ./afclient -u -n <name of the server> -p 27960
+ Where <name of the server> is a name (or ip) of a host where our server is
+ running.
+
+6) Connecting to our game is more complicated. The user must use afclient to do
+ this. He has to specify the server he is connecting to and the port, which
+ his program will be listening on:
+ $ ./afclient -U -d <hostname> -p <portnum> -n <name of the server> \
+ -m <server port>
+ Where <hostname> is the name of the user machine (who wants to connect to our
+ game). <portnum> is the port he will be connecting to. <name of the server>
+ is the name of the host where our server is running. <server port> is the
+ port on which the server is listening for users. In order to connect to our
+ game, the user has to connect to <hostname>:<portnum>.
+
+================================================================================
+
+================
+6. BUGS/PROBLEMS
+================
+
+There are no known/open bugs at the moment.
+
+================================================================================
+
+=====
+NOTES
+=====
+
+Active port forwarder is still under development, so please sent any comments,
+bugs notices and suggestions about it to <jeremian [at] poczta.fm>
+
+If you have some problems or want to share your opinions with others, feel free
+to post a message at http://gray-world.net/board/
+
+================================================================================
+
+======
+THANKS
+======
+
+ Big thanks to the GW Team:
+
+ to Alex <alex [at] gray-world.net>
+ and Simon <scastro [at] entreelibre.com> for testing AF and a lot of advices.
+
+ Thanks to Ilia Perevezentsev <iliaper [at] mail.ru> who read and corrected the
+README file.
+
+ Thanks to Marco Solari <marco.solari [at] koinesistemi.it> for a lot of
+requests, suggestions and ideas.
+
+ And thanks for using this software!
+
+LICENSE
+-------
+
+ Active Port Forwarder is distributed under the terms of the GNU General
+ Public License v2.0 and is copyright (C) 2003,2004,2005 jeremian <jeremian
+ [at] poczta.fm>. See the file COPYING for details.
+