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