wvdial/README

   1
   2 Welcome to WvDial
   3 =================
   4
   5 It's amazing!  It's your wildest dream come true!  Dialup networking for
   6 Linux that doesn't require chat scripts!
   7
   8 Okay, so maybe you're not as excited as I am, but we hope this will brighten
   9 up your week.  WvDial attempts to make the previously rather complicated
  10 configuration of Linux dial-up networking as simple as
  11 phone number - username - password.
  12
  13 But first there is something we should tell you:
  14
  15 The GNU Library General Public License
  16 ======================================
  17
  18 WvDial was originally written by Dave Coombs and Avery Pennarun of Net
  19 Integration Technologies, and is released to the public under the terms of
  20 GNU's LGPL, or Library General Public License.
  21
  22 This is not quite the same as the General Public License (GPL) that most
  23 Linux software uses.  The LGPL is actually *less* restrictive -- you can use
  24 LGPL software inside your own programs, and you are *not* required to place
  25 your program under the GPL or LGPL.  That means companies or individuals
  26 can, if they want, take all the code in WvDial and use it in a product
  27 without giving anyone their own source code.
  28
  29 But there's a catch, of course -- basically, you have to make the source
  30 code to WvDial itself available to users, and if you *change* the WvDial
  31 code in any way, you must also release the changes under the terms of the
  32 LGPL.  That means you have to give out the source code to your changes.
  33 That also means that we or anyone can build a product based on the modified
  34 WvDial, and although the source code to WvDial must be provided, the rest of
  35 the system does not have to be (L)GPL'd.
  36
  37 We think that this is a fair way to share this software, because it
  38 guarantees that everyone can fix bugs and when anyone does, everyone can get
  39 the patch.  But still, people can build small Linux systems based on WvDial
  40 without having to give out the source code to their *entire* main program.
  41
  42 Naturally none of that is legally binding.  The nice people at GNU have
  43 prepared the legalese already and you can find their license verbatim in the
  44 file COPYING.LIB or, if you installed the Debian package,
  45 /usr/doc/copyright/LGPL.  Please read it carefully before distributing (or
  46 worse, not distributing) modified copies of WvDial, because the rules aren't
  47 quite as simple as I've made them sound.
  48
  49
  50 Compiling and Installing WvDial
  51 ===============================
  52
  53 If you are not using our pre-compiled Debian package, you will need to
  54 compile WvDial yourself.  This is not too difficult as long as you have a
  55 few things installed on your Linux system:
  56
  57         - pppd 2.2.0f or 2.3.5, with the pppd program preferably
  58                 at /usr/sbin/pppd.
  59
  60         - gcc 2.7.2 or higher, with g++.
  61
  62         - GNU make; you may need version 3.75 or higher, I'm not sure.
  63
  64         - WvStreams; version 4.4 or higher.
  65
  66 Almost any halfway modern Linux system should have all of these. The last is
  67 available from http://alumnit.ca/wiki/index.php?page=DownloadReleases
  68
  69 Building WvDial is a simple matter.  First, check the Makefile to see if
  70 everything looks okay to you.  By default, wvdial and wvdialconf will
  71 install in /usr/local/bin with their man pages in /usr/local/man/man1.
  72 That's probably right for most systems.
  73
  74 To build and install WvDial, then:
  75         make
  76         make install
  77
  78 Assuming you don't have any compile errors (and really, you shouldn't,
  79 right?) you now have an installed WvDial system.
  80
  81
  82 Configuring for the First Time
  83 ==============================
  84
  85 Again Debian users have a nice soft fuzzy warm cushion to land on: when
  86 installing the WvDial package, Debian's "dpkg" automatically runs wvdialconf
  87 and asks all the right questions to get you going.
  88
  89 If you compiled manually, you have to go through a little bit more trouble
  90 -- but don't worry, not that much.
  91
  92 The first thing to do is have wvdialconf detect your modem and create your
  93 initial configuration.  'su' to root and type the following:
  94         wvdialconf /etc/wvdial.conf
  95
  96 If all goes well, your modem will be detected and its configuration stored
  97 in /etc/wvdial.conf.  If it doesn't work, all is not lost but you will have
  98 to build the configuration completely by yourself.  Read the wvdial(1) man
  99 page ("man wvdial") for more information about that.
 100
 101 In any case, if your modem is not detected or the detection sequence
 102 confuses you in some way, let us know by sending us a message -- this is
 103 supposed to be a stable release, but everybody knows that doesn't really mean
 104 anything.  Things could still go wrong, and we really want to know if they do.
 105 Remember, if we don't know there's a problem, we can't fix it.
 106
 107 On my computer the modem detection sequence looks like this:
 108
 109         Scanning your serial ports for a modem.
 110
 111         modemscan<Info>: Ignoring ttyS0 because /dev/mouse is a link to it.
 112         ttyS1<*1>: AT -- AT -- AT -- nothing.
 113         ttyS2<*1>: AT -- OK
 114         ttyS2<*1>: ATZ -- OK
 115         ttyS2<*1>: ATQ0 -- OK
 116         ttyS2<*1>: ATQ0 V1 -- OK
 117         ttyS2<*1>: ATQ0 V1 E1 -- OK
 118                 [more init string testing]
 119         ttyS2<*1>: Speed 2400: AT -- OK
 120         ttyS2<*1>: Speed 4800: AT -- OK
 121                 [more baud rate testing]
 122         ttyS2<*1>: Speed 230400: AT -- AT
 123         ttyS2<*1>: Max speed is 115200; using 57600 to be safe.
 124         ttyS2<*1>: ATQ0 V1 E1 S0=0 &C1 &D2 S11=55 -- OK
 125
 126         Found 1 available modem; using /dev/ttyS2.
 127         ttyS2<Info>: Speed 57600; init "ATQ0 V1 E1 S0=0 &C1 &D2 S11=55"
 128
 129 wvdialconf will scan all your /dev/ttyS* serial ports *except* the
 130 /dev/mouse port (if you have a /dev/mouse link) because sometimes probing
 131 the mouse port can cause mouse problems.  In any case, try not to move your
 132 mouse while wvdialconf is probing and you should be safe.
 133
 134 After wvdialconf runs successfully (ie., you receive a message like the one
 135 above) it writes your configuration to /etc/wvdial.conf, the filename you
 136 gave it on the command line.  My auto-generated wvdial.conf file looks like
 137 this:
 138
 139         [Dialer Defaults]
 140         Modem = /dev/ttyS2
 141         Baud = 57600
 142         Init = ATZ
 143         Init2 = ATQ0 V1 E1 S0=0 &C1 &D2 S11=55
 144         ; Phone = <Target Phone Number>
 145         ; Username = <Your Login Name>
 146         ; Password = <Your Password>
 147
 148 After [Dialer Defaults], the first four lines have been autodetected for
 149 your system, so don't worry if they look a little different.
 150
 151 The next three lines are commented out.  You need to edit the file to fill
 152 in the information about your Internet provider.  Here's a sample completed
 153 wvdial.conf file:
 154
 155         [Dialer Defaults]
 156         Modem = /dev/ttyS2
 157         Baud = 57600
 158         Init = ATZ
 159         Init2 = ATQ0 V1 E1 S0=0 &C1 &D2 S11=55
 160         Phone = 555-4242
 161         Username = apenwarr
 162         Password = my-password
 163
 164 This contains all the information needed to dial my favourite non-existent
 165 Internet provider.
 166
 167 If you use more than one modem, dial-in account, Internet provider, init
 168 string, or anything, you can use additional "override" sections in
 169 wvdial.conf to support this.  See the wvdial(1) man page for more
 170 information.  (Type "man wvdial")
 171
 172
 173 Testing it for the First Time
 174 =============================
 175
 176 Now you've compiled, installed, and configured WvDial.  Doesn't that make
 177 you mad at all the darn Debian users who didn't have to do any of this
 178 stuff?  Well, now you've caught up with them.  Sooner or later, everyone has
 179 to try dialing for the first time.
 180
 181 To do this, type
 182         wvdial
 183 (surprise!).
 184
 185 Unlike other ppp dialers you might have used, the wvdial program runs in the
 186 foreground and never exits until you disconnect or have some kind of fatal
 187 error.  You can also quit (and disconnect the phone, and clean up politely)
 188 by pressing CTRL-C.  I think this is more user-friendly, myself.  Of course
 189 if you want it to work like pppd you can always do it in the usual way:
 190
 191         wvdial >/var/log/wvdial.log 2>&1 &
 192
 193 It is interesting to note that almost all of WvDial's functionality is found
 194 in a C++ class called WvDialer.  That means it's easy for a programmer to
 195 take WvDial and put in whatever kind of user interface he wants.  The
 196 "wvdial" program serves as a simple example.  So with WvDial, if someone
 197 (say) wanted to write an X-Windows dialup button bar, they could simply link
 198 in the C++ class and not have to worry about messy interactions with
 199 self-backgrounding pppd scripts and other gruesome stuff.
 200
 201 Anyway, if you have any gripes about the way this works, let us know.
 202 The more stuff you complain about, the more likely we are to do something
 203 about it.
 204
 205
 206 Assuming it Worked...
 207 =====================
 208
 209 If you ran wvdial and it connected to and logged into your Internet
 210 provider, you're in business.  If it said anything strange or confusing
 211 along the way, e-mail us anyway -- it could be the sign of a nasty problem
 212 hiding somewhere.
 213
 214
 215 Nah, it Didn't Work After All
 216 =============================
 217
 218 Because WvDial has a pretty nasty bunch of heuristics included for dialing
 219 modems, finding login/password prompts, guessing at menu options and command
 220 prompts, and so on, it has been known to screw up on occasion.  If WvDial
 221 doesn't quite work for you, it's probably our fault, not yours!  It's
 222 difficult for us to guess typical login sequences for various ISP's, and
 223 it's completely impossible for us to guess them all.  If WvDial doesn't seem
 224 to like your ISP, I've got some good news and some bad news for you.
 225
 226 The bad news about WvDial versus 'chat' scripts:  if your chat script
 227 doesn't work, you can always fix it without doing any programming.  WvDial
 228 uses built-in intelligence, but if its intelligence fails, you're out of
 229 luck.
 230
 231 And now the good news: Let us know about the problem and we'll do our best to
 232 help.  If we can do it, we want WvDial to work with nearly every ISP around,
 233 without any special configuration.
 234
 235 The most useful thing you can do for us is create a complete transcript
 236 of your wvdial session:
 237         wvdial 2>&1 | tee wvdial.out
 238
 239 Then send the wvdial.out file to us along with your comments.  Similarly,
 240 if the problem is during the modem detection phase (ALL modems should be
 241 detected successfully in a working wvdialconf!) you can get a transcript
 242 like this:
 243         wvdialconf /dev/null 2>&1 | tee wvdialconf.out
 244
 245 And send us wvdialconf.out.
 246
 247
 248 Concluding Notes
 249 ================
 250
 251 WvDial has support for switching easily between multiple Internet accounts:
 252 read the wvdial(1) man page for more information.
 253
 254 For that matter, it would do you well to read the wvdial(1) and
 255 wvdialconf(1) man pages anyway. (Oh, and don't forget about wvdial.conf(5)
 256 too!)
 257
 258 Even though this is supposed to be a stable release, there may still be bugs
 259 in this thing.  Tell us about them, every last one.  For up-to-date contact
 260 information, see the WvDial web page at:
 261
 262                 http://alumnit.ca/wiki/index.php?page=WvDial
 263
 264 ...have fun with it!
 265
 266 Remember:
 267         It's only big and scary looking if you look too closely.