summaryrefslogtreecommitdiff
path: root/docs/en/README
blob: e9ded512d20287929c136c148f5eef06b3c62650 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
AF - Active Port Forwarder v0.5.4 - README
Copyright (C) 2003,2004 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. EXAMPLES
  3.1 tcp mode
  3.2 reverse udp mode
4. 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.

================================================================================

===============
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 "make".
4. 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. Freebsd:
  4.4, 4.9 - have to use patch from project homepage
3. Windows:
  win32 - cygwin version is available on the project homepage
  
================================================================================

========
2. USAGE
========

  2.1 afserver
  ------------

  Options:
  -h, --help          - prints this help
  -n, --hostname      - it's used when creating listening sockets
                        (default: name returned by hostname function)
  -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)
  -u, --users         - the amount of users allowed to use this server
                        (default: 5)
  -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)
  -p, --proto         - type of server (tcp|udp) - for which protocol it will be
                        operating (default: tcp)
  -O, --heavylog      - logging everything to a logfile
  -o, --lightlog      - logging some data to a logfile
  -v, --verbose       - to be verbose - program won't enter the daemon mode
                        (use several times for greater effect)
  --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)
  --pass              - set the password used for client identification
                        (default: no password)
  -4, --ipv4          - use ipv4 only
  -6, --ipv6          - use ipv6 only

  2.2 afclient
  ------------

  Options:
  -h, --help          - prints this help
  -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 the connection to (required)
  -k, --keyfile       - the name of the file with RSA key (default: client.rsa)
  -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)
  -O, --heavylog      - logging everything to a logfile
  -o, --lightlog      - logging some data to a logfile
  -v, --verbose       - to be verbose - program won't enter the daemon mode
                        (use several times for greater effect)
  --pass              - set the password used for client identification
                        (default: no password)
  -4, --ipv4          - use ipv4 only
  -6, --ipv6          - use ipv6 only
  -l, --load          - load a module for packets filtering

================================================================================

===========
3. EXAMPLES
===========

  3.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.

  3.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>.

================================================================================

================
4. 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.

 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  jeremian  <jeremian  [at]
  poczta.fm>. See the file COPYING for details.