Fix bug in handling return value from decompress routine.
[ppp.git] / 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.