summaryrefslogtreecommitdiffstats
path: root/usr.sbin/ppp/ppp.8
blob: 2c4a1d163761dfee86f6bc29df10a4868a5443fe (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
.\" manual page [] for ppp 0.94 beta2 + alpha
.\" $Id: ppp.8,v 1.17 1996/05/11 20:48:40 phk Exp $
.Dd 20 September 1995
.Os FreeBSD
.Dt PPP 8
.Sh NAME
.Nm ppp
.Nd
Point to Point Protocol (aka iijppp) 
.Sh SYNOPSIS
.Nm
.Op Fl auto | Fl direct | Fl dedicated
.Op Ar system
.Sh DESCRIPTION
This is a user process
.Em PPP
software package.  Normally,
.Em PPP
is implemented as a part of the kernel (e.g. as managed by pppd) and it's
thus somewhat hard to debug and/or modify its behavior.  However, in this
implementation
.Em PPP
is done as a user process with the help of the
tunnel device driver (tun).

.Sh Major Features

.Bl -diag
.It Provides interactive user interface.
Using its command mode, the user can
easily enter commands to establish the connection with the remote end, check
the status of connection and close the connection.  All functions can
also be optionally password protected for security.

.It Supports both manual and automatic dialing. 
Interactive mode has a
.Dq term
command which enables you to talk to your modem directly.  When your
modem is connected to the remote peer and it starts to talk
.Em PPP
, the
.Em PPP
software detects it and switches to packet
mode automatically. Once you have determined the proper sequence for connecting
with the remote host, you can write a chat script to define the necessary
dialing and login procedure for later convenience.

.It Supports on-demand dialup capability.
By using auto mode,
.Nm
will act as a daemon and wait for a packet to be sent over the
.Em PPP
link.  When this happens, the daemon automatically dials and establishes the
connection.

.It Supports server-side PPP connections.
Can act as server which accepts incoming
.Em PPP
connections. 
 
.It Supports PAP and CHAP authentication.

.It Supports Proxy Arp.
When
.Em PPP
is set up as server, you can also configure it to do proxy arp for your
connection.

.It Supports packet filtering.
User can define four kinds of filters:
.Em ifilter
for incoming packets, 
.Em ofilter
for outgoing packets,
.Em dfilter
to define a dialing trigger packet and
.Em afilter
for keeping a connection alive with the trigger packet.

.It Tunnel driver supports bpf.
The user can use
.Xr tcpdump 1
to check the packet flow over the
.Em PPP
link.

.It Supports PPP over TCP capability. 


.It Supports IETF draft Predictor-1 compression.  
.Nm
supports not only VJ-compression but also Predictor-1 compression.
Normally, a modem has built-in compression (e.g. v42.bis) and the system
may receive higher data rates from it as a result of such compression. 
While this is generally a good thing in most other situations, this
higher speed data imposes a penalty on the system by increasing the
number of serial interrupts the system has to process in talking to the
modem and also increases latency.  Unlike VJ-compression, Predictor-1
compression pre-compresses
.Em all
data flowing through the link, thus reducing overhead to a minimum.

.It Supports Microsofts IPCP extentions.
Name Server Addresses and NetBIOS Name Server Addresses can be negotiated
with clients using the Microsoft
.Em PPP
stack (ie. Win95, WinNT)

.It Runs under BSDI-1.1 and FreeBSD.

.El


Patches for NeXTSTEP 3.2 are also available on the net.

.Sh GETTING STARTED

When you first run
.Nm
you may need to deal with some initial configuration details.  First,
your kernel should include a tunnel device (the default in FreeBSD 2.0.5
and later). If it doesn't, you'll need to rebuild your kernel with the
following line in your kernel configuration file:

.Dl pseudo-device   tun             1

You should set the numeric field to the maximum number of 
.Em PPP
connections you wish to support.

Second, check your
.Pa /dev
directory for the tunnel device entry
.Pa /dev/tun0.
If it doesn't exist, you can create it by running "MAKEDEV tun0"

.Sh MANUAL DIALING

% 
.Nm
User Process PPP written by Toshiharu OHNO.

* If you set your hostname and password in
.Pa /etc/ppp/ppp.secret,
you can't do
anything except run the quit and help commands *

ppp on "your hostname"> help
  passwd  : Password for security
  quit    : Quit the PPP program    
  help    : Display this message

ppp on tama> pass <password>

* "on" will change to "ON" if you specify the correct password. *

ppp ON tama>

* You can specify the device name and speed for your modem using the
following commands: *

ppp ON tama> set line /dev/cuaa0

ppp ON tama> set speed 38400

ppp ON tama> set parity even

ppp ON tama> show modem

* Modem related parameters are shown in here *

ppp ON tama>

* Use term command to talk with your modem *

ppp ON tama> term
 at
 OK
 atdt123456
 CONNECT

 login: ppp
 Password:

* PPP started in remote side.  When the peer start to talk PPP, the
program will detect it automatically and return to command mode. *

ppp ON tama>

.Nm PPP
ON tama>

* NOW, you are connected!  Note that
.Sq PPP
in the prompt has changed to capital letters to indicate this. *

PPP ON tama> show lcp

* You'll see LCP status *

PPP ON tama> show ipcp

* You'll see IPCP status.  At this point, your machine has a host route
to the peer. If you want to add a default route entry, then enter the
following command. *

PPP ON tama> add 0 0 HISADDR

* The string
.Sq HISADDR
represents the IP address of connected peer. *

PPP ON tama>

* Use network applications (i.e. ping, telnet, ftp) in other windows *

PPP ON tama> show log

* Gives you some logging messages *

PPP ON tama> close

* The connection is closed and modem will be disconnected. *

ppp ON tama> quit

%

.Sh AUTOMATIC DIALING

To use automatic dialing, you must prepare some Dial and Login chat scripts.
See the example definitions in
.Pa /etc/ppp/ppp.conf.sample
(the format of ppp.conf is pretty simple).

.Bl -bullet -compact
.It
Each line contains one command, label or comment.
.It
A line starting with a
.Sq #
character is treated as a comment line.
.It
A label name has to start in the first column and should be followed by
a colon (:).
.It
A command line must contain a space or tab in the first column.
.El

Once ppp.conf is ready, specify the destination label name when you
invoke
.Nm ppp .
Commands associated with the destination label are then
executed. Note that the commands associated with the
.Dq default
label are ALWAYS executed.

Once the connection is made, you'll find that the
.Nm ppp
portion of the prompt has changed to
.Nm PPP .

   % ppp pm2
   ...
   ppp ON tama> dial
   dial OK!
   login OK!
   PPP ON tama>

If the
.Pa /etc/ppp/ppp.linkup
file is available, its contents are executed
when the
.Em PPP
connection is established.  See the provided example which adds a
default route.  The string HISADDR represents the IP address of the
remote peer.

.Sh DIAL ON DEMAND

To play with demand dialing, you must use the
.Fl auto
option.  You must also specify the destination label in
.Pa /etc/ppp/ppp.conf
to use.  It should contain the
.Dq ifaddr
command to define the remote peer's IP address. (refer to
.Pa /etc/ppp/ppp.conf.sample )

   % ppp -auto pm2demand
   ...
   %

When
.Fl auto
is specified,
.Nm
runs as a daemon but you can still configure or examine its
configuration by using the diagnostic port as follows:


  % telnet localhost 3000
    Trying 127.0.0.1...
    Connected to localhost.spec.co.jp.
    Escape character is '^]'.
    User Process PPP. Written by Toshiharu OHNO.
    Working as auto mode. 
    PPP on tama> show ipcp
    what ?
    PPP on tama> pass xxxx
    PPP ON tama> show ipcp
    IPCP [OPEND]
      his side: xxxx
      ....

.Pp
Each
.Nm
daemon has an associated port number which is computed as "3000 +
tunnel_device_number". If 3000 is not good base number, edit defs.h in
the ppp sources (
.Pa /usr/src/usr.sbin/ppp )
and recompile it.

When an outgoing packet is detected,
.Nm
will perform the dialing action (chat script) and try to connect
with the peer.

If the connect fails, the default behavior is to wait 30 seconds
and then attempt to connect when another outgoing packet is detected.
This behavior can be changed with
.Bd -literal -offset indent
set redial seconds|random [dial_attempts]
.Ed
.Pp
Seconds is the number of seconds to wait before attempting
to connect again. If the argument is
.Sq random ,
the delay period is a random value between 0 and 30 seconds.
.Sq dial_attempts
is the number of times to try to connect for each outgoing packet
that is received. The previous value is unchanged if this parameter
is omitted.
.Bd -literal -offset indent
set redial 10 4
.Ed
.Pp
will attempt to connect 4 times for each outgoing packet that is
detected with a 10 second delay between each attempt.

Modifying the dial delay is very useful when running
.Nm
in demand
dial mode on both ends of the link. If each end has the same timeout,
both ends wind up calling each other at the same time if the link
drops and both ends have packets queued.

 To terminate the program, type

  PPP ON tama> close
  ppp ON tama> quit all

.Pp
A simple
.Dq quit
command will terminate the telnet connection but not the program itself.
You must use
.Dq quit all
to terminate the program as well.

.Sh PACKET FILTERING

This implementation supports packet filtering. There are three kinds of
filters: ifilter, ofilter and dfilter.  Here are the basics:

.Bl -bullet -compact
.It
A filter definition has the following syntax:

set filter-name rule-no action [src_addr/src_width] [dst_addr/dst_width]
[proto [src [lt|eq|gt] port ]] [dst [lt|eq|gt] port] [estab]
.Bl -enum
.It
.Sq filter-name
should be one of ifilter, ofilter, or dfilter.
.It
There are two actions: 
.Sq permit
and
.Sq deny .
If a given packet 
matches the rule, the associated action is taken immediately.
.It
.Sq src_width
and
.Sq dst_width
work like a netmask to represent an address range.
.It
.Sq proto
must be one of icmp, udp or tcp.
.It
.Sq port number
can be specified by number and service name from
.Pa /etc/services .

.El

.It
Each filter can hold up to 20 rules, starting from rule 0.

The entire rule set is not effective until rule 0 is defined.

.It
If no rule is matched to a packet, that packet will be discarded
(blocked).

.It
Use
.Dq set filter-name -1
to flush all rules.

.El

See
.Pa /etc/ppp/ppp.conf.filter.example .


.Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1)

To handle an incoming
.Em PPP
connection request, follow these steps:

.Bl -enum
.It 
Make sure the modem and (optionally)
.Pa /etc/rc.serial
is configured correctly.
.Bl -bullet -compact
.It
Use Hardware Handshake (CTS/RTS) for flow control.
.It
Modem should be set to NO echo back (ATE0) and NO results string (ATQ1).
.El

.It
Edit
.Pa /etc/ttys
to enable a getty on the port where the modem is attached.

For example:

.Dl ttyd1  "/usr/libexec/getty std.38400" dialup on secure

Don't forget to send a HUP signal to the init process to start the getty.

.Dl # kill -HUP 1

.It
Prepare an account for the incoming user.
.Bd -literal
ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin
.Ed

.It
Create a 
.Pa /usr/local/bin/ppplogin
file with the following contents:
.Bd -literal -offset indent
#!/bin/sh
/usr/sbin/ppp -direct
.Ed

(You can specify a label name for further control.)

.Pp
Direct mode (
.Fl direct )
lets
.Nm
work with stdin and stdout.  You can also telnet to port 3000 to get
command mode control in the same manner as client-side
.Nm.

.It
Optional support for Microsoft's IPCP Name Server and NetBIOS
Name Server negotiation can be enabled use
.Dq enable msext
and 
.Dq set ns pri-addr [sec-addr]
along with
.Dq set nbns pri-addr [sec-addr]
in your ppp.conf file

.El

.Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2)

This method differs in that it recommends the use of 
.Em mgetty+sendfax
to handle the modem connections.  The latest version 0.99
can be compiled with the
.Dq AUTO_PPP
option to allow detection of clients speaking PPP to the login
prompt.

Follow these steps:

.Bl -enum
.It
Get, configure, and install mgetty+sendfax v0.99 or later (beta)
making sure you have used the AUTO_PPP option.
.It
Edit
.Pa /etc/ttys
to enable a mgetty on the port where the modem is attached.

For example:

.Dl cuaa1  "/usr/local/sbin/mgetty -s 57600"       dialup on

.It
Prepare an account for the incoming user.
.Bd -literal
Pfred:xxxx:66:66:Fred's PPP:/home/ppp:/etc/ppp/ppp-dialup
.Ed

.It
Examine the files
.Pa /etc/ppp/sample.ppp-dialup
.Pa /etc/ppp/sample.ppp-pap-dialup
and
.Pa /etc/ppp/sample.ppp.conf
for ideas.   ppp-pap-dialup is supposed to be called from
.Pa /usr/local/etc/mgetty+sendfax/login.conf
from a line like

.Dl /AutoPPP/ -     -       /etc/ppp/ppp-pap-dialup

.Sh SETTING IDLE, LINE QUALITY REQUEST, RETRY TIMER

To check/set idletimer, use the
.Dq show timeout
and
.Dq set timeout [lqrtimer [retrytimer]]
commands.

 Ex:
.Dl ppp ON tama> set timeout 600

The timeout period is measured in seconds, the  default values for which
are timeout = 180 or 3 min, lqrtimer = 30sec and retrytimer = 3sec. 
To disable the idle timer function,
use the command
.Dq set timeout 0 .

In
.Fl auto
mode, an idle timeout causes the
.Em PPP
session to be
closed, though the
.Nm
program itself remains running.  Another trigger packet will cause it to
attempt to reestablish the link.

.Sh Predictor-1 compression

This version supports CCP and Predictor type 1 compression based on
the current IETF-draft specs. As a default behavior,
.Nm
will attempt to use (or be willing to accept) this capability when the
peer agrees (or requests it).

To disable CCP/predictor functionality completely, use the
.Dq disable pred1
and
.Dq deny pred1
commands.

.Sh Controlling IP address

.Nm
uses IPCP to negotiate IP addresses. Each side of the connection
specifies the IP address that it's willing to use, and if the requested
IP address is acceptable then
.Nm
returns ACK to the requester.  Otherwise, 
.Nm
returns NAK to suggest that the peer use a different IP address. When
both sides of the connection agree to accept the received request (and
send ACK), IPCP is set to the open state and a network level connection
is established.

To control this IPCP behavior, this implementation has the
.Dq set ifaddr
command for defining the local and remote IP address:

.Nm set ifaddr
.Op src_addr Op dst_addr Op netmask Op trg_addr

Where,
.Sq src_addr
is the IP address that the local side is willing to use and
.Sq dst_addr
is the IP address which the remote side should use.
.Sq netmask
is interface netmask.
.Sq trg_addr
is the IP address which used in address negotiation.

Ex:
.Dl set ifaddr 192.244.177.38 192.244.177.2 255.255.255.0

The above specification means:
.Bl -bullet -compact
.It
I strongly want to use 192.244.177.38 as my IP address, and I'll
disagree if the peer suggests that I use another address.

.It
I strongly insist that peer use 192.244.177.2 as own side address and
don't permit it to use any IP address but 192.244.177.2.  When peer
request another IP address, I always suggest that it use 192.244.177.2.

.It
My interface netmask will be 255.255.255.0.

.It
This is all fine when each side has a pre-determined IP address, however
it is often the case that one side is acting as a server which controls
all IP addresses and the other side should obey the direction from it. 
.El

In order to allow more flexible behavior, `ifaddr' variable allows the
user to specify IP address more loosely:

.Dl set ifaddr 192.244.177.38/24 192.244.177.2/20

A number followed by a slash (/) represent the number of bits significant in
the IP address.  The above example signifies that:

.Bl -bullet -compact
.It
I'd like to use 192.244.177.38 as my address if it is possible, but I'll
also accept any IP address between 192.244.177.0 and 192.244.177.255.

.It 
I'd like to make him use 192.244.177.2 as his own address, but I'll also
permit him to use any IP address between 192.244.176.0 and
192.244.191.255.

.It
As you may have already noticed, 192.244.177.2 is equivalent to saying
192.244.177.2/32.

.It
As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no
preferred IP address and will obey the remote peer's selection.

.It
192.244.177.2/0 means that I'll accept/permit any IP address but I'll
try to insist that 192.244.177.2 be used first.
.El

.Sh Connecting with your service provider

.Bl -enum
.It
Describe provider's phone number(s) in DialScript: Use the
.Dq set dial
or
.Dq set phone
commands.
.Dq Set phone
command allows you to set multiply phone numbers for dialing and redialing
separated by a colon (:).
.It
Describe login procedure in LoginScript: Use the
.Dq set login
command.
.It
Use
.Dq set ifaddr
command to define the IP address.
.Bl -bullet
.It
If you know what IP address provider uses, then use it as the remote address.
.It
If provider has assigned a particular IP address to you, then use it as
your address.
.It
If provider assigns your address dynamically, use 0 as your address.
.It
If you have no idea which IP addresses to use, then try
.Dq set ifaddr 0 0 .
.El
.It
If provider requests that you use PAP/CHAP authentication methods, add
the next lines to your
.Pa ppp.conf
file:
.Bd -literal -offset indent
enable pap (or enable chap)
disable chap (or disable pap)
set authname MyName
set authkey MyPassword
.Ed
.El

Please refer to
.Pa /etc/ppp/ppp.conf.iij
for some real examples.

.Sh Logging facility

.Nm
is able to generate the following log info into
.Pa /var/log/ppp.log :

.Bl -column SMMMMMM -offset indent -compat
.It Li Phase	Phase transition log output
.It Li Chat	Generate Chat script trace log
.It Li Connect	Generate complete Chat log
.It Li Carrier	Log Chat lines with 'CARRIER'
.It Li LQM	Generate LQR report
.It Li LCP	Generate LCP/IPCP packet trace
.It Li Link	Log address assignments and link up/down events
.It Li TCP/IP	Dump TCP/IP packet
.It Li HDLC	Dump HDLC packet in hex
.It Li Async	Dump async level packet in hex
.El

The
.Dq set debug
command allows you to set logging output level, of which
multiple levels can be specified.  The default is equivalent to
.Dq set debug carrier link phase .

.Sh MORE DETAILS

.Bl -bullet -compact
.It
Please read the Japanese doc for complete explanation. It may not be
useful for non-japanese readers,  but examples in the document may help
you to guess.

.It
Please read example configuration files.

.It
Use
.Dq help ,
.Dq show ? ,
.Dq set ?
and
.Dq set ? <var>
commands.

.It
NetBSD and BSDI-1.0 were supported in previous releases but are no
longer supported in this release.  Please contact the author if you need
old driver code.
.El

.Sh FILES
.Nm
refers to three files: ppp.conf, ppp.linkup and ppp.secret.
These files are placed in
.Pa /etc/ppp ,
but the user can create his own files under his $HOME directory as
.Pa .ppp.conf ,
.Pa .ppp.linkup
and
.Pa .ppp.secret.
.Nm
will always try to consult the user's personal setup first.

.Bl -tag -width flag
.Pa $HOME/ppp/.ppp.[conf|linkup|secret]
User dependent configuration files.

.Pa /etc/ppp/ppp.conf
System default configuration file.

.Pa /etc/ppp/ppp.secret
An authorization file for each system.

.Pa /etc/ppp/ppp.linkup
A file to check when
.Nm
establishes a network level connection.

.Pa /var/log/ppp.log
Logging and debugging information file.

.Pa /var/spool/lock/Lck..* 
tty port locking file.

.Pa /var/run/PPP.system
Holds the pid for ppp -auto system.

.Pa /etc/services
Get port number if port number is using service name.
.El
.Sh SEE ALSO
.Xr chat 8 ,
.Xr pppd 8
.Sh HISTORY
This program was submitted in FreeBSD-2.0.5 Atsushi Murai (amurai@spec.co.jp).

.Sh AUTHORS
Toshiharu OHNO (tony-o@iij.ad.jp)
OpenPOWER on IntegriCloud