How to run SLiRP
----------------

First, compile SLiRP according to the instructions in the file COMPILING.
Then all you need to do is run "slirp", quit your comms software (or disable
it, or whatever) and run your SLIP/CSLIP software on your home machine.


Which programs do not work over SLiRP?
--------------------------------------

Any programs that bind() a port, then tell the other end of the connection
where they should connect() to this bound port.

For example: when you "get" a file during an ftp session, the ftp client
bind()'s a socket, has a look at which port the socket is bound to, then
tells the ftp server the address and port of this socket (with the PORT
command). The ftp server then connect()'s to this address/socket pair.

Now, since your machine isn't really on the Internet, this connect() request
will not arrive to your host, so it will not work.

SLiRP emulates this by bind()ing it's own port on the server that *is* on
the internet, and tells the ftp server about *that* address/socket pair.
When the server connect()'s to it, SLiRP will then connect back to your
machine.

Currently, ftp (PORT) and irc (DCC SEND and DCC CHAT) are emulated, since
these are the only programs I use which require this emulation. [I'm also
working on "talk", but it's not finished yet]

If you have a program that does not work with SLiRP, you can do one of 2
things:

* Find out the format of the "command" and write the code to do a similar 
  type of translation as is currently done by SLiRP.  See the functions
  tcp_emu() and tcp_tos() to see how this is done.

* If you can't do the above, and you have the sources to the program, you
  can recompile it with XXX included in the SLiRP package (XXX actually, I
  haven't written this yet..)


How do I redirect a port?
-------------------------

Say you want to let your friend ftp to your home machine.  Because your home
machine isn't really on the Internet, they can't ftp into it directly.  You
need to redirect a port from the host machine (where SLiRP is running) to
your home machine.

There are 2 ways of doing this:

1) Put a line in your config file like the following:

redir tcp [port to redirect] [your home IP address]:[port to redirect to]

For example, if you want to redirect port 5000 to port 21 on your home
machine (ftp port), and your home machine's IP is 123.123.123.123, you'd have:

redir tcp 5000 123.123.123.123:21

Now, your friend can "ftp host.SLiRP.is.running.on 5000" and she'll be
ftp-ing to your home machine.

The second way is shown below...


Controlling SLiRP using telnet
------------------------------

Redirection (and other misc. config stuff) can be done on the fly by
telneting to a specific C class address. (Currently, 10.0.2.x)

All you need to do is telnet to 10.0.2.0, which will give you a
"command-line" where you can enter commands directly to SLiRP.  Most of the
config-file options are supported, the only ones that aren't are the ones
which would crash SLiRP (eg: increasing the MTU on-the-fly will crash SLiRP)

There are also additional ones, read the file docs/CONFIG for most of them.


Notes
-----

* The C class address 10.0.2.xxx is a special address to SLiRP.
  10.0.2.0 - SLiRP "command line"
  10.0.2.1 - An alias for the remote-host, -e and -p programs will be run
              on connection to the specified port.
  10.0.2.2 - An alias for the remote-host, but no -e, -p programs are
              executed.
              
  The difference between the last 2 are subtle, but distinct; for example,
  by default, when you telnet to 10.0.2.1 port 21 (telnet port) you'll
  automatically get a shell instead of a login prompt.  But if you telnet to
  10.0.2.2, you'll get the login prompt as offered by the remote-host.

* To quit SLiRP you simply kill your SLIP/CSLIP software then send 5 0's
  (zeros) down the line, with a 1/2 second pause between each.

* The code to try and "guess" how much it can write to the modem is flakey.
  If you see that your modem isn't being used at it's maximum capacity (eg:
  an ftp session to the remote-host, the modem's RECEIVE light is not
  shining brightly all the time), you might want to increase the baudrate by
  using the -b BAUDRATE command-line option.  If you choose a number which
  is far greater than the actual baud rate, SLiRP will write to the modem
  as fast as the OS allows, hence you'll get the maximum bandwidth.
  However, there will be a noticeable increase in lag for interactive data
  (eg: a telnet session).  (the -b BAUDRATE option has nothing to do with
  the actual baudrate, it's simply a guide for slirp so that interactive
  sessions are responsive)

* SLiRP was written in an xterm which is 110x35 characters in size.  I just
  had a look at portions of the source through an 80x25 character console.  It
  is NOT pretty! :)  Apologies to the xterm-deficient.

* You can choose any IP you wish for your home machine, except the following:

  - Any weird IP address which has some meaning to IP, like 255.255.255.255,
    0.0.0.0, 127.0.0.1 (in fact, all 127.xxx.yyy.zzz), etc., etc.

* PING does NOT yet work, so don't use ping to test the link.  Use
  telnet 10.0.2.0 instead.  This should give a "SLiRP command-line ready."
  message.  If not, then the link is not working.  If you can't telnet/ftp
  to a hostname, then your DNS entry is wrong.


How to contact the author
-------------------------

If you have any suggestions, additions, patches, questions, comments, liquor
you can e-mail me at danjo@blitzen.canberra.edu.au.

You can ftp SLiRP updates and patches from
ftp://blitzen.canberra.edu.au/pub/slirp.

There's also a WWW page (under construction) at
http://blitzen.canberra.edu.au/~danjo.  I'll put the latest information on
SLiRP on this WWW page, so please check this page before e-mailing me.  (Of
course, if you need SLiRP to work to be able to use
Mosaic/Netscape/whatever, then you better e-mail me instead)

