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