Table Of Contents :

1. Legal Disclaimer
2. About
3. Installation
4. Using
5. Security
6. Troubleshooting
7. To-do


1. LEGAL DISCLAIMER

   By using this software, you agree with the following terms :
   
   a) This software protected by the GNU license
   b) the author cannot be held responsible for any harm/damage
      caused directly or indirectly by this software. In short :
      USE IT AT YOUR OWN RISK !
      
      The script was tested under the following conditions :
   
      Distribution :
      SuSE 5.3, Kernel 2.0.3x
   
      Authentication :
      PAP
      "normal"
      
      If you have any acknowledgements, you might reach me via email :
      patrick@unix-ag.uni-siegen.de
      
      
      The default setup for the script actually looks like this :
      
      - Distribution : SuSE 5.x  (but it should of course work with any 
                                  distribution, so email me, if it doesn't,
				  and why it doesn't, I'll try to fix it then)
				  
      - Kernel : 2.0.3* (Let's see, what the next generation brings, probably
                         I'll have to adapt some services)
      
      - Services : logging only (the other stuff may either not work every-
                                 where, or is probably not wanted, so you have
				 to turn it on yourself, if you need it).
      
      - Authentication : PAP (like the University of Siegen, Germany uses
                              it)


      Newer versions of this package can be obtained from the following 
      locations (at least I plan toput them there occasionally ;) ) :
      
      www.unix-ag.uni-siegen.de/~patrick
      www.ldknet.org/LUG
      sunsite.unc.edu
      
 
2. ABOUT

   This packages consists of several shellscripts, used for making a PPP
   connection to the internet using either a modem, or (not tested) an
   external ISDN modem, but not with an ISDN card (Should I ever get ISDN,
   I'll try to adopt the script to ISDN, too) and then running several
   services like exchanging like email and news. It was witten with 
   simplicity in mind, to get something easy to use and easy to configure 
   (since making a ppp connection seems to give most people a hard time),
   but alas I fear, I bloated it with features to a point, where neither
   of these two goals is archieved ;) (email me, if you haven't lost the
   overview yet, and I bloat it a bit more ;> ). Well, at least it is now
   able to do complex tasks, that is, automate things you did manually in
   the past ;). But see for yourself, if my work is of any use to you. 
   Maybe you want even to extend it a bit (adding a new usefull service
   for example)...
   
   
  
3. INSTALLATION
  
   First thing to do, is unpack the contents of this package to
   /etc/ppp (well, you probably did this by now, otherwise, you
   could probably not read this ;) ). 
   The software consists of two parts :
   
   a) the dialer part
   b) the service part 
   
   Part b) (consisting of /etc/ppp/ip-* and /etc/ppp/service/*) doesn't need
   any maintaince unless you got part a) setup. To say it in short : 
   Nothing included in /etc/ppp/service neither the two files /etc/ppp/ip-up
   and /etc/ppp/ip-down are are responsible for anything regarding the 
   process of dialing-in. If you can't connect, please don't try to mess
   around with these files. 
   
   Ok, now to get part a) working, grab yourself your favourite texteditor,
   you'll have to edit some files (I'm trying to keep this stuff as much 
   modulized as possible, therefore there is no master config file, and 
   will never be, sorry). Hopefully, you only need to change the variables
   (the words in capital letters), everything is heavily commented, so
   you should have no big problems :
   
   /etc/ppp/data/ppp-config
   
   /etc/ppp/data/dialer.pap  AND  /etc/ppp/data/pap-secrets 
                        OR 
	       /etc/ppp/data/dialer.normal    
   
   Depending on what kind of authentication you are required, your ISP
   should be able to tell you this (well, sadly most don't seem to be
   able to ;(, so if in doupt edit all three files). I heavily commented
   my work, so you should have no problems with adjusting the scripts
   to your system. The only exception are the files /etc/ppp/dialer* ,
   which don't allow comments in them. To understand how they work, read
   the manualpage of chat(8). Basicly said, the first word in a line is
   an expect string, the second one is the send string. This means, chat
   waits till it gets the first string of the line from the modem and then
   sends the second one. NOTE: make sure, there are only two words per
   line present ! That is the line to dial the number must look like this :
   
   OK ATDT555-0815
   
   not
   
   OK ATDT 555-0815
   
   Since in this case 555-0815 would be the next expect string (which would
   of course mess up the diealerscript). Also note, that an expect string
   doen't need to be the complete response from the modem. That is, if the
   modem responds :
   
   Login:
   
   it is enough to put 
   
   ogin:
   
   or 
   
   gin:
   
   in the expect string. If my dialerscripts don't work for you (which will
   probably the case), grab yourself a terminalprogram (minicom is fine),
   and dial the number of your ISP, to find out, what you should use for
   expect and send strings.If you are still clueless afterwards and feel, like
   you gotta email me for help, please include a FULL screen dump with 
   completed login sequence (please don't forget to change your password 
   afterwards) in the email.
   
   Next link (you could also copy it, but linking is smarter) 
   
   /etc/ppp/dialer
   
   To 
   
   /etc/ppp/data/dialer.<choose your favourite one>
   
   And
   
   /etc/ppp/ppp-config 
   
   To 
   
   /etc/ppp/data/ppp-config.<choose your favourite one>
   
   
   If in doubt, ask your ISP, about what kind of authentication they are 
   using. Possibilities are : PAP, CHAP and "normal", CHAP might not
   work, sorry, but I don't have the possibility to adjust the script
   to work with CHAP (if someone can do this, send me the "patch").

   Make sure, everything, in /etc/ppp (including the directory itself) 
   is owned by user root, group root, and is inaccessable to anyone
   else !!!  
   
   You also need to create a directory :
   
   /var/lock/internet
   
   Don't forget to edit /etc/resolv.conf and put your ISP's DNS in 
   it !
   
4. USING
   
   As root (it may be wise using sudo, so non-priviledged users can
   establish the link, too) cd to /etc/ppp and call the script with
   ./ppp start
   you can shut the link down with 
   ./ppp stop
   
   After the ppp script established/shut down the link, pppd will call the 
   script ip-up/ip-down (also located in /etc/ppp) which will start/stop 
   the scripts found in /etc/ppp/service/start and /etc/ppp/service/stop (read the 
   comments in ip-up or ip-down, to find out, how this exactly works). You 
   may want to make some adjustments here, to match your configuration. 
   So by default only the logging facility will be started.
   
5. SECURITY

   A WORD OF WARNING
   
   As pointed out in 4. /etc/ppp/ppp can only be called by root, as it 
   deals with passwords and other security matter, this is not only sane,
   but extremly uncompfortable, since
   
   a) you always have to log in as root just to (dis)connect to the internet
   b) you always have to be around if your familly wants to have fun
   
   Therefore you might want to use the sudo program. sudo let's normal users
   execute programs, as if they were another user, in our case, they could
   call ppp as if they were root. /etc/ppp/ppp should be safe to use with
   sudo, the way I wrote it (at least I hope so ;) ). But unfortunatly,
   I wrote it also extendable. So, if you add a new service(script) to it,
   make sure to always use ABSOLUTE pathnames in that script (and also use
   absolute pathnames when setting links). This is very IMPORTANT, because 
   if you don't, it'll be VERY easy for a normal user to GET ROOT ACCESS !!!
   The only thing s/he has to do, is modify his/her search path a bit and
   make a special link to a shell (or any other command s/he would like to
   call as root).
   
   PERMISSIONS :
   
   As said before, anything under /etc/ppp (including the directory itself)
   must be owned by root AND INACCESSIBLE by anyone else. Normally the 
   permissions should be ok, but it won't hurt to check them, as I can 
   assure you, it can hurt you, if you don't. Since everything in this 
   package is build up using shell scripts, it is very easy to either get
   your password for your internetaccount or root access to your machine,
   or both, if you don't pay attention.
   
   Also make sure (should you happen to run NFS), you don't have a line like
   / (rw,no_root_squash) 
   
   in your /etc/exports (that's an invitation for any hacker !). Either 
   put only the pathes you really need to export in that file, or use 
   at least the line : 
   
   /etc (noaccess)
   
   Since /etc holds also some data, you won't want to get in the wrong hands 
   (like your password database for example). 
   
   
   
   ACCESSCONTROL 
   
   Accesscontrol is possible by creating a file
   
   /var/lock/internet/block-ppp
   
   If this file exists, /etc/ppp/ppp exits (with an errorlevel of 1) after
   printing the contents of this file to the standard output (this way, 
   you can tell folks, why they are not allowed to dial-in right know).
   You can also block a single user from connecting by adding his/her login-
   handle as a suffix to this file e.g :
   
   /var/lock/internet/block-ppp.Fred
   
   Will (only) prevent user Fred from dialing out, while others are still
   allowed to.
   

   FOCUS ON CHAT 
   
   chat is potentially insecure, especially, if you 
   have to give it loginname and passwort, then every user can view them
   with the simple command :
   cat /proc/`pidof chat`/cmdline
   So make sure to NEVER give chat valuable data as a commandline parameter,
   at least not as long, as you haven't applied a securitty patch to the
   kernel, which set's the permission in /proc correctly.
   
   FOCUS ON MAIL AND NEWS 
  
   You may have noticed by now, that I pay much
   attention on securitty ;). But alas, this goes for your local securitty
   only (meaning : I take much effort, so your local system cannot be 
   exploited), this goes not for the services email and news ! As for 
   now, these two are potentially securitty holes. Since fetchmail and
   suck transfer loginnames, mailbodies and PASSWORDS over the line in CLEAR 
   TEXT, allowing for so called "man-in-the-middle" attack (I heard of a way
   to use ssh or so for encryption, and will surely look into this). This may
   be ok, as long, as you only fetch your email from your ISP's mailserver
   (since there can't be a "man-in-the-middle" here, and if, shoot you ISP, 
   for his sloppy handling of sensible data), but as soon as you use an 
   external mailserver, your data will be routed over several potential 
   insecure networks. Use nslookup <mailservername> to find out, which
   way your mail travels, and consider for yourself, if you trust those 
   sites (rule of thumb : don't trust them ;) ).
   
   6. TROUBLESHOOTING

* My modem dosn't response at all to your script
- Well this could have several reasons, try the following steps :
  1. Switch on your modem ;>.
  2. Plug in the cables (the one leading to your computer and the
     one to your telephone) ;>.
  3. Make sure the programs pppd and chat are installed.
  4. Now start minicom and give your modem the command 
     AT
     it should respond with
     OK
     and a flicker of the LED's, if it does, mail me, there might
     be actually a problem with the script, preceed if it doesn't.
  5. Check if /dev/modem points to the right device (/dev/ttyS0 for
     COM1 and /dev/ttyS1 for COM2) and if you compiled serial support
     in your kernel.
  6. Check if you have one of those junky WINmodems. In this case you
     should 
     a) abandom all hope, you won't get it going with Linux (or anything
        else then winblows for that matter).
     b) smack your dealer with a bat for selling such junk.
     c) Try to see, if your dealer will give you a refund and buy a 
        real modem.
     (I'd prefer method b) enough is enough)
     
     Why this ? you may ask. Well, according to what I know about
     WINmodems, those crappy thing are lacking some important chips, 
     this makes it cheaper to produce them (so the manufacturor saved a
     lot of money), but of course the modem needs those chips, so they 
     are emulated by the driver software (which is of course only 
     available for winblows) on your computers main CPU. To point this 
     out (and of course to have a legitimation, why your modem is more
     expensive then normal (better !!!) modems), the thing is named
     WINmodem. As you see, you were cheated tripple (higher price for
     lower quality at the cost of CPU time) when you bought your WIN-
     modem, now do you feel ready for b) ;> ?
     
* My modem seems to be ready for dialing, but doesn't actually dial.
- Check the dialerscript, chances are, that you put a whitespace between
  ATD and your telephonenumber, those are meant to be together.
  
* My modem dials, and connects to, but somehowe it doesn't seem, like
  I'm connected, after some time, the modem just hangs up.
- You are an AOL user, you can't connect to AOL using linux, since AOL
  doesn't support PPP (for no obvious reason, they use some proprietary
  protocoll). Solution : Get yourself a REAL internet account, this is 
  also a good way to avoid getting the lamer flag set by other online
  folks ;>
  
- This is an indicator of a failed authentication, check if your 
  loginname and password is correct. This shouldn't happen, if your
  ISP uses PAP (as mine does, and it works here ;) ), so either 
  the dialerscriptdoesn't work correctly, or your ISP uses CHAP,
  in the last case, email me (as I don't know what to do about
  it right now). In the first case check the following :
  a) is /etc/ppp/dialer linked to /etc/ppp/dialer.normal ?
  b) grab yourself minicom and dial your providers number, check,
     if the challenge and response strings in the dialerscript match
     what you see on the screen (though I can't imagine, the won't)

          
* It seems like the link is established, but I can't can't connect to
  any (web,ftp,..)server
- Solution 
  a) you forgot the proxy entry in your browser, some ISPs require 
     this for securitty and performance reasons.
  b) you forgot to put 
     nameserver 141.99.2.2
     in your /etc/resolv.conf, otherwise you'll be unable to resolve
     domainnames into IP number (please use your ISP's DNS, instead
     of the DNS of the University of Siegen ;)). You can still surf
     using IP numbers only ;). 
      
   
7. TO-DO

- Better documentation (write me an email, if you have an understanding  
  problem with this one). Parts of this writing is quite outdated, and
  applies to earlier versions, sorry. For more actual info, you should also
  read the ABOUT files, as well as the comments in the scripts.
- Add more services (if you made some spiffy service, which you think the
  world can't do without, send it to me).
- Write a cgi interface, so the link can be started within a web browser
- write a setup shell script
- make some services a bit smarter