SETUP

   1                 Setting up a PPP link.
   2
   3 Setting up a PPP link between two machines involves several steps:
   4
   5 1. Prepare both of the machines which are to be connected:
   6    1A. Make and install the pppd, pppstats and chat programs.
   7    1B. Install the ppp driver in the kernel.
   8 The README.* files give details on this step.
   9
  10 2. Decide on the IP addresses to be used and the level of
  11 authentication required by each machine, and set up the /etc/ppp
  12 directories accordingly.
  13
  14 3. Set up the serial link between the two machines and run pppd on
  15 each machine.  The two pppd's then negotiate and set up the link.
  16
  17 Step 1 is described in the system-specific README.* files.  The
  18 remaining steps are described below.  Steps 1 and 2 need only be done
  19 once; step 3 is done each time the link is to be established.
  20
  21
  22 Choosing IP addresses.
  23
  24 If a host is already connected to the Internet via a LAN such as
  25 Ethernet, then it will already have at least one IP address assigned,
  26 which will usually be the IP address of the LAN interface.  In such
  27 cases, it is usually most convenient to use that address as the local
  28 IP address of the PPP interface(s) on that host.  This is OK because
  29 the PPP interface(s) are point-to-point interfaces.
  30
  31 If a host is not connected to the Internet, then an IP address needs
  32 to be assigned for it.  If PPP is to be used to link it to another
  33 host which is connected to the Internet, is is usually most convenient
  34 to assign it an address on the same subnet as the remote host.  If the
  35 other host is not connected to the Internet either, then the choice of
  36 IP addresses is quite arbitrary.
  37
  38 Authentication.
  39
  40 The level of authentication required depends on the situation, but
  41 generally hosts which are connected to the Internet via a LAN should
  42 be set up to (a) require the remote host to authenticate itself, and
  43 (b) restrict the remote host's choice of IP address, based on its
  44 identity.  Otherwise the possibility exists for a remote host to
  45 impersonate another host on the local subnet.  (However, when you are
  46 first installing PPP, it is probably easier to leave authentication
  47 disabled until you get to the point where you can successfully
  48 establish a link.)
  49
  50 Setting up /etc/ppp.
  51
  52 The /etc/ppp directory contains various files used by pppd; it should
  53 be created by the system administrator when installing PPP.  It would
  54 typically contain the following files:
  55
  56     chap-secrets        Secrets used for authenticating with CHAP
  57     pap-secrets         Secrets used for authenticating with PAP
  58     options             Options that the system administrator wants to
  59                         apply whenever pppd is run
  60
  61 Since this directory contains files of secrets used for
  62 authentication, it should not be in a partition which is accessible
  63 from other hosts (e.g., exported by NFS).
  64
  65 The `options' file contains any options which the system administrator
  66 wants pppd to use whenever it is run.  If authentication is to be
  67 required, this should contain the `auth' and `usehostname' options.
  68 If the /etc/ppp/options file does not exist, or is not readable by
  69 pppd, it will refuse to run.
  70
  71 Secrets for PAP (Password Authentication Protocol) authentication are
  72 stored in /etc/ppp/pap-secrets; secrets for CHAP (Cryptographic
  73 Authentication Protocol) are stored in /etc/ppp/chap-secrets.  These
  74 files have the same format, and store secrets both for authenticating
  75 other hosts, and for authenticating this host to others.  The format
  76 is that there are 3 or more words per line, which are:
  77
  78         client - name of the machine to be authenticated
  79         server - name of the machine requiring the authentication
  80         secret - password or CHAP secret known by both client and server
  81         IP addresses - zero or more IP addresses which the client may
  82                 use (this field is only used on the server).
  83
  84 For example, if a LAN-connected host called "worksun" is to require
  85 authentication, and a host "bsdbox" is to connect to it and
  86 authenticate itself using CHAP, then both machines should have a
  87 /etc/ppp/chap-secrets file, which should contain a line something
  88 like:
  89
  90         bsdbox  worksun "an unguessable secret" bsdbox.my.domain
  91
  92 Setting up syslog.
  93
  94 pppd issues messages using syslog facility daemon (or local2 if it has
  95 been compiled with debugging enabled); chat uses facility local2.  It
  96 is useful to see messages of priority notice or higher on the console.
  97 To see these, find the line in /etc/syslog.conf which has /dev/console
  98 on the right-hand side, and add `daemon.notice' on the left.  This
  99 line should end up something like this:
 100
 101 *.err;kern.debug;daemon,local2,auth.notice;mail.crit    /dev/console
 102
 103 If you want to see more messages from pppd, request messages of
 104 priority info or higher for facility daemon, like this:
 105
 106 *.err;kern.debug;daemon.info;local2,auth.notice;mail.crit  /dev/console
 107
 108 It is also useful to add a line like this:
 109
 110 daemon,local2.debug             /etc/ppp/ppp-log
 111
 112 If you do this, you will need to create an empty /etc/ppp/ppp-log
 113 file.
 114
 115 After modifying syslog.conf, you will then need to send a HUP signal
 116 to syslogd (or reboot).
 117
 118
 119 Setting up a PPP link.
 120
 121 Establishing a PPP connection between two machines basically involves
 122 setting up a serial link and running pppd on both ends of the link.
 123 How this is done depends on the nature of the serial link, which may
 124 be as simple as a null modem cable between two machines, or it may
 125 involve modems, terminal servers, telnet sessions, etc.  The `chat'
 126 program is very useful in setting up the serial link because it
 127 enables you to automate any dialog which may be required, e.g.,
 128 logging in to the remote machine with a username and password, issuing
 129 a command to start ppp on the remote machine, etc.  As an example,
 130 the link could be started by issuing a command like
 131
 132         pppd /dev/ttya 38400 connect 'chat -f /etc/ppp/chat-script'
 133
 134 where the file /etc/ppp/chat-script contains
 135
 136         "" atdt2135476
 137         login: myname
 138         Password: "\qmypassword"
 139         "$ " "\qpppd"
 140
 141 The words in this script are alternately strings to look for and
 142 strings to send.  In this example, we start by sending a dial command
 143 to the modem; then we look for "login:", send "myname", look for
 144 "Password:", send "mypassword" (the "\q" prevents chat from logging it
 145 when you use the -v option), look for "$ " (the end of the shell
 146 prompt) and send "pppd" to start up ppp on the remote machine (the
 147 "\q" cancels the effect of the previous "\q").
 148
 149 In another scenario, you could establish the serial link manually,
 150 e.g. using Kermit to dial out, log into the remote machine, and issue
 151 the commands to start ppp there.  Then you have to exit Kermit without
 152 having the modem hang up, and then start pppd locally, using a command
 153 like this:
 154
 155         pppd /dev/ttya 38400
 156
 157 When a device is given, as in this command line, pppd will put itself
 158 in the background.  The two pppd's should then negotiate and bring up
 159 the link.  If you have edited /etc/syslog.conf as described above, you
 160 will see messages from pppd giving the local and remote IP addresses
 161 of the link when it is successfully established.
 162
 163 If the local machine has no other connection to the Internet, you can
 164 ask pppd to add a default route via the remote host by adding the
 165 `defaultroute' option to the pppd command.
 166
 167 N.B. When you run pppd on the remote machine, you usually want it to
 168 use the tty device where you logged in.  In this case, do not give a
 169 device name to pppd; it uses the controlling tty by default.  This may
 170 be a pty, e.g., if the serial link contains a telnet session, except
 171 under Ultrix (pppd will not run on a pty under Ultrix, due to the pty
 172 driver not passing ioctls to the ppp line discipline code).
 173
 174 If the remote machine is connected to the Internet via a LAN, it is
 175 often useful to add the `proxyarp' option.  The `asyncmap' option is
 176 also useful if the serial line is not completely transparent;
 177 `asyncmap 200a0000' is appropriate if the serial link includes a
 178 telnet.
 179
 180 Some people find it convenient to set up a `ppp' username on the
 181 remote machine, with no password, and a shell script which runs pppd
 182 as its login shell.
 183
 184 Other random points about running pppd:
 185         - If you want the local address of the PPP link to be
 186           different from the (first) IP address of the host, you need
 187           to put the desired address on the pppd command line with a
 188           colon appended.
 189         - The performance will probably be better if you reduce the
 190           MRU (maximum receive unit) on both ends; 296 is a good
 191           value.  To do this, use the option `mru 296'.
 192         - You DO NOT need to use ifconfig to configure the addresses
 193           of the ppp interface.  Pppd does all the necessary work
 194           (assigning addresses, marking the interface up, etc.).
 195
 196
 197 Terminating the PPP link.
 198
 199 When you wish terminate the PPP link, you should send a TERM or INTR
 200 signal to one of the pppd's, e.g., with a command like:
 201
 202         kill `cat /etc/ppp/ppp0.pid`
 203
 204 on SunOS or Ultrix, or
 205
 206         kill `cat /var/run/ppp0.pid`
 207
 208 on {386,Net,Free}BSD.
 209
 210 That pppd will inform the other pppd to terminate, and they will both
 211 clean up and exit.
 212
 213 If pppd is attached to a hardware serial port connected to a modem,
 214 then it should get a HUP signal when the modem hangs up, which will
 215 cause it to clean up and exit.  Whether it does or not depends on the
 216 driver, and on Suns, on the setting of the `tty soft carrier' flag,
 217 which is manipulated by the /usr/etc/ttysoftcar program (see
 218 ttysoftcar(8)).
 219
 220
 221 Debugging.
 222
 223 If the link comes up successfully, you should see messages logged to
 224 the console like "Local IP address:  xx.xx.xx.xx" and "Remote IP
 225 address: yy.yy.yy.yy" (assuming you've edited /etc/syslog.conf as
 226 described above).  If the link doesn't come up, it could be due to any
 227 of several factors:
 228
 229 - Perhaps the serial connection is not being set up successfully, or
 230 you haven't succeeded in getting ppp running on the remote machine.
 231 You can use the -v flag to chat; it will then log the characters it
 232 sends and receives (using syslog with facility `local2' and level
 233 `debug').
 234
 235 - Perhaps the PPP negotiation with the peer is failing.  You can use
 236 the `debug' option to pppd; it will then log the contents of all
 237 control packets sent and received (using syslog with facility `daemon'
 238 and level `debug').
 239
 240 In some cases, the link will come up successfully, but you may then be
 241 unable to use network-based applications over the link.  This usually
 242 indicates an IP-address assignment problem or a routing problem.  Or
 243 you may be able to communicate with the peer machine but not any
 244 machine beyond that.  Typically this is a routing problem.  For the
 245 common case where the local machine is only connected to the Internet
 246 via the peer, this problem can usually be solved if you:
 247         - assign the local machine an IP address on the same subnet
 248           as the remote machine
 249         - use the `defaultroute' option on the local pppd
 250         - use the `proxyarp' option on the remote pppd.
 251
 252 For solving routing and network problems, the ifconfig, netstat -i,
 253 netstat -r, ping and traceroute commands are useful.