1.\" $Id: ppp.8,v 1.69 1997/10/05 10:29:32 brian Exp $ 2.Dd 20 September 1995 3.Os FreeBSD 4.Dt PPP 8 5.Sh NAME 6.Nm ppp 7.Nd 8Point to Point Protocol (aka iijppp) 9.Sh SYNOPSIS 10.Nm 11.Op Fl auto | background | ddial | direct | dedicated 12.Op Fl alias 13.Op Ar system 14.Sh DESCRIPTION 15This is a user process 16.Em PPP 17software package. Normally, 18.Em PPP 19is implemented as a part of the kernel (e.g. as managed by pppd) and it's 20thus somewhat hard to debug and/or modify its behavior. However, in this 21implementation 22.Em PPP 23is done as a user process with the help of the 24tunnel device driver (tun). 25 26.Sh Major Features 27 28.Bl -diag 29.It Provides interactive user interface. 30Using its command mode, the user can 31easily enter commands to establish the connection with the remote end, check 32the status of connection and close the connection. All functions can 33also be optionally password protected for security. 34 35.It Supports both manual and automatic dialing. 36Interactive mode has a 37.Dq term 38command which enables you to talk to your modem directly. When your 39modem is connected to the remote peer and it starts to talk 40.Em PPP 41, the 42.Em PPP 43software detects it and switches to packet 44mode automatically. Once you have determined the proper sequence for connecting 45with the remote host, you can write a chat script to define the necessary 46dialing and login procedure for later convenience. 47 48.It Supports on-demand dialup capability. 49By using auto mode, 50.Nm 51will act as a daemon and wait for a packet to be sent over the 52.Em PPP 53link. When this happens, the daemon automatically dials and establishes the 54connection. 55 56In almost the same manner ddial mode (dedicated or daemon dialing) 57also automatically dials and establishes the connection. However, it 58differs in that it will dial the remote site any time it detects the 59link is down, even if there are no packets to be sent. This mode is 60useful for full-time connections who worry less about line charges 61and more about being connected full time. 62 63.It Supports packet aliasing. 64Packet aliasing, more commonly known as masquerading, allows computers 65on a private, unregistered network to access the internet. The 66.Em PPP 67host acts as a masquerading gateway. IP addresses as well as TCP and 68UDP port numbers are aliased for outgoing packets and de-aliased for 69returning packets. 70 71.It Supports background PPP connections. 72In background mode, if 73.Nm 74successfully establishes the connection, it will become a daemon. 75Otherwise, it will exit with an error. 76 77.It Supports server-side PPP connections. 78In direct mode, 79.nm 80acts as server which accepts incoming 81.Em PPP 82connections on stdin/stdout. 83 84.It Supports PAP and CHAP authentication. 85 86.It Supports Proxy Arp. 87When 88.Em PPP 89is set up as server, you can also configure it to do proxy arp for your 90connection. 91 92.It Supports packet filtering. 93User can define four kinds of filters: 94.Em ifilter 95for incoming packets, 96.Em ofilter 97for outgoing packets, 98.Em dfilter 99to define a dialing trigger packet and 100.Em afilter 101for keeping a connection alive with the trigger packet. 102 103.It Tunnel driver supports bpf. 104The user can use 105.Xr tcpdump 1 106to check the packet flow over the 107.Em PPP 108link. 109 110.It Supports PPP over TCP capability. 111 112 113.It Supports IETF draft Predictor-1 compression. 114.Nm 115supports not only VJ-compression but also Predictor-1 compression. 116Normally, a modem has built-in compression (e.g. v42.bis) and the system 117may receive higher data rates from it as a result of such compression. 118While this is generally a good thing in most other situations, this 119higher speed data imposes a penalty on the system by increasing the 120number of serial interrupts the system has to process in talking to the 121modem and also increases latency. Unlike VJ-compression, Predictor-1 122compression pre-compresses 123.Em all 124data flowing through the link, thus reducing overhead to a minimum. 125 126.It Supports Microsofts IPCP extensions. 127Name Server Addresses and NetBIOS Name Server Addresses can be negotiated 128with clients using the Microsoft 129.Em PPP 130stack (ie. Win95, WinNT) 131 132.Sh PERMISSIONS 133.Nm Ppp 134is installed as user 135.Dv root 136and group 137.Dv network , 138with permissions 139.Dv 4550 . 140.Nm Ppp 141will not execute in client mode if the invoking user id is not zero. 142.Nm Ppp 143will run in 144.Fl direct 145mode as a normal user, but due to its execution permissions, this user 146must be a member of group 147.Dv network . 148When running as a normal user, 149.Nm 150switches to user id 0 in order to alter the system routing table. All 151external commands (executed via the "shell" or "!bg" commands) are executed 152as the user id that invoked 153.Nm ppp . 154 155.Sh GETTING STARTED 156 157When you first run 158.Nm 159you may need to deal with some initial configuration details. First, 160your kernel should include a tunnel device (the GENERIC kernel includes 161one by default). If it doesn't, or if you require more than one tun 162interface, you'll need to rebuild your kernel with the following line in 163your kernel configuration file: 164 165.Dl pseudo-device tun N 166 167where 168.Ar N 169is the maximum number of 170.Em PPP 171connections you wish to support. 172 173Second, check your 174.Pa /dev 175directory for the tunnel device entries 176.Pa /dev/tunN , 177where 178.Ar N 179represents the number of the tun device, starting at zero. 180If they don't exist, you can create them by running "sh ./MAKEDEV tunN". 181This will create tun devices 0 through 182.Ar N . 183 184Last of all, create a log file. 185.Nm Ppp 186uses 187.Xr syslog 3 188to log information. A common log file name is 189.Pa /var/log/ppp.log . 190To make output go to this file, put the following lines in the 191.Pa /etc/syslog.conf 192file: 193 194.Dl !ppp 195.Dl *.*<TAB>/var/log/ppp.log 196 197Make sure you use actual TABs here. If you use spaces, the line will be 198silently ignored. 199 200It is possible to have more than one ppp log file by creating a link 201to the ppp executable: 202 203.Dl # cd /usr/sbin 204.Dl # ln ppp ppp0 205 206and using 207 208.Dl !ppp0 209.Dl *.* /var/log/ppp0.log 210 211in 212.Pa /etc/syslog.conf . 213Don't forget to send a 214.Dv HUP 215signal to 216.Nm syslogd 217after altering 218.Pa /etc/syslog.conf . 219 220.Sh MANUAL DIALING 221 222In the following examples, we assume that your machine name is 223.Nm awfulhak . 224 225If you set your hostname and password in 226.Pa /etc/ppp/ppp.secret , 227you can't do anything except run the help, passwd and quit commands. 228 229.Bd -literal -offset indent 230ppp on "your hostname"> help 231 help : Display this message 232 passwd : Password for security 233 quit : Quit the PPP program 234ppp on awfulhak> pass <password> 235.Ed 236 237The "on" part of your prompt will change to "ON" if you specify the 238correct password. 239 240.Bd -literal -offset indent 241ppp ON awfulhak> 242.Ed 243 244You can now specify the device name, speed and parity for your modem, 245and whether CTS/RTS signalling should be used (CTS/RTS is used by 246default). If your hardware does not provide CTS/RTS lines (as 247may happen when you are connected directly to certain ppp-capable 248terminal servers), 249.Nm 250will never send any output through the port; it waits for a signal 251which never comes. Thus, if you have a direct line and can't seem 252to make a connection, try turning ctsrts off: 253 254 255.Bd -literal -offset indent 256ppp ON awfulhak> set line /dev/cuaa0 257ppp ON awfulhak> set speed 38400 258ppp ON awfulhak> set parity even 259ppp ON awfulhak> set ctsrts on 260ppp ON awfulhak> show modem 261 262* Modem related information is shown here * 263 264ppp ON awfulhak> 265.Ed 266 267The term command can now be used to talk directly with your modem: 268 269.Bd -literal -offset indent 270ppp ON awfulhak> term 271at 272OK 273atdt123456 274CONNECT 275login: ppp 276Password: 277Protocol: ppp 278.Ed 279 280When the peer starts to talk in PPP, 281.Nm 282detects this automatically and returns to command mode. 283 284.Bd -literal -offset indent 285ppp ON awfulhak> 286PPP ON awfulhak> 287.Ed 288 289You are now connected! Note that 290.Sq PPP 291in the prompt has changed to capital letters to indicate that you have 292a peer connection. The show command can be used to see how things are 293going: 294 295.Bd -literal -offset indent 296PPP ON awfulhak> show lcp 297 298* LCP related information is shown here * 299 300PPP ON awfulhak> show ipcp 301 302* IPCP related information is shown here * 303.Ed 304 305At this point, your machine has a host route to the peer. This means 306that you can only make a connection with the host on the other side 307of the link. If you want to add a default route entry (telling your 308machine to send all packets without another routing entry to the other 309side of the ppp link), enter the following command: 310 311.Bd -literal -offset indent 312PPP ON awfulhak> add 0 0 HISADDR 313.Ed 314 315The string 316.Sq HISADDR 317represents the IP address of the connected peer. This variable is only 318available once a connection has been established. A common error 319is to specify the above command in your 320.Pa ppp.conf 321file. This won't work as the remote IP address hasn't been 322established when this file is read. 323 324You can now use your network applications (ping, telnet, ftp etc.) 325in other windows on your machine. 326 327Refer to the PPP COMMAND LIST section for details on all available commands. 328 329.Sh AUTOMATIC DIALING 330 331To use automatic dialing, you must prepare some Dial and Login chat scripts. 332See the example definitions in 333.Pa /etc/ppp/ppp.conf.sample 334(the format of ppp.conf is pretty simple). 335 336.Bl -bullet -compact 337 338.It 339Each line contains one command, label or comment. 340 341.It 342A line starting with a 343.Sq # 344character is treated as a comment line. 345 346.It 347A label name starts in the first column and is followed by 348a colon (:). 349 350.It 351A command line must contain a space or tab in the first column. 352 353.El 354 355The 356.Pa ppp.conf 357file should consist of at least a 358.Dq default 359section. This section is always executed. It should also contain 360one or more sections, named according to their purpose, for example, 361.Dq MyISP 362would represent your ISP, and 363.Dq ppp-in 364would represent an incoming 365.Nm 366configuration. 367 368You can now specify the destination label name when you invoke 369.Nm ppp . 370Commands associated with the 371.Dq default 372label are executed, followed by those associated with the destination 373label provided. When 374.Nm 375is started with no arguments, the 376.Dq default 377section is still executed. The load command can be used to manually 378load a section from the 379.Pa ppp.conf 380file: 381 382.Bd -literal -offset indent 383PPP ON awfulhak> load MyISP 384.Ed 385 386Once the connection is made, the ppp portion of the prompt will change 387to PPP: 388 389.Bd -literal -offset indent 390# ppp MyISP 391... 392ppp ON awfulhak> dial 393dial OK! 394login OK! 395PPP ON awfulhak> 396.Ed 397 398If the 399.Pa /etc/ppp/ppp.linkup 400file is available, its contents are executed 401when the 402.Em PPP 403connection is established. See the provided 404.Dq pmdemand 405example in 406.Pa /etc/ppp/ppp.conf.sample 407which adds a default route. The string HISADDR is available as the IP 408address of the remote peer. Similarly, when a connection is closed, the 409contents of the 410.Pa /etc/ppp/ppp.linkdown 411file are executed. 412 413.Sh BACKGROUND DIALING 414 415If you want to establish a connection using 416.Nm 417non-interactively (such as from a 418.Xr crontab(5) 419entry or an 420.Xr at(1) 421job) you should use the 422.Fl background 423option. You must also specify the destination label in 424.Pa /etc/ppp/ppp.conf 425to use. This label must contain the 426.Dq set ifaddr 427command to define the remote peer's IP address. (refer to 428.Pa /etc/ppp/ppp.conf.sample ) 429 430When 431.Fl background 432is specified, 433.Nm 434attempts to establish the connection immediately. If multiple phone 435numbers are specified, each phone number will be tried once. If the 436attempt fails, 437.Nm 438exits immediately with a non-zero exit code. 439 440If it succeeds, then 441.Nm 442becomes a daemon, and returns an exit status of zero to its caller. 443The daemon exits automatically if the connection is dropped by the 444remote system, or it receives a 445.Dv TERM 446signal. 447 448.Sh DIAL ON DEMAND 449 450Demand dialing is enabled with the 451.Fl auto 452or 453.Fl ddial 454options. You must also specify the destination label in 455.Pa /etc/ppp/ppp.conf 456to use. It must contain the 457.Dq set ifaddr 458command to define the remote peer's IP address. (refer to 459.Pa /etc/ppp/ppp.conf.sample ) 460 461.Bd -literal -offset indent 462# ppp -auto pmdemand 463... 464# 465.Ed 466 467When 468.Fl auto 469or 470.Fl ddial 471is specified, 472.Nm 473runs as a daemon but you can still configure or examine its 474configuration by using the diagnostic port as follows (this 475can be done in 476.Fl background 477and 478.Fl direct 479mode too): 480 481.Bd -literal -offset indent 482# pppctl -v 3000 show ipcp 483Password: 484IPCP [OPEND] 485 his side: xxxx 486 .... 487.Ed 488 489Currently, 490.Xr telnet 1 491may also be used to talk interactively. 492 493.Pp 494Each 495.Nm 496daemon has an associated port number which is computed as "3000 + 497tunnel_device_number". 498 499In 500.Fl auto 501mode, when an outgoing packet is detected, 502.Nm 503will perform the dialing action (chat script) and try to connect 504with the peer. In 505.Fl ddial 506mode, the dialing action is performed any time the line is found 507to be down. 508 509If the connect fails, the default behavior is to wait 30 seconds 510and then attempt to connect when another outgoing packet is detected. 511This behavior can be changed with 512.Bd -literal -offset indent 513set redial seconds|random[.nseconds|random] [dial_attempts] 514.Ed 515.Pp 516.Sq Seconds 517is the number of seconds to wait before attempting 518to connect again. If the argument is 519.Sq random , 520the delay period is a random value between 0 and 30 seconds. 521.Sq Nseconds 522is the number of seconds to wait before attempting 523to dial the next number in a list of numbers (see the 524.Dq set phone 525command). The default is 3 seconds. Again, if the argument is 526.Sq random , 527the delay period is a random value between 0 and 30 seconds. 528.Sq dial_attempts 529is the number of times to try to connect for each outgoing packet 530that is received. The previous value is unchanged if this parameter 531is omitted. If a value of zero is specified for 532.Sq dial_attempts , 533.Nm 534will keep trying until a connection is made. 535.Bd -literal -offset indent 536set redial 10.3 4 537.Ed 538.Pp 539will attempt to connect 4 times for each outgoing packet that is 540detected with a 3 second delay between each number and a 10 second 541delay after all numbers have been tried. If multiple phone numbers 542are specified, the total number of attempts is still 4 (it does not 543attempt each number 4 times). 544 545Modifying the dial delay is very useful when running 546.Nm 547in demand 548dial mode on both ends of the link. If each end has the same timeout, 549both ends wind up calling each other at the same time if the link 550drops and both ends have packets queued. 551 552At some locations, the serial link may not be reliable, and carrier 553may be lost at inappropriate times. It is possible to have 554.Nm 555redial should carrier be unexpectedly lost during a session. 556.Bd -literal -offset indent 557set reconnect timeout ntries 558.Ed 559 560This command tells ppp to re-establish the connection 561.Ar ntries 562times on loss of carrier with a pause of 563.Ar timeout 564seconds before each try. For example, 565.Bd -literal -offset indent 566set reconnect 3 5 567.Ed 568 569tells 570.Nm 571that on an unexpected loss of carrier, it should wait 572.Ar 3 573seconds before attempting to reconnect. This may happen up to 574.Ar 5 575times before 576.Nm 577gives up. The default value of ntries is zero (no reconnect). Care 578should be taken with this option. If the local timeout is slightly 579longer than the remote timeout, the reconnect feature will always be 580triggered (up to the given number of times) after the remote side 581times out and hangs up. 582 583NOTE: In this context, losing too many LQRs constitutes a loss of 584carrier and will trigger a reconnect. 585 586If the 587.Fl background 588flag is specified, all phone numbers are dialed at most once until 589a connection is made. The next number redial period specified with 590the 591.Dq set redial 592command is honoured, as is the reconnect tries value. If your redial 593value is less than the number of phone numbers specified, not all 594the specified numbers will be tried. 595 596To terminate the program, type 597 598 PPP ON awfulhak> close 599 ppp ON awfulhak> quit all 600 601.Pp 602A simple 603.Dq quit 604command will terminate the telnet connection but not the program itself. 605You must use 606.Dq quit all 607to terminate the program as well. 608 609.Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1) 610 611To handle an incoming 612.Em PPP 613connection request, follow these steps: 614 615.Bl -enum 616.It 617Make sure the modem and (optionally) 618.Pa /etc/rc.serial 619is configured correctly. 620.Bl -bullet -compact 621.It 622Use Hardware Handshake (CTS/RTS) for flow control. 623.It 624Modem should be set to NO echo back (ATE0) and NO results string (ATQ1). 625.El 626 627.It 628Edit 629.Pa /etc/ttys 630to enable a getty on the port where the modem is attached. 631 632For example: 633 634.Dl ttyd1 "/usr/libexec/getty std.38400" dialup on secure 635 636Don't forget to send a 637.Dv HUP 638signal to the init process to start the getty. 639 640.Dl # kill -HUP 1 641 642.It 643Prepare an account for the incoming user. 644.Bd -literal 645ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin 646.Ed 647 648.It 649Create a 650.Pa /usr/local/bin/ppplogin 651file with the following contents: 652.Bd -literal -offset indent 653#!/bin/sh -p 654exec /usr/sbin/ppp -direct 655.Ed 656 657(You can specify a label name for further control.) 658 659.Pp 660Direct mode ( 661.Fl direct 662) lets 663.Nm 664work with stdin and stdout. You can also use 665.Nm pppctl 666or 667.Nm telnet 668to connect to port 3000 plus the current tunnel device number to get 669command mode control in the same manner as client-side 670.Nm. 671 672.It 673Optional support for Microsoft's IPCP Name Server and NetBIOS 674Name Server negotiation can be enabled use 675.Dq enable msext 676and 677.Dq set ns pri-addr [sec-addr] 678along with 679.Dq set nbns pri-addr [sec-addr] 680in your ppp.conf file 681 682.El 683 684.Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2) 685 686This method differs in that it recommends the use of 687.Em mgetty+sendfax 688to handle the modem connections. The latest version 0.99 689can be compiled with the 690.Dq AUTO_PPP 691option to allow detection of clients speaking PPP to the login 692prompt. 693 694Follow these steps: 695 696.Bl -enum 697 698.It 699Get, configure, and install mgetty+sendfax v0.99 or later making 700sure you have used the AUTO_PPP option. 701 702.It 703Edit 704.Pa /etc/ttys 705to enable a mgetty on the port where the modem is attached. For 706example: 707 708.Dl cuaa1 "/usr/local/sbin/mgetty -s 57600" dialup on 709 710.It 711Prepare an account for the incoming user. 712.Bd -literal 713Pfred:xxxx:66:66:Fred's PPP:/home/ppp:/etc/ppp/ppp-dialup 714.Ed 715 716.It 717Examine the files 718.Pa /etc/ppp/sample.ppp-dialup 719.Pa /etc/ppp/sample.ppp-pap-dialup 720and 721.Pa /etc/ppp/ppp.conf.sample 722for ideas. ppp-pap-dialup is supposed to be called from 723.Pa /usr/local/etc/mgetty+sendfax/login.conf 724from a line like 725 726.Dl /AutoPPP/ - - /etc/ppp/ppp-pap-dialup 727.El 728 729.Sh PPP OVER TCP (a.k.a Tunneling) 730 731Instead of running ppp over a serial link, it is possible to 732use a tcp connection instead by specifying a host and port as the 733device: 734 735.Dl set device ui-gate:6669 736 737Instead of opening a serial device, 738.Nm 739will open a tcp connection to the given machine on the given 740socket. It should be noted however that 741.Nm 742doesn't use the telnet protocol and will be unable to negotiate 743with a telnet server. You should set up a port for receiving 744this ppp connection on the receiving machine (ui-gate). This is 745done by first updating 746.Pa /etc/services 747to name the service: 748 749.Dl ppp-in 6669/tcp # Incoming ppp connections over tcp 750 751and updating 752.Pa /etc/inetd.conf 753to tell inetd how to deal with incoming connections on that port: 754 755.Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in 756 757Don't forget to send a 758.Dv HUP 759signal to 760.Nm inetd 761after you've updated 762.Pa /etc/inetd.conf . 763 764Here, we use a label named 765.Dq ppp-in . 766The entry in 767.Pa /etc/ppp/ppp.conf 768on ui-gate (the receiver) should contain the following: 769 770.Bd -literal -offset indent 771ppp-in: 772 set timeout 0 773 set ifaddr 10.0.4.1 10.0.4.2 774 add 10.0.1.0 255.255.255.0 10.0.4.1 775.Ed 776 777You may also want to enable PAP or CHAP for security. To enable PAP, add 778the following line: 779.Bd -literal -offset indent 780 enable PAP 781.Ed 782.Pp 783You'll also need to create the following entry in 784.Pa /etc/ppp/ppp.secret : 785.Bd -literal -offset indent 786MyAuthName MyAuthPasswd 787.Ed 788.Pp 789The entry in 790.Pa /etc/ppp/ppp.conf 791on awfulhak (the initiator) should contain the following: 792 793.Bd -literal -offset indent 794ui-gate: 795 set escape 0xff 796 set device ui-gate:ppp-in 797 set dial 798 set timeout 30 5 4 799 set log Phase Chat Connect Carrier hdlc LCP IPCP CCP tun 800 set ifaddr 10.0.4.2 10.0.4.1 801 add 10.0.2.0 255.255.255.0 10.0.4.2 802.Ed 803.Pp 804Again, if you're enabling PAP, you'll also need: 805.Bd -literal -offset indent 806 set authname MyAuthName 807 set authkey MyAuthKey 808.Ed 809 810We're assigning the address of 10.0.4.1 to ui-gate, and the address 81110.0.4.2 to awfulhak. 812 813To open the connection, just type 814 815.Dl awfulhak # ppp -background ui-gate 816 817The result will be an additional "route" on awfulhak to the 81810.0.2.0/24 network via the tcp connection, and an additional 819"route" on ui-gate to the 10.0.1.0/24 network. 820 821The networks are effectively bridged - the underlying tcp 822connection may be across a public network (such as the 823Internet), and the ppp traffic is conceptually encapsulated 824(although not packet by packet) inside the tcp stream between 825the two gateways. 826 827The major disadvantage of this mechanism is that there are two 828"guaranteed delivery" mechanisms in place - the underlying tcp 829stream and whatever protocol is used over the ppp link - probably 830tcp again. If packets are lost, both levels will get in eachothers 831way trying to negotiate sending of the missing packet. 832 833.Sh PACKET ALIASING 834 835The 836.Fl alias 837command line option enables packet aliasing. This allows the 838ppp host to act as a masquerading gateway for other computers over 839a local area network. Outgoing IP packets are aliased so that 840they appear to come from the ppp host, and incoming packets are 841de-aliased so that they are routed to the correct machine on the 842local area network. 843 844Packet aliasing allows computers on private, unregistered 845subnets to have internet access, although they are invisible 846from the outside world. 847 848In general, correct ppp operation should first be verified 849with packet aliasing disabled. Then, the 850.Fl alias 851option should be switched on, and network applications (web browser, 852telnet, ftp, ping, traceroute) should be checked on the ppp host. 853Finally, the same or similar applications should be checked on other 854computers in the LAN. 855 856If network applications work correctly on the ppp host, but not on 857other machines in the LAN, then the masquerading software is working 858properly, but the host is either not forwarding or possibly receiving 859IP packets. Check that IP forwarding is enabled in 860.Pa /etc/rc.conf 861and that other machines have designated the ppp host as the gateway 862for the LAN. 863 864.Sh PACKET FILTERING 865 866This implementation supports packet filtering. There are four kinds of 867filters; ifilter, ofilter, dfilter and afilter. Here are the basics: 868 869.Bl -bullet -compact 870.It 871A filter definition has the following syntax: 872 873set filter-name rule-no action [src_addr/src_width] [dst_addr/dst_width] 874[proto [src [lt|eq|gt] port ]] [dst [lt|eq|gt] port] [estab] 875.Bl -enum 876.It 877.Sq filter-name 878should be one of ifilter, ofilter, dfilter or afilter. 879.It 880There are two actions: 881.Sq permit 882and 883.Sq deny . 884If a given packet 885matches the rule, the associated action is taken immediately. 886.It 887.Sq src_width 888and 889.Sq dst_width 890work like a netmask to represent an address range. 891.It 892.Sq proto 893must be one of icmp, udp or tcp. 894.It 895.Sq port number 896can be specified by number and service name from 897.Pa /etc/services . 898 899.El 900 901.It 902Each filter can hold up to 20 rules, starting from rule 0. 903The entire rule set is not effective until rule 0 is defined, 904ie. the default is to allow everything through. 905 906.It 907If no rule is matched to a packet, that packet will be discarded 908(blocked). 909 910.It 911Use 912.Dq set filter-name -1 913to flush all rules. 914 915.El 916 917See 918.Pa /etc/ppp/ppp.conf.filter.example . 919 920 921.Sh SETTING IDLE, LINE QUALITY REQUEST, RETRY TIMER 922 923To check/set idletimer, use the 924.Dq show timeout 925and 926.Dq set timeout [lqrtimer [retrytimer]] 927commands: 928 929.Bd -literal -offset indent 930ppp ON awfulhak> set timeout 600 931.Ed 932 933The timeout period is measured in seconds, the default values for which 934are timeout = 180 or 3 min, lqrtimer = 30sec and retrytimer = 3sec. 935To disable the idle timer function, use the command 936 937.Bd -literal -offset indent 938ppp ON awfulhak> set timeout 0 939.Ed 940 941In 942.Fl auto 943mode, an idle timeout causes the 944.Em PPP 945session to be 946closed, though the 947.Nm 948program itself remains running. Another trigger packet will cause it to 949attempt to reestablish the link. 950 951.Sh PREDICTOR-1 COMPRESSION 952 953This version supports CCP and Predictor type 1 compression based on 954the current IETF-draft specs. As a default behavior, 955.Nm 956will attempt to use (or be willing to accept) this capability when the 957peer agrees (or requests it). 958 959To disable CCP/predictor functionality completely, use the 960.Dq disable pred1 961and 962.Dq deny pred1 963commands. 964 965.Sh CONTROLLING IP ADDRESS 966 967.Nm 968uses IPCP to negotiate IP addresses. Each side of the connection 969specifies the IP address that it's willing to use, and if the requested 970IP address is acceptable then 971.Nm 972returns ACK to the requester. Otherwise, 973.Nm 974returns NAK to suggest that the peer use a different IP address. When 975both sides of the connection agree to accept the received request (and 976send ACK), IPCP is set to the open state and a network level connection 977is established. 978 979To control this IPCP behavior, this implementation has the 980.Dq set ifaddr 981command for defining the local and remote IP address: 982 983.Bd -literal -offset indent 984set ifaddr [src_addr [dst_addr [netmask [trigger_addr]]]] 985.Ed 986 987where, 988.Sq src_addr 989is the IP address that the local side is willing to use, 990.Sq dst_addr 991is the IP address which the remote side should use and 992.Sq netmask 993is the netmask that should be used. 994.Sq Src_addr 995and 996.Sq dst_addr 997default to 0.0.0.0, and 998.Sq netmask 999defaults to whatever mask is appropriate for 1000.Sq src_addr . 1001It is only possible to make 1002.Sq netmask 1003smaller than the default. The usual value is 255.255.255.255. 1004Some incorrect ppp implementations require that the peer negotiates 1005a specific IP address instead of 1006.Sq src_addr . 1007If this is the case, 1008.Sq trigger_addr 1009may be used to specify this IP number. This will not affect the 1010routing table unless the other side agrees with this proposed number. 1011 1012.Bd -literal -offset indent 1013set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0 1014.Ed 1015 1016The above specification means: 1017.Bl -bullet -compact 1018.It 1019I will first suggest that my IP address should be 0.0.0.0, but I 1020will only accept an address of 192.244.177.38. 1021 1022.It 1023I strongly insist that the peer uses 192.244.177.2 as his own 1024address and won't permit the use of any IP address but 192.244.177.2. 1025When the peer requests another IP address, I will always suggest that 1026it uses 192.244.177.2. 1027 1028.It 1029The routing table entry will have a netmask of 0xffffffff. 1030.El 1031 1032This is all fine when each side has a pre-determined IP address, however 1033it is often the case that one side is acting as a server which controls 1034all IP addresses and the other side should obey the direction from it. 1035 1036In order to allow more flexible behavior, `ifaddr' variable allows the 1037user to specify IP address more loosely: 1038 1039.Dl set ifaddr 192.244.177.38/24 192.244.177.2/20 1040 1041A number followed by a slash (/) represent the number of bits significant in 1042the IP address. The above example signifies that: 1043 1044.Bl -bullet -compact 1045.It 1046I'd like to use 192.244.177.38 as my address if it is possible, but I'll 1047also accept any IP address between 192.244.177.0 and 192.244.177.255. 1048 1049.It 1050I'd like to make him use 192.244.177.2 as his own address, but I'll also 1051permit him to use any IP address between 192.244.176.0 and 1052192.244.191.255. 1053 1054.It 1055As you may have already noticed, 192.244.177.2 is equivalent to saying 1056192.244.177.2/32. 1057 1058.It 1059As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no 1060preferred IP address and will obey the remote peer's selection. When 1061using zero, no routing table entries will be made until a connection 1062is established. 1063 1064.It 1065192.244.177.2/0 means that I'll accept/permit any IP address but I'll 1066try to insist that 192.244.177.2 be used first. 1067.El 1068 1069.Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER 1070 1071The following steps should be taken when connecting to your ISP: 1072 1073.Bl -enum 1074.It 1075Describe your provider's phone number(s) in the dial script using the 1076.Dq set phone 1077command. This command allows you to set multiple phone numbers for 1078dialing and redialing separated by either a pipe (|) or a colon (:) 1079.Bd -literal -offset indent 1080set phone "111[|222]...[:333[|444]...]... 1081.Ed 1082Numbers after the first in a pipe-separated list are only used if the 1083previous number was used in a failed dial or login script. Numbers 1084separated by a colon are used sequentially, irrespective of what happened 1085as a result of using the previous number. For example: 1086.Bd -literal -offset indent 1087set phone "1234567|2345678:3456789|4567890" 1088.Ed 1089.Pp 1090Here, the 1234567 number is attempted. If the dial or login script fails, 1091the 2345678 number is used next time, but *only* if the dial or login script 1092fails. On the dial after this, the 3456789 number is used. The 4567890 1093number is only used if the dial or login script using the 3456789 fails. If 1094the login script of the 2345678 number fails, the next number is still the 10953456789 number. As many pipes and colons can be used as are necessary 1096(although a given site would usually prefer to use either the pipe or the 1097colon, but not both). The next number redial timeout is used between all 1098numbers. When the end of the list is reached, the normal redial period is 1099used before starting at the beginning again. 1100 1101The selected phone number is substituted for the \\\\T string in the 1102.Dq set dial 1103command (see below). 1104 1105.It 1106Set up your redial requirements using 1107.Dq set redial . 1108For example, if you have a bad telephone line or your provider is 1109usually engaged (not so common these days), you may want to specify 1110the following: 1111.Bd -literal -offset indent 1112set redial 10 4 1113.Ed 1114.Pp 1115This says that up to 4 phone calls should be attempted with a pause of 10 1116seconds before dialing the first number again. 1117 1118.It 1119Describe your login procedure using the 1120.Dq set dial 1121and 1122.Dq set login 1123commands. The 1124.Dq set dial 1125command is used to talk to your modem and establish a link with your 1126ISP, for example: 1127.Bd -literal -offset indent 1128set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT" 1129.Ed 1130.Pp 1131This modem "chat" string means: 1132 1133.Bl -bullet 1134.It 1135Abort if the string "BUSY" or "NO CARRIER" are received. 1136.It 1137Set the timeout to 4. 1138.It 1139Expect nothing. 1140.It 1141Send ATZ. 1142.It 1143Expect OK. If that's not received, send ATZ and expect OK. 1144.It 1145Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from 1146above. 1147.It 1148Set the timeout to 60. 1149.It 1150Wait for the CONNECT string. 1151.El 1152 1153Once the connection is established, the login script is executed. This 1154script is written in the same style as the dial script: 1155.Bd -literal -offset indent 1156set login "TIMEOUT 15 login:-\\\\r-login: awfulhak word: xxx ocol: PPP HELLO" 1157.Ed 1158.Pp 1159This login "chat" string means: 1160 1161.Bl -bullet 1162.It 1163Set the timeout to 15 seconds. 1164.It 1165Expect "login:". If it's not received, send a carriage return and expect 1166"login:" again. 1167.It 1168Send "awfulhak" 1169.It 1170Expect "word:" (the tail end of a "Password:" prompt). 1171.It 1172Send "xxx". 1173.It 1174Expect "ocol:" (the tail end of a "Protocol:" prompt). 1175.It 1176Send "PPP". 1177.It 1178Expect "HELLO". 1179.El 1180.Pp 1181Login scripts vary greatly between ISPs. 1182 1183.It 1184Use 1185.Dq set line 1186and 1187.Dq set speed 1188to specify your serial line and speed, for example: 1189.Bd -literal -offset indent 1190set line /dev/cuaa0 1191set sp 115200 1192.Ed 1193.Pp 1194Cuaa0 is the first serial port on FreeBSD. If you're running 1195.Nm 1196on OpenBSD, cua00 is the first. A speed of 115200 should be specified 1197if you have a modem capable of bit rates of 28800 or more. In general, 1198the serial speed should be about four times the modem speed. 1199 1200.It 1201Use the 1202.Dq set ifaddr 1203command to define the IP address. 1204.Bl -bullet 1205.It 1206If you know what IP address your provider uses, then use it as the remote 1207address (dst_addr), otherwise choose something like 10.0.0.2/0 (see below). 1208.It 1209If your provider has assigned a particular IP address to you, then use 1210it as your address (src_addr). 1211.It 1212If your provider assigns your address dynamically, choose a suitably 1213unobtrusive and unspecific IP number as your address. 10.0.0.1/0 would 1214be appropriate. The bit after the / specifies how many bits of the 1215address you consider to be important, so if you wanted to insist on 1216something in the class C network 1.2.3.0, you could specify 1.2.3.1/24. 1217.It 1218If you find that your ISP accepts the first IP number that you suggest, 1219specify third and forth arguments of 1220.Dq 0.0.0.0 . 1221This will force your ISP to assign a number. (The third argument will 1222be ignored as it is less restrictive than the default mask for your 1223.Sq src_addr . 1224.El 1225.Pp 1226An example for a connection where you don't know your IP number or your 1227ISPs IP number would be: 1228.Bd -literal -offset indent 1229set ifaddr 10.10.10.10/0 10.10.11.11/0 0.0.0.0 0.0.0.0 1230.Ed 1231 1232.It 1233In most cases, your ISP will also be your default router. If this is 1234the case, add the lines 1235 1236.Bd -literal -offset indent 1237delete ALL 1238add 0 0 HISADDR 1239.Ed 1240 1241.Pp 1242to 1243.Pa ppp.conf . 1244.Pp 1245This tells 1246.Nm 1247to delete all non-direct routing entries for the tun interface that 1248.Nm 1249is running on, then to add a default route to 10.10.11.11. 1250.Pp 1251If you're using dynamic IP numbers, you must also put these two lines 1252in the 1253.Pa ppp.linkup 1254file: 1255 1256.Bd -literal -offset indent 1257delete ALL 1258add 0 0 HISADDR 1259.Ed 1260 1261HISADDR is a macro meaning the "other side"s IP number, and is 1262available once an IP number has been agreed (using IPCP). 1263Now, once a connection is established, 1264.Nm 1265will delete all non-direct interface routes, and add a default route 1266pointing at the peers IP number. You should use the same label as the 1267one used in 1268.Pa ppp.conf . 1269.Pp 1270If commands are being typed interactively, the only requirement is 1271to type 1272.Bd -literal -offset indent 1273add 0 0 HISADDR 1274.Ed 1275.Pp 1276after a successful dial. 1277 1278.It 1279If your provider requests that you use PAP/CHAP authentication methods, add 1280the next lines to your 1281.Pa ppp.conf 1282file: 1283.Bd -literal -offset indent 1284set authname MyName 1285set authkey MyPassword 1286.Ed 1287.Pp 1288Both are accepted by default, so ppp will provide whatever your ISP 1289requires. 1290.El 1291 1292Please refer to 1293.Pa /etc/ppp/ppp.conf.sample 1294and 1295.Pa /etc/ppp/ppp.linkup.sample 1296for some real examples. The pmdemand label should be appropriate for most 1297ISPs. 1298 1299.Sh LOGGING FACILITY 1300 1301.Nm 1302is able to generate the following log info via 1303.Xr syslog 3 : 1304 1305.Bl -column SMMMMMM -offset indent 1306.It Li Async Dump async level packet in hex 1307.It Li Carrier Log Chat lines with 'CARRIER' 1308.It Li CCP Generate a CPP packet trace 1309.It Li Chat Generate Chat script trace log 1310.It Li Command Log commands executed 1311.It Li Connect Generate complete Chat log 1312.It Li Debug Log (very verbose) debug information 1313.It Li HDLC Dump HDLC packet in hex 1314.It Li IPCP Generate an IPCP packet trace 1315.It Li LCP Generate an LCP packet trace 1316.It Li Link Log address assignments and link up/down events 1317.It Li LQM Generate LQR report 1318.It Li Phase Phase transition log output 1319.It Li TCP/IP Dump all TCP/IP packets 1320.It Li TUN Include the tun device on each log line 1321.It Li Warning Output to the terminal device. If there is currently no 1322terminal, output is sent to the log file using LOG_WARNING. 1323.It Li Error Output to both the terminal device and the log file using 1324LOG_ERROR. 1325.It Li Alert Output to the log file using LOG_ALERT 1326.El 1327 1328The 1329.Dq set log 1330command allows you to set logging output level, of which 1331multiple levels can be specified. The default is equivalent to 1332.Dq set log Carrier Link Phase . 1333 1334If The first argument to 1335.Dq set log 1336begins with a '+' or a '-' character, the current log levels are 1337not cleared, for example: 1338 1339.Bd -literal -offset indent 1340PPP ON awfulhak> show log 1341Log: Carrier Link Phase 1342PPP ON awfulhak> set log -Link +tcp/ip 1343PPP ON awfulhak> show log 1344Log: Carrier Phase TCP/IP 1345.Ed 1346 1347Log messages of level Warning, Error and Alert are not controlable 1348using 1349.Dq set log . 1350 1351.Sh SIGNAL HANDLING 1352 1353.Nm Ppp 1354deals with the following signals: 1355 1356.Bl -tag -width 20 1357.It INT 1358Receipt of this signal causes the termination of the current connection 1359(if any). This will cause 1360.Nm 1361to exit unless it is in 1362.Fl auto 1363or 1364.Fl ddial 1365mode. 1366 1367.It HUP, TERM & QUIT 1368These signals tell 1369.Nm 1370to exit. 1371 1372.It USR1 1373This signal, when not in interactive mode, tells 1374.Nm 1375to close any existing server socket and open an internet socket using 1376the default rules for choosing a port number - that is, using port 13773000 plus the current tunnel device number. 1378 1379.El 1380 1381.Sh PPP COMMAND LIST 1382 1383This section lists the available commands and their effect. They are 1384usable either from an interactive ppp session, from a configuration 1385file or from a telnet session. 1386 1387.Bl -tag -width 20 1388.It accept|deny|enable|disable option.... 1389These directives tell 1390.Nm 1391how to negotiate the initial connection with the peer. Each 1392.Dq option 1393has a default of either accept or deny and enable or disable. 1394.Dq Accept 1395means that the option will be ACK'd if the peer asks for it. 1396.Dq Deny 1397means that the option will be NAK'd if the peer asks for it. 1398.Dq Enable 1399means that the option will be requested by us. 1400.Dq Disable 1401means that the option will not be requested by us. 1402.Pp 1403.Dq Option 1404may be one of the following: 1405 1406.Bl -tag -width 20 1407.It vjcomp 1408Default: Enabled and Accepted. This option decides if Van Jacobson 1409header compression will be used. 1410 1411.It lqr 1412Default: Disabled and Accepted. This option decides if Link Quality 1413Requests will be sent. LQR is a protocol that allows 1414.Nm 1415to determine that the link is down without relying on the modems 1416carrier detect. 1417 1418.It chap 1419Default: Disabled and Accepted. CHAP stands for Challenge Handshake 1420Authentication Protocol. Only one of CHAP and PAP (below) may be 1421negotiated. With CHAP, the authenticator sends a "challenge" message 1422to its peer. The peer uses a one-way hash function to encrypt the 1423challenge and sends the result back. The authenticator does the same, 1424and compares the results. The advantage of this mechanism is that no 1425passwords are sent across the connection. 1426 1427A challenge is made when the connection is first made. Subsequent 1428challenges may occur. If you want to have your peer authenticate 1429itself, you must 1430.Dq enable chap . 1431in 1432.Pa ppp.conf , 1433and have an entry in 1434.Pa ppp.secret 1435for the peer. 1436.Pp 1437When using CHAP as the client, you need only specify 1438.Dq AuthName 1439and 1440.Dq AuthKey 1441in 1442.Pa ppp.conf . 1443CHAP is accepted by default. 1444 1445Some ppp implementations use "MS-CHAP" rather than MD5 when encrypting the 1446challenge. Refer to the description of the 1447.Dq set encrypt 1448command for further details. 1449 1450.It pap 1451Default: Disabled and Accepted. PAP stands for Password Authentication 1452Protocol. Only one of PAP and CHAP (above) may be negotiated. With 1453PAP, the ID and Password are sent repeatedly to the peer until 1454authentication is acknowledged or the connection is terminated. This 1455is a rather poor security mechanism. It is only performed when the 1456connection is first established. 1457 1458If you want to have your peer authenticate itself, you must 1459.Dq enable pap . 1460in 1461.Pa ppp.conf , 1462and have an entry in 1463.Pa ppp.secret 1464for the peer (although see the 1465.Dq passwdauth 1466option below). 1467.Pp 1468When using PAP as the client, you need only specify 1469.Dq AuthName 1470and 1471.Dq AuthKey 1472in 1473.Pa ppp.conf . 1474PAP is accepted by default. 1475 1476.It acfcomp 1477Default: Enabled and Accepted. ACFComp stands for Address and Control 1478Field Compression. Non LCP packets usually have very similar address 1479and control fields - making them easily compressable. 1480 1481.It protocomp 1482Default: Enabled and Accepted. This option is used to negotiate 1483PFC (Protocol Field Compression), a mechanism where the protocol 1484field number is reduced to one octet rather than two. 1485 1486.It pred1 1487Default: Enabled and Accepted. This option decides if Predictor 1 1488compression will be used. 1489 1490.It msext 1491Default: Disabled. This option allows the use of Microsoft's ppp 1492extensions, supporting the negotiation of the Microsoft PPP DNS 1493and the Microsoft NetBIOS NS. Enabling this allows us to pass back 1494the values given in "set ns" and "set nbns". 1495 1496.El 1497The following options are not actually negotiated with the peer. 1498Therefore, accepting or denying them makes no sense. 1499 1500.Bl -tag -width 20 1501.It proxy 1502Default: Disabled. Enabling this option will tell 1503.Nm 1504to proxy ARP for the peer. 1505 1506.It passwdauth 1507Default: Disabled. Enabling this option will tell the PAP authentication 1508code to use the 1509.Pa passwd 1510file to authenticate the caller rather than the 1511.Pa ppp.secret 1512file. 1513 1514.It utmp 1515Default: Enabled. Normally, when a user is authenticated using PAP or 1516CHAP, and when 1517.Nm 1518is running in 1519.Fl direct 1520mode, an entry is made in the utmp and wtmp files for that user. Disabling 1521this option will tell ppp not to make any utmp or wtmp entries. This is 1522usually only necessary if you require the user to both login and authenticate 1523themselves. 1524 1525.El 1526 1527.It add dest mask gateway 1528.Dq Dest 1529is the destination IP address and 1530.Dq mask 1531is its mask. 1532.Dq 0 0 1533refers to the default route. 1534.Dq Gateway 1535is the next hop gateway to get to the given 1536.Dq dest 1537machine/network. 1538 1539.It [!]bg command 1540The given command is executed in the background. 1541Any of the pseudo arguments 1542.Dv HISADDR , 1543.Dv INTERFACE 1544and 1545.Dv MYADDR 1546will be replaced with the appropriate values. If you wish to pause 1547.Nm 1548while the command executes, use the 1549.Dv shell 1550command instead. 1551 1552.It close 1553Close the current connection (but don't quit). 1554 1555.It delete ALL | dest [gateway [mask]] 1556If 1557.Dq ALL 1558is specified, all non-direct entries in the routing for the interface 1559that 1560.Nm 1561is using are deleted. This means all entries for tunX, except the entry 1562representing the actual link. When 1563.Dq ALL 1564is not used, any existing route with the given 1565.Dq dest , 1566destination network 1567.Dq mask 1568and 1569.Dq gateway 1570is deleted. The default 1571.Dq mask 1572value is 0.0.0.0. 1573 1574.It dial|call [remote] 1575If 1576.Dq remote 1577is specified, a connection is established using the 1578.Dq dial 1579and 1580.Dq login 1581scripts for the given 1582.Dq remote 1583system. Otherwise, the current settings are used to establish 1584the connection. 1585 1586.It display 1587Displays the current status of the negotiable protocol 1588values as specified under 1589.Dq accept|deny|enable|disable option.... 1590above. 1591 1592.It passwd pass 1593Specify the password required for access to the full 1594.Nm 1595command set. 1596 1597.It load [remote] 1598Load the given 1599.Dq remote 1600label. If 1601.Dq remote 1602is not given, the 1603.Dq default 1604label is assumed. 1605 1606.It save 1607This option is not (yet) implemented. 1608 1609.It set[up] var value 1610This option allows the setting of any of the following variables: 1611 1612.Bl -tag -width 20 1613.It set accmap hex-value 1614ACCMap stands for Asyncronous Control Character Map. This is always 1615negotiated with the peer, and defaults to a value of 0x00000000. 1616This protocol is required to defeat hardware that depends on passing 1617certain characters from end to end (such as XON/XOFF etc). 1618 1619.It set filter-name rule-no action [src_addr/src_width] 1620[dst_addr/dst_width] [proto [src [lt|eq|gt] port ]] 1621[dst [lt|eq|gt] port] [estab] 1622.Pp 1623.Nm Ppp 1624supports four filter sets. The afilter specifies packets that keep 1625the connection alive - reseting the idle timer. The dfilter specifies 1626packets that cause 1627.Nm 1628to dial when in 1629.Fl auto 1630mode. The ifilter specifies packets that are allowed to travel 1631into the machine and the ofilter specifies packets that are allowed 1632out of the machine. By default all filter sets allow all packets 1633to pass. 1634 1635Rules are processed in order according to 1636.Dq n . 1637Up to 20 rules may be given for each set. If a packet doesn't match 1638any of the rules in a given set, it is discarded. In the case of 1639ifilters and ofilters, this means that the packet is dropped. In 1640the case of afilters it means that the packet will not reset the 1641idle timer and in the case of dfilters it means that the packet will 1642not trigger a dial. 1643 1644Refer to the section on PACKET FILTERING above for further details. 1645 1646.It set authkey|key value 1647This sets the authentication key (or password) used in client mode 1648PAP or CHAP negotiation to the given value. It can also be used to 1649specify the password to be used in the dial or login scripts, preventing 1650the actual password from being logged. 1651 1652.It set authname id 1653This sets the authentication id used in client mode PAP or CHAP negotiation. 1654 1655.It set ctsrts 1656This sets hardware flow control and is the default. 1657 1658.It set device|line value 1659This sets the device to which ppp will talk to the given 1660.Dq value . 1661All serial device names are expected to begin with 1662.Pa /dev/ . 1663If 1664.Dq value 1665does not begin with 1666.Pa /dev/ , 1667it must be of the format 1668.Dq host:port . 1669If this is the case, 1670.Nm 1671will attempt to connect to the given 1672.Dq host 1673on the given 1674.Dq port . 1675Refer to the section on PPP OVER TCP above for further details. 1676 1677.It set dial chat-script 1678This specifies the chat script that will be used to dial the other 1679side. See also the 1680.Dv set login 1681command below. Refer to 1682.Xr chat 8 1683and to the example configuration files for details of the chat script 1684format. The string \\\\T will be replaced with the current phone number 1685(see 1686.Dq set phone 1687below) and the string \\\\P will be replaced with the password (see 1688.Dq set key 1689above). 1690 1691.It set hangup chat-script 1692This specifies the chat script that will be used to reset the modem 1693before it is closed. It should not normally be necessary, but can 1694be used for devices that fail to reset themselves properly on close. 1695 1696.It set encrypt MSChap|MD5 1697This specifies the encryption algorithm to request and use when issuing 1698the CHAP challenge, and defaults to MD5. If this is set to MSChap, 1699.Nm 1700will behave like a Microsoft RAS when sending the CHAP challenge (assuming 1701CHAP is enabled). When responding to a challenge, 1702.Nm 1703determines how to encrypt the response based on the challenge, so this 1704setting is ignored. 1705 1706.Bl -tag -width NOTE: 1707.It NOTE: 1708Because the Microsoft encryption algorithm uses a combination of MD4 and DES, 1709if you have not installed DES encryption software on your machine 1710before building 1711.Nm ppp , 1712this option will not be available - only MD5 will be used. 1713.El 1714 1715.It set escape value... 1716This option is similar to the 1717.Dq set accmap 1718option above. It allows the user to specify a set of characters that 1719will be `escaped' as they travel across the link. 1720 1721.It set ifaddr [myaddr [hisaddr [netmask [triggeraddr]]]] 1722This command specifies the IP addresses that will be used during 1723IPCP negotiation. Addresses are specified using the format 1724 1725.Dl a.b.c.d/n 1726 1727Where a.b.c.d is the preferred IP, but n specifies how many bits 1728of the address we will insist on. If the /n bit is omitted, it 1729defaults to /32 unless the IP address is 0.0.0.0 in which case 1730the mask defaults to /0. 1731 1732If 1733.Dq triggeraddr 1734is specified, it is used in place of 1735.Dq myaddr 1736in the initial IPCP negotiation. However, only an address in the 1737.Dq myaddr 1738range will be accepted. 1739 1740.It set loopback on|off 1741When set to 1742.Dq on 1743(the default), 1744.Nm 1745will automatically loop back packets being sent 1746out with a destination address equal to that of the ppp interface. 1747If set to 1748.Dq off , 1749.Nm 1750will send the packet, probably resulting in an ICMP redirect from 1751the other end. 1752 1753.It set log [+|-]value... 1754This command allows the adjustment of the current log level. Please 1755refer to the Logging Facility section for further details. 1756 1757.It set login chat-script 1758This chat-script compliments the dial-script. If both are specified, 1759the login script will be executed after the dial script. Escape 1760sequences available in the dial script are also available here. 1761 1762.It set mru value 1763The default MRU is 1500. If it is increased, the other side *may* 1764increase its mtu. There is no use decreasing the MRU to below the 1765default as the PPP protocol *must* be able to accept packets of at 1766least 1500 octets. 1767 1768.It set mtu value 1769The default MTU is 1500. This may be increased by the MRU specified 1770by the peer. It may only be subsequently decreased by this option. 1771Increasing it is not valid as the peer is not necessarily able to 1772receive the increased packet size. 1773 1774.It set openmode active|passive 1775By default, openmode is always active. That is, 1776.Nm 1777will always initiate LCP/IPCP/CCP negotiation. If you want to wait for the 1778peer to initiate negotiations, you may use the value 1779.Dq passive . 1780 1781.It set parity odd|even|none|mark 1782This allows the line parity to be set. The default value is none. 1783 1784.It set phone telno[|telno]...[:telno[|telno]...]... 1785This allows the specification of the phone number to be used in 1786place of the \\\\T string in the dial and login chat scripts. 1787Multiple phone numbers may be given separated by a pipe (|) or 1788a colon (:). Numbers after the pipe are only dialed if the dial or login 1789script for the previous number failed. Numbers separated by a colon are 1790tried sequentially, irrespective of the reason the line was dropped. 1791If multiple numbers are given, 1792.Nm 1793will dial them according to these rules until a connection is made, retrying 1794the maximum number of times specified by 1795.Dq set redial 1796below. In 1797.Fl background 1798mode, each number is attempted at most once. 1799 1800.It set reconnect timeout ntries 1801Should the line drop unexpectedly (due to loss of CD or LQR 1802failure), a connection will be re-established after the given 1803.Dq timeout . 1804The line will be re-connected at most 1805.Dq ntries 1806times. 1807.Dq Ntries 1808defaults to zero. A value of 1809.Dq random 1810for 1811.Dq timeout 1812will result in a variable pause, somewhere between 0 and 30 seconds. 1813 1814.It set redial seconds[.nseconds] [attempts] 1815.Nm Ppp 1816can be instructed to attempt to redial 1817.Dq attempts 1818times. If more than one number is specified (see 1819.Dq set phone 1820above), a pause of 1821.Dq nseconds 1822is taken before dialing each number. A pause of 1823.Dq seconds 1824is taken before starting at the first number again. A value of 1825.Dq random 1826may be used here too. 1827 1828.It set stopped [LCPseconds [IPCPseconds [CCPseconds]]] 1829If this option is set, 1830.Nm 1831will time out after the given FSM (Finite State Machine) has been in 1832the stopped state for the given number of 1833.Dq seconds . 1834This option may be useful if you see ppp failing to respond in the 1835stopped state. Use 1836.Dq set log +lcp +ipcp +ccp 1837to make 1838.Nm 1839log all state transitions. 1840.Pp 1841The default value is zero, where ppp doesn't time out in the stopped 1842state. 1843 1844.It set server|socket TcpPort|LocalName|none [mask] 1845Normally, when not in interactive mode, 1846.Nm 1847listens to a tcp socket for incoming command connections. The 1848default socket number is calculated as 3000 plus the number of the 1849tunnel device that 1850.Nm 1851opened. So, for example, if 1852.Nm 1853opened tun2, socket 3002 would be used. 1854.Pp 1855Using this command, you can specify your own port number, a 1856local domain socket (specified as an absolute file name), or 1857you can tell 1858.Nm 1859not to accept any command connections. If a local domain socket 1860is specified, you may also specify an octal mask that should be 1861set before creating the socket. See also the use of 1862the 1863.Dv USR1 1864signal. 1865 1866.Pp 1867When using 1868.Nm 1869with a server socket, the 1870.Xr pppctl 8 1871command is the preferred mechanism of communications. Currently, 1872.Xr telnet 1 1873can also be used, but link encryption may be implemented in the future, so 1874.Nm telnet 1875should not be relied upon. 1876 1877.It set speed value 1878This sets the speed of the serial device. 1879 1880.It set timeout Idle [ lqr [ retry ] ] 1881This command allows the setting of the idle timer, the LQR timer (if 1882enabled) and the retry timer. 1883 1884.It set ns x.x.x.x y.y.y.y 1885This option allows the setting of the Microsoft PPP DNS servers that 1886will be negotiated. 1887 1888.It set nbns x.x.x.x y.y.y.y 1889This option allows the setting of the Microsoft NetBIOS DNS servers that 1890will be negotiated. 1891 1892.It set help|? 1893This command gives a summary of available set commands. 1894.El 1895 1896.It shell|! [command] 1897If 1898.Dq command 1899is not specified a shell is invoked according to the 1900.Dv SHELL 1901environment variable. Otherwise, the given command is executed. 1902Any of the pseudo arguments 1903.Dv HISADDR , 1904.Dv INTERFACE 1905and 1906.Dv MYADDR 1907will be replaced with the appropriate values. Use of the ! character 1908requires a following space as with any other commands. You should note 1909that this command is executed in the foreground - ppp will not continue 1910running until this process has exited. Use the 1911.Dv bg 1912command if you wish processing to happen in the background. 1913 1914.It show var 1915This command allows the user to examine the following: 1916 1917.Bl -tag -width 20 1918.It show [adio]filter 1919List the current rules for the given filter. 1920 1921.It show auth 1922Show the current authname and authkey. 1923 1924.It show ccp 1925Show the current CCP statistics. 1926 1927.It show compress 1928Show the current compress statistics. 1929 1930.It show escape 1931Show the current escape characters. 1932 1933.It show hdlc 1934Show the current HDLC statistics. 1935 1936.It show ipcp 1937Show the current IPCP statistics. 1938 1939.It show lcp 1940Show the current LCP statistics. 1941 1942.It show loopback 1943Show the current loopback status. 1944 1945.It show log 1946Show the current log values. 1947 1948.It show mem 1949Show current memory statistics. 1950 1951.It show modem 1952Show current modem statistics. 1953 1954.It show mru 1955Show the current MRU. 1956 1957.It show mtu 1958Show the current MTU. 1959 1960.It show proto 1961Show current protocol totals. 1962 1963.It show reconnect 1964Show the current reconnect values. 1965 1966.It show redial 1967Show the current redial values. 1968 1969.It show stopped 1970Show the current stopped timeouts. 1971 1972.It show route 1973Show the current routing tables. 1974 1975.It show timeout 1976Show the current timeout values. 1977 1978.It show msext 1979Show the current Microsoft extension values. 1980 1981.It show version 1982Show the current version number of ppp. 1983 1984.It show help|? 1985Give a summary of available show commands. 1986.El 1987 1988.It term 1989Go into terminal mode. Characters typed at the keyboard are sent to 1990the modem. Characters read from the modem are displayed on the 1991screen. When a 1992.Nm 1993peer is detected on the other side of the modem, 1994.Nm 1995automatically enables Packet Mode and goes back into command mode. 1996 1997.It alias ..... 1998This command allows the control of the aliasing (or masquerading) 1999facilities that are built into 2000.Nm ppp . 2001Until this code is required, it is not loaded by 2002.Nm ppp , 2003and it is quite possible that the alias library is not installed 2004on your system (some administrators consider it a security risk). 2005 2006If aliasing is enabled on your system, the following commands are 2007possible: 2008 2009.Bl -tag -width 20 2010.It alias enable [yes|no] 2011This command either switches aliasing on or turns it off. 2012The 2013.Fl alias 2014command line flag is synonomous with 2015.Dq alias enable yes . 2016 2017.It alias port [proto targetIP:targetPORT [aliasIP:]aliasPORT] 2018This command allows us to redirect connections arriving at 2019.Dq aliasPORT 2020for machine [aliasIP] to 2021.Dq targetPORT 2022on 2023.Dq targetIP . 2024If proto is specified, only connections of the given protocol 2025are matched. This option is useful if you wish to run things like 2026internet phone on the machines behind your gateway. 2027 2028.It alias addr [addr_local addr_alias] 2029This command allows data for 2030.Dq addr_alias 2031to be redirected to 2032.Dq addr_local . 2033It is useful if you own a small number of real IP numbers that 2034you wish to map to specific machines behind your gateway. 2035 2036.It alias deny_incoming [yes|no] 2037If set to yes, this command will refuse all incoming connections 2038by dropping the packets in much the same way as a firewall would. 2039 2040.It alias log [yes|no] 2041This option causes various aliasing statistics and information to 2042be logged to the file 2043.Pa /var/log/alias.log . 2044 2045.It alias same_ports [yes|no] 2046When enabled, this command will tell the alias library attempt to 2047avoid changing the port number on outgoing packets. This is useful 2048if you want to support protocols such as RPC and LPD which require 2049connections to come from a well known port. 2050 2051.It alias use_sockets [yes|no] 2052When enabled, this option tells the alias library to create a 2053socket so that it can guarantee a correct incoming ftp data or 2054IRC connection. 2055 2056.It alias unregistered_only [yes|no] 2057Only alter outgoing packets with an unregistered source ad- 2058dress. According to rfc 1918, unregistered source addresses 2059are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16. 2060 2061.It alias help|? 2062This command gives a summary of available alias commands. 2063 2064.El 2065 2066.It quit|bye [all] 2067Exit 2068.Nm ppp . 2069If 2070.Nm 2071is in interactive mode or if the 2072.Dq all 2073argument is given, ppp will exit, closing the connection. A simple 2074.Dq quit 2075issued from a telnet session will not close the current connection. 2076 2077.It help|? [command] 2078Show a list of available commands. If 2079.Dq command 2080is specified, show the usage string for that command. 2081 2082.It down 2083Bring the link down ungracefully. It's not considered polite to 2084use this command. 2085 2086.El 2087 2088.Sh MORE DETAILS 2089 2090.Bl -bullet -compact 2091 2092.It 2093Read the example configuration files. They are a good source of information. 2094 2095.It 2096Use 2097.Dq help , 2098.Dq show ? , 2099.Dq alias ? , 2100.Dq set ? 2101and 2102.Dq set ? <var> 2103commands. 2104.El 2105 2106.Sh FILES 2107.Nm Ppp 2108refers to four files: ppp.conf, ppp.linkup, ppp.linkdown and 2109ppp.secret. These files are placed in 2110.Pa /etc/ppp , 2111but the user can create his own files under his $HOME directory as 2112.Pa .ppp.conf , 2113.Pa .ppp.linkup , 2114.Pa .ppp.linkdown 2115and 2116.Pa .ppp.secret. 2117.Nm 2118will always try to consult the user's personal setup first. 2119 2120.Bl -tag -width flag 2121.Pa $HOME/ppp/.ppp.[conf|linkup|linkdown|secret] 2122User dependent configuration files. 2123 2124.Pa /etc/ppp/ppp.conf 2125System default configuration file. 2126 2127.Pa /etc/ppp/ppp.secret 2128An authorization file for each system. 2129 2130.Pa /etc/ppp/ppp.linkup 2131A file to check when 2132.Nm 2133establishes a network level connection. 2134 2135.Pa /etc/ppp/ppp.linkdown 2136A file to check when 2137.Nm 2138closes a network level connection. 2139 2140.Pa /var/log/ppp.log 2141Logging and debugging information file. 2142 2143.Pa /var/spool/lock/LCK..* 2144tty port locking file. Refer to 2145.Xr uucplock 8 2146for further details. 2147 2148.Pa /var/run/tunX.pid 2149The process id (pid) of the ppp program connected to the tunX device, where 2150'X' is the number of the device. This file is only created in 2151.Fl background , 2152.Fl auto 2153and 2154.Fl ddial 2155modes. 2156 2157.Pa /var/run/ttyXX.if 2158The tun interface used by this port. Again, this file is only created in 2159.Fl background , 2160.Fl auto 2161and 2162.Fl ddial 2163modes. 2164 2165.Pa /etc/services 2166Get port number if port number is using service name. 2167.El 2168 2169.Sh SEE ALSO 2170 2171.Xr chat 8 , 2172.Xr pppd 8 , 2173.Xr uucplock 3 , 2174.Xr syslog 3 , 2175.Xr syslog.conf 5 , 2176.Xr syslogd 8 , 2177.Xr pppctl 8 , 2178.Xr telnet 1 2179 2180.Sh HISTORY 2181 2182This program was originally written by Toshiharu OHNO (tony-o@iij.ad.jp), 2183and was submitted to FreeBSD-2.0.5 by Atsushi Murai (amurai@spec.co.jp). 2184It has since had an enormous face lift and looks substantially different. 2185