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