1.\" $Id: ppp.8,v 1.132 1998/10/27 22:53:22 brian Exp $ 2.Dd 20 September 1995 3.Os FreeBSD 4.Dt PPP 8 5.Sh NAME 6.Nm ppp 7.Nd Point to Point Protocol (a.k.a. user-ppp) 8.Sh SYNOPSIS 9.Nm 10.Oo 11.Fl auto | 12.Fl background | 13.Fl ddial | 14.Fl direct | 15.Fl dedicated 16.Oc 17.Op Fl alias 18.Op Ar system ... 19.Sh DESCRIPTION 20This is a user process 21.Em PPP 22software package. Normally, 23.Em PPP 24is implemented as a part of the kernel (e.g. as managed by 25.Xr pppd 8 ) 26and it's thus somewhat hard to debug and/or modify its behaviour. 27However, in this implementation 28.Em PPP 29is done as a user process with the help of the 30tunnel device driver (tun). 31.Sh Major Features 32.Bl -diag 33.It Provides interactive user interface. 34Using its command mode, the user can 35easily enter commands to establish the connection with the remote end, check 36the status of connection and close the connection. All functions can 37also be optionally password protected for security. 38.It Supports both manual and automatic dialing. 39Interactive mode has a 40.Dq term 41command which enables you to talk to your modem directly. When your 42modem is connected to the remote peer and it starts to talk 43.Em PPP , 44.Nm 45detects it and switches to packet mode automatically. Once you have 46determined the proper sequence for connecting with the remote host, you 47can write a chat script to define the necessary dialing and login 48procedure for later convenience. 49.It Supports on-demand dialup capability. 50By using 51.Fl auto 52mode, 53.Nm 54will act as a daemon and wait for a packet to be sent over the 55.Em PPP 56link. When this happens, the daemon automatically dials and establishes the 57connection. 58In almost the same manner 59.Fl ddial 60mode (direct-dial mode) also automatically dials and establishes the 61connection. However, it differs in that it will dial the remote site 62any time it detects the link is down, even if there are no packets to be 63sent. This mode is useful for full-time connections where we worry less 64about line charges and more about being connected full time. 65A third 66.Fl dedicated 67mode is also available. This mode is targeted at a dedicated link 68between two machines. 69.Nm Ppp 70will never voluntarily quit from dedicated mode - you must send it the 71.Dq quit all 72command via its diagnostic socket. A 73.Dv SIGHUP 74will force an LCP renegotiation, and a 75.Dv SIGTERM 76will force it to exit. 77.It Supports client callback. 78.Nm Ppp 79can use either the standard LCP callback protocol or the Microsoft 80CallBack Control Protocol (ftp://ftp.microsoft.com/developr/rfc/cbcp.txt). 81.It Supports packet aliasing. 82Packet aliasing (a.k.a. IP masquerading) allows computers on a 83private, unregistered network to access the Internet. The 84.Em PPP 85host acts as a masquerading gateway. IP addresses as well as TCP and 86UDP port numbers are aliased for outgoing packets and de-aliased for 87returning packets. 88.It Supports background PPP connections. 89In background mode, if 90.Nm 91successfully establishes the connection, it will become a daemon. 92Otherwise, it will exit with an error. This allows the setup of 93scripts that wish to execute certain commands only if the connection 94is successfully established. 95.It Supports server-side PPP connections. 96In direct mode, 97.nm 98acts as server which accepts incoming 99.Em PPP 100connections on stdin/stdout. 101.It Supports PAP and CHAP authentication. 102With PAP or CHAP, it is possible to skip the Unix style 103.Xr login 1 104procedure, and use the 105.Em PPP 106protocol for authentication instead. If the peer requests Microsoft 107CHAP authentication and 108.Nm 109is compiled with DES support, an appropriate MD4/DES response will be 110made. 111.It Supports Proxy Arp. 112When 113.Em PPP 114is set up as server, you can also configure it to do proxy arp for your 115connection. 116.It Supports packet filtering. 117User can define four kinds of filters: the 118.Em in 119filter for incoming packets, the 120.Em out 121filter for outgoing packets, the 122.Em dial 123filter to define a dialing trigger packet and the 124.Em alive 125filter for keeping a connection alive with the trigger packet. 126.It Tunnel driver supports bpf. 127The user can use 128.Xr tcpdump 1 129to check the packet flow over the 130.Em PPP 131link. 132.It Supports PPP over TCP capability. 133If a device name is specified as 134.Em host Ns No : Ns Em port , 135.Nm 136will open a TCP connection for transporting data rather than using a 137conventional serial device. 138.It Supports IETF draft Predictor-1 and DEFLATE compression. 139.Nm 140supports not only VJ-compression but also Predictor-1 and DEFLATE compression. 141Normally, a modem has built-in compression (e.g. v42.bis) and the system 142may receive higher data rates from it as a result of such compression. 143While this is generally a good thing in most other situations, this 144higher speed data imposes a penalty on the system by increasing the 145number of serial interrupts the system has to process in talking to the 146modem and also increases latency. Unlike VJ-compression, Predictor-1 and 147DEFLATE compression pre-compresses 148.Em all 149network traffic flowing through the link, thus reducing overheads to a 150minimum. 151.It Supports Microsoft's IPCP extensions. 152Name Server Addresses and NetBIOS Name Server Addresses can be negotiated 153with clients using the Microsoft 154.Em PPP 155stack (ie. Win95, WinNT) 156.It Supports Multi-link PPP 157It is possible to configure 158.Nm 159to open more than one physical connection to the peer, combining the 160bandwidth of all links for better throughput. 161.El 162.Sh PERMISSIONS 163.Nm Ppp 164is installed as user 165.Dv root 166and group 167.Dv network , 168with permissions 169.Dv 4554 . 170By default, 171.Nm 172will not run if the invoking user id is not zero. This may be overridden 173by using the 174.Dq allow users 175command in 176.Pa /etc/ppp/ppp.conf . 177When running as a normal user, 178.Nm 179switches to user id 0 in order to alter the system routing table, set up 180system lock files and read the ppp configuration files. All 181external commands (executed via the "shell" or "!bg" commands) are executed 182as the user id that invoked 183.Nm ppp . 184Refer to the 185.Sq ID0 186logging facility if you're interested in what exactly is done as user id 187zero. 188.Sh GETTING STARTED 189When you first run 190.Nm 191you may need to deal with some initial configuration details. 192.Bl -bullet 193.It 194Your kernel must include a tunnel device (the GENERIC kernel includes 195one by default). If it doesn't, or if you require more than one tun 196interface, you'll need to rebuild your kernel with the following line in 197your kernel configuration file: 198.Pp 199.Dl pseudo-device tun N 200.Pp 201where 202.Ar N 203is the maximum number of 204.Em PPP 205connections you wish to support. 206.It 207Check your 208.Pa /dev 209directory for the tunnel device entries 210.Pa /dev/tunN , 211where 212.Sq N 213represents the number of the tun device, starting at zero. 214If they don't exist, you can create them by running "sh ./MAKEDEV tunN". 215This will create tun devices 0 through 216.Ar N . 217.It 218Make sure that your system has a group named 219.Dq network 220in the 221.Pa /etc/group 222file and that that group contains the names of all users expected to use 223.Nm ppp . 224Refer to the 225.Xr group 5 226manual page for details. Each of these uses must also be given access 227using the 228.Dq allow users 229command in 230.Pa /etc/ppp/ppp.conf . 231.It 232Create a log file. 233.Nm Ppp 234uses 235.Xr syslog 3 236to log information. A common log file name is 237.Pa /var/log/ppp.log . 238To make output go to this file, put the following lines in the 239.Pa /etc/syslog.conf 240file: 241.Bd -literal -offset indent 242!ppp 243*.*<TAB>/var/log/ppp.log 244.Ed 245.Pp 246Make sure you use actual TABs here. If you use spaces, the line will be 247silently ignored by 248.Xr syslogd 8 . 249.Pp 250It is possible to have more than one 251.Em PPP 252log file by creating a link to the 253.Nm 254executable: 255.Pp 256.Dl # cd /usr/sbin 257.Dl # ln ppp ppp0 258.Pp 259and using 260.Bd -literal -offset indent 261!ppp0 262*.*<TAB>/var/log/ppp0.log 263.Ed 264.Pp 265in 266.Pa /etc/syslog.conf . 267Don't forget to send a 268.Dv HUP 269signal to 270.Xr syslogd 8 271after altering 272.Pa /etc/syslog.conf . 273.It 274Although not strictly relevant to 275.Nm ppp Ns No s 276operation, you should configure your resolver so that it works correctly. 277This can be done by configuring a local DNS 278.Pq using Xr named 8 279or by adding the correct 280.Sq name-server 281lines to the file 282.Pa /etc/resolv.conf . 283Refer to the 284.Xr resolv.conf 5 285manual page for details. 286.Pp 287Alternatively, if the peer supports it, 288.Nm 289can be configured to ask the peer for the nameserver address(es) and to 290update 291.Pa /etc/resolv.conf 292automatically. Refer to the 293.Dq enable dns 294command below for details. 295.El 296.Sh MANUAL DIALING 297In the following examples, we assume that your machine name is 298.Dv awfulhak . 299when you invoke 300.Nm 301(see 302.Em PERMISSIONS 303above) with no arguments, you are presented with a prompt: 304.Bd -literal -offset indent 305ppp ON awfulhak> 306.Ed 307.Pp 308The 309.Sq ON 310part of your prompt should always be in upper case. If it is in lower 311case, it means that you must supply a password using the 312.Dq passwd 313command. This only ever happens if you connect to a running version of 314.Nm 315and have not authenticated yourself using the correct password. 316.Pp 317You can start by specifying the device name, speed and parity for your modem, 318and whether CTS/RTS signalling should be used (CTS/RTS is used by 319default). If your hardware does not provide CTS/RTS lines (as 320may happen when you are connected directly to certain PPP-capable 321terminal servers), 322.Nm 323will never send any output through the port; it waits for a signal 324which never comes. Thus, if you have a direct line and can't seem 325to make a connection, try turning CTS/RTS off: 326.Bd -literal -offset indent 327ppp ON awfulhak> set line /dev/cuaa0 328ppp ON awfulhak> set speed 38400 329ppp ON awfulhak> set parity even 330ppp ON awfulhak> set ctsrts on 331ppp ON awfulhak> show modem 332* Modem related information is shown here * 333ppp ON awfulhak> 334.Ed 335.Pp 336The term command can now be used to talk directly with your modem: 337.Bd -literal -offset indent 338ppp ON awfulhak> term 339at 340OK 341atdt123456 342CONNECT 343login: ppp 344Password: 345Protocol: ppp 346.Ed 347.Pp 348When the peer starts to talk in 349.Em PPP , 350.Nm 351detects this automatically and returns to command mode. 352.Bd -literal -offset indent 353ppp ON awfulhak> 354Ppp ON awfulhak> 355PPp ON awfulhak> 356PPP ON awfulhak> 357.Ed 358.Pp 359If it does not, it's possible that the peer is waiting for your end to 360start negotiating. To force 361.Nm 362to start sending PPP configuration packets to the peer, use the 363.Dq ~p 364command to enter packet mode. 365.Pp 366You are now connected! Note that 367.Sq PPP 368in the prompt has changed to capital letters to indicate that you have 369a peer connection. If only some of the three Ps go uppercase, wait 'till 370either everything is uppercase or lowercase. If they revert to lowercase, 371it means that 372.Nm 373couldn't successfully negotiate with the peer. This is probably because 374your PAP or CHAP authentication name or key is incorrect. A good first step 375for troubleshooting at this point would be to 376.Dq set log local phase . 377Refer to the 378.Dq set log 379command description below for further details. 380.Pp 381When the link is established, the show command can be used to see how 382things are going: 383.Bd -literal -offset indent 384PPP ON awfulhak> show modem 385* Modem related information is shown here * 386PPP ON awfulhak> show ccp 387* CCP (compression) related information is shown here * 388PPP ON awfulhak> show lcp 389* LCP (line control) related information is shown here * 390PPP ON awfulhak> show ipcp 391* IPCP (IP) related information is shown here * 392PPP ON awfulhak> show link 393* Link (high level) related information is shown here * 394PPP ON awfulhak> show bundle 395* Logical (high level) connection related information is shown here * 396.Ed 397.Pp 398At this point, your machine has a host route to the peer. This means 399that you can only make a connection with the host on the other side 400of the link. If you want to add a default route entry (telling your 401machine to send all packets without another routing entry to the other 402side of the 403.Em PPP 404link), enter the following command: 405.Bd -literal -offset indent 406PPP ON awfulhak> add default HISADDR 407.Ed 408.Pp 409The string 410.Sq HISADDR 411represents the IP address of the connected peer. 412If the 413.Dq add 414command fails due to an existing route, you can overwrite the existing 415route using 416.Bd -literal -offset indent 417PPP ON awfulhak> add! default HISADDR 418.Ed 419.Pp 420You can now use your network applications (ping, telnet, ftp etc.) 421in other windows on your machine. 422Refer to the 423.Em PPP COMMAND LIST 424section for details on all available commands. 425.Sh AUTOMATIC DIALING 426To use automatic dialing, you must prepare some Dial and Login chat scripts. 427See the example definitions in 428.Pa /etc/ppp/ppp.conf.sample 429(the format of 430.Pa /etc/ppp/ppp.conf 431is pretty simple). 432Each line contains one comment, inclusion, label or command: 433.Bl -bullet 434.It 435A line starting with a 436.Pq Dq # 437character is treated as a comment line. Leading whitespace are ignored 438when identifying comment lines. 439.It 440An inclusion is a line beginning with the word 441.Sq !include . 442It must have one argument - the file to include. You may wish to 443.Dq !include ~/.ppp.conf 444for compatibility with older versions of 445.Nm ppp . 446.It 447A label name starts in the first column and is followed by 448a colon 449.Pq Dq \&: . 450.It 451A command line must contain a space or tab in the first column. 452.El 453.Pp 454The 455.Pa /etc/ppp/ppp.conf 456file should consist of at least a 457.Dq default 458section. This section is always executed. It should also contain 459one or more sections, named according to their purpose, for example, 460.Dq MyISP 461would represent your ISP, and 462.Dq ppp-in 463would represent an incoming 464.Nm 465configuration. 466You can now specify the destination label name when you invoke 467.Nm ppp . 468Commands associated with the 469.Dq default 470label are executed, followed by those associated with the destination 471label provided. When 472.Nm 473is started with no arguments, the 474.Dq default 475section is still executed. The load command can be used to manually 476load a section from the 477.Pa /etc/ppp/ppp.conf 478file: 479.Bd -literal -offset indent 480PPP ON awfulhak> load MyISP 481.Ed 482.Pp 483Once the connection is made, the 484.Sq ppp 485portion of the prompt will change to 486.Sq PPP : 487.Bd -literal -offset indent 488# ppp MyISP 489... 490ppp ON awfulhak> dial 491Ppp ON awfulhak> 492PPp ON awfulhak> 493PPP ON awfulhak> 494.Ed 495.Pp 496The Ppp prompt indicates that 497.Nm 498has entered the authentication phase. The PPp prompt indicates that 499.Nm 500has entered the network phase. The PPP prompt indicates that 501.Nm 502has successfully negotiated a network layer protocol and is in 503a usable state. 504.Pp 505If the 506.Pa /etc/ppp/ppp.linkup 507file is available, its contents are executed 508when the 509.Em PPP 510connection is established. See the provided 511.Dq pmdemand 512example in 513.Pa /etc/ppp/ppp.conf.sample 514which runs a script in the background after the connection is established 515(refer to the 516.Dq shell 517and 518.Dq bg 519commands below for a description of possible substition strings). Similarly, 520when a connection is closed, the contents of the 521.Pa /etc/ppp/ppp.linkdown 522file are executed. Both of these files have the same format as 523.Pa /etc/ppp/ppp.conf . 524.Pp 525In previous versions of 526.Nm ppp , 527it was necessary to re-add routes such as the default route in the 528.Pa ppp.linkup 529file. 530.Nm Ppp 531now supports 532.Sq sticky routes , 533where all routes that contain the 534.Dv HISADDR 535or 536.Dv MYADDR 537literals will automatically be updated when the values of 538.Dv HISADDR 539and/or 540.Dv MYADDR 541change. 542.Sh BACKGROUND DIALING 543If you want to establish a connection using 544.Nm 545non-interactively (such as from a 546.Xr crontab 5 547entry or an 548.Xr at 1 549job) you should use the 550.Fl background 551option. 552When 553.Fl background 554is specified, 555.Nm 556attempts to establish the connection immediately. If multiple phone 557numbers are specified, each phone number will be tried once. If the 558attempt fails, 559.Nm 560exits immediately with a non-zero exit code. 561If it succeeds, then 562.Nm 563becomes a daemon, and returns an exit status of zero to its caller. 564The daemon exits automatically if the connection is dropped by the 565remote system, or it receives a 566.Dv TERM 567signal. 568.Sh DIAL ON DEMAND 569Demand dialing is enabled with the 570.Fl auto 571or 572.Fl ddial 573options. You must also specify the destination label in 574.Pa /etc/ppp/ppp.conf 575to use. It must contain the 576.Dq set ifaddr 577command to define the remote peers IP address. (refer to 578.Pa /etc/ppp/ppp.conf.sample ) 579.Bd -literal -offset indent 580# ppp -auto pmdemand 581.Ed 582.Pp 583When 584.Fl auto 585or 586.Fl ddial 587is specified, 588.Nm 589runs as a daemon but you can still configure or examine its 590configuration by using the 591.Dq set server 592command in 593.Pa /etc/ppp/ppp.conf , 594.Pq for example, Dq set server +3000 mypasswd 595and connecting to the diagnostic port as follows: 596.Bd -literal -offset indent 597# pppctl 3000 (assuming tun0 - see the ``set server'' description) 598Password: 599PPP ON awfulhak> show who 600tcp (127.0.0.1:1028) * 601.Ed 602.Pp 603The 604.Dq show who 605command lists users that are currently connected to 606.Nm 607itself. If the diagnostic socket is closed or changed to a different 608socket, all connections are immediately dropped. 609.Pp 610In 611.Fl auto 612mode, when an outgoing packet is detected, 613.Nm 614will perform the dialing action (chat script) and try to connect 615with the peer. In 616.Fl ddial 617mode, the dialing action is performed any time the line is found 618to be down. 619If the connect fails, the default behaviour is to wait 30 seconds 620and then attempt to connect when another outgoing packet is detected. 621This behaviour can be changed with 622.Bd -literal -offset indent 623set redial seconds|random[.nseconds|random] [dial_attempts] 624.Ed 625.Pp 626.Sq Seconds 627is the number of seconds to wait before attempting 628to connect again. If the argument is 629.Sq random , 630the delay period is a random value between 0 and 30 seconds. 631.Sq Nseconds 632is the number of seconds to wait before attempting 633to dial the next number in a list of numbers (see the 634.Dq set phone 635command). The default is 3 seconds. Again, if the argument is 636.Sq random , 637the delay period is a random value between 0 and 30 seconds. 638.Sq dial_attempts 639is the number of times to try to connect for each outgoing packet 640that is received. The previous value is unchanged if this parameter 641is omitted. If a value of zero is specified for 642.Sq dial_attempts , 643.Nm 644will keep trying until a connection is made. 645.Bd -literal -offset indent 646set redial 10.3 4 647.Ed 648.Pp 649will attempt to connect 4 times for each outgoing packet that is 650detected with a 3 second delay between each number and a 10 second 651delay after all numbers have been tried. If multiple phone numbers 652are specified, the total number of attempts is still 4 (it does not 653attempt each number 4 times). 654Modifying the dial delay is very useful when running 655.Nm 656in demand 657dial mode on both ends of the link. If each end has the same timeout, 658both ends wind up calling each other at the same time if the link 659drops and both ends have packets queued. 660At some locations, the serial link may not be reliable, and carrier 661may be lost at inappropriate times. It is possible to have 662.Nm 663redial should carrier be unexpectedly lost during a session. 664.Bd -literal -offset indent 665set reconnect timeout ntries 666.Ed 667.Pp 668This command tells 669.Nm 670to re-establish the connection 671.Ar ntries 672times on loss of carrier with a pause of 673.Ar timeout 674seconds before each try. For example, 675.Bd -literal -offset indent 676set reconnect 3 5 677.Ed 678.Pp 679tells 680.Nm 681that on an unexpected loss of carrier, it should wait 682.Ar 3 683seconds before attempting to reconnect. This may happen up to 684.Ar 5 685times before 686.Nm 687gives up. The default value of ntries is zero (no reconnect). Care 688should be taken with this option. If the local timeout is slightly 689longer than the remote timeout, the reconnect feature will always be 690triggered (up to the given number of times) after the remote side 691times out and hangs up. 692NOTE: In this context, losing too many LQRs constitutes a loss of 693carrier and will trigger a reconnect. 694If the 695.Fl background 696flag is specified, all phone numbers are dialed at most once until 697a connection is made. The next number redial period specified with 698the 699.Dq set redial 700command is honoured, as is the reconnect tries value. If your redial 701value is less than the number of phone numbers specified, not all 702the specified numbers will be tried. 703To terminate the program, type 704.Bd -literal -offset indent 705PPP ON awfulhak> close 706ppp ON awfulhak> quit all 707.Ed 708.Pp 709A simple 710.Dq quit 711command will terminate the 712.Xr pppctl 8 713or 714.Xr telnet 1 715connection but not the 716.Nm 717program itself. 718You must use 719.Dq quit all 720to terminate 721.Nm 722as well. 723.Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1) 724To handle an incoming 725.Em PPP 726connection request, follow these steps: 727.Bl -enum 728.It 729Make sure the modem and (optionally) 730.Pa /etc/rc.serial 731is configured correctly. 732.Bl -bullet -compact 733.It 734Use Hardware Handshake (CTS/RTS) for flow control. 735.It 736Modem should be set to NO echo back (ATE0) and NO results string (ATQ1). 737.El 738.Pp 739.It 740Edit 741.Pa /etc/ttys 742to enable a 743.Xr getty 8 744on the port where the modem is attached. 745For example: 746.Pp 747.Dl ttyd1 "/usr/libexec/getty std.38400" dialup on secure 748.Pp 749Don't forget to send a 750.Dv HUP 751signal to the 752.Xr init 8 753process to start the 754.Xr getty 8 : 755.Pp 756.Dl # kill -HUP 1 757.It 758Create a 759.Pa /usr/local/bin/ppplogin 760file with the following contents: 761.Bd -literal -offset indent 762#! /bin/sh 763exec /usr/sbin/ppp -direct incoming 764.Ed 765.Pp 766Direct mode 767.Pq Fl direct 768lets 769.Nm 770work with stdin and stdout. You can also use 771.Xr pppctl 8 772to connect to a configured diagnostic port, in the same manner as with 773client-side 774.Nm ppp . 775.Pp 776Here, the 777.Ar incoming 778section must be set up in 779.Pa /etc/ppp/ppp.conf . 780.Pp 781Make sure that the 782.Ar incoming 783section contains the 784.Dq allow users 785command as appropriate. 786.It 787Prepare an account for the incoming user. 788.Bd -literal 789ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin 790.Ed 791.Pp 792Refer to the manual entries for 793.Xr adduser 8 794and 795.Xr vipw 8 796for details. 797.It 798Support for IPCP Domain Name Server and NetBIOS Name Server negotiation 799can be enabled using the 800.Dq accept dns 801and 802.Dq set nbns 803commands. Refer to their descriptions below. 804.El 805.Pp 806.Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2) 807This method differs in that we use 808.Nm ppp 809to authenticate the connection rather than 810.Xr login 1 : 811.Bl -enum 812.It 813Configure your default section in 814.Pa /etc/gettytab 815with automatic ppp recognition by specifying the 816.Dq pp 817capability: 818.Bd -literal 819default:\\ 820 :pp=/usr/local/bin/ppplogin:\\ 821 ..... 822.Ed 823.It 824Configure your serial device(s), enable a 825.Xr getty 8 826and create 827.Pa /usr/local/bin/ppplogin 828as in the first three steps for method 1 above. 829.It 830Add either 831.Dq enable chap 832or 833.Dq enable pap 834.Pq or both 835to 836.Pa /etc/ppp/ppp.conf 837under the 838.Sq incoming 839label (or whatever label 840.Pa ppplogin 841uses). 842.It 843Create an entry in 844.Pa /etc/ppp/ppp.secret 845for each incoming user: 846.Bd -literal 847Pfred<TAB>xxxx 848Pgeorge<TAB>yyyy 849.Ed 850.El 851.Pp 852Now, as soon as 853.Xr getty 8 854detects a ppp connection (by recognising the HDLC frame headers), it runs 855.Dq /usr/local/bin/ppplogin . 856.Pp 857It is 858.Em VITAL 859that either PAP or CHAP are enabled as above. If they are not, you are 860allowing anybody to establish ppp session with your machine 861.Em without 862a password, opening yourself up to all sorts of potential attacks. 863.Sh AUTHENTICATING INCOMING CONNECTIONS 864Normally, the receiver of a connection requires that the peer 865authenticates itself. This may be done using 866.Xr login 1 , 867but alternatively, you can use PAP or CHAP. CHAP is the more secure 868of the two, but some clients may not support it. Once you decide which 869you wish to use, add the command 870.Sq enable chap 871or 872.Sq enable pap 873to the relevant section of 874.Pa ppp.conf . 875.Pp 876You must then configure the 877.Pa /etc/ppp/ppp.secret 878file. This file contains one line per possible client, each line 879containing up to four fields: 880.Bd -literal -offset indent 881name key [hisaddr [label]] 882.Ed 883.Pp 884The 885.Ar name 886and 887.Ar key 888specify the client as expected. If 889.Ar key 890is 891.Dq \&* 892and PAP is being used, 893.Nm 894will look up the password database 895.Pq Xr passwd 5 896when authenticating. If the client does not offer a suitable 897response based on any 898.Ar name No / Ar key 899combination in 900.Pa ppp.secret , 901authentication fails. 902.Pp 903If authentication is successful, 904.Ar hisaddr 905.Pq if specified 906is used when negotiating IP numbers. See the 907.Dq set ifaddr 908command for details. 909.Pp 910If authentication is successful and 911.Ar label 912is specified, the current system label is changed to match the given 913.Ar label . 914This will change the subsequent parsing of the 915.Pa ppp.linkup 916and 917.Pa ppp.linkdown 918files. 919.Sh PPP OVER TCP (a.k.a Tunnelling) 920Instead of running 921.Nm 922over a serial link, it is possible to 923use a TCP connection instead by specifying a host and port as the 924device: 925.Pp 926.Dl set device ui-gate:6669 927.Pp 928Instead of opening a serial device, 929.Nm 930will open a TCP connection to the given machine on the given 931socket. It should be noted however that 932.Nm 933doesn't use the telnet protocol and will be unable to negotiate 934with a telnet server. You should set up a port for receiving this 935.Em PPP 936connection on the receiving machine (ui-gate). This is 937done by first updating 938.Pa /etc/services 939to name the service: 940.Pp 941.Dl ppp-in 6669/tcp # Incoming PPP connections over TCP 942.Pp 943and updating 944.Pa /etc/inetd.conf 945to tell 946.Xr inetd 8 947how to deal with incoming connections on that port: 948.Pp 949.Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in 950.Pp 951Don't forget to send a 952.Dv HUP 953signal to 954.Xr inetd 8 955after you've updated 956.Pa /etc/inetd.conf . 957Here, we use a label named 958.Dq ppp-in . 959The entry in 960.Pa /etc/ppp/ppp.conf 961on ui-gate (the receiver) should contain the following: 962.Bd -literal -offset indent 963ppp-in: 964 set timeout 0 965 set ifaddr 10.0.4.1 10.0.4.2 966 add 10.0.1.0/24 10.0.4.2 967.Ed 968.Pp 969You may also want to enable PAP or CHAP for security. To enable PAP, add 970the following line: 971.Bd -literal -offset indent 972 enable PAP 973.Ed 974.Pp 975You'll also need to create the following entry in 976.Pa /etc/ppp/ppp.secret : 977.Bd -literal -offset indent 978MyAuthName MyAuthPasswd 979.Ed 980.Pp 981If 982.Ar MyAuthPasswd 983is a 984.Pq Dq * , 985the password is looked up in the 986.Xr passwd 5 987database. 988.Pp 989The entry in 990.Pa /etc/ppp/ppp.conf 991on awfulhak (the initiator) should contain the following: 992.Bd -literal -offset indent 993ui-gate: 994 set escape 0xff 995 set device ui-gate:ppp-in 996 set dial 997 set timeout 30 998 set log Phase Chat Connect hdlc LCP IPCP CCP tun 999 set ifaddr 10.0.4.2 10.0.4.1 1000 add 10.0.2.0/24 10.0.4.1 1001.Ed 1002.Pp 1003Again, if you're enabling PAP, you'll also need: 1004.Bd -literal -offset indent 1005 set authname MyAuthName 1006 set authkey MyAuthKey 1007.Ed 1008.Pp 1009We're assigning the address of 10.0.4.1 to ui-gate, and the address 101010.0.4.2 to awfulhak. 1011To open the connection, just type 1012.Pp 1013.Dl awfulhak # ppp -background ui-gate 1014.Pp 1015The result will be an additional "route" on awfulhak to the 101610.0.2.0/24 network via the TCP connection, and an additional 1017"route" on ui-gate to the 10.0.1.0/24 network. 1018The networks are effectively bridged - the underlying TCP 1019connection may be across a public network (such as the 1020Internet), and the 1021.Em PPP 1022traffic is conceptually encapsulated 1023(although not packet by packet) inside the TCP stream between 1024the two gateways. 1025The major disadvantage of this mechanism is that there are two 1026"guaranteed delivery" mechanisms in place - the underlying TCP 1027stream and whatever protocol is used over the 1028.Em PPP 1029link - probably TCP again. If packets are lost, both levels will 1030get in each others way trying to negotiate sending of the missing 1031packet. 1032.Sh PACKET ALIASING 1033The 1034.Fl alias 1035command line option enables packet aliasing. This allows the 1036.Nm 1037host to act as a masquerading gateway for other computers over 1038a local area network. Outgoing IP packets are aliased so that 1039they appear to come from the 1040.Nm 1041host, and incoming packets are de-aliased so that they are routed 1042to the correct machine on the local area network. 1043Packet aliasing allows computers on private, unregistered 1044subnets to have Internet access, although they are invisible 1045from the outside world. 1046In general, correct 1047.Nm 1048operation should first be verified with packet aliasing disabled. 1049Then, the 1050.Fl alias 1051option should be switched on, and network applications (web browser, 1052.Xr telnet 1 , 1053.Xr ftp 1 , 1054.Xr ping 8 , 1055.Xr traceroute 8 ) 1056should be checked on the 1057.Nm 1058host. Finally, the same or similar applications should be checked on other 1059computers in the LAN. 1060If network applications work correctly on the 1061.Nm 1062host, but not on other machines in the LAN, then the masquerading 1063software is working properly, but the host is either not forwarding 1064or possibly receiving IP packets. Check that IP forwarding is enabled in 1065.Pa /etc/rc.conf 1066and that other machines have designated the 1067.Nm 1068host as the gateway for the LAN. 1069.Sh PACKET FILTERING 1070This implementation supports packet filtering. There are four kinds of 1071filters; the 1072.Em in 1073filter, the 1074.Em out 1075filter, the 1076.Em dial 1077filter and the 1078.Em alive 1079filter. Here are the basics: 1080.Bl -bullet 1081.It 1082A filter definition has the following syntax: 1083.Pp 1084set filter 1085.Ar name 1086.Ar rule-no 1087.Ar action 1088.Op Ar src_addr Ns Op / Ns Ar width 1089.Op Ar dst_addr Ns Op / Ns Ar width 1090[ 1091.Ar proto 1092.Op src Op Ar cmp No Ar port 1093.Op dst Op Ar cmp No Ar port 1094.Op estab 1095.Op syn 1096.Op finrst 1097] 1098.Bl -enum 1099.It 1100.Ar Name 1101should be one of 1102.Sq in , 1103.Sq out , 1104.Sq dial 1105or 1106.Sq alive . 1107.It 1108.Ar Rule-no 1109is a numeric value between 1110.Sq 0 1111and 1112.Sq 19 1113specifying the rule number. Rules are specified in numeric order according to 1114.Ar rule-no , 1115but only if rule 1116.Sq 0 1117is defined. 1118.It 1119.Ar Action 1120is either 1121.Sq permit 1122or 1123.Sq deny . 1124If a given packet 1125matches the rule, the associated action is taken immediately. 1126.It 1127.Op Ar src_addr Ns Op / Ns Ar width 1128and 1129.Op Ar dst_addr Ns Op / Ns Ar width 1130are the source and destination IP number specifications. If 1131.Op / Ns Ar width 1132is specified, it gives the number of relevant netmask bits, 1133allowing the specification of an address range. 1134.It 1135.Ar Proto 1136must be one of 1137.Sq icmp , 1138.Sq udp 1139or 1140.Sq tcp . 1141.It 1142.Ar Cmp 1143is one of 1144.Sq \< , 1145.Sq \&eq 1146or 1147.Sq \> , 1148meaning less-than, equal and greater-than respectively. 1149.Ar Port 1150can be specified as a numeric port or by service name from 1151.Pa /etc/services . 1152.It 1153The 1154.Sq estab , 1155.Sq syn , 1156and 1157.Sq finrst 1158flags are only allowed when 1159.Ar proto 1160is set to 1161.Sq tcp , 1162and represent the TH_ACK, TH_SYN and TH_FIN or TH_RST TCP flags respectively. 1163.El 1164.Pp 1165.It 1166Each filter can hold up to 20 rules, starting from rule 0. 1167The entire rule set is not effective until rule 0 is defined, 1168ie. the default is to allow everything through. 1169.It 1170If no rule is matched to a packet, that packet will be discarded 1171(blocked). 1172.It 1173Use 1174.Dq set filter Ar name No -1 1175to flush all rules. 1176.El 1177.Pp 1178See 1179.Pa /etc/ppp/ppp.conf.example . 1180.Sh SETTING THE IDLE TIMER 1181To check/set the idle timer, use the 1182.Dq show bundle 1183and 1184.Dq set timeout 1185commands: 1186.Bd -literal -offset indent 1187ppp ON awfulhak> set timeout 600 1188.Ed 1189.Pp 1190The timeout period is measured in seconds, the default value for which 1191is 180 seconds 1192.Pq or 3 min . 1193To disable the idle timer function, use the command 1194.Bd -literal -offset indent 1195ppp ON awfulhak> set timeout 0 1196.Ed 1197.Pp 1198In 1199.Fl ddial 1200and 1201.Fl direct 1202modes, the idle timeout is ignored. In 1203.Fl auto 1204mode, when the idle timeout causes the 1205.Em PPP 1206session to be 1207closed, the 1208.Nm 1209program itself remains running. Another trigger packet will cause it to 1210attempt to re-establish the link. 1211.Sh PREDICTOR-1 and DEFLATE COMPRESSION 1212.Nm Ppp 1213supports both Predictor type 1 and deflate compression. 1214By default, 1215.Nm 1216will attempt to use (or be willing to accept) both compression protocols 1217when the peer agrees 1218.Pq or requests them . 1219The deflate protocol is preferred by 1220.Nm ppp . 1221Refer to the 1222.Dq disable 1223and 1224.Dq deny 1225commands if you wish to disable this functionality. 1226.Pp 1227It is possible to use a different compression algorithm in each direction 1228by using only one of 1229.Dq disable deflate 1230and 1231.Dq deny deflate 1232.Pq assuming that the peer supports both algorithms . 1233.Pp 1234By default, when negotiating DEFLATE, 1235.Nm 1236will use a window size of 15. Refer to the 1237.Dq set deflate 1238command if you wish to change this behaviour. 1239.Pp 1240A special algorithm called DEFLATE24 is also available, and is disabled 1241and denied by default. This is exactly the same as DEFLATE except that 1242it uses CCP ID 24 to negotiate. This allows 1243.Nm 1244to successfully negotiate DEFLATE with 1245.Nm pppd 1246version 2.3.*. 1247.Sh CONTROLLING IP ADDRESS 1248.Nm 1249uses IPCP to negotiate IP addresses. Each side of the connection 1250specifies the IP address that it's willing to use, and if the requested 1251IP address is acceptable then 1252.Nm 1253returns ACK to the requester. Otherwise, 1254.Nm 1255returns NAK to suggest that the peer use a different IP address. When 1256both sides of the connection agree to accept the received request (and 1257send ACK), IPCP is set to the open state and a network level connection 1258is established. 1259To control this IPCP behaviour, this implementation has the 1260.Dq set ifaddr 1261command for defining the local and remote IP address: 1262.Bd -literal -offset indent 1263set ifaddr [src_addr [dst_addr [netmask [trigger_addr]]]] 1264.Ed 1265.Pp 1266where, 1267.Sq src_addr 1268is the IP address that the local side is willing to use, 1269.Sq dst_addr 1270is the IP address which the remote side should use and 1271.Sq netmask 1272is the netmask that should be used. 1273.Sq Src_addr 1274defaults to the current 1275.Xr hostname 1 , 1276.Sq dst_addr 1277defaults to 0.0.0.0, and 1278.Sq netmask 1279defaults to whatever mask is appropriate for 1280.Sq src_addr . 1281It is only possible to make 1282.Sq netmask 1283smaller than the default. The usual value is 255.255.255.255, as 1284most kernels ignore the netmask of a POINTOPOINT interface. 1285.Pp 1286Some incorrect 1287.Em PPP 1288implementations require that the peer negotiates a specific IP 1289address instead of 1290.Sq src_addr . 1291If this is the case, 1292.Sq trigger_addr 1293may be used to specify this IP number. This will not affect the 1294routing table unless the other side agrees with this proposed number. 1295.Bd -literal -offset indent 1296set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0 1297.Ed 1298.Pp 1299The above specification means: 1300.Pp 1301.Bl -bullet -compact 1302.It 1303I will first suggest that my IP address should be 0.0.0.0, but I 1304will only accept an address of 192.244.177.38. 1305.It 1306I strongly insist that the peer uses 192.244.177.2 as his own 1307address and won't permit the use of any IP address but 192.244.177.2. 1308When the peer requests another IP address, I will always suggest that 1309it uses 192.244.177.2. 1310.It 1311The routing table entry will have a netmask of 0xffffffff. 1312.El 1313.Pp 1314This is all fine when each side has a pre-determined IP address, however 1315it is often the case that one side is acting as a server which controls 1316all IP addresses and the other side should obey the direction from it. 1317In order to allow more flexible behaviour, `ifaddr' variable allows the 1318user to specify IP address more loosely: 1319.Pp 1320.Dl set ifaddr 192.244.177.38/24 192.244.177.2/20 1321.Pp 1322A number followed by a slash (/) represent the number of bits significant in 1323the IP address. The above example signifies that: 1324.Pp 1325.Bl -bullet -compact 1326.It 1327I'd like to use 192.244.177.38 as my address if it is possible, but I'll 1328also accept any IP address between 192.244.177.0 and 192.244.177.255. 1329.It 1330I'd like to make him use 192.244.177.2 as his own address, but I'll also 1331permit him to use any IP address between 192.244.176.0 and 1332192.244.191.255. 1333.It 1334As you may have already noticed, 192.244.177.2 is equivalent to saying 1335192.244.177.2/32. 1336.It 1337As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no 1338preferred IP address and will obey the remote peers selection. When 1339using zero, no routing table entries will be made until a connection 1340is established. 1341.It 1342192.244.177.2/0 means that I'll accept/permit any IP address but I'll 1343try to insist that 192.244.177.2 be used first. 1344.El 1345.Pp 1346.Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER 1347The following steps should be taken when connecting to your ISP: 1348.Bl -enum 1349.It 1350Describe your providers phone number(s) in the dial script using the 1351.Dq set phone 1352command. This command allows you to set multiple phone numbers for 1353dialing and redialing separated by either a pipe (|) or a colon (:) 1354.Bd -literal -offset indent 1355set phone "111[|222]...[:333[|444]...]... 1356.Ed 1357.Pp 1358Numbers after the first in a pipe-separated list are only used if the 1359previous number was used in a failed dial or login script. Numbers 1360separated by a colon are used sequentially, irrespective of what happened 1361as a result of using the previous number. For example: 1362.Bd -literal -offset indent 1363set phone "1234567|2345678:3456789|4567890" 1364.Ed 1365.Pp 1366Here, the 1234567 number is attempted. If the dial or login script fails, 1367the 2345678 number is used next time, but *only* if the dial or login script 1368fails. On the dial after this, the 3456789 number is used. The 4567890 1369number is only used if the dial or login script using the 3456789 fails. If 1370the login script of the 2345678 number fails, the next number is still the 13713456789 number. As many pipes and colons can be used as are necessary 1372(although a given site would usually prefer to use either the pipe or the 1373colon, but not both). The next number redial timeout is used between all 1374numbers. When the end of the list is reached, the normal redial period is 1375used before starting at the beginning again. 1376The selected phone number is substituted for the \\\\T string in the 1377.Dq set dial 1378command (see below). 1379.It 1380Set up your redial requirements using 1381.Dq set redial . 1382For example, if you have a bad telephone line or your provider is 1383usually engaged (not so common these days), you may want to specify 1384the following: 1385.Bd -literal -offset indent 1386set redial 10 4 1387.Ed 1388.Pp 1389This says that up to 4 phone calls should be attempted with a pause of 10 1390seconds before dialing the first number again. 1391.It 1392Describe your login procedure using the 1393.Dq set dial 1394and 1395.Dq set login 1396commands. The 1397.Dq set dial 1398command is used to talk to your modem and establish a link with your 1399ISP, for example: 1400.Bd -literal -offset indent 1401set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" \e 1402 ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT" 1403.Ed 1404.Pp 1405This modem "chat" string means: 1406.Bl -bullet 1407.It 1408Abort if the string "BUSY" or "NO CARRIER" are received. 1409.It 1410Set the timeout to 4 seconds. 1411.It 1412Expect nothing. 1413.It 1414Send ATZ. 1415.It 1416Expect OK. If that's not received within the 4 second timeout, send ATZ 1417and expect OK. 1418.It 1419Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from 1420above. 1421.It 1422Set the timeout to 60. 1423.It 1424Wait for the CONNECT string. 1425.El 1426.Pp 1427Once the connection is established, the login script is executed. This 1428script is written in the same style as the dial script, but care should 1429be taken to avoid having your password logged: 1430.Bd -literal -offset indent 1431set authkey MySecret 1432set login "TIMEOUT 15 login:-\\\\r-login: awfulhak \e 1433 word: \\\\P ocol: PPP HELLO" 1434.Ed 1435.Pp 1436This login "chat" string means: 1437.Bl -bullet 1438.It 1439Set the timeout to 15 seconds. 1440.It 1441Expect "login:". If it's not received, send a carriage return and expect 1442"login:" again. 1443.It 1444Send "awfulhak" 1445.It 1446Expect "word:" (the tail end of a "Password:" prompt). 1447.It 1448Send whatever our current 1449.Ar authkey 1450value is set to. 1451.It 1452Expect "ocol:" (the tail end of a "Protocol:" prompt). 1453.It 1454Send "PPP". 1455.It 1456Expect "HELLO". 1457.El 1458.Pp 1459The 1460.Dq set authkey 1461command is logged specially (when using 1462.Ar command 1463logging) so that the actual password is not compromised 1464(it is logged as 1465.Sq ******** Ns 1466), and the '\\P' is logged when 1467.Ar chat 1468logging is active rather than the actual password. 1469.Pp 1470Login scripts vary greatly between ISPs. If you're setting one up 1471for the first time, 1472.Em ENABLE CHAT LOGGING 1473so that you can see if your script is behaving as you expect. 1474.It 1475Use 1476.Dq set line 1477and 1478.Dq set speed 1479to specify your serial line and speed, for example: 1480.Bd -literal -offset indent 1481set line /dev/cuaa0 1482set speed 115200 1483.Ed 1484.Pp 1485Cuaa0 is the first serial port on FreeBSD. If you're running 1486.Nm 1487on OpenBSD, cua00 is the first. A speed of 115200 should be specified 1488if you have a modem capable of bit rates of 28800 or more. In general, 1489the serial speed should be about four times the modem speed. 1490.It 1491Use the 1492.Dq set ifaddr 1493command to define the IP address. 1494.Bl -bullet 1495.It 1496If you know what IP address your provider uses, then use it as the remote 1497address (dst_addr), otherwise choose something like 10.0.0.2/0 (see below). 1498.It 1499If your provider has assigned a particular IP address to you, then use 1500it as your address (src_addr). 1501.It 1502If your provider assigns your address dynamically, choose a suitably 1503unobtrusive and unspecific IP number as your address. 10.0.0.1/0 would 1504be appropriate. The bit after the / specifies how many bits of the 1505address you consider to be important, so if you wanted to insist on 1506something in the class C network 1.2.3.0, you could specify 1.2.3.1/24. 1507.It 1508If you find that your ISP accepts the first IP number that you suggest, 1509specify third and forth arguments of 1510.Dq 0.0.0.0 . 1511This will force your ISP to assign a number. (The third argument will 1512be ignored as it is less restrictive than the default mask for your 1513.Sq src_addr . 1514.El 1515.Pp 1516An example for a connection where you don't know your IP number or your 1517ISPs IP number would be: 1518.Bd -literal -offset indent 1519set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0 1520.Ed 1521.Pp 1522.It 1523In most cases, your ISP will also be your default router. If this is 1524the case, add the line 1525.Bd -literal -offset indent 1526add default HISADDR 1527.Ed 1528.Pp 1529to 1530.Pa /etc/ppp/ppp.conf . 1531.Pp 1532This tells 1533.Nm 1534to add a default route to whatever the peer address is 1535.Pq 10.0.0.2 in this example . 1536This route is 1537.Sq sticky , 1538meaning that should the value of 1539.Dv HISADDR 1540change, the route will be updated accordingly. 1541.Pp 1542Previous versions of 1543.Nm 1544required a similar entry in the 1545.Pa /etc/ppp/ppp.linkup 1546file. Since the advent of 1547.Sq sticky routes , 1548his is no longer required. 1549.It 1550If your provider requests that you use PAP/CHAP authentication methods, add 1551the next lines to your 1552.Pa /etc/ppp/ppp.conf 1553file: 1554.Bd -literal -offset indent 1555set authname MyName 1556set authkey MyPassword 1557.Ed 1558.Pp 1559Both are accepted by default, so 1560.Nm 1561will provide whatever your ISP requires. 1562.Pp 1563It should be noted that a login script is rarely (if ever) required 1564when PAP or CHAP are in use. 1565.It 1566Ask your ISP to authenticate your nameserver address(es) with the line 1567.Bd -literal -offset indent 1568enable dns 1569.Ed 1570Do 1571.Em NOT 1572do this if you are running an local DNS, as 1573.Nm 1574will simply circumvent its use by entering some nameserver lines in 1575.Pa /etc/resolv.conf . 1576.El 1577.Pp 1578Please refer to 1579.Pa /etc/ppp/ppp.conf.sample 1580and 1581.Pa /etc/ppp/ppp.linkup.sample 1582for some real examples. The pmdemand label should be appropriate for most 1583ISPs. 1584.Sh LOGGING FACILITY 1585.Nm Ppp 1586is able to generate the following log info either via 1587.Xr syslog 3 1588or directly to the screen: 1589.Bl -column SMMMMMM -offset indent 1590.It Li Async Dump async level packet in hex 1591.It Li CBCP Generate CBCP (CallBack Control Protocol) logs 1592.It Li CCP Generate a CCP packet trace 1593.It Li Chat Generate Chat script trace log 1594.It Li Command Log commands executed 1595.It Li Connect Generate complete Chat log 1596.It Li Debug Log debug information 1597.It Li HDLC Dump HDLC packet in hex 1598.It Li ID0 Log all function calls specifically made as user id 0. 1599.It Li IPCP Generate an IPCP packet trace 1600.It Li LCP Generate an LCP packet trace 1601.It Li LQM Generate LQR report 1602.It Li Phase Phase transition log output 1603.It Li TCP/IP Dump all TCP/IP packets 1604.It Li Timer Log timer manipulation 1605.It Li TUN Include the tun device on each log line 1606.It Li Warning Output to the terminal device. If there is currently no 1607terminal, output is sent to the log file using LOG_WARNING. 1608.It Li Error Output to both the terminal device and the log file using 1609LOG_ERROR. 1610.It Li Alert Output to the log file using LOG_ALERT 1611.El 1612.Pp 1613The 1614.Dq set log 1615command allows you to set the logging output level. Multiple levels 1616can be specified on a single command line. The default is equivalent to 1617.Dq set log Phase . 1618.Pp 1619It is also possible to log directly to the screen. The syntax is 1620the same except that the word 1621.Dq local 1622should immediately follow 1623.Dq set log . 1624The default is 1625.Dq set log local 1626(ie. only the un-maskable warning, error and alert output). 1627.Pp 1628If The first argument to 1629.Dq set log Op local 1630begins with a '+' or a '-' character, the current log levels are 1631not cleared, for example: 1632.Bd -literal -offset indent 1633PPP ON awfulhak> set log phase 1634PPP ON awfulhak> show log 1635Log: Phase Warning Error Alert 1636Local: Warning Error Alert 1637PPP ON awfulhak> set log +tcp/ip -warning 1638PPP ON awfulhak> set log local +command 1639PPP ON awfulhak> show log 1640Log: Phase TCP/IP Warning Error Alert 1641Local: Command Warning Error Alert 1642.Ed 1643.Pp 1644Log messages of level Warning, Error and Alert are not controllable 1645using 1646.Dq set log Op local . 1647.Pp 1648The 1649.Ar Warning 1650level is special in that it will not be logged if it can be displayed 1651locally. 1652.Sh SIGNAL HANDLING 1653.Nm Ppp 1654deals with the following signals: 1655.Bl -tag -width XX 1656.It INT 1657Receipt of this signal causes the termination of the current connection 1658(if any). This will cause 1659.Nm 1660to exit unless it is in 1661.Fl auto 1662or 1663.Fl ddial 1664mode. 1665.It HUP, TERM & QUIT 1666These signals tell 1667.Nm 1668to exit. 1669.It USR2 1670This signal, tells 1671.Nm 1672to close any existing server socket, dropping all existing diagnostic 1673connections. 1674.El 1675.Pp 1676.Sh MULTI-LINK PPP 1677If you wish to use more than one physical link to connect to a 1678.Em PPP 1679peer, that peer must also understand the 1680.Em MULTI-LINK PPP 1681protocol. Refer to RFC 1990 for specification details. 1682.Pp 1683The peer is identified using a combination of his 1684.Dq endpoint discriminator 1685and his 1686.Dq authentication id . 1687Either or both of these may be specified. It is recommended that 1688at least one is specified, otherwise there is no way of ensuring that 1689all links are actually connected to the same peer program, and some 1690confusing lock-ups may result. Locally, these identification variables 1691are specified using the 1692.Dq set enddisc 1693and 1694.Dq set authname 1695commands. The 1696.Sq authname 1697.Pq and Sq authkey 1698must be agreed in advance with the peer. 1699.Pp 1700Multi-link capabilities are enabled using the 1701.Dq set mrru 1702command (set maximum reconstructed receive unit). Once multi-link 1703is enabled, 1704.Nm 1705will attempt to negotiate a multi-link connection with the peer. 1706.Pp 1707By default, only one 1708.Sq link 1709is available 1710.Pq called Sq deflink . 1711To create more links, the 1712.Dq clone 1713command is used. This command will clone existing links, where all 1714characteristics are the same except: 1715.Bl -enum 1716.It 1717The new link has its own name as specified on the 1718.Dq clone 1719command line. 1720.It 1721The new link is an 1722.Sq interactive 1723link. It's mode may subsequently be changed using the 1724.Dq set mode 1725command. 1726.It 1727The new link is in a 1728.Sq closed 1729state. 1730.El 1731.Pp 1732A summary of all available links can be seen using the 1733.Dq show links 1734command. 1735.Pp 1736Once a new link has been created, command usage varies. All link 1737specific commands must be prefixed with the 1738.Dq link Ar name 1739command, specifying on which link the command is to be applied. When 1740only a single link is available, 1741.Nm 1742is smart enough not to require the 1743.Dq link Ar name 1744prefix. 1745.Pp 1746Some commands can still be used without specifying a link - resulting 1747in an operation at the 1748.Sq bundle 1749level. For example, once two or more links are available, the command 1750.Dq show ccp 1751will show CCP configuration and statistics at the multi-link level, and 1752.Dq link deflink show ccp 1753will show the same information at the 1754.Dq deflink 1755link level. 1756.Pp 1757Armed with this information, the following configuration might be used: 1758.Pp 1759.Bd -literal -offset indent 1760mp: 1761 set timeout 0 1762 set log phase chat 1763 set device /dev/cuaa0 /dev/cuaa1 /dev/cuaa2 1764 set phone "123456789" 1765 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \\"\\" ATZ \e 1766 OK-AT-OK \\\\dATDT\\\\T TIMEOUT 45 CONNECT" 1767 set login 1768 set ifaddr 10.0.0.1/0 10.0.0.2/0 1769 set authname ppp 1770 set authkey ppppassword 1771 1772 set mrru 1500 1773 clone 1,2,3 1774 link deflink remove 1775.Ed 1776.Pp 1777Note how all cloning is done at the end of the configuration. Usually, 1778the link will be configured first, then cloned. If you wish all links 1779to be up all the time, you can add the following line to the end of your 1780configuration. 1781.Pp 1782.Bd -literal -offset indent 1783 link 1,2,3 set mode ddial 1784.Ed 1785.Pp 1786If you want the links to dial on demand, this command could be used: 1787.Pp 1788.Bd -literal -offset indent 1789 link * set mode auto 1790.Ed 1791.Pp 1792Links may be tied to specific names by removing the 1793.Dq set device 1794line above, and specifying the following after the 1795.Dq clone 1796command: 1797.Pp 1798.Bd -literal -offset indent 1799 link 1 set device /dev/cuaa0 1800 link 2 set device /dev/cuaa1 1801 link 3 set device /dev/cuaa2 1802.Ed 1803.Pp 1804Use the 1805.Dq help 1806command to see which commands require context (using the 1807.Dq link 1808command), which have optional 1809context and which should not have any context. 1810.Pp 1811When 1812.Nm 1813has negotiated 1814.Em MULTI-LINK 1815mode with the peer, it creates a local domain socket in the 1816.Pa /var/run 1817directory. This socket is used to pass link information (including 1818the actual link file descriptor) between different 1819.Nm 1820invocations. This facilitates 1821.Nm ppp Ns No s 1822ability to be run from a 1823.Xr getty 8 1824or directly from 1825.Pa /etc/gettydefs 1826(using the 1827.Sq pp= 1828capability), without needing to have initial control of the serial 1829line. Once 1830.Nm 1831negotiates multi-link mode, it will pass its open link to any 1832already running process. If there is no already running process, 1833.Nm 1834will act as the master, creating the socket and listening for new 1835connections. 1836.Sh PPP COMMAND LIST 1837This section lists the available commands and their effect. They are 1838usable either from an interactive 1839.Nm 1840session, from a configuration file or from a 1841.Xr pppctl 8 1842or 1843.Xr telnet 1 1844session. 1845.Bl -tag -width XX 1846.It accept|deny|enable|disable Ar option.... 1847These directives tell 1848.Nm 1849how to negotiate the initial connection with the peer. Each 1850.Dq option 1851has a default of either accept or deny and enable or disable. 1852.Dq Accept 1853means that the option will be ACK'd if the peer asks for it. 1854.Dq Deny 1855means that the option will be NAK'd if the peer asks for it. 1856.Dq Enable 1857means that the option will be requested by us. 1858.Dq Disable 1859means that the option will not be requested by us. 1860.Pp 1861.Dq Option 1862may be one of the following: 1863.Bl -tag -width XX 1864.It acfcomp 1865Default: Enabled and Accepted. ACFComp stands for Address and Control 1866Field Compression. Non LCP packets usually have very similar address 1867and control fields - making them easily compressible. 1868.It chap 1869Default: Disabled and Accepted. CHAP stands for Challenge Handshake 1870Authentication Protocol. Only one of CHAP and PAP (below) may be 1871negotiated. With CHAP, the authenticator sends a "challenge" message 1872to its peer. The peer uses a one-way hash function to encrypt the 1873challenge and sends the result back. The authenticator does the same, 1874and compares the results. The advantage of this mechanism is that no 1875passwords are sent across the connection. 1876A challenge is made when the connection is first made. Subsequent 1877challenges may occur. If you want to have your peer authenticate 1878itself, you must 1879.Dq enable chap . 1880in 1881.Pa /etc/ppp/ppp.conf , 1882and have an entry in 1883.Pa /etc/ppp/ppp.secret 1884for the peer. 1885.Pp 1886When using CHAP as the client, you need only specify 1887.Dq AuthName 1888and 1889.Dq AuthKey 1890in 1891.Pa /etc/ppp/ppp.conf . 1892CHAP is accepted by default. 1893Some 1894.Em PPP 1895implementations use "MS-CHAP" rather than MD5 when encrypting the 1896challenge. MS-CHAP is a combination of MD4 and DES. If 1897.Nm 1898was built on a machine with DES libraries available, it will respond 1899to MS-CHAP authentication requests, but will never request them. 1900.It deflate 1901Default: Enabled and Accepted. This option decides if deflate 1902compression will be used by the Compression Control Protocol (CCP). 1903This is the same algorithm as used by the 1904.Xr gzip 1 1905program. 1906Note: There is a problem negotiating 1907.Ar deflate 1908capabilities with 1909.Xr pppd 8 1910- a 1911.Em PPP 1912implementation available under many operating systems. 1913.Nm Pppd 1914(version 2.3.1) incorrectly attempts to negotiate 1915.Ar deflate 1916compression using type 1917.Em 24 1918as the CCP configuration type rather than type 1919.Em 26 1920as specified in 1921.Pa rfc1979 . 1922Type 1923.Ar 24 1924is actually specified as 1925.Dq PPP Magna-link Variable Resource Compression 1926in 1927.Pa rfc1975 Ns No ! 1928.Nm Ppp 1929is capable of negotiating with 1930.Nm pppd , 1931but only if 1932.Dq deflate24 1933is 1934.Ar enable Ns No d 1935and 1936.Ar accept Ns No ed . 1937.It deflate24 1938Default: Disabled and Denied. This is a variance of the 1939.Ar deflate 1940option, allowing negotiation with the 1941.Xr pppd 8 1942program. Refer to the 1943.Ar deflate 1944section above for details. It is disabled by default as it violates 1945.Pa rfc1975 . 1946.It dns 1947Default: Disabled and Denied. This option allows DNS negotiation. 1948.Pp 1949If 1950.Dq enable Ns No d, 1951.Nm 1952will request that the peer confirms the entries in 1953.Pa /etc/resolv.conf . 1954If the peer NAKs our request (suggesting new IP numbers), 1955.Pa /etc/resolv.conf 1956is updated and another request is sent to confirm the new entries. 1957.Pp 1958If 1959.Dq accept Ns No ed, 1960.Nm 1961will answer any DNS queries requested by the peer rather than rejecting 1962them. The answer is taken from 1963.Pa /etc/resolv.conf 1964unless the 1965.Dq set dns 1966command is used as an override. 1967.It lqr 1968Default: Disabled and Accepted. This option decides if Link Quality 1969Requests will be sent or accepted. LQR is a protocol that allows 1970.Nm 1971to determine that the link is down without relying on the modems 1972carrier detect. When LQR is enabled, 1973.Nm 1974sends the 1975.Em QUALPROTO 1976option (see 1977.Dq set lqrperiod 1978below) as part of the LCP request. If the peer agrees, both sides will 1979exchange LQR packets at the agreed frequency, allowing detailed link 1980quality monitoring by enabling LQM logging. If the peer doesn't agree, 1981ppp will send ECHO LQR requests instead. These packets pass no 1982information of interest, but they 1983.Em MUST 1984be replied to by the peer. 1985.Pp 1986Whether using LQR or ECHO LQR, 1987.Nm 1988will abruptly drop the connection if 5 unacknowledged packets have been 1989sent rather than sending a 6th. A message is logged at the 1990.Em PHASE 1991level, and any appropriate 1992.Dq reconnect 1993values are honoured as if the peer were responsible for dropping the 1994connection. 1995.It pap 1996Default: Disabled and Accepted. PAP stands for Password Authentication 1997Protocol. Only one of PAP and CHAP (above) may be negotiated. With 1998PAP, the ID and Password are sent repeatedly to the peer until 1999authentication is acknowledged or the connection is terminated. This 2000is a rather poor security mechanism. It is only performed when the 2001connection is first established. 2002If you want to have your peer authenticate itself, you must 2003.Dq enable pap . 2004in 2005.Pa /etc/ppp/ppp.conf , 2006and have an entry in 2007.Pa /etc/ppp/ppp.secret 2008for the peer (although see the 2009.Dq passwdauth 2010option below). 2011.Pp 2012When using PAP as the client, you need only specify 2013.Dq AuthName 2014and 2015.Dq AuthKey 2016in 2017.Pa /etc/ppp/ppp.conf . 2018PAP is accepted by default. 2019.It pred1 2020Default: Enabled and Accepted. This option decides if Predictor 1 2021compression will be used by the Compression Control Protocol (CCP). 2022.It protocomp 2023Default: Enabled and Accepted. This option is used to negotiate 2024PFC (Protocol Field Compression), a mechanism where the protocol 2025field number is reduced to one octet rather than two. 2026.It shortseq 2027Default: Enabled and Accepted. This option determines if 2028.Nm 2029will request and accept requests for short 2030.Pq 12 bit 2031sequence numbers when negotiating multi-link mode. This is only 2032applicable if our MRRU is set (thus enabling multi-link). 2033.It vjcomp 2034Default: Enabled and Accepted. This option determines if Van Jacobson 2035header compression will be used. 2036.El 2037.Pp 2038The following options are not actually negotiated with the peer. 2039Therefore, accepting or denying them makes no sense. 2040.Bl -tag -width XX 2041.It idcheck 2042Default: Enabled. When 2043.Nm 2044exchanges low-level LCP, CCP and IPCP configuration traffic, the 2045.Em Identifier 2046field of any replies is expected to be the same as that of the request. 2047By default, 2048.Nm 2049drops any reply packets that do not contain the expected identifier 2050field, reporting the fact at the respective log level. If 2051.Ar idcheck 2052is disabled, 2053.Nm 2054will ignore the identifier field. 2055.It loopback 2056Default: Enabled. When 2057.Ar loopback 2058is enabled, 2059.Nm 2060will automatically loop back packets being sent 2061out with a destination address equal to that of the 2062.Em PPP 2063interface. If disabled, 2064.Nm 2065will send the packet, probably resulting in an ICMP redirect from 2066the other end. It is convenient to have this option enabled when 2067the interface is also the default route as it avoids the necessity 2068of a loopback route. 2069.It passwdauth 2070Default: Disabled. Enabling this option will tell the PAP authentication 2071code to use the password database (see 2072.Xr passwd 5 ) 2073to authenticate the caller if they cannot be found in the 2074.Pa /etc/ppp/ppp.secret 2075file. 2076.Pa /etc/ppp/ppp.secret 2077is always checked first. If you wish to use passwords from 2078.Xr passwd 5 , 2079but also to specify an IP number or label for a given client, use 2080.Dq \&* 2081as the client password in 2082.Pa /etc/ppp/ppp.secret . 2083.It proxy 2084Default: Disabled. Enabling this option will tell 2085.Nm 2086to proxy ARP for the peer. 2087.It proxyall 2088Default: Disabled. Enabling this will tell 2089.Nm 2090to add proxy arp entries for every IP address in all class C or 2091smaller subnets routed via the tun interface. 2092.It sroutes 2093Default: Enabled. When the 2094.Dq add 2095command is used with the 2096.Dv HISADDR 2097or 2098.Dv MYADDR 2099values, entries are stored in the 2100.Sq stick route 2101list. Each time 2102.Dv HISADDR 2103or 2104.Dv MYADDR 2105change, this list is re-applied to the routing table. 2106.Pp 2107Disabling this option will prevent the re-application of sticky routes, 2108although the 2109.Sq stick route 2110list will still be maintained. 2111.It throughput 2112Default: Enabled. This option tells 2113.Nm 2114to gather throughput statistics. Input and output is sampled over 2115a rolling 5 second window, and current, best and total figures are 2116retained. This data is output when the relevant 2117.Em PPP 2118layer shuts down, and is also available using the 2119.Dq show 2120command. Throughput statistics are available at the 2121.Dq IPCP 2122and 2123.Dq modem 2124levels. 2125.It utmp 2126Default: Enabled. Normally, when a user is authenticated using PAP or 2127CHAP, and when 2128.Nm 2129is running in 2130.Fl direct 2131mode, an entry is made in the utmp and wtmp files for that user. Disabling 2132this option will tell 2133.Nm 2134not to make any utmp or wtmp entries. This is usually only necessary if 2135you require the user to both login and authenticate themselves. 2136.It iface-alias 2137Default: Enabled if 2138.Fl alias 2139is specified. This option simply tells 2140.Nm 2141to add new interface addresses to the interface rather than replacing them. 2142The option can only be enabled if IP aliasing is enabled 2143.Pq Dq alias enable yes . 2144.Pp 2145With this option enabled, 2146.Nm 2147will pass traffic for old interface addresses through the IP alias engine 2148.Pq see Xr libalias 5 , 2149resulting in the ability (in 2150.Fl auto 2151mode) to properly connect the process that caused the PPP link to 2152come up in the first place. 2153.Pp 2154Disabling IP aliasing with 2155.Dq alias enable off 2156will also disable 2157.Sq iface-alias . 2158.El 2159.Pp 2160.It add[!] Ar dest[/nn] [mask] gateway 2161.Ar Dest 2162is the destination IP address. The netmask is specified either as a 2163number of bits with 2164.Ar /nn 2165or as an IP number using 2166.Ar mask . 2167.Ar 0 0 2168or simply 2169.Ar 0 2170with no mask refers to the default route. It is also possible to use the 2171literal name 2172.Sq default 2173instead of 2174.Ar 0 . 2175.Ar Gateway 2176is the next hop gateway to get to the given 2177.Ar dest 2178machine/network. Refer to the 2179.Xr route 8 2180command for further details. 2181.Pp 2182It is possible to use the symbolic names 2183.Sq MYADDR 2184or 2185.Sq HISADDR 2186as the destination, and 2187.Sq HISADDR 2188as the 2189.Ar gateway . 2190.Sq MYADDR 2191is replaced with the interface address and 2192.Sq HISADDR 2193is replaced with the interface destination (peer) address. 2194.Pp 2195If the 2196.Ar add! 2197command is used 2198.Pq note the trailing Dq \&! , 2199then if the route already exists, it will be updated as with the 2200.Sq route change 2201command (see 2202.Xr route 8 2203for further details). 2204.Pp 2205Routes that contain the 2206.Dq HISADDR 2207or 2208.Dq MYADDR 2209constants are considered 2210.Sq sticky . 2211They are stored in a list (use 2212.Dq show ipcp 2213to see the list), and each time the value of 2214.Dv HISADDR 2215or 2216.Dv MYADDR 2217changes, the appropriate routing table entries are updated. This facility 2218may be disabled using 2219.Dq disable sroutes . 2220.It allow Ar command Op Ar args 2221This command controls access to 2222.Nm 2223and its configuration files. It is possible to allow user-level access, 2224depending on the configuration file label and on the mode that 2225.Nm 2226is being run in. For example, you may wish to configure 2227.Nm 2228so that only user 2229.Sq fred 2230may access label 2231.Sq fredlabel 2232in 2233.Fl background 2234mode. 2235.Pp 2236User id 0 is immune to these commands. 2237.Bl -tag -width XX 2238.It allow user[s] Ar logname... 2239By default, only user id 0 is allowed access to 2240.Nm ppp . 2241If this command is used, all of the listed users are allowed access to 2242the section in which the 2243.Dq allow users 2244command is found. The 2245.Sq default 2246section is always checked first (even though it is only ever automatically 2247loaded at startup). Each successive 2248.Dq allow users 2249command overrides the previous one, so it's possible to allow users access 2250to everything except a given label by specifying default users in the 2251.Sq default 2252section, and then specifying a new user list for that label. 2253.Pp 2254If user 2255.Sq * 2256is specified, access is allowed to all users. 2257.It allow mode[s] Ar modelist... 2258By default, access using any 2259.Nm 2260mode is possible. If this command is used, it restricts the access 2261mode allowed to load the label under which this command is specified. 2262Again, as with the 2263.Dq allow users 2264command, each 2265.Dq allow modes 2266command overrides the previous, and the 2267.Sq default 2268section is always checked first. 2269.Pp 2270Possible modes are: 2271.Sq interactive , 2272.Sq auto , 2273.Sq direct , 2274.Sq dedicated , 2275.Sq ddial , 2276.Sq background 2277and 2278.Sq * . 2279.Pp 2280When running in multi-link mode, a section can be loaded if it allows 2281.Em any 2282of the currently existing line modes. 2283.El 2284.Pp 2285.It alias Ar command Op Ar args 2286This command allows the control of the aliasing (or masquerading) 2287facilities that are built into 2288.Nm ppp . 2289If aliasing is enabled on your system (it may be omitted at compile time), 2290the following commands are possible: 2291.Bl -tag -width XX 2292.It alias enable [yes|no] 2293This command either switches aliasing on or turns it off. 2294The 2295.Fl alias 2296command line flag is synonymous with 2297.Dq alias enable yes . 2298.It alias port Op Ar proto targetIP:targetPORT [aliasIP:]aliasPORT 2299This command allows us to redirect connections arriving at 2300.Ar aliasPORT 2301for machine 2302.Ar aliasIP 2303to 2304.Ar targetPORT 2305on 2306.Ar targetIP . 2307.Ar Proto 2308may be either 2309.Sq tcp 2310or 2311.Sq udp , 2312and only connections of the given protocol 2313are matched. This option is useful if you wish to run things like 2314Internet phone on the machines behind your gateway. 2315.It alias addr Op Ar addr_local addr_alias 2316This command allows data for 2317.Ar addr_alias 2318to be redirected to 2319.Ar addr_local . 2320It is useful if you own a small number of real IP numbers that 2321you wish to map to specific machines behind your gateway. 2322.It alias deny_incoming [yes|no] 2323If set to yes, this command will refuse all incoming connections 2324by dropping the packets in much the same way as a firewall would. 2325.It alias help|? 2326This command gives a summary of available alias commands. 2327.It alias log [yes|no] 2328This option causes various aliasing statistics and information to 2329be logged to the file 2330.Pa /var/log/alias.log . 2331.It alias same_ports [yes|no] 2332When enabled, this command will tell the alias library attempt to 2333avoid changing the port number on outgoing packets. This is useful 2334if you want to support protocols such as RPC and LPD which require 2335connections to come from a well known port. 2336.It alias use_sockets [yes|no] 2337When enabled, this option tells the alias library to create a 2338socket so that it can guarantee a correct incoming ftp data or 2339IRC connection. 2340.It alias unregistered_only [yes|no] 2341Only alter outgoing packets with an unregistered source ad- 2342dress. According to RFC 1918, unregistered source addresses 2343are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16. 2344.El 2345.Pp 2346These commands are also discussed in the file 2347.Pa README.alias 2348which comes with the source distribution. 2349.Pp 2350.It [!]bg Ar command 2351The given 2352.Ar command 2353is executed in the background with the following words replaced: 2354.Bl -tag -width PEER_ENDDISC 2355.It Li AUTHNAME 2356This is replaced with the local 2357.Ar authname 2358value. See the 2359.Dq set authname 2360command below. 2361.It Li ENDDISC 2362This is replaced with the local endpoint discriminator value. See the 2363.Dq set enddisc 2364command below. 2365.It Li HISADDR 2366This is replaced with the peers IP number. 2367.It Li INTERFACE 2368This is replaced with the name of the interface that's in use. 2369.It Li LABEL 2370This is replaced with the last label name used. A label may be specified 2371on the 2372.Nm 2373command line, via the 2374.Dq load 2375or 2376.Dq dial 2377commands and in the 2378.Pa ppp.secret 2379file. 2380.It Li MYADDR 2381This is replaced with the IP number assigned to the local interface. 2382.It Li PEER_ENDDISC 2383This is replaced with the value of the peers endpoint discriminator. 2384.It Li PROCESSID 2385This is replaced with the current process id. 2386.It Li USER 2387This is replaced with the username that has been authenticated with PAP or 2388CHAP. Normally, this variable is assigned only in -direct mode. This value 2389is available irrespective of whether utmp logging is enabled. 2390.El 2391.Pp 2392These substitutions are also done by the 2393.Dq set proctitle 2394command. 2395.Pp 2396If you wish to pause 2397.Nm 2398while the command executes, use the 2399.Dq shell 2400command instead. 2401.It clear modem|ipcp Op current|overall|peak... 2402Clear the specified throughput values at either the 2403.Dq modem 2404or 2405.Dq ipcp 2406level. If 2407.Dq modem 2408is specified, context must be given (see the 2409.Dq link 2410command below). If no second argument is given, all values are 2411cleared. 2412.It clone Ar name[,name]... 2413Clone the specified link, creating one or more new links according to the 2414.Ar name 2415argument(s). This command must be used from the 2416.Dq link 2417command below unless you've only got a single link (in which case that 2418link becomes the default). Links may be removed using the 2419.Dq remove 2420command below. 2421.Pp 2422The default link name is 2423.Dq deflink . 2424.It close Op lcp|ccp[!] 2425If no arguments are given, the relevant protocol layers will be brought 2426down and the link will be closed. If 2427.Dq lcp 2428is specified, the LCP layer is brought down, but 2429.Nm 2430will not bring the link offline. It is subsequently possible to use 2431.Dq term 2432.Pq see below 2433to talk to the peer machine if, for example, something like 2434.Dq slirp 2435is being used. If 2436.Dq ccp 2437is specified, only the relevant compression layer is closed. If the 2438.Dq \&! 2439is used, the compression layer will remain in the closed state, otherwise 2440it will re-enter the STOPPED state, waiting for the peer to initiate 2441further CCP negotiation. In any event, this command does not disconnect 2442the user from 2443.Nm 2444or exit 2445.Nm ppp . 2446See the 2447.Dq quit 2448command below. 2449.It delete[!] Ar dest 2450This command deletes the route with the given 2451.Ar dest 2452IP address. If 2453.Ar dest 2454is specified as 2455.Sq ALL , 2456all non-direct entries in the routing table for the current interface, 2457and all 2458.Sq sticky route 2459entries are deleted. If 2460.Ar dest 2461is specified as 2462.Sq default , 2463the default route is deleted. 2464.Pp 2465If the 2466.Ar delete! 2467command is used 2468.Pq note the trailing Dq \&! , 2469.Nm 2470will not complain if the route does not already exist. 2471.It dial|call Op Ar label 2472When used with no argument, this command is the same as the 2473.Dq open 2474command. When one or more 2475.Ar label 2476is specified, a 2477.Dq load 2478will be done first. 2479.It down Op Ar lcp|ccp 2480Bring the relevant layer down ungracefully, as if the underlying layer 2481had become unavailable. It's not considered polite to use this command on 2482a Finite State Machine that's in the OPEN state. If no arguments are 2483supplied, the entire link is closed (or if no context is given, all links 2484are terminated). If 2485.Sq lcp 2486is specified, the 2487.Em LCP 2488layer is terminated but the modem is not brought offline and the link 2489is not closed. If 2490.Sq ccp 2491is specified, only the relevant compression layer(s) are terminated. 2492.It help|? Op Ar command 2493Show a list of available commands. If 2494.Ar command 2495is specified, show the usage string for that command. 2496.It iface Ar command Op args 2497This command is used to control the interface used by 2498.Nm ppp . 2499.Ar Command 2500may be one of the following: 2501.Bl -tag -width XX 2502.It iface add[!] Ar addr[[/bits| mask] peer] 2503Add the given 2504.Ar addr mask peer 2505combination to the interface. Instead of specifying 2506.Ar mask , 2507.Ar /bits 2508can be used 2509.Pq with no space between \&it and Ar addr . 2510If the given address already exists, the command fails unless the 2511.Dq \&! 2512is used - in which case the previous interface address entry is overwritten 2513with the new one, allowing a change of netmask or peer address. 2514.Pp 2515If only 2516.Ar addr 2517is specified, 2518.Ar bits 2519defaults to 2520.Dq 32 2521and 2522.Ar peer 2523defaults to 2524.Dq 255.255.255.255 . 2525This address (the broadcast address) is the only duplicate peer address that 2526.Nm 2527allows. 2528.It iface clear 2529If this command is used while 2530.Nm 2531is in the OPENED state, all addresses except for the IPCP negotiated 2532address are deleted from the interface. If 2533.Nm 2534is not in the OPENED state, all interface addresses are deleted. 2535.Pp 2536.It iface delete[!]|rm[!] Ar addr 2537This command deletes the given 2538.Ar addr 2539from the interface. If the 2540.Dq \&! 2541is used, no error is given if the address isn't currently assigned to 2542the interface (and no deletion takes place). 2543.It iface show 2544Shows the current state and current addresses for the interface. It is 2545much the same as running 2546.Dq ifconfig INTERFACE . 2547.It iface help Op Ar sub-command 2548This command, when invoked without 2549.Ar sub-command , 2550will show a list of possbile 2551.Dq iface 2552sub-commands and a brief synopsis for each. When invoked with 2553.Ar sub-command , 2554only the synopsis for the given sub-command is shown. 2555.El 2556.It [data]link Ar name[,name...] command Op Ar args 2557This command may prefix any other command if the user wishes to 2558specify which link the command should affect. This is only 2559applicable after multiple links have been created in Multi-link 2560mode using the 2561.Dq clone 2562command. 2563.Pp 2564.Ar Name 2565specifies the name of an existing link. If 2566.Ar name 2567is a comma separated list, 2568.Ar command 2569is executed on each link. If 2570.Ar name 2571is 2572.Dq * , 2573.Ar command 2574is executed on all links. 2575.It load Op Ar label ... 2576Load the given 2577.Ar label(s) 2578from the 2579.Pa ppp.conf 2580file. If 2581.Ar label 2582is not given, the 2583.Ar default 2584label is used. 2585.It open Op lcp|ccp|ipcp 2586This is the opposite of the 2587.Dq close 2588command. Using 2589.Dq open 2590with no arguments is the same as using 2591.Dq dial 2592with no arguments, where all closed links are brought up (some auto 2593links may not come up based on the 2594.Dq set autoload 2595command) using the current configuration. 2596.Pp 2597If the 2598.Dq lcp 2599while the LCP layer is already open, LCP will be renegotiated. This 2600allows various LCP options to be changed, after which 2601.Dq open lcp 2602can be used to put them into effect. After renegotiating LCP, 2603any agreed authentication will also take place. 2604.Pp 2605If the 2606.Dq ccp 2607argument is used, the relevant compression layer is opened. Again, 2608if it is already open, it will be renegotiated. 2609.Pp 2610If the 2611.Dq ipcp 2612argument is used, the link will be brought up as normal, but if 2613IPCP is already open, it will be renegotiated and the network 2614interface will be reconfigured. 2615.Pp 2616It is probably not good practice to re-open the PPP state machines 2617like this as it's possible that the peer will not behave correctly. 2618It 2619.Em is 2620however useful as a way of forcing the CCP or VJ dictionaries to be reset. 2621.It passwd Ar pass 2622Specify the password required for access to the full 2623.Nm 2624command set. This password is required when connecting to the diagnostic 2625port (see the 2626.Dq set server 2627command). 2628.Ar Pass 2629is specified on the 2630.Dq set server 2631command line. The value of 2632.Ar pass 2633is not logged when 2634.Ar command 2635logging is active, instead, the literal string 2636.Sq ******** 2637is logged. 2638.It quit|bye [all] 2639If 2640.Dq quit 2641is executed from the controlling connection or from a command file, 2642ppp will exit after closing all connections. Otherwise, if the user 2643is connected to a diagnostic socket, the connection is simply dropped. 2644.Pp 2645If the 2646.Ar 2647all argument is given, 2648.Nm 2649will exit despite the source of the command after closing all existing 2650connections. 2651.It remove|rm 2652This command removes the given link. It is only really useful in 2653multi-link mode. A link must be 2654in the 2655.Dv CLOSED 2656state before it is removed. 2657.It rename|mv Ar name 2658This command renames the given link to 2659.Ar name . 2660It will fail if 2661.Ar name 2662is already used by another link. 2663.Pp 2664The default link name is 2665.Sq deflink . 2666Renaming it to 2667.Sq modem , 2668.Sq cuaa0 2669or 2670.Sq USR 2671may make the log file more readable. 2672.It save 2673This option is not (yet) implemented. 2674.It set[up] Ar var value 2675This option allows the setting of any of the following variables: 2676.Bl -tag -width XX 2677.It set accmap Ar hex-value 2678ACCMap stands for Asynchronous Control Character Map. This is always 2679negotiated with the peer, and defaults to a value of 00000000 in hex. 2680This protocol is required to defeat hardware that depends on passing 2681certain characters from end to end (such as XON/XOFF etc). 2682.Pp 2683For the XON/XOFF scenario, use 2684.Dq set accmap 000a0000 . 2685.It set authkey|key Ar value 2686This sets the authentication key (or password) used in client mode 2687PAP or CHAP negotiation to the given value. It can also be used to 2688specify the password to be used in the dial or login scripts in place 2689of the '\\P' sequence, preventing the actual password from being logged. If 2690.Ar command 2691logging is in effect, 2692.Ar value 2693is logged as 2694.Sq ******** 2695for security reasons. 2696.It set authname Ar id 2697This sets the authentication id used in client mode PAP or CHAP negotiation. 2698.Pp 2699If used in 2700.Fl direct 2701mode with PAP or CHAP enabled, 2702.Ar id 2703is used in the initial authentication request and is normally set to 2704the local machine name. 2705.It set autoload Ar max-duration max-load [min-duration min-load] 2706These settings apply only in multi-link mode and all default to zero. 2707When more than one 2708.Ar demand-dial 2709.Pq also known as Fl auto 2710mode link is available, only the first link is made active when 2711.Nm 2712first reads data from the tun device. The next 2713.Ar demand-dial 2714link will be opened only when at least 2715.Ar max-load 2716packets have been in the send queue for 2717.Ar max-duration 2718seconds. Because both values default to zero, 2719.Ar demand-dial 2720links will simply come up one at a time by default. 2721.Pp 2722If two or more links are open, at least one of which is a 2723.Ar demand-dial 2724link, a 2725.Ar demand-dial 2726link will be closed when there is less than 2727.Ar min-packets 2728in the queue for more than 2729.Ar min-duration . 2730If 2731.Ar min-duration 2732is zero, this timer is disabled. Because both values default to zero, 2733.Ar demand-dial 2734links will stay active until the bundle idle timer expires. 2735.It set callback [none|auth|cbcp|E.164 *|number[,number]...]... 2736If no arguments are given, callback is disabled, otherwise, 2737.Nm 2738will request (or in 2739.Fl direct 2740mode, will accept) one of the given protocols. In client mode, if a 2741request is NAK'd 2742.Nm 2743will request another, until no options remain at which point 2744.Nm 2745will terminate negotiations. In server mode, 2746.Nm 2747will accept any of the given protocols - but the client 2748.Em must 2749request one of them. If you wish callback to be optional, you must include 2750.Ar none 2751as an option. 2752.Pp 2753The options are as follows (in this order of preference): 2754.Pp 2755.Bl -tag 2756.It auth 2757The callee is expected to decide the callback number based on 2758authentication. If 2759.Nm 2760is the callee, the number should be specified as the fifth field of 2761the peers entry in 2762.Pa /etc/ppp/ppp.secret . 2763.It cbcp 2764Microsofts callback control protocol is used. See 2765.Dq set cbcp 2766below. 2767.It E.164 *|number[,number]... 2768The caller specifies the 2769.Ar number . 2770If 2771.Nm 2772is the callee, 2773.Ar number 2774should be either a comma seperated list of allowable numbers or a 2775.Dq \&* , 2776meaning any number is permitted. If 2777.Nm 2778is the caller, only a single number should be specified. 2779.Pp 2780Note, this option is very unsafe when used with a 2781.Dq \&* 2782as a malicious caller can tell 2783.Nm 2784to call any (possibly international) number without first authenticating 2785themselves. 2786.It none 2787If the peer does not wish to do callback at all, 2788.Nm 2789will accept the fact and continue without callback rather than terminating 2790the connection. This is required if you wish callback to be optional. 2791.El 2792.Pp 2793.It set cbcp Op *|number[,number]... Op delay Op retry 2794If no arguments are given, CBCP (Microsofts CallBack Control Protocol) 2795is disabled - ie, configuring CBCP in the 2796.Dq set callback 2797command will result in 2798.Nm 2799requesting no callback in the CBCP phase. 2800Otherwise, 2801.Nm 2802attempts to use the given phone 2803.Ar number Ns No (s). 2804.Pp 2805In server mode 2806.Pq Fl direct , 2807.Nm 2808will insist that the client uses one of these numbers, unless 2809.Dq \&* 2810is used in which case the client is expected to specify the number. 2811.Pp 2812In client mode, 2813.Nm 2814will attempt to use one of the given numbers (whichever it finds to 2815be agreeable with the peer), or if 2816.Dq \&* 2817is specified, 2818.Nm 2819will expect the peer to specify the number. 2820.It set choked Op Ar timeout 2821This sets the number of seconds that 2822.Nm 2823will keep a choked output queue before dropping all pending output packets. 2824If 2825.Ar timeout 2826is less than or equal to zero or if 2827.Ar timeout 2828isn't specified, it is set to the default value of 2829.Em 120 seconds . 2830.Pp 2831A choked output queue occurs when 2832.Nm 2833has read a certain number of packets from the local network for transmission, 2834but cannot send the data due to link failure (the peer is busy etc.). 2835.Nm Ppp 2836will not read packets indefinitely. Instead, it reads up to 2837.Em 20 2838packets (or 2839.Em 20 No + 2840.Em nlinks No * 2841.Em 2 2842packets in multi-link mode), then stops reading the network interface 2843until either 2844.Ar timeout 2845seconds have passed or at least one packet has been sent. 2846.Pp 2847If 2848.Ar timeout 2849seconds pass, all pending output packets are dropped. 2850.It set ctsrts|crtscts on|off 2851This sets hardware flow control. Hardware flow control is 2852.Ar on 2853by default. 2854.It set deflate Ar out-winsize Op Ar in-winsize 2855This sets the DEFLATE algorithms default outgoing and incoming window 2856sizes. Both 2857.Ar out-winsize 2858and 2859.Ar in-winsize 2860must be values between 2861.Em 8 2862and 2863.Em 15 . 2864If 2865.Ar in-winsize 2866is specified, 2867.Nm 2868will insist that this window size is used and will not accept any other 2869values from the peer. 2870.It set dns Op Ar primary Op Ar secondary 2871This command specifies DNS overrides for the 2872.Dq accept dns 2873command. Refer to the 2874.Dq accept 2875command description above for details. This command does not affect the 2876IP numbers requested using 2877.Dq enable dns . 2878.It set device|line Ar value[,value...] 2879This sets the device(s) to which 2880.Nm 2881will talk to the given 2882.Dq value . 2883All serial device names are expected to begin with 2884.Pa /dev/ . 2885If 2886.Dq value 2887does not begin with 2888.Pa /dev/ , 2889it must either begin with an exclamation mark 2890.Pq Dq \&! 2891or be of the format 2892.Dq host:port . 2893.Pp 2894If it begins with an exclamation mark, the rest of the device name is 2895treated as a program name, and that program is executed when the device 2896is opened. Standard input, output and error are fed back to 2897.Nm 2898and are read and written as if they were a regular device. 2899.Pp 2900If a 2901.Dq host:port 2902pair is given, 2903.Nm 2904will attempt to connect to the given 2905.Dq host 2906on the given 2907.Dq port . 2908Refer to the section on 2909.Em PPP OVER TCP 2910above for further details. 2911.Pp 2912If multiple 2913.Dq values 2914are specified, 2915.Nm 2916will attempt to open each one in turn until it succeeds or runs out of 2917devices. 2918.It set dial Ar chat-script 2919This specifies the chat script that will be used to dial the other 2920side. See also the 2921.Dq set login 2922command below. Refer to 2923.Xr chat 8 2924and to the example configuration files for details of the chat script 2925format. 2926It is possible to specify some special 2927.Sq values 2928in your chat script as follows: 2929.Bd -unfilled -offset indent 2930.It Li \\\\\\\\\\\\\\\\c 2931When used as the last character in a 2932.Sq send 2933string, this indicates that a newline should not be appended. 2934.It Li \\\\\\\\\\\\\\\\d 2935When the chat script encounters this sequence, it delays two seconds. 2936.It Li \\\\\\\\\\\\\\\\p 2937When the chat script encounters this sequence, it delays for one quarter of 2938a second. 2939.It Li \\\\\\\\\\\\\\\\n 2940This is replaced with a newline character. 2941.It Li \\\\\\\\\\\\\\\\r 2942This is replaced with a carriage return character. 2943.It Li \\\\\\\\\\\\\\\\s 2944This is replaced with a space character. 2945.It Li \\\\\\\\\\\\\\\\t 2946This is replaced with a tab character. 2947.It Li \\\\\\\\\\\\\\\\T 2948This is replaced by the current phone number (see 2949.Dq set phone 2950below). 2951.It Li \\\\\\\\\\\\\\\\P 2952This is replaced by the current 2953.Ar authkey 2954value (see 2955.Dq set authkey 2956above). 2957.It Li \\\\\\\\\\\\\\\\U 2958This is replaced by the current 2959.Ar authname 2960value (see 2961.Dq set authname 2962above). 2963.Ed 2964.Pp 2965Note that two parsers will examine these escape sequences, so in order to 2966have the 2967.Sq chat parser 2968see the escape character, it is necessary to escape it from the 2969.Sq command parser . 2970This means that in practice you should use two escapes, for example: 2971.Bd -literal -offset indent 2972set dial "... ATDT\\\\T CONNECT" 2973.Ed 2974.Pp 2975It is also possible to execute external commands from the chat script. 2976To do this, the first character of the expect or send string is an 2977exclamation mark 2978.Pq Dq \&! . 2979When the command is executed, standard input and standard output are 2980directed to the modem device (see the 2981.Dq set device 2982command), and standard error is read by 2983.Nm 2984and substituted as the expect or send string. If 2985.Nm 2986is running in interactive mode, file descriptor 3 is attached to 2987.Pa /dev/tty . 2988.Pp 2989For example (wrapped for readability); 2990.Bd -literal -offset indent 2991set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e 2992word: ppp \\"!sh \\\\\\\\-c \\\\\\"echo \\\\\\\\-n label: >&2\\\\\\"\\" \e 2993\\"!/bin/echo in\\" HELLO" 2994.Ed 2995.Pp 2996would result in the following chat sequence (output using the 2997.Sq set log local chat 2998command before dialing): 2999.Bd -literal -offset indent 3000Dial attempt 1 of 1 3001dial OK! 3002Chat: Expecting: 3003Chat: Sending: 3004Chat: Expecting: login:--login: 3005Chat: Wait for (5): login: 3006Chat: Sending: ppp 3007Chat: Expecting: word: 3008Chat: Wait for (5): word: 3009Chat: Sending: ppp 3010Chat: Expecting: !sh \\-c "echo \\-n label: >&2" 3011Chat: Exec: sh -c "echo -n label: >&2" 3012Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label: 3013Chat: Exec: /bin/echo in 3014Chat: Sending: 3015Chat: Expecting: HELLO 3016Chat: Wait for (5): HELLO 3017login OK! 3018.Ed 3019.Pp 3020Note (again) the use of the escape character, allowing many levels of 3021nesting. Here, there are four parsers at work. The first parses the 3022original line, reading it as three arguments. The second parses the 3023third argument, reading it as 11 arguments. At this point, it is 3024important that the 3025.Dq \&- 3026signs are escaped, otherwise this parser will see them as constituting 3027an expect-send-expect sequence. When the 3028.Dq \&! 3029character is seen, the execution parser reads the first command as three 3030arguments, and then 3031.Xr sh 1 3032itself expands the argument after the 3033.Fl c . 3034As we wish to send the output back to the modem, in the first example 3035we redirect our output to file descriptor 2 (stderr) so that 3036.Nm 3037itself sends and logs it, and in the second example, we just output to stdout, 3038which is attached directly to the modem. 3039.Pp 3040This, of course means that it is possible to execute an entirely external 3041.Dq chat 3042command rather than using the internal one. See 3043.Xr chat 8 3044for a good alternative. 3045.It set enddisc Op label|IP|MAC|magic|psn value 3046This command sets our local endpoint discriminator. If set prior to 3047LCP negotiation, 3048.Nm 3049will send the information to the peer using the LCP endpoint discriminator 3050option. The following discriminators may be set: 3051.Bd -unfilled -offset indent 3052.It Li label 3053The current label is used. 3054.It Li IP 3055Our local IP number is used. As LCP is negotiated prior to IPCP, it is 3056possible that the IPCP layer will subsequently change this value. If 3057it does, the endpoint discriminator stays at the old value unless manually 3058reset. 3059.It Li MAC 3060This is similar to the 3061.Ar IP 3062option above, except that the MAC address associated with the local IP 3063number is used. If the local IP number is not resident on any Ethernet 3064interface, the command will fail. 3065.Pp 3066As the local IP number defaults to whatever the machine host name is, 3067.Dq set enddisc mac 3068is usually done prior to any 3069.Dq set ifaddr 3070commands. 3071.It Li magic 3072A 20 digit random number is used. 3073.It Li psn Ar value 3074The given 3075.Ar value 3076is used. 3077.Ar Value 3078should be set to an absolute public switched network number with the 3079country code first. 3080.Ed 3081.Pp 3082If no arguments are given, the endpoint discriminator is reset. 3083.It set escape Ar value... 3084This option is similar to the 3085.Dq set accmap 3086option above. It allows the user to specify a set of characters that 3087will be `escaped' as they travel across the link. 3088.It set filter dial|alive|in|out rule-no permit|deny Ar "[src_addr/width] [dst_addr/width] [proto [src [lt|eq|gt port]] [dst [lt|eq|gt port]] [estab] [syn] [finrst]]" 3089.Nm Ppp 3090supports four filter sets. The 3091.Em alive 3092filter specifies packets that keep the connection alive - reseting the 3093idle timer. The 3094.Em dial 3095filter specifies packets that cause 3096.Nm 3097to dial when in 3098.Fl auto 3099mode. The 3100.Em in 3101filter specifies packets that are allowed to travel 3102into the machine and the 3103.Em out 3104filter specifies packets that are allowed out of the machine. 3105.Pp 3106Filtering is done prior to any IP alterations that might be done by the 3107alias engine. By default all filter sets allow all packets to pass. 3108Rules are processed in order according to 3109.Ar rule-no . 3110Up to 20 rules may be given for each set. If a packet doesn't match 3111any of the rules in a given set, it is discarded. In the case of 3112.Em in 3113and 3114.Em out 3115filters, this means that the packet is dropped. In the case of 3116.Em alive 3117filters it means that the packet will not reset the idle timer and in 3118the case of 3119.Em dial 3120filters it means that the packet will not trigger a dial. A packet failing 3121to trigger a dial will be dropped rather than queued. Refer to the 3122section on PACKET FILTERING above for further details. 3123.It set hangup Ar chat-script 3124This specifies the chat script that will be used to reset the modem 3125before it is closed. It should not normally be necessary, but can 3126be used for devices that fail to reset themselves properly on close. 3127.It set help|? Op Ar command 3128This command gives a summary of available set commands, or if 3129.Ar command 3130is specified, the command usage is shown. 3131.It set ifaddr Ar [myaddr [hisaddr [netmask [triggeraddr]]]] 3132This command specifies the IP addresses that will be used during 3133IPCP negotiation. Addresses are specified using the format 3134.Pp 3135.Dl a.b.c.d/n 3136.Pp 3137Where 3138.Ar a.b.c.d 3139is the preferred IP, but 3140.Ar n 3141specifies how many bits of the address we will insist on. If 3142.Ar /n 3143is omitted, it defaults to 3144.Ar /32 3145unless the IP address is 0.0.0.0 in which case it defaults to 3146.Ar /0 . 3147.Pp 3148.Ar Hisaddr 3149may also be specified as a range of IP numbers in the format 3150.Pp 3151.Dl a.b.c.d[-d.e.f.g][,h.i.j.k[-l,m,n,o]]... 3152.Pp 3153for example: 3154.Pp 3155.Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20 3156.Pp 3157will only negotiate 3158.Ar 10.0.0.1 3159as the local IP number, but may assign any of the given 10 IP 3160numbers to the peer. If the peer requests one of these numbers, 3161and that number is not already in use, 3162.Nm 3163will grant the peers request. This is useful if the peer wants 3164to re-establish a link using the same IP number as was previously 3165allocated (thus maintaining any existing tcp connections). 3166.Pp 3167If the peer requests an IP number that's either outside 3168of this range or is already in use, 3169.Nm 3170will suggest a random unused IP number from the range. 3171.Pp 3172If 3173.Ar triggeraddr 3174is specified, it is used in place of 3175.Ar myaddr 3176in the initial IPCP negotiation. However, only an address in the 3177.Ar myaddr 3178range will be accepted. This is useful when negotiating with some 3179.Dv PPP 3180implementations that will not assign an IP number unless their peer 3181requests 3182.Ar 0.0.0.0 . 3183.Pp 3184It should be noted that in 3185.Fl auto 3186mode, 3187.Nm 3188will configure the interface immediately upon reading the 3189.Dq set ifaddr 3190line in the config file. In any other mode, these values are just 3191used for IPCP negotiations, and the interface isn't configured 3192until the IPCP layer is up. 3193.Pp 3194Note that the 3195.Ar HISADDR 3196argument may be overridden by the third field in the 3197.Pa ppp.secret 3198file once the client has authenticated itself 3199.Pq if PAP or CHAP are Dq enabled . 3200Refer to the 3201.Em AUTHENTICATING INCOMING CONNECTIONS 3202section for details. 3203.Pp 3204In all cases, if the interface is already configured, 3205.Nm 3206will try to maintain the interface IP numbers so that any existing 3207bound sockets will remain valid. 3208.It set ccpretry Ar period 3209.It set chapretry Ar period 3210.It set ipcpretry Ar period 3211.It set lcpretry Ar period 3212.It set papretry Ar period 3213These commands set the number of seconds that 3214.Nm 3215will wait before resending Finite State Machine (FSM) Request packets. 3216The default 3217.Ar period 3218for all FSMs is 3 seconds (which should suffice in most cases). 3219.It set log [local] [+|-] Ns Ar value... 3220This command allows the adjustment of the current log level. Refer 3221to the Logging Facility section for further details. 3222.It set login Ar chat-script 3223This 3224.Ar chat-script 3225compliments the dial-script. If both are specified, the login 3226script will be executed after the dial script. Escape sequences 3227available in the dial script are also available here. 3228.It set lqrperiod Ar frequency 3229This command sets the 3230.Ar frequency 3231in seconds at which 3232.Em LQR 3233or 3234.Em ECHO LQR 3235packets are sent. The default is 30 seconds. You must also use the 3236.Dq enable lqr 3237command if you wish to send LQR requests to the peer. 3238.It set mode Ar interactive|auto|ddial|background 3239This command allows you to change the 3240.Sq mode 3241of the specified link. This is normally only useful in multi-link mode, 3242but may also be used in uni-link mode. 3243.Pp 3244It is not possible to change a link that is 3245.Sq direct 3246or 3247.Sq dedicated . 3248.Pp 3249Note: If you issue the command 3250.Dq set mode auto , 3251and have IP aliasing enabled, it may be useful to 3252.Dq enable iface-alias 3253afterwards. This will allow 3254.Nm 3255to do the necessary address translations to enable the process that 3256triggers the connection to connect once the link is up despite the 3257peer assigning us a new (dynamic) IP address. 3258.It set mrru Op Ar value 3259Setting this option enables Multi-link PPP negotiations, also known as 3260Multi-link Protocol or MP. There is no default MRRU (Maximum 3261Reconstructed Receive Unit) value. If no argument is given, multi-link 3262mode is disabled. 3263.It set mru Op Ar value 3264The default MRU (Maximum Receive Unit) is 1500. If it is increased, the 3265other side *may* increase its mtu. There is no point in decreasing the 3266MRU to below the default as the 3267.Em PPP 3268protocol *must* be able to accept packets of at least 1500 octets. If 3269no argument is given, 1500 is assumed. 3270.It set mtu Op Ar value 3271The default MTU is 1500. At negotiation time, 3272.Nm 3273will accept whatever MRU or MRRU that the peer wants (assuming it's 3274not less than 296 bytes). If the MTU is set, 3275.Nm 3276will not accept MRU/MRRU values less than 3277.Ar value . 3278When negotiations are complete, the MTU is assigned to the interface, even 3279if the peer requested a higher value MRU/MRRU. This can be useful for 3280limiting your packet size (giving better bandwidth sharing at the expense 3281of more header data). 3282.Pp 3283If no 3284.Ar value 3285is given, 1500, or whatever the peer asks for is used. 3286.It set nbns Op Ar x.x.x.x Op Ar y.y.y.y 3287This option allows the setting of the Microsoft NetBIOS name server 3288values to be returned at the peers request. If no values are given, 3289.Nm 3290will reject any such requests. 3291.It set openmode active|passive Op Ar delay 3292By default, 3293.Ar openmode 3294is always 3295.Ar active 3296with a one second 3297.Ar delay . 3298That is, 3299.Nm 3300will always initiate LCP/IPCP/CCP negotiation one second after the line 3301comes up. If you want to wait for the peer to initiate negotiations, you 3302can use the value 3303.Ar passive . 3304If you want to initiate negotiations immediately or after more than one 3305second, the appropriate 3306.Ar delay 3307may be specified here in seconds. 3308.It set parity odd|even|none|mark 3309This allows the line parity to be set. The default value is 3310.Ar none . 3311.It set phone Ar telno[|telno]...[:telno[|telno]...]... 3312This allows the specification of the phone number to be used in 3313place of the \\\\T string in the dial and login chat scripts. 3314Multiple phone numbers may be given separated by a pipe (|) or 3315a colon (:). Numbers after the pipe are only dialed if the dial or login 3316script for the previous number failed. Numbers separated by a colon are 3317tried sequentially, irrespective of the reason the line was dropped. 3318If multiple numbers are given, 3319.Nm 3320will dial them according to these rules until a connection is made, retrying 3321the maximum number of times specified by 3322.Dq set redial 3323below. In 3324.Fl background 3325mode, each number is attempted at most once. 3326.It set [proc]title Op Ar value 3327The current process title as displayed by 3328.Xr ps 1 3329is changed according to 3330.Ar value . 3331If 3332.Ar value 3333is not specified, the original process title is restored. All the 3334word replacements done by the shell commands (see the 3335.Dq bg 3336command above) are done here too. 3337.It set reconnect Ar timeout ntries 3338Should the line drop unexpectedly (due to loss of CD or LQR 3339failure), a connection will be re-established after the given 3340.Ar timeout . 3341The line will be re-connected at most 3342.Ar ntries 3343times. 3344.Ar Ntries 3345defaults to zero. A value of 3346.Ar random 3347for 3348.Ar timeout 3349will result in a variable pause, somewhere between 0 and 30 seconds. 3350.It set recvpipe Op Ar value 3351This sets the routing table RECVPIPE value. The optimum value is 3352just over twice the MTU value. If 3353.Ar value 3354is unspecified or zero, the default kernel controlled value is used. 3355.It set redial Ar seconds[.nseconds] [attempts] 3356.Nm Ppp 3357can be instructed to attempt to redial 3358.Ar attempts 3359times. If more than one phone number is specified (see 3360.Dq set phone 3361above), a pause of 3362.Ar nseconds 3363is taken before dialing each number. A pause of 3364.Ar seconds 3365is taken before starting at the first number again. A value of 3366.Ar random 3367may be used here in place of 3368.Ar seconds 3369and 3370.Ar nseconds , 3371causing a random delay of between 0 and 30 seconds. 3372.Pp 3373Note, this delay will be effective, even after 3374.Ar attempts 3375has been exceeded, so an immediate manual dial may appear to have 3376done nothing. If an immediate dial is required, a 3377.Dq \&! 3378should immediately follow the 3379.Dq open 3380keyword. See the 3381.Dq open 3382description above for further details. 3383.It set sendpipe Op Ar value 3384This sets the routing table SENDPIPE value. The optimum value is 3385just over twice the MTU value. If 3386.Ar value 3387is unspecified or zero, the default kernel controlled value is used. 3388.It set server|socket Ar TcpPort|LocalName|none password Op Ar mask 3389This command tells 3390.Nm 3391to listen on the given socket or 3392.Sq diagnostic port 3393for incoming command connections. 3394.Pp 3395The word 3396.Ar none 3397instructs 3398.Nm 3399to close any existing socket. 3400.Pp 3401If you wish to specify a local domain socket, 3402.Ar LocalName 3403must be specified as an absolute file name, otherwise it is assumed 3404to be the name or number of a TCP port. You may specify the octal umask that 3405should be used with local domain sockets as a four character octal number 3406beginning with 3407.Sq 0 . 3408Refer to 3409.Xr umask 2 3410for umask details. Refer to 3411.Xr services 5 3412for details of how to translate TCP port names. 3413.Pp 3414You must also specify the password that must be entered by the client 3415(using the 3416.Dq passwd 3417command above) when connecting to this socket. If the password is 3418specified as an empty string, no password is required for connecting clients. 3419.Pp 3420When specifying a local domain socket, the first 3421.Dq %d 3422sequence found in the socket name will be replaced with the current 3423interface unit number. This is useful when you wish to use the same 3424profile for more than one connection. 3425.Pp 3426In a similar manner TCP sockets may be prefixed with the 3427.Dq + 3428character, in which case the current interface unit number is added to 3429the port number. 3430.Pp 3431When using 3432.Nm 3433with a server socket, the 3434.Xr pppctl 8 3435command is the preferred mechanism of communications. Currently, 3436.Xr telnet 1 3437can also be used, but link encryption may be implemented in the future, so 3438.Xr telnet 1 3439should not be relied upon. 3440.It set speed Ar value 3441This sets the speed of the serial device. 3442.It set stopped Ar [LCPseconds [CCPseconds]] 3443If this option is set, 3444.Nm 3445will time out after the given FSM (Finite State Machine) has been in 3446the stopped state for the given number of 3447.Dq seconds . 3448This option may be useful if the peer sends a terminate request, 3449but never actually closes the connection despite our sending a terminate 3450acknowledgement. This is also useful if you wish to 3451.Dq set openmode passive 3452and time out if the peer doesn't send a Configure Request within the 3453given time. Use 3454.Dq set log +lcp +ccp 3455to make 3456.Nm 3457log the appropriate state transitions. 3458.Pp 3459The default value is zero, where 3460.Nm 3461doesn't time out in the stopped state. 3462.Pp 3463This value should not be set to less than the openmode delay (see 3464.Dq set openmode 3465above). 3466.It set timeout Ar idleseconds 3467This command allows the setting of the idle timer. Refer to the 3468section titled 3469.Dq SETTING THE IDLE TIMER 3470for further details. 3471.It set vj slotcomp on|off 3472This command tells 3473.Nm 3474whether it should attempt to negotiate VJ slot compression. By default, 3475slot compression is turned 3476.Ar on . 3477.It set vj slots Ar nslots 3478This command sets the initial number of slots that 3479.Nm 3480will try to negotiate with the peer when VJ compression is enabled (see the 3481.Sq enable 3482command above). It defaults to a value of 16. 3483.Ar Nslots 3484must be between 3485.Ar 4 3486and 3487.Ar 16 3488inclusive. 3489.El 3490.Pp 3491.It shell|! Op Ar command 3492If 3493.Ar command 3494is not specified a shell is invoked according to the 3495.Dv SHELL 3496environment variable. Otherwise, the given 3497.Ar command 3498is executed. Word replacement is done in the same way as for the 3499.Dq !bg 3500commanad as described above. 3501.Pp 3502Use of the ! character 3503requires a following space as with any of the other commands. You should 3504note that this command is executed in the foreground - 3505.Nm 3506will not continue running until this process has exited. Use the 3507.Dv bg 3508command if you wish processing to happen in the background. 3509.It show Ar var 3510This command allows the user to examine the following: 3511.Bl -tag -width XX 3512.It show bundle 3513Show the current bundle settings. 3514.It show ccp 3515Show the current CCP compression statistics. 3516.It show compress 3517Show the current VJ compression statistics. 3518.It show escape 3519Show the current escape characters. 3520.It show filter Op Ar name 3521List the current rules for the given filter. If 3522.Ar name 3523is not specified, all filters are shown. 3524.It show hdlc 3525Show the current HDLC statistics. 3526.It show help|? 3527Give a summary of available show commands. 3528.It show iface 3529Show the current interface information 3530.Pq the same \&as Dq iface show . 3531.It show ipcp 3532Show the current IPCP statistics. 3533.It show lcp 3534Show the current LCP statistics. 3535.It show [data]link 3536Show high level link information. 3537.It show links 3538Show a list of available logical links. 3539.It show log 3540Show the current log values. 3541.It show mem 3542Show current memory statistics. 3543.It show modem 3544Show low level link information. 3545.It show proto 3546Show current protocol totals. 3547.It show route 3548Show the current routing tables. 3549.It show stopped 3550Show the current stopped timeouts. 3551.It show timer 3552Show the active alarm timers. 3553.It show version 3554Show the current version number of 3555.Nm ppp . 3556.El 3557.Pp 3558.It term 3559Go into terminal mode. Characters typed at the keyboard are sent to 3560the modem. Characters read from the modem are displayed on the 3561screen. When a 3562.Nm 3563peer is detected on the other side of the modem, 3564.Nm 3565automatically enables Packet Mode and goes back into command mode. 3566.El 3567.Pp 3568.Sh MORE DETAILS 3569.Bl -bullet 3570.It 3571Read the example configuration files. They are a good source of information. 3572.It 3573Use 3574.Dq help , 3575.Dq alias ? , 3576.Dq enable ? , 3577.Dq set ? 3578and 3579.Dq show ? 3580to get online information about what's available. 3581.It 3582The following urls contain useful information: 3583.Bl -bullet -compact 3584.It 3585http://www.FreeBSD.org/FAQ/userppp.html 3586.It 3587http://www.FreeBSD.org/handbook/userppp.html 3588.El 3589.Pp 3590.El 3591.Pp 3592.Sh FILES 3593.Nm Ppp 3594refers to four files: 3595.Pa ppp.conf , 3596.Pa ppp.linkup , 3597.Pa ppp.linkdown 3598and 3599.Pa ppp.secret . 3600These files are placed in the 3601.Pa /etc/ppp 3602directory. 3603.Bl -tag -width XX 3604.It Pa /etc/ppp/ppp.conf 3605System default configuration file. 3606.It Pa /etc/ppp/ppp.secret 3607An authorisation file for each system. 3608.It Pa /etc/ppp/ppp.linkup 3609A file to check when 3610.Nm 3611establishes a network level connection. 3612.It Pa /etc/ppp/ppp.linkdown 3613A file to check when 3614.Nm 3615closes a network level connection. 3616.It Pa /var/log/ppp.log 3617Logging and debugging information file. Note, this name is specified in 3618.Pa /etc/syslogd.conf . 3619See 3620.Xr syslog.conf 5 3621for further details. 3622.It Pa /var/spool/lock/LCK..* 3623tty port locking file. Refer to 3624.Xr uucplock 3 3625for further details. 3626.It Pa /var/run/tunN.pid 3627The process id (pid) of the 3628.Nm 3629program connected to the tunN device, where 3630.Sq N 3631is the number of the device. 3632.It Pa /var/run/ttyXX.if 3633The tun interface used by this port. Again, this file is only created in 3634.Fl background , 3635.Fl auto 3636and 3637.Fl ddial 3638modes. 3639.It Pa /etc/services 3640Get port number if port number is using service name. 3641.It Pa /var/run/ppp-authname-class-value 3642In multi-link mode, local domain sockets are created using the peer 3643authentication name 3644.Pq Sq authname , 3645the peer endpoint discriminator class 3646.Pq Sq class 3647and the peer endpoint discriminator value 3648.Pq Sq value . 3649As the endpoint discriminator value may be a binary value, it is turned 3650to HEX to determine the actual file name. 3651.Pp 3652This socket is used to pass links between different instances of 3653.Nm ppp . 3654.El 3655.Pp 3656.Sh SEE ALSO 3657.Xr at 1 , 3658.Xr ftp 1 , 3659.Xr gzip 1 , 3660.Xr hostname 1 , 3661.Xr login 1 , 3662.Xr tcpdump 1 , 3663.Xr telnet 1 , 3664.Xr syslog 3 , 3665.Xr uucplock 3 , 3666.Xr crontab 5 , 3667.Xr group 5 , 3668.Xr passwd 5 , 3669.Xr resolv.conf 5 , 3670.Xr syslog.conf 5 , 3671.Xr adduser 8 , 3672.Xr chat 8 , 3673.Xr getty 8 , 3674.Xr inetd 8 , 3675.Xr init 8 , 3676.Xr named 8 , 3677.Xr ping 8 , 3678.Xr pppctl 8 , 3679.Xr pppd 8 , 3680.Xr route 8 , 3681.Xr syslogd 8 , 3682.Xr traceroute 8 , 3683.Xr vipw 8 3684.Sh HISTORY 3685This program was originally written by Toshiharu OHNO (tony-o@iij.ad.jp), 3686and was submitted to FreeBSD-2.0.5 by Atsushi Murai (amurai@spec.co.jp). 3687.Pp 3688It was substantially modified during 1997 by Brian Somers 3689(brian@Awfulhak.org), and was ported to OpenBSD in November that year 3690(just after the 2.2 release). 3691.Pp 3692Most of the code was rewritten by Brian Somers in early 1998 when 3693multi-link ppp support was added. 3694