Slirp Manual Copyright (c) 1995 Danny Gasparovski All Rights Reserved. Updated 18/12/95 =============================================================================== Contents 0. Introduction - What is Slirp?.............................................. 1. Slirp Copyright............................................................ 2. Slirp Features............................................................. 2.1 Advantages of real SLIP/PPP over Slirp 2.2 Advantages of Slirp over real SLIP/PPP 3. Unpacking and Compiling Slirp.............................................. 4. Running and Quitting Slirp................................................. 5. Slirp Special Addresses.................................................... 6. Configuring Slirp.......................................................... 6.1 Slirp Commands 7. Port Redirection........................................................... 7.1 What is Port Redirection? 7.2 How do I Redirect a Port? 7.3 Common Port Redirections 8. Setting the "baudrate" Option.............................................. 9. Connecting a LAN over Slirp................................................ 10. Load-balancing............................................................. 10.1 What is Load-balancing? 10.2 Compiling Slirp for Load-balancing 10.3 Setting up your Configuration Files 10.4 Connecting More Modems 10.5 Load-balancing Notes 10.6 Tuning the Connection 11. Link-resumption............................................................ 11.1 What is Link-resumption? 11.2 How do I use Link-resumption? 12. Technical Information about Slirp.......................................... 8.1 Which programs do not work over Slirp? 13. Troubleshooting............................................................ 14. Answers to Frequently Asked Questions (FAQs)............................... 15. Getting Help............................................................... 9.1 Contacting the Author 16. Thanks..................................................................... 0. Introduction - What is Slirp? =============================================================================== Slirp is a TCP/IP emulator which turns an ordinary shell account into a (C)SLIP/PPP account. This allows shell users to use all the funky Internet applications like Netscape, Mosaic, CUSeeMe, etc. 1. Slirp Copyright =============================================================================== Slirp was written by Danny Gasparovski. Copyright (c) 1995 Danny Gasparovski. All Rights Reserved. Slirp is free software; "free" as in you don't have to pay for it, and you are free to do whatever you want with it. I do not accept any donations, monetary or otherwise, for Slirp. Instead, I would ask you to pass this potential donation to your favorite charity. In fact, I encourage *everyone* who finds Slirp useful to make a small donation to their favorite charity (for example, GreenPeace). This is not a requirement, but a suggestion from someone who highly values the service they provide. The copyright terms and conditions: ---BEGIN--- Copyright (c) 1995 Danny Gasparovski. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. 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. 3. All advertising materials mentioning features or use of this software must display the following acknowledgment: This product includes software developed by Danny Gasparovski. THIS SOFTWARE IS PROVIDED ``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 DANNY GASPAROVSKI 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. ---END--- This basically means you can do anything you want with the software, except 1) call it your own, and 2) claim warranty on it. There is no warranty for this software. None. Nada. If you lose a million dollars while using Slirp, that's your loss not mine. So, ***USE AT YOUR OWN RISK!***. If these conditions cannot be met due to legal restrictions (E.g. where it is against the law to give out Software without warranty), you must cease using the software and delete all copies you have. Slirp uses code that is copyrighted by the following people/organizations: Juha Pirkola. Gregory M. Christy. The Regents of the University of California. Carnegie Mellon University. The Australian National University. RSA Data Security, Inc. Please read the top of each source file for the details on the various copyrights. 2. Slirp Features =============================================================================== * Freedom. It's free, in every sense of the word. * Source code. Slirp comes with *all* source code. * Portability. Slirp should compile on most Unix compatible Operating Systems, thanks mainly to the GNU Autoconf package. * Flexibility. You can use *any* Operating System on your home PC provided you can get SLIP/PPP software for it. * 4.4BSD TCP/IP code base. The TCP/IP code is based on 4.4BSD which is widely regarded as a very stable and complete implementation. This means it does all the things expected of TCP implementations. E.g: slow start, congestion avoidance, exponential back-off, round-trip-time calculation, delayed ACKs, Nagle algorithm, incoming and outgoing IP fragments, etc. The TCP/IP code was actually taken from the excellent FreeBSD 2.0 sources. In fact, I went out of my way to do as little modification to it as possible. Most things that I regarded as unnecessary (E.g.: the rfc1323 performance enhancements) were simply commented out, so if you want to experiment with them, you can. * PPP-2.2 code. Slirp uses code from the wonderful PPP-2.2 package, so you get all the funky PPP-2.2 bonuses like BSD-compression (if your PC supports it). * Port redirection. This is used to make your PC look more like it was really connected to the Internet, hence allowing others to access services on your PC, etc. * Program execution. Slirp can execute a program on connection to a certain address/port so you can use things like nntpd if your remote host does not have an nntp server installed. * Load-balancing. You can use multiple modems and Slirp will "balance" the load on each modem. So, for example, if you load-balance two 28.8K modems your throughput will be as if you had one 57.6K modem. There is no inherent limit as to how many modems you can load-balance, if you have the modems and phone lines, Slirp will slurp them all up! * Link-resumption. If your modem dies, or the connection is somehow lost, you can log back in, restart Slirp and all your connections will continue as if nothing happened. * Command mode. Telnet to 10.0.2.0 and you can control Slirp using an on-the-fly command mode. Here, you can change certain parameters, close connections, gather statistics, execute programs, get extensive on-line help, etc. * LAN connection. If you have a LAN (Local Area Network) at home, you can connect *all* the PC's connected to the LAN onto the Internet, through Slirp. * And more ... 2.1 Advantages of real SLIP/PPP over Slirp ------------------------------------------ * Compatibility. Every TCP/IP application will work, whereas in Slirp a small subset of applications need emulation to work properly. * Addressability. Since you have a real IP address, anyone on the Internet can contact you or a service you're running directly instead of going through a redirected port as in Slirp. 2.2 Advantages of Slirp over real SLIP/PPP ------------------------------------------ * Security. You control the amount of access others have to your PC via port redirection. Also, you can't be hit by nasty things like the TCP sequence attack, "ICMP bombs", etc. Your PC is effectively firewall-ed from the Internet. * Convenience. You have all the easy, fast access and convenience of a shell account with the option to load up Slirp anytime you want. * Speed. Slirp will usually be faster than real SLIP/PPP especially if the remote host has a fast connection to the Internet, so the remote host will do a lot more buffering. This is highly dependent on your situation though. * Functionality. Because Slirp comes with source, you can easily add new functionality. For example BSD-compression is available in Slirp, whereas few SLIP/PPP accounts have it. Also, all the points mentioned in the Section 2, "Slirp Features" including Link-resumption, Load-balancing, LAN connection, etc. 3. Unpacking and Compiling Slirp =============================================================================== To unpack Slirp type the following command at your shell prompt: gzip -dc slirp-VERSION.tar.gz | tar xvf - Where VERSION is the version of Slirp you are unpacking. This will unpack the Slirp package into a directory called slirp-VERSION. To compile Slirp type the following commands at your shell prompt: cd slirp-VERSION/src ./configure make Note: if you do not intend to use PPP you can give ./configure the flag "--disable-ppp". This will make a somewhat smaller executable. That's all there is to it. If the compilation failed, read Section 15, "Getting Help" in how to get help. You should be left with a file called "slirp", this is the Slirp executable. After compilation, you can type: strip slirp to make the Slirp executable smaller, but this will also remove any debugging information from the executable. Here are some common ./configure/compiler/pre-processor/etc. problems and suggestions for fixing them: * "configure: error: can not run test program while cross compiling" (or similar errors about cross compiling). This almost always happens due to an error in the setup of the compiler. Look in the file config.log for clues as to why it failed, or send it to your sysadmin for help. * "gcc: xxxxxxx.p: No such file or directory.": This can be completely ignored when running the pre-processor, and can probably be ignored in the actual compilation. The .p files only contain the function prototypes. * "gcc: warning: no previous prototype for XXX'": Again, you can ignore this. * "RUN_MAKE_AGAIN: not found ... *** Error code 1": This is normal. As suggested, simply run "make" again. 4. Running and Quitting Slirp =============================================================================== Once you have compiled Slirp you can delete everything except the file called "slirp", this is the Slirp executable. I suggest you also keep all the files in the "docs" directory, this is where all the documentation is kept. Copy the Slirp executable somewhere in your home directory (E.g.: ~/bin) then to run Slirp, you simply type: ~/bin/slirp (or whatever the full path to "slirp" is). That's it. Now you activate your SLIP/PPP software, and start your applications. All you have to remember is this: Once you run Slirp, your shell account now looks exactly like a SLIP/PPP account (with some limitations of course). Any documentation that you have telling you how to connect to a SLIP/PPP account is completely valid for Slirp as well. To quit Slirp you simply kill your SLIP/PPP software and type five 0's (zeroes), with a 1 second gap between each zero. Slirp will then exit and you will be back at your shell prompt. You can also "disconnect" Slirp by typing five 1's (one's), with a 1 second gap between each. This will disconnect Slirp from your shell's terminal and put Slirp in the background. Later, you can type "slirp -l 0" to "reconnect" Slirp again. Please read Section 10, "Load-balancing" and Section 11, "Link-resumption" for more information. 5. Slirp Special Addresses =============================================================================== All addresses of the form 10.0.2.xxx are special to Slirp (this can be changed with the "special addr" command). The following is a description of what each of the addresses mean: 10.0.2.0 This is the Slirp "on-line" configuration address. When you telnet to 10.0.2.0 you can close connections, configure Slirp, redirect ports, etc. all while Slirp is running. Please read Section 6, "Configuring Slirp" for details on how to use this. 10.0.2.1 This is the address used by Slirp to execute programs. For example, if you give Slirp the command "add exec /bin/ls:23", when a connection is made to 10.0.2.1 on port 23, Slirp will execute /bin/ls and redirect the output to that connection. E.g., with "add exec /bin/ls:23", if you telnet to 10.0.2.1 (telnet uses port 23) you will get a list of files in the directory Slirp was started. Another example could be "add exec /path/to/nntpd:119". Now you can tell your News reader to use 10.0.2.1 as the News host and it will actually connect to the running program "nntpd". 10.0.2.2 This is an alias for the remote host. When you connect to 10.0.2.2 you will actually connect to the host Slirp is running on. This is useful if your shell account can be on different hosts, 10.0.2.2 will always mean the host Slirp is running on. 10.0.2.3 This is an alias for your DNS. Slirp will try to figure out your DNS address and all data sent to 10.0.2.3 will be redirected to your DNS address, so you can tell your TCP/IP software to use 10.0.2.3 as your DNS. This can also be useful if your run Slirp from multiple hosts; you don't need to change your DNS for each host. 10.0.2.15 This is the address recommended by Slirp to be used on your PC. However this is merely a suggestion, Slirp does not care what address you use. 6. Configuring Slirp =============================================================================== Slirp can be configured in 3 different ways: the command line, the configuration files, and "on-the-fly" configuration by telnet-ing to 10.0.2.0 and entering the commands there. The configuration file is located in your home directory (~) and is called ".slirprc", hence the path to your configuration file is ~/.slirprc. Options which can appear in a configuration file can also be given on the command line. E.g., If your .slirprc file looks like the following: redir 5022 21 redir X you can achieve the same thing by running Slirp as: slirp "redir 5022 21" "redir X" (Notice the quotes, they ARE significant). The reverse is also true. E.g., if you run slirp as: slirp -P -b 14400 you can create your .slirprc file too look like the following: -P -b 14400 (Notice that only ONE command per line is allowed in configuration files). The 2 types of options can also be mixed. E.g.: In .slirprc: -P -b 14400 redir 5022 21 command line: slirp -P -b 14400 "redir 5022 21" Note that on the command line, any command/option that does not begin with a '-' or '+', and has spaces in it, MUST be enclosed in quotes. E.g., The following are all legal: slirp -P "redir udp 5022 25" -vj -b 14400 slirp "ppp" "baudrate 14400" slirp ppp "baudrate 14400" (Notice that even though "ppp" does not begin with a '-' or '+', it does not need to be enclosed in quotes because it has no spaces in it) The following are NOT legal: slirp baudrate 14400 slirp "-b 14400" (Because "-b" starts with a '-' you must NOT enclose it in quotes) Easy, eh? Note: Whenever Slirp expects an IP address as an argument (E.g., in the command "redir") and the IP address argument is not given, then the default used is different depending on where the command appeared; if it was in ~/.slirprc then the default is 10.0.2.15; if it was in a telnet 10.0.2.0, then the IP address used is the IP address from where the telnet 10.0.2.0 connection was made. For example, if you have a LAN at home and telnet to 10.0.2.0 from one of the hosts and issue a "redir" command, Slirp will use the IP address of the host from where you made the telnet 10.0.2.0 connection. Also, if you use an IP address on your PC other than 10.0.2.15, you should include it as an argument whenever Slirp expects it, for example with the redir command: redir 5555 your.ip.address:5555 A few notes on configuration: * You should have "ppp" or "-P" before any PPP options (because when Slirp parses -P or ppp, it will initialize all related fields, hence clearing anything that was parsed before it). * Upon startup, the configuration is done in this order: 1) ~/.slirprc-N (if using Load-balancing or Link-resumption) 2) ~/.slirprc 3) command-line options This is important because, for example, if you have "initiate-options" (a PPP option) in ~/.slirprc-0, and you run slirp with -P, "initiate-options" will not be valid, because -P will clear the fact that you want options initiated by Slirp (remember, -P should always come before any PPP options). 6.1 Slirp Commands ------------------ Slirp includes an "online-help" facility. To get a list of commands accepted by Slirp give it the command "help". I.e, you can either run Slirp from your shell prompt as: slirp "help" or once Slirp is running, telnet to 10.0.2.0 and type: help To get a brief description of each command simply type "help COMMAND". E.g.: slirp "help baudrate" or help baudrate in telnet 10.0.2.0 will print out the following: Command: "baudrate" Usage: baudrate BAUDRATE Command-line: -b Available: command-line, config-file, telnet change the baudrate Usage tells you the arguments the command accepts, command-line tells you the command line ("dash") equivalent, Availability tells you where the command can be executed from, and the final line tells you exactly what the command does. Also, take a look at the file CONFIG in the "docs" directory in the Slirp distribution. It has a more detailed explanation of the Slirp commands, but is most probably out of date. 7. Port redirection =============================================================================== 7.1 What is Port redirection? ----------------------------- Port redirection is an important concept in TCP/IP emulators because it allows other people to connect to your PC, as well as allowing some programs to work which normally would not work. 7.2 How do I Redirect a Port? ----------------------------- First you need to realize that under Slirp, nobody on the Internet can address your PC directly, since you do NOT have an IP address that anybody else can see. The ONLY way they can contact you is through the remote host (where Slirp is running). What has this got to do with Port redirection? Lots. For other people on the Internet to be able to connect to your PC, Slirp needs to listen for connections on a specific port on the remote host, then "redirect" this connection and have it connect back to your PC. For example, say you are running an FTP server on your PC and you want others to be able to connect to it, get files, upload files, etc. What you need to do is pick a port number, any port number above 1024 (for security reasons), and tell Slirp that any connections on that port are really connections to your FTP server. You do this with the "redir" command. For this example, say you choose 5555 as the port to redirect (this can be ANY number, provided nobody else is using it). You simply give Slirp the command: redir 5555 21 The second argument, 21, is the port that is used by FTP. You could have also used the command: redir 5555 ftp and Slirp will figure out that "ftp" means 21. This command is basically telling Slirp "any connections to this host (where Slirp is running) on port 5555 are really connections to the home PC on port 21 (the port used by the FTP server)". Now you simply tell others to connect to the Remote Host (where Slirp is running), which IS visible on the Internet, on port 5555 and they will be connected to your FTP server. This same technique is used when a program uses a specific port for communication, for example Kali, an IPX emulator over TCP/IP allowing users to run IPX games over the Internet. Kali uses UDP port 2213 for communication so for others to be able to send a packet to your PC on UDP port 2213 you need to do the following: redir udp 2213 2213 All packets now destined for the Remote Host on UDP port 2213 will be sent to your PC on port 2213. 7.3 Common Port Redirections ---------------------------- Here is a list of programs which need a port redirection to work. YOUR_PC_ADDRESS refers to the IP address you assigned to your PC. If it is not supplied, 10.0.2.15 is assumed. Kali redir udp 2213 YOUR_PC_ADDRESS:2213 (Note: you MUST also set your PC's IP address to the same IP address as the Remote Host (where Slirp is running)) IPhone redir udp 22555 YOUR_PC_ADDRESS:22555 StreamWorks redir udp 8000 YOUR_PC_ADDRESS:8000 (the 8000 is configurable) PowWow redir tcp 13223 YOUR_PC_ADDRESS:13223 WebPhone redir tcp 21845 YOUR_PC_ADDRESS:21845 redir udp 21845 YOUR_PC_ADDRESS:21845 (Note: WebPhone uses BOTH tcp and udp port 21845. In addition, you probably need to set your PC's address to the same IP address as the RemoteHost in order to get full functionality) [Please let me know of other programs which require redirection like the above. See Section 15, "Getting Help" for details on how to contact me] 8. Setting the "baudrate" Option =============================================================================== Slirp's "baudrate" option has caused some confusion. This section will explain exactly what it's for and how to use it. When sending data over the modem to your PC, Slirp needs to know how much data it can send over without "saturating" the link. If Slirp was to send as much data as it could, the Operating System would buffer a LOT of it - 20k is not uncommon. This could severely "lag" any telnet connections if you happen to be FTP-ing a file at the same time. This is because when you type a character, you will not see that character on the screen until the the other end sends you the "echo", so if there is 20k worth of data buffered you will need to wait until 20k of data is received before you see that character on your screen. To counter this, Slirp uses the "baudrate" option to limit the amount of data it sends over the link to prevent the Operating System from buffering too much of it. So if you give Slirp a "baudrate" of 14400, Slirp will send data at a rate of 14400 Baud modem (with no compression). In general, the baud rate at which the connection was made should be the "baudrate" you give to Slirp. So, for example, if you connected at 14400 Baud, you should give Slirp the option "baudrate 14400". However, since most modems today do compression (v.42bis), it is very difficult for Slirp know how much data to send to keep the link "full", yet prevent too much buffering by the Operating system. Therefore you should choose a "baudrate" appropriate to your needs: if you use telnet a lot while downloading compressed files, you should set your "baudrate" to the same as the CONNECT speed of your modem. Downloading compressed files should not suffer, and telnet sessions will be far more responsive. However, sending text over the modem will not be as fast, because your modem will compress the data and send it faster than Slirp expects. Giving a "baudrate" the same as the CONNECT speed will effectively turn off modem compression. If you do not use telnet very much, you should set your "baudrate" to the maximum theoretical speed your modem can do. For example, if you connect at 14400 and use v.42bis compression, which can compress up to 4x, you should set your "baudrate" to 14400*4 = 57600. This will ensure any compressible data will get compressed, and a maximum throughput will be attained, at the expense of telnet sessions which will be almost unusable if you happen to be downloading files at the same time. Note however that you can change the "baudrate" setting at any time. Simply telnet to 10.0.2.0 and enter "baudrate XXX" and Slirp will change the rate at which data is sent. This can be useful for example if you're downloading a lot of compressed files, but in the middle of the download you want to read mail. Simply change the "baudrate" to the CONNECT speed, and when you're finished, change it back to the maximum theoretical speed. Also, keep in mind that the "baudrate" is also used for other calculations. For example, if there are many connections, Slirp will try to be fair and send one packet per connection in a round-robin fashion. This makes all connections "smooth" instead of sending a bunch of packets for one connection, then a bunch of packets for another connection, etc. But if the "baudrate" is too high, the is exactly what will happen. Packet priority selection also uses the "baudrate"; I.e., if there are packets queued ready for sending from both an FTP connection and a telnet connection, the telnet packets will be sent first. But again, this will only work if the "baudrate" reflects the amount of data Slirp can send, and generally won't work if you set it to the maximum theoretical connection speed. So here are my tips: * If you download a lot of compressed files and occasionally use telnet, or other "interactive" programs, set your "baudrate" to your CONNECT speed (because already compressed files won't compress any more with the modem compression, so you're unlikely to get faster download's as a result of modem compression); * If you mainly use telnet, or other "interactive" programs, and you occasionally download some compressed files, set your "baudrate" to the maximum theoretical speed (because telnet sessions are usually text, which compresses very well, hence screen updates will be faster. Only when downloading compressed files will you experience severe lag); * If you mainly browse the Web (E.g., using Netscape, etc.), then you should set your "baudrate" to the theoretical maximum speed (because there's lots of text in Web documents which is very compressible, and there's no telnet sessions so lag will not be a problem); I personally have by baudrate set at 14400, the speed at which my modem connects, even though the modems do v.42bis compression. Compressed file downloads are just as fast, and telnet sessions during FTP downloads are surprisingly responsive. Try it yourself, there's a world of difference. 9. Connecting a LAN over Slirp =============================================================================== From the very beginning, Slirp was designed to allow more than one host access the 'Net at once. And doing so is *very* easy. First, you need to setup the LAN (Local Area Network) as if it was really going to connect to the Internet. That is, you must give them each a unique IP (unique relative to each other, not globally unique. E.g., you could give them all an IP address in the 10.0.2.xxx class of addresses). You also must tell each host on the LAN to route it's IP packets to the host that is connected to the Internet via Slirp. Here's a diagram: [Ethernet] ------------------------------------------------- | | | | | [Host A] [Host B] [Host C] [Host D] [Host E] | | | | | <- Slirp link | <- SLIP link | | | | [Remote Host] [Another LAN] | ... to the Internet Now, in this diagram, Host A is the Slirp-connected host. Host's B through to E can also access the 'Net by simply using Host A as the gateway. Host A also must be told to "forward" IP packets (using Remote Host as the gateway) so that it will send any IP packets not destined for itself to Slirp, and vice versa (route all packets sent by Slirp, not destined for itself, back to their respective host's IP). In other words, the Slirp link is just like a real SLIP/PPP link, which is what I've been telling you all this time! :) Note that it is possible to hook up many LAN's to the 'Net by simply following the normal Internet conventions, and route the packets properly. In this case "Another LAN" would use Host E as a gateway to the 'Net, Host E, provided it can forward IP packets, will send them to it's gateway, Host A, which will send it over Slirp, etc. In theory, you could connect another whole Global Internet to the current Internet with no IP address clashes. Not recommended though :) 10. Load Balancing =============================================================================== 10.1 What is Load-balancing? ---------------------------- Load-balancing is the ability to use more than one network interface (modem) at the same time, and sending traffic over both in such a way as to effectively double the throughput (actually, it will "concatenate" the number of modems to one). So, for example, if you have a 28.8k modem, and a 14.4k modem, your throughput will effectively be 28.8+14.4 = 43.2k. Obviously, you need more than one modem, and the same amount of phone lines. You also need a TCP/IP stack that can handle more than one interface (modems). Linux and FreeBSD have no troubles here, but stacks like Trumpet Winsock I don't believe would work, since they can only use one modem at a time. Slirp is flexible enough to be able to load-balance over multiple hosts. For example, you could have two accounts with two different ISP's (Internet Service Providers) and still load-balance over them. 10.2 Compiling Slirp for Load-balancing --------------------------------------- First you must compile into Slirp the ability to have use Load-balancing. To do this, edit config.h (after running ./configure) and go to the lines: #define MAX_INTERFACES 1 #define MAX_PPP_INTERFACES 1 Change the "1" for MAX_INTERFACES to the MAXIMUM number of interfaces (modems) you expect to have at connected once. If you plan to use PPP while load-balancing, you should set MAX_PPP_INTERFACES to the same number as MAX_INTERFACES. Once you've changed these values, (re)compile Slirp. 10.3 Setting up your Configuration Files --------------------------------------- Each modem (or "unit") needs to have it's own unit number, and it's own configuration file called ~/.slirprc-N, where N is it's unit number. When Slirp is run for just one modem, it is assigned unit number 0, so the first time you run Slirp (or if you plan to use link-resumption as per Section 11, "Link-resumption") it will read the file ~/slirprc-0. This file must hold modem/SLIP/PPP-specific configuration (except MTU and MRU!). You shouldn't have any general commands in there like "redir" or "add exec", they go in ~/.slirprc. You must also put the "socket" command in your ~/.slirprc file. If all connections are on the same host with the same account, you should simply put "socket" in your ~/.slirprc file. If on the other hand you have different account, possibly on different hosts, you should put the following in your ~/slirprc file: socket PORT,PASSWORD where PORT is an arbitrary port number for Slirp to listen to (must be greater than 1024), and PASSWORD is the password to use when connecting. This is explained in Section 10.4, "Connecting More Modems". E.g., if your ~/.slirprc currently looks like: redir 5000 21 baudrate 57600 ppp socket ipcp-accept-remote mtu 552 mru 552 Then you should make your config files look like the following: ~/.slirprc: redir 5000 21 socket mtu 552 mru 552 ~/.slirprc-0 baudrate 57600 ppp ipcp-accept-remote (Note: mtu and mru go into ~/.slirprc even though it is a modem-specific command, they are the only exceptions to the rule) 10.4 Connecting More Modems --------------------------- Once you have the config files and interfaces ready, you connect all your modems to the same shell account as the same user. The first Slirp that you run should be run normally, as "slirp" (this is unit 0, the "main" Slirp). If all connections are from the same host and the same account (you have "socket" in your ~/.slirprc file), then for each other connection, you run subsequent Slirp's as "slirp -l UNIT", where UNIT corresponds to that connection's ~/.slirprc-UNIT file. If in the other hand you are connecting from multiple accounts and/or multiple hosts (I.e. you used a command of the form "socket PORT,PASSWORD" in your ~/.slirprc file) then you run subsequent Slirp's as "slirp -l UNIT,HOST:PORT,PASSWORD", where UNIT corresponds to that connection's ~/.slirprc-UNIT file, HOST is the address where the main Slirp (unit 0, as described above) is running, and PORT and PASSWORD correspond to those used in the "socket" command. The reason for a password is so that others who connect to this port are not allowed to send anything to Slirp, which would be a major security hole. Note that you can also pass Slirp the password using the environmental variable SLIRP_PASSWORD (this is for hosts which do not properly delete the password from the argument list). In this case, simply use "slirp -l UNIT,HOST:PORT,-" instead. The "-" tells Slirp the password is in the environmental variable. The -l option MUST be the only command given to all subsequent Slirp's. If there are other commands after it, they will be ignored. If there are other commands before it, it will not work. If it succeeds, you should get a message like "Connected: Attached as unit N on device D". Once you get this message, you can tell your local SLIP/PPP software to make the connection (you should make all interfaces have the same IP address). You can attach and detach modems as you wish. For example, you could be running Slirp as unit 0 as usual, then when you feel like it, you dial-in with your second modem and attach it while all the connections are still active. They will all continue as normal. You can also detach each unit as you wish, by typing 5 ones ('1') into the unit you wish to be disconnected (remember, sending 5 zeroes ('0') will kill ALL the unit's and all running Slirp's). When all unit's are disconnected, Slirp will sit in the background and wait. If you do not re-attach a new unit in 10 minutes, Slirp will exit. 10.5 Load-balancing Notes ------------------------- * There are no limits to how many modems you can attach to one running Slirp. If you have 12 modems, Slirp will slurp them all up! (lucky you! :) * You MUST use the same MTU/MRU on all interfaces (and hence MTU/MRU should only be in ~/.slirprc). This is the only *real* limitation when using load-balancing. It is needed because of the way Slirp allocates data (mbufs) and the fact that at the TCP/UDP layer, Slirp does not yet know over which interface it is going to send the data, and so it can't tell how big the packet is allowed to be. I suppose I *could* lift this restriction, but I don't wanna :) (I don't think the extra code justifies the *small* gain). You should also try and keep both MTU and MRU the same. * Because SLIP is dumb, you should be careful when attaching a new SLIP unit. As soon as you attach the new unit, Slirp will start sending data over it. Try and attach it quickly, and keep traffic to a minimum when attaching. PPP on the other hand does not suffer from this, since it will not be active until the two ends negotiate all options etc. and mark the interface as "up". * Do NOT use vj compression any ANY of the interfaces when using more than one link. It will not work, period. * You can mix SLIP/PPP interfaces in whatever way you wish. E.g.: have 2 modems using PPP and 1 modem using SLIP. 10.6 Tuning the Connection -------------------------- The two variables Slirp uses to determine the ratio of data which should go to each unit is the "baudrate" and "towrite_max", as given to it via the ~/.slirprc* files (baudrate is per-unit, towrite_max is the same for all units). The "baudrate" should be the maximum theoretical throughput on that modem, and, more importantly, each unit should be given a baudrate which is reflective of it's performance relative to the other units. I.e., the ratio of any 2 "baudrate"'s on any 2 units should be the same as the ratio of the 2 modems actual baudrate. E.g.: if you have 2 modems that are the same speed, the "baudrate" should also be the same. Or, if one modem is twice as fast as the other, then the baudrate should also be twice as fast as the other, etc. Note: play around with the baudrates to get the best results. Sometimes, depending on the type of data, setting the baudrates to the actual CONNECT speed can improve performance. The "towrite_max" option tells Slirp the minimum number of bytes it will write to each modem before it "backs off" and starts baudrate calculations. Why is this important? Resolution. If towrite_max is only 1, then each modem will be either "ready" or "not ready" with nothing in between; nothing to determine which modem has been written to the most recently. Conversly, if you have towrite_max at 20k and you have a 2400 baud and a 28.8k baud modem, then Slirp will write 20k to each modem before "backing off" and doing any calculation. This means the 2400 baud modem will have 20k of data sent over it, no matter what the situation, which is obviously wrong (consider sending a 40k file; the load will be equally shared between the two modems, which is obviously wrong). In general, "towrite_max" should be higher for faster modems. E.g., I'd recommend 2048 when load-balancing over 28.8k modems. So basically, it comes down to this: the "baudrate" determines how to share the data between the modems, the "towrite_max" determines when to start calculating the load share. There is no set formula to determine what these should be, since a lot of it is determined by the nature and type of data being sent over the modems. Use these suggestions as a guide, but there's no substitute for good'ol trial-and-error. During the initial tests, one tester regularly acheived 6.6k/sec with 2 modems connected at 31.2K. 11. Link-resumption =============================================================================== 11.1 What is Link-resumption? ----------------------------- Link-resumption is the ability to resume all connections even if the modem gets accidently (or deliberately) disconnected. 11.2 How do I use Link-resumption? ---------------------------------- To be able to resume a connection you first need to setup your configuration files similar to when using Load-balancing. See Section 10.3, "Setting up your Configuration Files [for Load-balancing]" to see how to setup your ~/.slirprc-0 file. Once the configuration files are setup, all you need to do is always run Slirp as "slirp -l 0". Do NOT include the "-l 0" in your ~/.slirprc file, it MUST be on the command line. You can run Slirp like this even if there is no link to be resumed, Slirp will run as normal in that case. Also, remember that sending 5 1's down the line will detach only the current link. This allows you to do funky things like detach the current PPP link, then re-attach it as a SLIP link, without disturbing any of the current connections. Note that if you do not resume your disconnected link within 10 minutes, Slirp will exit. 12. Technical Information about Slirp =============================================================================== 12.1 Which programs do not work over Slirp? ------------------------------------------- Any programs that bind()'s 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. At present, the following programs are emulated: rlogin ftp ksh irc (for /dcc) RealAudio talk/ytalk/ntalk CUSeeMe 13. Troubleshooting =============================================================================== Symptom ------- The connection will "freeze". E.g., while downloading a picture on WWW it will stop halfway and no connections will continue. Diagnosis --------- You probably don't have an 8bit clean link. Cure ---- You should try and find out from your sysadmin which characters need to be "escaped", then tell Slirp about them using the "asyncmap" and "escape" commands. Note that you need to use PPP for this to work. (One way to test for 8bit cleanliness is to download a BINARY file with Z-Modem. If the file doesn't make it, you have a "dirty" link) One thing you might try is run Slirp as: slirp "asyncmap ffffffff" "escape ff" (quotes included!) This will tell Slirp to escape the most common "nasty characters. Symptom ------- You can connect to hosts using numerical addresses (of the form aa.bb.cc.dd) but you cannot connect to hosts when you use their hostname (E.g.: ftp.cdrom.com). It usually times out with a DNS error. Diagnosis --------- You probably did not set your DNS address properly. Cure ---- Try setting your DNS address to 10.0.2.3. This should work for most situations. If that fails, go to your shell prompt and type "nslookup". This should print the address and hostname of your DNS server. Use the numerical IP address as your DNS. Do NOT use the hostname. If you still can't find your DNS address, ask your sysadmin for it. 14. Answers to Frequently Asked Questions (FAQs) =============================================================================== Q1. Can I use Slirp through Telnet or Rlogin? A1. Yes, usually. But this is highly dependent on your situation. The reason Slirp usually doesn't work through telnet is because of the ^] character is interpreted by the telnet client, and 0xff interpreted by the server. While you can tell Slirp to escape these characters while using PPP, it may not be possible to get your local PPP software to escape characters greater than ASCII 31. Rlogin also interprets the ~ character, which may interfere with PPP (especially considering ~ is ASCII 0x7e which is used by PPP as the "end of packet" character"). If your PPP software is unable to escape these characters, or you're using (C)SLIP (which must have an 8bit clean link), your best bet is to try and make the link 8bit clean. For example, on some systems you can give telnet the -8 flag to make the link 8bit, and -E to stop it from interpreting the ^] character. Similarly for rlogin; -8 to make the link 8bit, -E to stop rlogin from interpreting the ~ character. You should look at the telnet and rlogin manual pages ("man telnet" and "man rlogin" respectively) to see if your telnet/rlogin has similar options. Another possible solution is to use Slirp's ability to work over multiple hosts. See Section 10, "Load-balancing" for details on how to disconnect/reconnect Slirp sessions using Internet-domain sockets. Q2. How do I run an X program on another host and have it display on my PC? A2. Use the "redir X" command in ~/.slirprc. This will redirect a port for use with X programs. On startup, Slirp should print something like: X Redir: In sh/bash/zsh/etc. type: DISPLAY=IP.ADDRESS:X.Y; export DISPLAY X Redir: In csh/tcsh/etc. type: setenv DISPLAY IP.ADDRESS:X.Y Now, when you telnet to the host you wish to run the X programs from, you should do as Slirp suggest above; type either of the two commands, depending on which shell you are using. You could also run the X program as "xprog -display IP.ADDRESS:X.Y" as printed above. If you missed what Slirp displayed on startup, you can telnet to 10.0.2.0 and give Slirp the command "show X", and the above will be printed. Note that you also have to make sure your X server will accept the connection. See the man page for xhost and Xsecurity. Be careful with issuing commands like "xhost +", this will allow anyone to connect to your X server and do basically anything they want. Q3. When I run "talk" or "wintalk", etc. I am able to send requests to other people but they cannot send requests to me. Why? A3. You won't be able to receive talk requests, period. This is because Slirp never see's the incoming talk request; it is sent directly over the modem, most likely corrupting any incoming packet with it (which will have to be retransmitted). Slirp turns off your messages so the person who tries to talk to you should receive a "User is refusing messages" error. Q4. I can't telnet to 10.0.2.0, the Slirp control address. What's wrong? A4. Your TCP/IP stack probably has a problem with addresses ending in 0. Edit the file ctl.h in the "src" directory and change the 0 in the line: #define CTL_CMD 0 to something else, say 10. Then you "telnet 10.0.2.10" to get the Slirp command-line. Q5. I'm having a few problems with Slirp and want to try and find the problem myself. Does Slirp have any debugging facilities? A5. Yes. After you type ./configure, edit Makefile and uncomment the -DDEBUG argument in the COMMON_DEFS section. I.e. the line: COMMON_DEFS = -I. -I${srcdir} -DUSE_PPP #-DDEBUG should look like: COMMON_DEFS = -I. -I${srcdir} -DUSE_PPP -DDEBUG and recompile. Then, simply give Slirp the arguments "-d -1" and Slirp will log lots of stuff to a file called slirp_debug. Q6. My ISP logs me out if I idle too long. How can I get Slirp to prevent this? A6. First of all, the idle-logout mechanism is used for a reason: to prevent people from hogging a modem which is not in use. So if you're idle, logout and give others chance to use the modem. Having said that, you can make Slirp use TCP keep-alive timers to regularly probe each TCP connection. To activate this, add: keepalive to your ~/.slirprc file. This will make Slirp probe each TCP connection every minute or so. You can change this interval by giving keepalive the number of seconds: keepalive SECONDS Note that no probes will be sent if there are no TCP connections. So you need at least one active TCP connection for this to work. Q7. When I ftp to a non-standard port (like when another Slirp user is redirecting a port for their ftp server on their PC) it doesn't work. Why? A7. You need to tell Slirp about the non-standard port by issuing the command: add emu ftp PORT where PORT is the port you are ftping to. The same goes for other emulated services. 15. Getting Help =============================================================================== There are several sources of help. First, read Section 13, "Troubleshooting" and Section 14, "Answers to Frequently Asked Questions (FAQs)". If that fails, try the Slirp Home Page at: http://blitzen.canberra.edu.au/slirp There are lots of neat links there to other pages which have specific configuration information. There is also a Newsgroup dedicated to SLIP-emulators called alt.dcom.slip-emulators. You will find lots of discussion about Slirp and other "SLIP-emulators". The FAQ (Frequently Asked Questions) for alt.dcom.slip-emulators is included in the "docs" directory, I would suggest reading this as well. If all else fails, send me e-mail to danjo@blitzen.canberra.edu.au with the following information: * Output of the command "uname -a" on the remote system; * Operating System name and version you run on your PC; * Version of Slirp you are using (IMPORTANT!!!); * If you managed to get Slirp running, run Slirp as "slirp -S" then try whatever failed. When you exit Slirp, you should have a file called "slirp_stats". Send me this file; and * Anything else you consider relevant. *PLEASE* include all the above information. If you do not, I may simply press "d". I can't guarantee a response, but I will try my best. 16. Thanks =============================================================================== A big "THANK YOU!" goes to the following people for their help in creating Slirp. Juha Pirkola, Gregory M. Christy, The Regents of the University of California, Carnegie Mellon University, The Australian National University, and RSA Data Security, Inc. whose source code is used throughout Slirp. Slirp would not be without them. Thanks to all the contributors who helped with bugs, suggestions, code, etc. Read the file ChangeLog to see exactly who helped with what. A special thanks goes to Chris Metcalf and Juha Pirkola for their contributions (see ChangeLog). They put in extra effort and Slirp wouldn't be the same without their help. Thanks guys! Thanks to all the people who sent very kind and encouraging e-mail, it's sincerely appreciated. Thanks to all the admins and Head Honcho's at UCNet, the University of Canberra Computer Club ("blitzen") who gave me some real-estate on their machine (blitzen.canberra.edu.au) to work with (thanks to Tony Delroy for giving me the account originally). Hey! Why don't you check out their home page at http://blitzen.canberra.edu.au/? Thanks to Brazil for coffee (and Sepultura! :) Thanks to the laws of physics, the building blocks of the universe. The End =============================================================================== I hope you enjoy using Slirp as much as I enjoyed writing it. Dan ...