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 , 1986.Sq logout 1987and 1988.Sq hangup 1989chat script trace logs. 1990.It Li Command 1991Log commands executed either from the command line or any of the configuration 1992files. 1993.It Li Connect 1994Log Chat lines containing the string "CONNECT". 1995.It Li Debug 1996Log debug information. 1997.It Li HDLC 1998Dump HDLC packet in hex. 1999.It Li ID0 2000Log all function calls specifically made as user id 0. 2001.It Li IPCP 2002Generate an IPCP packet trace. 2003.It Li LCP 2004Generate an LCP packet trace. 2005.It Li LQM 2006Generate LQR reports. 2007.It Li Phase 2008Phase transition log output. 2009.It Li Physical 2010Dump physical level packet in hex. 2011.It Li Sync 2012Dump sync level packet in hex. 2013.It Li TCP/IP 2014Dump all TCP/IP packets. 2015.It Li Timer 2016Log timer manipulation. 2017.It Li TUN 2018Include the tun device on each log line. 2019.It Li Warning 2020Output to the terminal device. If there is currently no terminal, 2021output is sent to the log file using syslogs 2022.Dv LOG_WARNING . 2023.It Li Error 2024Output to both the terminal device 2025and the log file using syslogs 2026.Dv LOG_ERROR . 2027.It Li Alert 2028Output to the log file using 2029.Dv LOG_ALERT . 2030.El 2031.Pp 2032The 2033.Dq set log 2034command allows you to set the logging output level. Multiple levels 2035can be specified on a single command line. The default is equivalent to 2036.Dq set log Phase . 2037.Pp 2038It is also possible to log directly to the screen. The syntax is 2039the same except that the word 2040.Dq local 2041should immediately follow 2042.Dq set log . 2043The default is 2044.Dq set log local 2045(ie. only the un-maskable warning, error and alert output). 2046.Pp 2047If The first argument to 2048.Dq set log Op local 2049begins with a 2050.Sq + 2051or a 2052.Sq - 2053character, the current log levels are 2054not cleared, for example: 2055.Bd -literal -offset indent 2056PPP ON awfulhak> set log phase 2057PPP ON awfulhak> show log 2058Log: Phase Warning Error Alert 2059Local: Warning Error Alert 2060PPP ON awfulhak> set log +tcp/ip -warning 2061PPP ON awfulhak> set log local +command 2062PPP ON awfulhak> show log 2063Log: Phase TCP/IP Warning Error Alert 2064Local: Command Warning Error Alert 2065.Ed 2066.Pp 2067Log messages of level Warning, Error and Alert are not controllable 2068using 2069.Dq set log Op local . 2070.Pp 2071The 2072.Ar Warning 2073level is special in that it will not be logged if it can be displayed 2074locally. 2075.Sh SIGNAL HANDLING 2076.Nm 2077deals with the following signals: 2078.Bl -tag -width XX 2079.It INT 2080Receipt of this signal causes the termination of the current connection 2081(if any). This will cause 2082.Nm 2083to exit unless it is in 2084.Fl auto 2085or 2086.Fl ddial 2087mode. 2088.It HUP, TERM & QUIT 2089These signals tell 2090.Nm 2091to exit. 2092.It USR2 2093This signal, tells 2094.Nm 2095to close any existing server socket, dropping all existing diagnostic 2096connections. 2097.El 2098.Pp 2099.Sh MULTI-LINK PPP 2100If you wish to use more than one physical link to connect to a 2101.Em PPP 2102peer, that peer must also understand the 2103.Em MULTI-LINK PPP 2104protocol. Refer to RFC 1990 for specification details. 2105.Pp 2106The peer is identified using a combination of his 2107.Dq endpoint discriminator 2108and his 2109.Dq authentication id . 2110Either or both of these may be specified. It is recommended that 2111at least one is specified, otherwise there is no way of ensuring that 2112all links are actually connected to the same peer program, and some 2113confusing lock-ups may result. Locally, these identification variables 2114are specified using the 2115.Dq set enddisc 2116and 2117.Dq set authname 2118commands. The 2119.Sq authname 2120.Pq and Sq authkey 2121must be agreed in advance with the peer. 2122.Pp 2123Multi-link capabilities are enabled using the 2124.Dq set mrru 2125command (set maximum reconstructed receive unit). Once multi-link 2126is enabled, 2127.Nm 2128will attempt to negotiate a multi-link connection with the peer. 2129.Pp 2130By default, only one 2131.Sq link 2132is available 2133.Pq called Sq deflink . 2134To create more links, the 2135.Dq clone 2136command is used. This command will clone existing links, where all 2137characteristics are the same except: 2138.Bl -enum 2139.It 2140The new link has its own name as specified on the 2141.Dq clone 2142command line. 2143.It 2144The new link is an 2145.Sq interactive 2146link. It's mode may subsequently be changed using the 2147.Dq set mode 2148command. 2149.It 2150The new link is in a 2151.Sq closed 2152state. 2153.El 2154.Pp 2155A summary of all available links can be seen using the 2156.Dq show links 2157command. 2158.Pp 2159Once a new link has been created, command usage varies. All link 2160specific commands must be prefixed with the 2161.Dq link Ar name 2162command, specifying on which link the command is to be applied. When 2163only a single link is available, 2164.Nm 2165is smart enough not to require the 2166.Dq link Ar name 2167prefix. 2168.Pp 2169Some commands can still be used without specifying a link - resulting 2170in an operation at the 2171.Sq bundle 2172level. For example, once two or more links are available, the command 2173.Dq show ccp 2174will show CCP configuration and statistics at the multi-link level, and 2175.Dq link deflink show ccp 2176will show the same information at the 2177.Dq deflink 2178link level. 2179.Pp 2180Armed with this information, the following configuration might be used: 2181.Pp 2182.Bd -literal -offset indent 2183mp: 2184 set timeout 0 2185 set log phase chat 2186 set device /dev/cuaa0 /dev/cuaa1 /dev/cuaa2 2187 set phone "123456789" 2188 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \\"\\" ATZ \e 2189 OK-AT-OK \\\\dATDT\\\\T TIMEOUT 45 CONNECT" 2190 set login 2191 set ifaddr 10.0.0.1/0 10.0.0.2/0 2192 set authname ppp 2193 set authkey ppppassword 2194 2195 set mrru 1500 2196 clone 1,2,3 2197 link deflink remove 2198.Ed 2199.Pp 2200Note how all cloning is done at the end of the configuration. Usually, 2201the link will be configured first, then cloned. If you wish all links 2202to be up all the time, you can add the following line to the end of your 2203configuration. 2204.Pp 2205.Bd -literal -offset indent 2206 link 1,2,3 set mode ddial 2207.Ed 2208.Pp 2209If you want the links to dial on demand, this command could be used: 2210.Pp 2211.Bd -literal -offset indent 2212 link * set mode auto 2213.Ed 2214.Pp 2215Links may be tied to specific names by removing the 2216.Dq set device 2217line above, and specifying the following after the 2218.Dq clone 2219command: 2220.Pp 2221.Bd -literal -offset indent 2222 link 1 set device /dev/cuaa0 2223 link 2 set device /dev/cuaa1 2224 link 3 set device /dev/cuaa2 2225.Ed 2226.Pp 2227Use the 2228.Dq help 2229command to see which commands require context (using the 2230.Dq link 2231command), which have optional 2232context and which should not have any context. 2233.Pp 2234When 2235.Nm 2236has negotiated 2237.Em MULTI-LINK 2238mode with the peer, it creates a local domain socket in the 2239.Pa /var/run 2240directory. This socket is used to pass link information (including 2241the actual link file descriptor) between different 2242.Nm 2243invocations. This facilitates 2244.Nm ppp Ns No s 2245ability to be run from a 2246.Xr getty 8 2247or directly from 2248.Pa /etc/gettydefs 2249(using the 2250.Sq pp= 2251capability), without needing to have initial control of the serial 2252line. Once 2253.Nm 2254negotiates multi-link mode, it will pass its open link to any 2255already running process. If there is no already running process, 2256.Nm 2257will act as the master, creating the socket and listening for new 2258connections. 2259.Sh PPP COMMAND LIST 2260This section lists the available commands and their effect. They are 2261usable either from an interactive 2262.Nm 2263session, from a configuration file or from a 2264.Xr pppctl 8 2265or 2266.Xr telnet 1 2267session. 2268.Bl -tag -width XX 2269.It accept|deny|enable|disable Ar option.... 2270These directives tell 2271.Nm 2272how to negotiate the initial connection with the peer. Each 2273.Dq option 2274has a default of either accept or deny and enable or disable. 2275.Dq Accept 2276means that the option will be ACK'd if the peer asks for it. 2277.Dq Deny 2278means that the option will be NAK'd if the peer asks for it. 2279.Dq Enable 2280means that the option will be requested by us. 2281.Dq Disable 2282means that the option will not be requested by us. 2283.Pp 2284.Dq Option 2285may be one of the following: 2286.Bl -tag -width XX 2287.It acfcomp 2288Default: Enabled and Accepted. ACFComp stands for Address and Control 2289Field Compression. Non LCP packets will usually have an address 2290field of 0xff (the All-Stations address) and a control field of 22910x03 (the Unnumbered Information command). If this option is 2292negotiated, these two bytes are simply not sent, thus minimising 2293traffic. 2294.Pp 2295See 2296.Pa rfc1662 2297for details. 2298.It chap Ns Op \&05 2299Default: Disabled and Accepted. CHAP stands for Challenge Handshake 2300Authentication Protocol. Only one of CHAP and PAP (below) may be 2301negotiated. With CHAP, the authenticator sends a "challenge" message 2302to its peer. The peer uses a one-way hash function to encrypt the 2303challenge and sends the result back. The authenticator does the same, 2304and compares the results. The advantage of this mechanism is that no 2305passwords are sent across the connection. 2306A challenge is made when the connection is first made. Subsequent 2307challenges may occur. If you want to have your peer authenticate 2308itself, you must 2309.Dq enable chap . 2310in 2311.Pa /etc/ppp/ppp.conf , 2312and have an entry in 2313.Pa /etc/ppp/ppp.secret 2314for the peer. 2315.Pp 2316When using CHAP as the client, you need only specify 2317.Dq AuthName 2318and 2319.Dq AuthKey 2320in 2321.Pa /etc/ppp/ppp.conf . 2322CHAP is accepted by default. 2323Some 2324.Em PPP 2325implementations use "MS-CHAP" rather than MD5 when encrypting the 2326challenge. MS-CHAP is a combination of MD4 and DES. If 2327.Nm 2328was built on a machine with DES libraries available, it will respond 2329to MS-CHAP authentication requests, but will never request them. 2330.It deflate 2331Default: Enabled and Accepted. This option decides if deflate 2332compression will be used by the Compression Control Protocol (CCP). 2333This is the same algorithm as used by the 2334.Xr gzip 1 2335program. 2336Note: There is a problem negotiating 2337.Ar deflate 2338capabilities with 2339.Xr pppd 8 2340- a 2341.Em PPP 2342implementation available under many operating systems. 2343.Nm pppd 2344(version 2.3.1) incorrectly attempts to negotiate 2345.Ar deflate 2346compression using type 2347.Em 24 2348as the CCP configuration type rather than type 2349.Em 26 2350as specified in 2351.Pa rfc1979 . 2352Type 2353.Ar 24 2354is actually specified as 2355.Dq PPP Magna-link Variable Resource Compression 2356in 2357.Pa rfc1975 Ns No ! 2358.Nm 2359is capable of negotiating with 2360.Nm pppd , 2361but only if 2362.Dq deflate24 2363is 2364.Ar enable Ns No d 2365and 2366.Ar accept Ns No ed . 2367.It deflate24 2368Default: Disabled and Denied. This is a variance of the 2369.Ar deflate 2370option, allowing negotiation with the 2371.Xr pppd 8 2372program. Refer to the 2373.Ar deflate 2374section above for details. It is disabled by default as it violates 2375.Pa rfc1975 . 2376.It dns 2377Default: Disabled and Denied. This option allows DNS negotiation. 2378.Pp 2379If 2380.Dq enable Ns No d, 2381.Nm 2382will request that the peer confirms the entries in 2383.Pa /etc/resolv.conf . 2384If the peer NAKs our request (suggesting new IP numbers), 2385.Pa /etc/resolv.conf 2386is updated and another request is sent to confirm the new entries. 2387.Pp 2388If 2389.Dq accept Ns No ed, 2390.Nm 2391will answer any DNS queries requested by the peer rather than rejecting 2392them. The answer is taken from 2393.Pa /etc/resolv.conf 2394unless the 2395.Dq set dns 2396command is used as an override. 2397.It enddisc 2398Default: Enabled and Accepted. This option allows control over whether we 2399negotiate an endpoint discriminator. We only send our discriminator if 2400.Dq set enddisc 2401is used and 2402.Ar enddisc 2403is enabled. We reject the peers discriminator if 2404.Ar enddisc 2405is denied. 2406.It LANMan|chap80lm 2407Default: Disabled and Accepted. The use of this authentication protocol 2408is discouraged as it partially violates the authentication protocol by 2409implementing two different mechanisms (LANMan & NT) under the guise of 2410a single CHAP type (0x80). 2411.Dq LANMan 2412uses a simple DES encryption mechanism and is the least secure of the 2413CHAP alternatives (although is still more secure than PAP). 2414.Pp 2415Refer to the 2416.Dq MSChap 2417description below for more details. 2418.It lqr 2419Default: Disabled and Accepted. This option decides if Link Quality 2420Requests will be sent or accepted. LQR is a protocol that allows 2421.Nm 2422to determine that the link is down without relying on the modems 2423carrier detect. When LQR is enabled, 2424.Nm 2425sends the 2426.Em QUALPROTO 2427option (see 2428.Dq set lqrperiod 2429below) as part of the LCP request. If the peer agrees, both sides will 2430exchange LQR packets at the agreed frequency, allowing detailed link 2431quality monitoring by enabling LQM logging. If the peer doesn't agree, 2432ppp will send ECHO LQR requests instead. These packets pass no 2433information of interest, but they 2434.Em MUST 2435be replied to by the peer. 2436.Pp 2437Whether using LQR or ECHO LQR, 2438.Nm 2439will abruptly drop the connection if 5 unacknowledged packets have been 2440sent rather than sending a 6th. A message is logged at the 2441.Em PHASE 2442level, and any appropriate 2443.Dq reconnect 2444values are honoured as if the peer were responsible for dropping the 2445connection. 2446.It MSChap|chap80nt 2447Default: Disabled and Accepted. The use of this authentication protocol 2448is discouraged as it partially violates the authentication protocol by 2449implementing two different mechanisms (LANMan & NT) under the guise of 2450a single CHAP type (0x80). It is very similar to standard CHAP (type 0x05) 2451except that it issues challenges of a fixed 8 bytes in length and uses a 2452combination of MD4 and DES to encrypt the challenge rather than using the 2453standard MD5 mechanism. CHAP type 0x80 for LANMan is also supported - see 2454.Dq enable LANMan 2455for details. 2456.Pp 2457Because both 2458.Dq LANMan 2459and 2460.Dq NT 2461use CHAP type 0x80, when acting as authenticator with both 2462.Dq enable Ns No d , 2463.Nm 2464will rechallenge the peer up to three times if it responds using the wrong 2465one of the two protocols. This gives the peer a chance to attempt using 2466both protocols. 2467.Pp 2468Conversely, when 2469.Nm 2470acts as the authenticatee with both protocols 2471.Dq accept Ns No ed , 2472the protocols are used alternately in response to challenges. 2473.Pp 2474Note: If only LANMan is enabled, 2475.Xr pppd 8 2476(version 2.3.5) misbehaves when acting as authenticatee. It provides both 2477the NT and the LANMan answers, but also suggests that only the NT answer 2478should be used. 2479.It pap 2480Default: Disabled and Accepted. PAP stands for Password Authentication 2481Protocol. Only one of PAP and CHAP (above) may be negotiated. With 2482PAP, the ID and Password are sent repeatedly to the peer until 2483authentication is acknowledged or the connection is terminated. This 2484is a rather poor security mechanism. It is only performed when the 2485connection is first established. 2486If you want to have your peer authenticate itself, you must 2487.Dq enable pap . 2488in 2489.Pa /etc/ppp/ppp.conf , 2490and have an entry in 2491.Pa /etc/ppp/ppp.secret 2492for the peer (although see the 2493.Dq passwdauth 2494and 2495.Dq set radius 2496options below). 2497.Pp 2498When using PAP as the client, you need only specify 2499.Dq AuthName 2500and 2501.Dq AuthKey 2502in 2503.Pa /etc/ppp/ppp.conf . 2504PAP is accepted by default. 2505.It pred1 2506Default: Enabled and Accepted. This option decides if Predictor 1 2507compression will be used by the Compression Control Protocol (CCP). 2508.It protocomp 2509Default: Enabled and Accepted. This option is used to negotiate 2510PFC (Protocol Field Compression), a mechanism where the protocol 2511field number is reduced to one octet rather than two. 2512.It shortseq 2513Default: Enabled and Accepted. This option determines if 2514.Nm 2515will request and accept requests for short 2516.Pq 12 bit 2517sequence numbers when negotiating multi-link mode. This is only 2518applicable if our MRRU is set (thus enabling multi-link). 2519.It vjcomp 2520Default: Enabled and Accepted. This option determines if Van Jacobson 2521header compression will be used. 2522.El 2523.Pp 2524The following options are not actually negotiated with the peer. 2525Therefore, accepting or denying them makes no sense. 2526.Bl -tag -width XX 2527.It idcheck 2528Default: Enabled. When 2529.Nm 2530exchanges low-level LCP, CCP and IPCP configuration traffic, the 2531.Em Identifier 2532field of any replies is expected to be the same as that of the request. 2533By default, 2534.Nm 2535drops any reply packets that do not contain the expected identifier 2536field, reporting the fact at the respective log level. If 2537.Ar idcheck 2538is disabled, 2539.Nm 2540will ignore the identifier field. 2541.It keep-session 2542Default: Disabled. When 2543.Nm 2544runs as a Multi-link server, a different 2545.Nm 2546instance initially receives each connection. After determining that 2547the link belongs to an already existing bundle (controlled by another 2548.Nm 2549invocation), 2550.Nm 2551will transfer the link to that process. 2552.Pp 2553If the link is a tty device or if this option is enabled, 2554.Nm 2555will not exit, but will change its process name to 2556.Dq session owner 2557and wait for the controlling 2558.Nm 2559to finish with the link and deliver a signal back to the idle process. 2560This prevents the confusion that results from 2561.Nm ppp Ns No 's 2562parent considering the link resource available again. 2563.Pp 2564For tty devices that have entries in 2565.Pa /etc/ttys , 2566this is necessary to prevent another 2567.Xr getty 8 2568from being started, and for program links such as 2569.Xr sshd 8 , 2570it prevents 2571.Xr sshd 8 2572from exiting due to the death of its child. As 2573.Nm 2574cannot determine its parents requirements (except for the tty case), this 2575option must be enabled manually depending on the circumstances. 2576.It loopback 2577Default: Enabled. When 2578.Ar loopback 2579is enabled, 2580.Nm 2581will automatically loop back packets being sent 2582out with a destination address equal to that of the 2583.Em PPP 2584interface. If disabled, 2585.Nm 2586will send the packet, probably resulting in an ICMP redirect from 2587the other end. It is convenient to have this option enabled when 2588the interface is also the default route as it avoids the necessity 2589of a loopback route. 2590.It passwdauth 2591Default: Disabled. Enabling this option will tell the PAP authentication 2592code to use the password database (see 2593.Xr passwd 5 ) 2594to authenticate the caller if they cannot be found in the 2595.Pa /etc/ppp/ppp.secret 2596file. 2597.Pa /etc/ppp/ppp.secret 2598is always checked first. If you wish to use passwords from 2599.Xr passwd 5 , 2600but also to specify an IP number or label for a given client, use 2601.Dq \&* 2602as the client password in 2603.Pa /etc/ppp/ppp.secret . 2604.It proxy 2605Default: Disabled. Enabling this option will tell 2606.Nm 2607to proxy ARP for the peer. This means that 2608.Nm 2609will make an entry in the ARP table using 2610.Dv HISADDR 2611and the 2612.Dv MAC 2613address of the local network in which 2614.Dv HISADDR 2615appears. The proxy entry cannot be made unless 2616.Dv HISADDR 2617is an address from a LAN. 2618.It proxyall 2619Default: Disabled. Enabling this will tell 2620.Nm 2621to add proxy arp entries for every IP address in all class C or 2622smaller subnets routed via the tun interface. 2623.Pp 2624Proxy arp entries are only made for sticky routes that are added 2625using the 2626.Dq add 2627command. No proxy arp entries are made for the interface address itself 2628(as created by the 2629.Dq set ifaddr 2630command). 2631.It sroutes 2632Default: Enabled. When the 2633.Dq add 2634command is used with the 2635.Dv HISADDR 2636or 2637.Dv MYADDR 2638values, entries are stored in the 2639.Sq stick route 2640list. Each time 2641.Dv HISADDR 2642or 2643.Dv MYADDR 2644change, this list is re-applied to the routing table. 2645.Pp 2646Disabling this option will prevent the re-application of sticky routes, 2647although the 2648.Sq stick route 2649list will still be maintained. 2650.It throughput 2651Default: Enabled. This option tells 2652.Nm 2653to gather throughput statistics. Input and output is sampled over 2654a rolling 5 second window, and current, best and total figures are 2655retained. This data is output when the relevant 2656.Em PPP 2657layer shuts down, and is also available using the 2658.Dq show 2659command. Throughput statistics are available at the 2660.Dq IPCP 2661and 2662.Dq physical 2663levels. 2664.It utmp 2665Default: Enabled. Normally, when a user is authenticated using PAP or 2666CHAP, and when 2667.Nm 2668is running in 2669.Fl direct 2670mode, an entry is made in the utmp and wtmp files for that user. Disabling 2671this option will tell 2672.Nm 2673not to make any utmp or wtmp entries. This is usually only necessary if 2674you require the user to both login and authenticate themselves. 2675.It iface-alias 2676Default: Enabled if 2677.Fl nat 2678is specified. This option simply tells 2679.Nm 2680to add new interface addresses to the interface rather than replacing them. 2681The option can only be enabled if network address translation is enabled 2682.Pq Dq nat enable yes . 2683.Pp 2684With this option enabled, 2685.Nm 2686will pass traffic for old interface addresses through the NAT engine 2687.Pq see Xr libalias 5 , 2688resulting in the ability (in 2689.Fl auto 2690mode) to properly connect the process that caused the PPP link to 2691come up in the first place. 2692.Pp 2693Disabling NAT with 2694.Dq nat enable no 2695will also disable 2696.Sq iface-alias . 2697.El 2698.Pp 2699.It add Ns Xo 2700.Op \&! 2701.Ar dest Ns Op / Ns Ar nn 2702.Op Ar mask 2703.Op Ar gateway 2704.Xc 2705.Ar Dest 2706is the destination IP address. The netmask is specified either as a 2707number of bits with 2708.Ar /nn 2709or as an IP number using 2710.Ar mask . 2711.Ar 0 0 2712or simply 2713.Ar 0 2714with no mask refers to the default route. It is also possible to use the 2715literal name 2716.Sq default 2717instead of 2718.Ar 0 . 2719.Ar Gateway 2720is the next hop gateway to get to the given 2721.Ar dest 2722machine/network. Refer to the 2723.Xr route 8 2724command for further details. 2725.Pp 2726It is possible to use the symbolic names 2727.Sq MYADDR 2728or 2729.Sq HISADDR 2730as the destination, and 2731.Sq HISADDR 2732as the 2733.Ar gateway . 2734.Sq MYADDR 2735is replaced with the interface address and 2736.Sq HISADDR 2737is replaced with the interface destination (peer) address. 2738.Pp 2739If the 2740.Ar add! 2741command is used 2742.Pq note the trailing Dq \&! , 2743then if the route already exists, it will be updated as with the 2744.Sq route change 2745command (see 2746.Xr route 8 2747for further details). 2748.Pp 2749Routes that contain the 2750.Dq HISADDR 2751or 2752.Dq MYADDR 2753constants are considered 2754.Sq sticky . 2755They are stored in a list (use 2756.Dq show ipcp 2757to see the list), and each time the value of 2758.Dv HISADDR 2759or 2760.Dv MYADDR 2761changes, the appropriate routing table entries are updated. This facility 2762may be disabled using 2763.Dq disable sroutes . 2764.It allow Ar command Op Ar args 2765This command controls access to 2766.Nm 2767and its configuration files. It is possible to allow user-level access, 2768depending on the configuration file label and on the mode that 2769.Nm 2770is being run in. For example, you may wish to configure 2771.Nm 2772so that only user 2773.Sq fred 2774may access label 2775.Sq fredlabel 2776in 2777.Fl background 2778mode. 2779.Pp 2780User id 0 is immune to these commands. 2781.Bl -tag -width XX 2782.It allow user Ns Xo 2783.Op s 2784.Ar logname Ns No ... 2785.Xc 2786By default, only user id 0 is allowed access to 2787.Nm ppp . 2788If this command is used, all of the listed users are allowed access to 2789the section in which the 2790.Dq allow users 2791command is found. The 2792.Sq default 2793section is always checked first (even though it is only ever automatically 2794loaded at startup). Each successive 2795.Dq allow users 2796command overrides the previous one, so it's possible to allow users access 2797to everything except a given label by specifying default users in the 2798.Sq default 2799section, and then specifying a new user list for that label. 2800.Pp 2801If user 2802.Sq * 2803is specified, access is allowed to all users. 2804.It allow mode Ns Xo 2805.Op s 2806.Ar mode Ns No ... 2807.Xc 2808By default, access using any 2809.Nm 2810mode is possible. If this command is used, it restricts the access 2811.Ar modes 2812allowed to load the label under which this command is specified. 2813Again, as with the 2814.Dq allow users 2815command, each 2816.Dq allow modes 2817command overrides any previous settings, and the 2818.Sq default 2819section is always checked first. 2820.Pp 2821Possible modes are: 2822.Sq interactive , 2823.Sq auto , 2824.Sq direct , 2825.Sq dedicated , 2826.Sq ddial , 2827.Sq background 2828and 2829.Sq * . 2830.Pp 2831When running in multi-link mode, a section can be loaded if it allows 2832.Em any 2833of the currently existing line modes. 2834.El 2835.Pp 2836.It nat Ar command Op Ar args 2837This command allows the control of the network address translation (also 2838known as masquerading or IP aliasing) facilities that are built into 2839.Nm ppp . 2840NAT is done on the external interface only, and is unlikely to make sense 2841if used with the 2842.Fl direct 2843flag. 2844.Pp 2845For backwards compatibility, the word 2846.Dq alias 2847may be used in place of 2848.Dq nat . 2849If nat is enabled on your system (it may be omitted at compile time), 2850the following commands are possible: 2851.Bl -tag -width XX 2852.It nat enable yes|no 2853This command either switches network address translation on or turns it off. 2854The 2855.Fl nat 2856command line flag is synonymous with 2857.Dq nat enable yes . 2858.It nat addr Op Ar addr_local addr_alias 2859This command allows data for 2860.Ar addr_alias 2861to be redirected to 2862.Ar addr_local . 2863It is useful if you own a small number of real IP numbers that 2864you wish to map to specific machines behind your gateway. 2865.It nat deny_incoming yes|no 2866If set to yes, this command will refuse all incoming connections 2867by dropping the packets in much the same way as a firewall would. 2868.It nat help|? 2869This command gives a summary of available nat commands. 2870.It nat log yes|no 2871This option causes various NAT statistics and information to 2872be logged to the file 2873.Pa /var/log/alias.log . 2874This file name is likely to change in the near future. 2875.It nat port Ar proto Ar targetIP Ns Xo 2876.No : Ns Ar targetPort Ns 2877.Oo 2878.No - Ns Ar targetPort 2879.Oc Ar aliasPort Ns 2880.Oo 2881.No - Ns Ar aliasPort 2882.Oc Oo Ar remoteIP : Ns 2883.Ar remotePort Ns 2884.Oo 2885.No - Ns Ar remotePort 2886.Oc Oc 2887.Xc 2888This command causes incoming 2889.Ar proto 2890connections to 2891.Ar aliasPort 2892to be redirected to 2893.Ar targetPort 2894on 2895.Ar targetIP . 2896.Ar proto 2897is either 2898.Dq tcp 2899or 2900.Dq udp . 2901.Pp 2902A range of port numbers may be specified as shown above. The ranges 2903must be of the same size. 2904.Pp 2905If 2906.Ar remoteIP 2907is specified, only data coming from that IP number is redirected. 2908.Ar remotePort 2909must either be 2910.Dq 0 2911.Pq indicating any source port 2912or a range of ports the same size as the other ranges. 2913.Pp 2914This option is useful if you wish to run things like Internet phone on 2915machines behind your gateway, but is limited in that connections to only 2916one interior machine per source machine and target port are possible. 2917.It nat pptp Op Ar addr 2918This tells 2919.Nm 2920to translate any 2921.Em G Ns No eneral 2922.Em R Ns No outing 2923.Em E Ns No encapsulated 2924.Pq Dv IPPROTO_GRE 2925packets using 2926.Ar addr 2927rather than the local interface address. This allows the uses of the 2928.Em P Ns No oint 2929to 2930.Em P Ns No oint 2931.Em T Ns No unneling 2932.Em P Ns No rotocol 2933on a machine on the internal network. 2934.Pp 2935If 2936.Ar addr 2937is not specified, 2938.Dv PPTP 2939address translation is disabled. 2940.It "nat proxy cmd" Ar arg Ns No ... 2941This command tells 2942.Nm 2943to proxy certain connections, redirecting them to a given server. Refer 2944to the description of 2945.Fn PacketAliasProxyRule 2946in 2947.Xr libalias 3 2948for details of the available commands. 2949.It nat same_ports yes|no 2950When enabled, this command will tell the network address translation engine to 2951 attempt to avoid changing the port number on outgoing packets. This is useful 2952if you want to support protocols such as RPC and LPD which require 2953connections to come from a well known port. 2954.It nat use_sockets yes|no 2955When enabled, this option tells the network address translation engine to 2956create a socket so that it can guarantee a correct incoming ftp data or 2957IRC connection. 2958.It nat unregistered_only yes|no 2959Only alter outgoing packets with an unregistered source ad- 2960dress. According to RFC 1918, unregistered source addresses 2961are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16. 2962.El 2963.Pp 2964These commands are also discussed in the file 2965.Pa README.alias 2966which comes with the source distribution. 2967.Pp 2968.It Op \&! Ns Xo 2969.No bg Ar command 2970.Xc 2971The given 2972.Ar command 2973is executed in the background with the following words replaced: 2974.Bl -tag -width PEER_ENDDISC 2975.It Li AUTHNAME 2976This is replaced with the local 2977.Ar authname 2978value. See the 2979.Dq set authname 2980command below. 2981.It Li ENDDISC 2982This is replaced with the local endpoint discriminator value. See the 2983.Dq set enddisc 2984command below. 2985.It Li HISADDR 2986This is replaced with the peers IP number. 2987.It Li INTERFACE 2988This is replaced with the name of the interface that's in use. 2989.It Li LABEL 2990This is replaced with the last label name used. A label may be specified 2991on the 2992.Nm 2993command line, via the 2994.Dq load 2995or 2996.Dq dial 2997commands and in the 2998.Pa ppp.secret 2999file. 3000.It Li MYADDR 3001This is replaced with the IP number assigned to the local interface. 3002.It Li PEER_ENDDISC 3003This is replaced with the value of the peers endpoint discriminator. 3004.It Li PROCESSID 3005This is replaced with the current process id. 3006.It Li USER 3007This is replaced with the username that has been authenticated with PAP or 3008CHAP. Normally, this variable is assigned only in -direct mode. This value 3009is available irrespective of whether utmp logging is enabled. 3010.El 3011.Pp 3012These substitutions are also done by the 3013.Dq set proctitle 3014command. 3015.Pp 3016If you wish to pause 3017.Nm 3018while the command executes, use the 3019.Dq shell 3020command instead. 3021.It clear physical|ipcp Op current|overall|peak... 3022Clear the specified throughput values at either the 3023.Dq physical 3024or 3025.Dq ipcp 3026level. If 3027.Dq physical 3028is specified, context must be given (see the 3029.Dq link 3030command below). If no second argument is given, all values are 3031cleared. 3032.It clone Ar name Ns Xo 3033.Op \&, Ns Ar name Ns 3034.No ... 3035.Xc 3036Clone the specified link, creating one or more new links according to the 3037.Ar name 3038argument(s). This command must be used from the 3039.Dq link 3040command below unless you've only got a single link (in which case that 3041link becomes the default). Links may be removed using the 3042.Dq remove 3043command below. 3044.Pp 3045The default link name is 3046.Dq deflink . 3047.It close Op lcp|ccp Ns Op \&! 3048If no arguments are given, the relevant protocol layers will be brought 3049down and the link will be closed. If 3050.Dq lcp 3051is specified, the LCP layer is brought down, but 3052.Nm 3053will not bring the link offline. It is subsequently possible to use 3054.Dq term 3055.Pq see below 3056to talk to the peer machine if, for example, something like 3057.Dq slirp 3058is being used. If 3059.Dq ccp 3060is specified, only the relevant compression layer is closed. If the 3061.Dq \&! 3062is used, the compression layer will remain in the closed state, otherwise 3063it will re-enter the STOPPED state, waiting for the peer to initiate 3064further CCP negotiation. In any event, this command does not disconnect 3065the user from 3066.Nm 3067or exit 3068.Nm ppp . 3069See the 3070.Dq quit 3071command below. 3072.It delete Ns Xo 3073.Op \&! 3074.Ar dest 3075.Xc 3076This command deletes the route with the given 3077.Ar dest 3078IP address. If 3079.Ar dest 3080is specified as 3081.Sq ALL , 3082all non-direct entries in the routing table for the current interface, 3083and all 3084.Sq sticky route 3085entries are deleted. If 3086.Ar dest 3087is specified as 3088.Sq default , 3089the default route is deleted. 3090.Pp 3091If the 3092.Ar delete! 3093command is used 3094.Pq note the trailing Dq \&! , 3095.Nm 3096will not complain if the route does not already exist. 3097.It dial|call Op Ar label Ns Xo 3098.No ... 3099.Xc 3100This command is the equivalent of 3101.Dq load label 3102followed by 3103.Dq open , 3104and is provided for backwards compatibility. 3105.It down Op Ar lcp|ccp 3106Bring the relevant layer down ungracefully, as if the underlying layer 3107had become unavailable. It's not considered polite to use this command on 3108a Finite State Machine that's in the OPEN state. If no arguments are 3109supplied, the entire link is closed (or if no context is given, all links 3110are terminated). If 3111.Sq lcp 3112is specified, the 3113.Em LCP 3114layer is terminated but the device is not brought offline and the link 3115is not closed. If 3116.Sq ccp 3117is specified, only the relevant compression layer(s) are terminated. 3118.It help|? Op Ar command 3119Show a list of available commands. If 3120.Ar command 3121is specified, show the usage string for that command. 3122.It iface Ar command Op args 3123This command is used to control the interface used by 3124.Nm ppp . 3125.Ar Command 3126may be one of the following: 3127.Bl -tag -width XX 3128.It iface add Ns Xo 3129.Op \&! 3130.Ar addr Ns Op / Ns Ar bits 3131.Op Ar peer 3132.Xc 3133.It iface add Ns Xo 3134.Op \&! 3135.Ar addr 3136.Ar mask 3137.Ar peer 3138.Xc 3139Add the given 3140.Ar addr mask peer 3141combination to the interface. Instead of specifying 3142.Ar mask , 3143.Ar /bits 3144can be used 3145.Pq with no space between \&it and Ar addr . 3146If the given address already exists, the command fails unless the 3147.Dq \&! 3148is used - in which case the previous interface address entry is overwritten 3149with the new one, allowing a change of netmask or peer address. 3150.Pp 3151If only 3152.Ar addr 3153is specified, 3154.Ar bits 3155defaults to 3156.Dq 32 3157and 3158.Ar peer 3159defaults to 3160.Dq 255.255.255.255 . 3161This address (the broadcast address) is the only duplicate peer address that 3162.Nm 3163allows. 3164.It iface clear 3165If this command is used while 3166.Nm 3167is in the OPENED state or while in 3168.Fl auto 3169mode, all addresses except for the IPCP negotiated address are deleted 3170from the interface. If 3171.Nm 3172is not in the OPENED state and is not in 3173.Fl auto 3174mode, all interface addresses are deleted. 3175.Pp 3176.It iface delete Ns Xo 3177.Op \&! Ns 3178.No |rm Ns Op \&! 3179.Ar addr 3180.Xc 3181This command deletes the given 3182.Ar addr 3183from the interface. If the 3184.Dq \&! 3185is used, no error is given if the address isn't currently assigned to 3186the interface (and no deletion takes place). 3187.It iface show 3188Shows the current state and current addresses for the interface. It is 3189much the same as running 3190.Dq ifconfig INTERFACE . 3191.It iface help Op Ar sub-command 3192This command, when invoked without 3193.Ar sub-command , 3194will show a list of possible 3195.Dq iface 3196sub-commands and a brief synopsis for each. When invoked with 3197.Ar sub-command , 3198only the synopsis for the given sub-command is shown. 3199.El 3200.It Op data Ns Xo 3201.No link 3202.Ar name Ns Op , Ns Ar name Ns 3203.No ... Ar command Op Ar args 3204.Xc 3205This command may prefix any other command if the user wishes to 3206specify which link the command should affect. This is only 3207applicable after multiple links have been created in Multi-link 3208mode using the 3209.Dq clone 3210command. 3211.Pp 3212.Ar Name 3213specifies the name of an existing link. If 3214.Ar name 3215is a comma separated list, 3216.Ar command 3217is executed on each link. If 3218.Ar name 3219is 3220.Dq * , 3221.Ar command 3222is executed on all links. 3223.It load Op Ar label Ns Xo 3224.No ... 3225.Xc 3226Load the given 3227.Ar label Ns No (s) 3228from the 3229.Pa ppp.conf 3230file. If 3231.Ar label 3232is not given, the 3233.Ar default 3234label is used. 3235.Pp 3236Unless the 3237.Ar label 3238section uses the 3239.Dq set mode , 3240.Dq open 3241or 3242.Dq dial 3243commands, 3244.Nm 3245will not attempt to make an immediate connection. 3246.It open Op lcp|ccp|ipcp 3247This is the opposite of the 3248.Dq close 3249command. All closed links are immediately brought up apart from second 3250and subsequent 3251.Ar demand-dial 3252links - these will come up based on the 3253.Dq set autoload 3254command that has been used. 3255.Pp 3256If the 3257.Dq lcp 3258argument is used while the LCP layer is already open, LCP will be 3259renegotiated. This allows various LCP options to be changed, after which 3260.Dq open lcp 3261can be used to put them into effect. After renegotiating LCP, 3262any agreed authentication will also take place. 3263.Pp 3264If the 3265.Dq ccp 3266argument is used, the relevant compression layer is opened. Again, 3267if it is already open, it will be renegotiated. 3268.Pp 3269If the 3270.Dq ipcp 3271argument is used, the link will be brought up as normal, but if 3272IPCP is already open, it will be renegotiated and the network 3273interface will be reconfigured. 3274.Pp 3275It is probably not good practice to re-open the PPP state machines 3276like this as it's possible that the peer will not behave correctly. 3277It 3278.Em is 3279however useful as a way of forcing the CCP or VJ dictionaries to be reset. 3280.It passwd Ar pass 3281Specify the password required for access to the full 3282.Nm 3283command set. This password is required when connecting to the diagnostic 3284port (see the 3285.Dq set server 3286command). 3287.Ar Pass 3288is specified on the 3289.Dq set server 3290command line. The value of 3291.Ar pass 3292is not logged when 3293.Ar command 3294logging is active, instead, the literal string 3295.Sq ******** 3296is logged. 3297.It quit|bye Op all 3298If 3299.Dq quit 3300is executed from the controlling connection or from a command file, 3301ppp will exit after closing all connections. Otherwise, if the user 3302is connected to a diagnostic socket, the connection is simply dropped. 3303.Pp 3304If the 3305.Ar all 3306argument is given, 3307.Nm 3308will exit despite the source of the command after closing all existing 3309connections. 3310.It remove|rm 3311This command removes the given link. It is only really useful in 3312multi-link mode. A link must be 3313in the 3314.Dv CLOSED 3315state before it is removed. 3316.It rename|mv Ar name 3317This command renames the given link to 3318.Ar name . 3319It will fail if 3320.Ar name 3321is already used by another link. 3322.Pp 3323The default link name is 3324.Sq deflink . 3325Renaming it to 3326.Sq modem , 3327.Sq cuaa0 3328or 3329.Sq USR 3330may make the log file more readable. 3331.It save 3332This option is not (yet) implemented. 3333.It set Ns Xo 3334.No Op up 3335.Ar var value 3336.Xc 3337This option allows the setting of any of the following variables: 3338.Bl -tag -width XX 3339.It set accmap Ar hex-value 3340ACCMap stands for Asynchronous Control Character Map. This is always 3341negotiated with the peer, and defaults to a value of 00000000 in hex. 3342This protocol is required to defeat hardware that depends on passing 3343certain characters from end to end (such as XON/XOFF etc). 3344.Pp 3345For the XON/XOFF scenario, use 3346.Dq set accmap 000a0000 . 3347.It set Op auth Ns Xo 3348.No key Ar value 3349.Xc 3350This sets the authentication key (or password) used in client mode 3351PAP or CHAP negotiation to the given value. It also specifies the 3352password to be used in the dial or login scripts in place of the 3353.Sq \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\P 3354sequence, preventing the actual password from being logged. If 3355.Ar command 3356or 3357.Ar chat 3358logging is in effect, 3359.Ar value 3360is logged as 3361.Sq ******** 3362for security reasons. 3363.Pp 3364If the first character of 3365.Ar value 3366is an exclaimation mark 3367.Pq Dq \&! , 3368.Nm 3369treats the remainder of the string as a program that must be executed 3370to determine the 3371.Dq authname 3372and 3373.Dq authkey 3374values. 3375.Pp 3376Ignoring the 3377.Dq \&! , 3378.Ar value 3379is parsed as a program to execute in the same was as the 3380.Dq !bg 3381command above, substituting special names in the same manner. Once executed, 3382.Nm 3383will feed the program three lines of input, each terminated by a newline 3384character: 3385.Bl -bullet 3386.It 3387The host name as sent in the CHAP challenge. 3388.It 3389The challenge string as sent in the CHAP challenge. 3390.It 3391The locally defined 3392.Dq authname . 3393.El 3394.Pp 3395Two lines of output are expected: 3396.Bl -bullet 3397.It 3398The 3399.Dq authname 3400to be sent with the CHAP response. 3401.It 3402The 3403.Dq authkey , 3404which is encrypted with the challenge and request id, the answer being sent 3405in the CHAP response packet. 3406.El 3407.Pp 3408When configuring 3409.Nm 3410in this manner, it's expected that the host challenge is a series of ASCII 3411digits or characters. An encryption device or Secure ID card is usually 3412required to calculate the secret appropriate for the given challenge. 3413.It set authname Ar id 3414This sets the authentication id used in client mode PAP or CHAP negotiation. 3415.Pp 3416If used in 3417.Fl direct 3418mode with CHAP enabled, 3419.Ar id 3420is used in the initial authentication challenge and should normally be set to 3421the local machine name. 3422.It set autoload Xo 3423.Ar min-percent max-percent period 3424.Xc 3425These settings apply only in multi-link mode and default to zero, zero and 3426five respectively. 3427When more than one 3428.Ar demand-dial 3429.Pq also known as Fl auto 3430mode link is available, only the first link is made active when 3431.Nm 3432first reads data from the tun device. The next 3433.Ar demand-dial 3434link will be opened only when the current bundle throughput is at least 3435.Ar max-percent 3436percent of the total bundle bandwidth for 3437.Ar period 3438seconds. When the current bundle throughput decreases to 3439.Ar min-percent 3440percent or less of the total bundle bandwidth for 3441.Ar period 3442seconds, a 3443.Ar demand-dial 3444link will be brought down as long as it's not the last active 3445.Ar demand-dial 3446link. 3447.Pp 3448The default values cause 3449.Ar demand-dial 3450links to simply come up one at a time. 3451.Pp 3452Certain devices cannot determine their physical bandwidth, so it 3453is sometimes necessary to use the 3454.Dq set bandwidth 3455command (described below) to make 3456.Dq set autoload 3457work correctly. 3458.It set bandwidth Ar value 3459This command sets the connection bandwidth in bits per second. 3460.Ar value 3461must be greater than zero. It is currently only used by the 3462.Dq set autoload 3463command above. 3464.It set callback Ar option Ns No ... 3465If no arguments are given, callback is disabled, otherwise, 3466.Nm 3467will request (or in 3468.Fl direct 3469mode, will accept) one of the given 3470.Ar option Ns No s . 3471In client mode, if an 3472.Ar option 3473is NAK'd 3474.Nm 3475will request a different 3476.Ar option , 3477until no options remain at which point 3478.Nm 3479will terminate negotiations (unless 3480.Dq none 3481is one of the specified 3482.Ar option Ns No ). 3483In server mode, 3484.Nm 3485will accept any of the given protocols - but the client 3486.Em must 3487request one of them. If you wish callback to be optional, you must include 3488.Ar none 3489as an option. 3490.Pp 3491The 3492.Ar option Ns No s 3493are as follows (in this order of preference): 3494.Pp 3495.Bl -tag 3496.It auth 3497The callee is expected to decide the callback number based on 3498authentication. If 3499.Nm 3500is the callee, the number should be specified as the fifth field of 3501the peers entry in 3502.Pa /etc/ppp/ppp.secret . 3503.It cbcp 3504Microsofts callback control protocol is used. See 3505.Dq set cbcp 3506below. 3507.Pp 3508If you wish to negotiate 3509.Ar cbcp 3510in client mode but also wish to allow the server to request no callback at 3511CBCP negotiation time, you must specify both 3512.Ar cbcp 3513and 3514.Ar none 3515as callback options. 3516.It E.164 *| Ns Xo 3517.Ar number Ns Op , Ns Ar number Ns 3518.No ... 3519.Xc 3520The caller specifies the 3521.Ar number . 3522If 3523.Nm 3524is the callee, 3525.Ar number 3526should be either a comma separated list of allowable numbers or a 3527.Dq \&* , 3528meaning any number is permitted. If 3529.Nm 3530is the caller, only a single number should be specified. 3531.Pp 3532Note, this option is very unsafe when used with a 3533.Dq \&* 3534as a malicious caller can tell 3535.Nm 3536to call any (possibly international) number without first authenticating 3537themselves. 3538.It none 3539If the peer does not wish to do callback at all, 3540.Nm 3541will accept the fact and continue without callback rather than terminating 3542the connection. This is required (in addition to one or more other callback 3543options) if you wish callback to be optional. 3544.El 3545.Pp 3546.It set cbcp Oo Xo 3547.No *| Ns Ar number Ns No 3548.Oo 3549.No , Ns Ar number Ns 3550.Oc 3551.No ... 3552.Op Ar delay Op Ar retry 3553.Oc 3554.Xc 3555If no arguments are given, CBCP (Microsofts CallBack Control Protocol) 3556is disabled - ie, configuring CBCP in the 3557.Dq set callback 3558command will result in 3559.Nm 3560requesting no callback in the CBCP phase. 3561Otherwise, 3562.Nm 3563attempts to use the given phone 3564.Ar number Ns No (s). 3565.Pp 3566In server mode 3567.Pq Fl direct , 3568.Nm 3569will insist that the client uses one of these numbers, unless 3570.Dq \&* 3571is used in which case the client is expected to specify the number. 3572.Pp 3573In client mode, 3574.Nm 3575will attempt to use one of the given numbers (whichever it finds to 3576be agreeable with the peer), or if 3577.Dq \&* 3578is specified, 3579.Nm 3580will expect the peer to specify the number. 3581.It "set cd off|" Ns Ar seconds Ns Op \&! 3582Normally, 3583.Nm 3584checks for the existence of carrier one second after the login script is 3585complete. If it's not set, 3586.Nm 3587assumes that this is because the device doesn't support carrier (which 3588is true for most 3589.Dq laplink 3590NULL-modem cables), logs the fact and stops checking 3591for carrier. However, some modems take some time to assert the carrier 3592signal, resulting in 3593.Nm ppp Ns No s 3594inability to detect when the link is dropped. 3595.Ar seconds 3596specifies the number of seconds that 3597.Nm 3598should wait after the dial script has finished before deciding if 3599carrier is available or not. 3600.Pp 3601If 3602.Dq off 3603is specified, 3604.Nm 3605will not check for carrier on the device, otherwise 3606.Nm 3607will not proceed to the login script until either carrier is detected 3608or until 3609.Ar seconds 3610has elapsed. 3611.Pp 3612If 3613.Ar seconds 3614is followed immediately by an exclaimation mark 3615.Pq Dq \&! , 3616.Nm 3617will 3618.Em require 3619carrier. If carrier is not detected after 3620.Ar seconds 3621seconds, the link will be disconnected. 3622.Pp 3623For ISDN devices, 3624.Nm 3625will always insist on carrier (the value 3626.Dq off 3627is invalid). Carrier is raised by the i4brbchX device driver only after 3628the call has connected. It is therefore wise to set a reasonable value 3629such as 3630.Ar 6 3631seconds. 3632.Pp 3633Carrier 3634.Em require Ns No ment 3635is ignored for all other device types - as if set to 3636.Dq off . 3637.It set choked Op Ar timeout 3638This sets the number of seconds that 3639.Nm 3640will keep a choked output queue before dropping all pending output packets. 3641If 3642.Ar timeout 3643is less than or equal to zero or if 3644.Ar timeout 3645isn't specified, it is set to the default value of 3646.Em 120 seconds . 3647.Pp 3648A choked output queue occurs when 3649.Nm 3650has read a certain number of packets from the local network for transmission, 3651but cannot send the data due to link failure (the peer is busy etc.). 3652.Nm 3653will not read packets indefinitely. Instead, it reads up to 3654.Em 30 3655packets (or 3656.Em 30 No + 3657.Em nlinks No * 3658.Em 2 3659packets in multi-link mode), then stops reading the network interface 3660until either 3661.Ar timeout 3662seconds have passed or at least one packet has been sent. 3663.Pp 3664If 3665.Ar timeout 3666seconds pass, all pending output packets are dropped. 3667.It set ctsrts|crtscts on|off 3668This sets hardware flow control. Hardware flow control is 3669.Ar on 3670by default. 3671.It set deflate Ar out-winsize Op Ar in-winsize 3672This sets the DEFLATE algorithms default outgoing and incoming window 3673sizes. Both 3674.Ar out-winsize 3675and 3676.Ar in-winsize 3677must be values between 3678.Em 8 3679and 3680.Em 15 . 3681If 3682.Ar in-winsize 3683is specified, 3684.Nm 3685will insist that this window size is used and will not accept any other 3686values from the peer. 3687.It set dns Op Ar primary Op Ar secondary 3688This command specifies DNS overrides for the 3689.Dq accept dns 3690command. Refer to the 3691.Dq accept 3692command description above for details. This command does not affect the 3693IP numbers requested using 3694.Dq enable dns . 3695.It set device|line Xo 3696.Ar value Ns No ... 3697.Xc 3698This sets the device(s) to which 3699.Nm 3700will talk to the given 3701.Dq value . 3702.Pp 3703All ISDN and serial device names are expected to begin with 3704.Pa /dev/ . 3705ISDN devices are usually called 3706.Pa i4brbchX 3707and serial devices are usually called 3708.Pa cuaaX . 3709.Pp 3710If 3711.Dq value 3712does not begin with 3713.Pa /dev/ , 3714it must either begin with an exclamation mark 3715.Pq Dq \&! 3716or be of the format 3717.Dq host:port Ns Op Ns /proto . 3718.Pp 3719If it begins with an exclamation mark, the rest of the device name is 3720treated as a program name, and that program is executed when the device 3721is opened. Standard input, output and error are fed back to 3722.Nm 3723and are read and written as if they were a regular device. 3724.Pp 3725If a 3726.Dq host:port Ns Op /tcp|/udp 3727specification is given, 3728.Nm 3729will attempt to connect to the given 3730.Dq host 3731on the given 3732.Dq port . 3733If a tcp or udp specification is not given, the default is tcp. Refer to 3734the section on 3735.Em PPP OVER TCP and UDP 3736above for further details. 3737.Pp 3738If multiple 3739.Dq values 3740are specified, 3741.Nm 3742will attempt to open each one in turn until it succeeds or runs out of 3743devices. 3744.It set dial Ar chat-script 3745This specifies the chat script that will be used to dial the other 3746side. See also the 3747.Dq set login 3748command below. Refer to 3749.Xr chat 8 3750and to the example configuration files for details of the chat script 3751format. 3752It is possible to specify some special 3753.Sq values 3754in your chat script as follows: 3755.Bd -unfilled -offset indent 3756.It Li \\\\\\\\\\\\\\\\c 3757When used as the last character in a 3758.Sq send 3759string, this indicates that a newline should not be appended. 3760.It Li \\\\\\\\\\\\\\\\d 3761When the chat script encounters this sequence, it delays two seconds. 3762.It Li \\\\\\\\\\\\\\\\p 3763When the chat script encounters this sequence, it delays for one quarter of 3764a second. 3765.It Li \\\\\\\\\\\\\\\\n 3766This is replaced with a newline character. 3767.It Li \\\\\\\\\\\\\\\\r 3768This is replaced with a carriage return character. 3769.It Li \\\\\\\\\\\\\\\\s 3770This is replaced with a space character. 3771.It Li \\\\\\\\\\\\\\\\t 3772This is replaced with a tab character. 3773.It Li \\\\\\\\\\\\\\\\T 3774This is replaced by the current phone number (see 3775.Dq set phone 3776below). 3777.It Li \\\\\\\\\\\\\\\\P 3778This is replaced by the current 3779.Ar authkey 3780value (see 3781.Dq set authkey 3782above). 3783.It Li \\\\\\\\\\\\\\\\U 3784This is replaced by the current 3785.Ar authname 3786value (see 3787.Dq set authname 3788above). 3789.Ed 3790.Pp 3791Note that two parsers will examine these escape sequences, so in order to 3792have the 3793.Sq chat parser 3794see the escape character, it is necessary to escape it from the 3795.Sq command parser . 3796This means that in practice you should use two escapes, for example: 3797.Bd -literal -offset indent 3798set dial "... ATDT\\\\T CONNECT" 3799.Ed 3800.Pp 3801It is also possible to execute external commands from the chat script. 3802To do this, the first character of the expect or send string is an 3803exclamation mark 3804.Pq Dq \&! . 3805When the command is executed, standard input and standard output are 3806directed to the open device (see the 3807.Dq set device 3808command), and standard error is read by 3809.Nm 3810and substituted as the expect or send string. If 3811.Nm 3812is running in interactive mode, file descriptor 3 is attached to 3813.Pa /dev/tty . 3814.Pp 3815For example (wrapped for readability); 3816.Bd -literal -offset indent 3817set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e 3818word: ppp \\"!sh \\\\\\\\-c \\\\\\"echo \\\\\\\\-n label: >&2\\\\\\"\\" \e 3819\\"!/bin/echo in\\" HELLO" 3820.Ed 3821.Pp 3822would result in the following chat sequence (output using the 3823.Sq set log local chat 3824command before dialing): 3825.Bd -literal -offset indent 3826Dial attempt 1 of 1 3827dial OK! 3828Chat: Expecting: 3829Chat: Sending: 3830Chat: Expecting: login:--login: 3831Chat: Wait for (5): login: 3832Chat: Sending: ppp 3833Chat: Expecting: word: 3834Chat: Wait for (5): word: 3835Chat: Sending: ppp 3836Chat: Expecting: !sh \\-c "echo \\-n label: >&2" 3837Chat: Exec: sh -c "echo -n label: >&2" 3838Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label: 3839Chat: Exec: /bin/echo in 3840Chat: Sending: 3841Chat: Expecting: HELLO 3842Chat: Wait for (5): HELLO 3843login OK! 3844.Ed 3845.Pp 3846Note (again) the use of the escape character, allowing many levels of 3847nesting. Here, there are four parsers at work. The first parses the 3848original line, reading it as three arguments. The second parses the 3849third argument, reading it as 11 arguments. At this point, it is 3850important that the 3851.Dq \&- 3852signs are escaped, otherwise this parser will see them as constituting 3853an expect-send-expect sequence. When the 3854.Dq \&! 3855character is seen, the execution parser reads the first command as three 3856arguments, and then 3857.Xr sh 1 3858itself expands the argument after the 3859.Fl c . 3860As we wish to send the output back to the modem, in the first example 3861we redirect our output to file descriptor 2 (stderr) so that 3862.Nm 3863itself sends and logs it, and in the second example, we just output to stdout, 3864which is attached directly to the modem. 3865.Pp 3866This, of course means that it is possible to execute an entirely external 3867.Dq chat 3868command rather than using the internal one. See 3869.Xr chat 8 3870for a good alternative. 3871.Pp 3872The external command that is executed is subjected to the same special 3873word expansions as the 3874.Dq !bg 3875command. 3876.It set enddisc Op label|IP|MAC|magic|psn value 3877This command sets our local endpoint discriminator. If set prior to 3878LCP negotiation, and if no 3879.Dq disable enddisc 3880command has been used, 3881.Nm 3882will send the information to the peer using the LCP endpoint discriminator 3883option. The following discriminators may be set: 3884.Bd -unfilled -offset indent 3885.It Li label 3886The current label is used. 3887.It Li IP 3888Our local IP number is used. As LCP is negotiated prior to IPCP, it is 3889possible that the IPCP layer will subsequently change this value. If 3890it does, the endpoint discriminator stays at the old value unless manually 3891reset. 3892.It Li MAC 3893This is similar to the 3894.Ar IP 3895option above, except that the MAC address associated with the local IP 3896number is used. If the local IP number is not resident on any Ethernet 3897interface, the command will fail. 3898.Pp 3899As the local IP number defaults to whatever the machine host name is, 3900.Dq set enddisc mac 3901is usually done prior to any 3902.Dq set ifaddr 3903commands. 3904.It Li magic 3905A 20 digit random number is used. Care should be taken when using magic 3906numbers as restarting 3907.Nm 3908or creating a link using a different 3909.Nm 3910invocation will also use a different magic number and will therefore not 3911be recognised by the peer as belonging to the same bundle. This makes it 3912unsuitable for 3913.Fl direct 3914connections. 3915.It Li psn Ar value 3916The given 3917.Ar value 3918is used. 3919.Ar Value 3920should be set to an absolute public switched network number with the 3921country code first. 3922.Ed 3923.Pp 3924If no arguments are given, the endpoint discriminator is reset. 3925.It set escape Ar value... 3926This option is similar to the 3927.Dq set accmap 3928option above. It allows the user to specify a set of characters that 3929will be 3930.Sq escaped 3931as they travel across the link. 3932.It set filter dial|alive|in|out Ar rule-no Xo 3933.No permit|deny|clear| Ns Ar rule-no 3934.Op \&! 3935.Oo Op host 3936.Ar src_addr Ns Op / Ns Ar width 3937.Op Ar dst_addr Ns Op / Ns Ar width 3938.Oc Oo tcp|udp|ospf|igmp|icmp Op src lt|eq|gt Ar port 3939.Op dst lt|eq|gt Ar port 3940.Op estab 3941.Op syn 3942.Op finrst 3943.Oc 3944.Xc 3945.Nm 3946supports four filter sets. The 3947.Em alive 3948filter specifies packets that keep the connection alive - resetting the 3949idle timer. The 3950.Em dial 3951filter specifies packets that cause 3952.Nm 3953to dial when in 3954.Fl auto 3955mode. The 3956.Em in 3957filter specifies packets that are allowed to travel 3958into the machine and the 3959.Em out 3960filter specifies packets that are allowed out of the machine. 3961.Pp 3962Filtering is done prior to any IP alterations that might be done by the 3963NAT engine on outgoing packets and after any IP alterations that might 3964be done by the NAT engine on incoming packets. By default all filter 3965sets allow all packets to pass. Rules are processed in order according to 3966.Ar rule-no 3967(unless skipped by specifying a rule number as the 3968.Ar action ) . 3969Up to 40 rules may be given for each set. If a packet doesn't match 3970any of the rules in a given set, it is discarded. In the case of 3971.Em in 3972and 3973.Em out 3974filters, this means that the packet is dropped. In the case of 3975.Em alive 3976filters it means that the packet will not reset the idle timer and in 3977the case of 3978.Em dial 3979filters it means that the packet will not trigger a dial. A packet failing 3980to trigger a dial will be dropped rather than queued. Refer to the 3981section on 3982.Sx PACKET FILTERING 3983above for further details. 3984.It set hangup Ar chat-script 3985This specifies the chat script that will be used to reset the device 3986before it is closed. It should not normally be necessary, but can 3987be used for devices that fail to reset themselves properly on close. 3988.It set help|? Op Ar command 3989This command gives a summary of available set commands, or if 3990.Ar command 3991is specified, the command usage is shown. 3992.It set ifaddr Oo Ar myaddr Ns 3993.Op / Ns Ar \&nn 3994.Oo Ar hisaddr Ns Op / Ns Ar \&nn 3995.Oo Ar netmask 3996.Op Ar triggeraddr 3997.Oc Oc 3998.Oc 3999This command specifies the IP addresses that will be used during 4000IPCP negotiation. Addresses are specified using the format 4001.Pp 4002.Dl a.b.c.d/nn 4003.Pp 4004Where 4005.Dq a.b.c.d 4006is the preferred IP, but 4007.Ar nn 4008specifies how many bits of the address we will insist on. If 4009.No / Ns Ar nn 4010is omitted, it defaults to 4011.Dq /32 4012unless the IP address is 0.0.0.0 in which case it defaults to 4013.Dq /0 . 4014.Pp 4015If you wish to assign a dynamic IP number to the peer, 4016.Ar hisaddr 4017may also be specified as a range of IP numbers in the format 4018.Bd -literal -offset indent 4019.Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Xo 4020.Oc Oo , Ns Ar \&IP Ns 4021.Op \&- Ns Ar \&IP Ns 4022.Oc No ... 4023.Xc 4024.Ed 4025.Pp 4026for example: 4027.Pp 4028.Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20 4029.Pp 4030will only negotiate 4031.Dq 10.0.0.1 4032as the local IP number, but may assign any of the given 10 IP 4033numbers to the peer. If the peer requests one of these numbers, 4034and that number is not already in use, 4035.Nm 4036will grant the peers request. This is useful if the peer wants 4037to re-establish a link using the same IP number as was previously 4038allocated (thus maintaining any existing tcp or udp connections). 4039.Pp 4040If the peer requests an IP number that's either outside 4041of this range or is already in use, 4042.Nm 4043will suggest a random unused IP number from the range. 4044.Pp 4045If 4046.Ar triggeraddr 4047is specified, it is used in place of 4048.Ar myaddr 4049in the initial IPCP negotiation. However, only an address in the 4050.Ar myaddr 4051range will be accepted. This is useful when negotiating with some 4052.Dv PPP 4053implementations that will not assign an IP number unless their peer 4054requests 4055.Dq 0.0.0.0 . 4056.Pp 4057It should be noted that in 4058.Fl auto 4059mode, 4060.Nm 4061will configure the interface immediately upon reading the 4062.Dq set ifaddr 4063line in the config file. In any other mode, these values are just 4064used for IPCP negotiations, and the interface isn't configured 4065until the IPCP layer is up. 4066.Pp 4067Note that the 4068.Ar HISADDR 4069argument may be overridden by the third field in the 4070.Pa ppp.secret 4071file once the client has authenticated itself 4072.Pq if PAP or CHAP are Dq enabled . 4073Refer to the 4074.Sx AUTHENTICATING INCOMING CONNECTIONS 4075section for details. 4076.Pp 4077In all cases, if the interface is already configured, 4078.Nm 4079will try to maintain the interface IP numbers so that any existing 4080bound sockets will remain valid. 4081.It set ccpretry|ccpretries Oo Ar timeout 4082.Op Ar reqtries Op Ar trmtries 4083.Oc 4084.It set chapretry|chapretries Oo Ar timeout 4085.Op Ar reqtries 4086.Oc 4087.It set ipcpretry|ipcpretries Oo Ar timeout 4088.Op Ar reqtries Op Ar trmtries 4089.Oc 4090.It set lcpretry|lcpretries Oo Ar timeout 4091.Op Ar reqtries Op Ar trmtries 4092.Oc 4093.It set papretry|papretries Oo Ar timeout 4094.Op Ar reqtries 4095.Oc 4096These commands set the number of seconds that 4097.Nm 4098will wait before resending Finite State Machine (FSM) Request packets. 4099The default 4100.Ar timeout 4101for all FSMs is 3 seconds (which should suffice in most cases). 4102.Pp 4103If 4104.Ar reqtries 4105is specified, it tells 4106.Nm 4107how many configuration request attempts it should make while receiving 4108no reply from the peer before giving up. The default is 5 attempts for 4109CCP, LCP and IPCP and 3 attempts for PAP and CHAP. 4110.Pp 4111If 4112.Ar trmtries 4113is specified, it tells 4114.Nm 4115how many terminate requests should be sent before giving up waiting for the 4116peers response. The default is 3 attempts. Authentication protocols are 4117not terminated and it is therefore invalid to specify 4118.Ar trmtries 4119for PAP or CHAP. 4120.Pp 4121In order to avoid negotiations with the peer that will never converge, 4122.Nm 4123will only send at most 3 times the configured number of 4124.Ar reqtries 4125in any given negotiation session before giving up and closing that layer. 4126.It set log Xo 4127.Op local 4128.Op +|- Ns 4129.Ar value Ns No ... 4130.Xc 4131This command allows the adjustment of the current log level. Refer 4132to the Logging Facility section for further details. 4133.It set login Ar chat-script 4134This 4135.Ar chat-script 4136compliments the dial-script. If both are specified, the login 4137script will be executed after the dial script. Escape sequences 4138available in the dial script are also available here. 4139.It set logout Ar chat-script 4140This specifies the chat script that will be used to logout 4141before the hangup script is called. It should not normally be necessary. 4142.It set lqrperiod Ar frequency 4143This command sets the 4144.Ar frequency 4145in seconds at which 4146.Em LQR 4147or 4148.Em ECHO LQR 4149packets are sent. The default is 30 seconds. You must also use the 4150.Dq enable lqr 4151command if you wish to send LQR requests to the peer. 4152.It set mode Ar interactive|auto|ddial|background 4153This command allows you to change the 4154.Sq mode 4155of the specified link. This is normally only useful in multi-link mode, 4156but may also be used in uni-link mode. 4157.Pp 4158It is not possible to change a link that is 4159.Sq direct 4160or 4161.Sq dedicated . 4162.Pp 4163Note: If you issue the command 4164.Dq set mode auto , 4165and have network address translation enabled, it may be useful to 4166.Dq enable iface-alias 4167afterwards. This will allow 4168.Nm 4169to do the necessary address translations to enable the process that 4170triggers the connection to connect once the link is up despite the 4171peer assigning us a new (dynamic) IP address. 4172.It set mrru Op Ar value 4173Setting this option enables Multi-link PPP negotiations, also known as 4174Multi-link Protocol or MP. There is no default MRRU (Maximum 4175Reconstructed Receive Unit) value. If no argument is given, multi-link 4176mode is disabled. 4177.It set mru Op Ar value 4178The default MRU (Maximum Receive Unit) is 1500. If it is increased, the 4179other side *may* increase its mtu. There is no point in decreasing the 4180MRU to below the default as the 4181.Em PPP 4182protocol *must* be able to accept packets of at least 1500 octets. If 4183no argument is given, 1500 is assumed. 4184.It set mtu Op Ar value 4185The default MTU is 1500. At negotiation time, 4186.Nm 4187will accept whatever MRU or MRRU that the peer wants (assuming it's 4188not less than 296 bytes). If the MTU is set, 4189.Nm 4190will not accept MRU/MRRU values less than 4191.Ar value . 4192When negotiations are complete, the MTU is assigned to the interface, even 4193if the peer requested a higher value MRU/MRRU. This can be useful for 4194limiting your packet size (giving better bandwidth sharing at the expense 4195of more header data). 4196.Pp 4197If no 4198.Ar value 4199is given, 1500, or whatever the peer asks for is used. 4200.It set nbns Op Ar x.x.x.x Op Ar y.y.y.y 4201This option allows the setting of the Microsoft NetBIOS name server 4202values to be returned at the peers request. If no values are given, 4203.Nm 4204will reject any such requests. 4205.It set openmode active|passive Op Ar delay 4206By default, 4207.Ar openmode 4208is always 4209.Ar active 4210with a one second 4211.Ar delay . 4212That is, 4213.Nm 4214will always initiate LCP/IPCP/CCP negotiation one second after the line 4215comes up. If you want to wait for the peer to initiate negotiations, you 4216can use the value 4217.Ar passive . 4218If you want to initiate negotiations immediately or after more than one 4219second, the appropriate 4220.Ar delay 4221may be specified here in seconds. 4222.It set parity odd|even|none|mark 4223This allows the line parity to be set. The default value is 4224.Ar none . 4225.It set phone Ar telno Ns Xo 4226.Oo \&| Ns Ar backupnumber 4227.Oc Ns ... Ns Oo : Ns Ar nextnumber 4228.Oc Ns ... 4229.Xc 4230This allows the specification of the phone number to be used in 4231place of the \\\\T string in the dial and login chat scripts. 4232Multiple phone numbers may be given separated either by a pipe 4233.Pq Dq \&| 4234or a colon 4235.Pq Dq \&: . 4236.Pp 4237Numbers after the pipe are only dialed if the dial or login 4238script for the previous number failed. 4239.Pp 4240Numbers after the colon are tried sequentially, irrespective of 4241the reason the line was dropped. 4242.Pp 4243If multiple numbers are given, 4244.Nm 4245will dial them according to these rules until a connection is made, retrying 4246the maximum number of times specified by 4247.Dq set redial 4248below. In 4249.Fl background 4250mode, each number is attempted at most once. 4251.It set Op proc Ns Xo 4252.No title Op Ar value 4253.Xc 4254The current process title as displayed by 4255.Xr ps 1 4256is changed according to 4257.Ar value . 4258If 4259.Ar value 4260is not specified, the original process title is restored. All the 4261word replacements done by the shell commands (see the 4262.Dq bg 4263command above) are done here too. 4264.Pp 4265Note, if USER is required in the process title, the 4266.Dq set proctitle 4267command must appear in 4268.Pa ppp.linkup , 4269as it is not known when the commands in 4270.Pa ppp.conf 4271are executed. 4272.It set radius Op Ar config-file 4273This command enables RADIUS support (if it's compiled in). 4274.Ar config-file 4275refers to the radius client configuration file as described in 4276.Xr radius.conf 5 . 4277If PAP or CHAP are 4278.Dq enable Ns No d , 4279.Nm 4280behaves as a 4281.Em \&N Ns No etwork 4282.Em \&A Ns No ccess 4283.Em \&S Ns No erver 4284and uses the configured RADIUS server to authenticate rather than 4285authenticating from the 4286.Pa ppp.secret 4287file or from the passwd database. 4288.Pp 4289If neither PAP or CHAP are enabled, 4290.Dq set radius 4291will do nothing. 4292.Pp 4293.Nm 4294uses the following attributes from the RADIUS reply: 4295.Bl -tag -width XXX -offset XXX 4296.It RAD_FRAMED_IP_ADDRESS 4297The peer IP address is set to the given value. 4298.It RAD_FRAMED_IP_NETMASK 4299The tun interface netmask is set to the given value. 4300.It RAD_FRAMED_MTU 4301If the given MTU is less than the peers MRU as agreed during LCP 4302negotiation, *and* it is less that any configured MTU (see the 4303.Dq set mru 4304command), the tun interface MTU is set to the given value. 4305.It RAD_FRAMED_COMPRESSION 4306If the received compression type is 4307.Dq 1 , 4308.Nm 4309will request VJ compression during IPCP negotiations despite any 4310.Dq disable vj 4311configuration command. 4312.It RAD_FRAMED_ROUTE 4313The received string is expected to be in the format 4314.Ar dest Ns Op / Ns Ar bits 4315.Ar gw 4316.Op Ar metrics . 4317Any specified metrics are ignored. 4318.Dv MYADDR 4319and 4320.Dv HISADDR 4321are understood as valid values for 4322.Ar dest 4323and 4324.Ar gw , 4325.Dq default 4326can be used for 4327.Ar dest 4328to sepcify the default route, and 4329.Dq 0.0.0.0 4330is understood to be the same as 4331.Dq default 4332for 4333.Ar dest 4334and 4335.Dv HISADDR 4336for 4337.Ar gw . 4338.Pp 4339For example, a returned value of 4340.Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400 4341would result in a routing table entry to the 1.2.3.0/24 network via 4342.Dv HISADDR 4343and a returned value of 4344.Dq 0.0.0.0 0.0.0.0 4345or 4346.Dq default HISADDR 4347would result in a default route to 4348.Dv HISADDR . 4349.Pp 4350All RADIUS routes are applied after any sticky routes are applied, making 4351RADIUS routes override configured routes. This also applies for RADIUS 4352routes that don't include the 4353.Dv MYADDR 4354or 4355.Dv HISADDR 4356keywords. 4357.Pp 4358.El 4359Values received from the RADIUS server may be viewed using 4360.Dq show bundle . 4361.It set reconnect Ar timeout ntries 4362Should the line drop unexpectedly (due to loss of CD or LQR 4363failure), a connection will be re-established after the given 4364.Ar timeout . 4365The line will be re-connected at most 4366.Ar ntries 4367times. 4368.Ar Ntries 4369defaults to zero. A value of 4370.Ar random 4371for 4372.Ar timeout 4373will result in a variable pause, somewhere between 1 and 30 seconds. 4374.It set recvpipe Op Ar value 4375This sets the routing table RECVPIPE value. The optimum value is 4376just over twice the MTU value. If 4377.Ar value 4378is unspecified or zero, the default kernel controlled value is used. 4379.It set redial Ar secs Ns Xo 4380.Oo + Ns Ar inc Ns 4381.Op - Ns Ar max Ns 4382.Oc Op . Ns Ar next 4383.Op Ar attempts 4384.Xc 4385.Nm 4386can be instructed to attempt to redial 4387.Ar attempts 4388times. If more than one phone number is specified (see 4389.Dq set phone 4390above), a pause of 4391.Ar next 4392is taken before dialing each number. A pause of 4393.Ar secs 4394is taken before starting at the first number again. A literal value of 4395.Dq Li random 4396may be used here in place of 4397.Ar secs 4398and 4399.Ar next , 4400causing a random delay of between 1 and 30 seconds. 4401.Pp 4402If 4403.Ar inc 4404is specified, its value is added onto 4405.Ar secs 4406each time 4407.Nm 4408tries a new number. 4409.Ar secs 4410will only be incremented at most 4411.Ar max 4412times. 4413.Ar max 4414defaults to 10. 4415.Pp 4416Note, the 4417.Ar secs 4418delay will be effective, even after 4419.Ar attempts 4420has been exceeded, so an immediate manual dial may appear to have 4421done nothing. If an immediate dial is required, a 4422.Dq \&! 4423should immediately follow the 4424.Dq open 4425keyword. See the 4426.Dq open 4427description above for further details. 4428.It set sendpipe Op Ar value 4429This sets the routing table SENDPIPE value. The optimum value is 4430just over twice the MTU value. If 4431.Ar value 4432is unspecified or zero, the default kernel controlled value is used. 4433.It set server|socket Ar TcpPort|LocalName|none password Op Ar mask 4434This command tells 4435.Nm 4436to listen on the given socket or 4437.Sq diagnostic port 4438for incoming command connections. 4439.Pp 4440The word 4441.Ar none 4442instructs 4443.Nm 4444to close any existing socket. 4445.Pp 4446If you wish to specify a local domain socket, 4447.Ar LocalName 4448must be specified as an absolute file name, otherwise it is assumed 4449to be the name or number of a TCP port. You must specify the octal umask 4450that should be used with local domain sockets as a four character octal 4451number beginning with 4452.Sq 0 . 4453Refer to 4454.Xr umask 2 4455for umask details. Refer to 4456.Xr services 5 4457for details of how to translate TCP port names. 4458.Pp 4459You must also specify the password that must be entered by the client 4460(using the 4461.Dq passwd 4462command above) when connecting to this socket. If the password is 4463specified as an empty string, no password is required for connecting clients. 4464.Pp 4465When specifying a local domain socket, the first 4466.Dq %d 4467sequence found in the socket name will be replaced with the current 4468interface unit number. This is useful when you wish to use the same 4469profile for more than one connection. 4470.Pp 4471In a similar manner TCP sockets may be prefixed with the 4472.Dq + 4473character, in which case the current interface unit number is added to 4474the port number. 4475.Pp 4476When using 4477.Nm 4478with a server socket, the 4479.Xr pppctl 8 4480command is the preferred mechanism of communications. Currently, 4481.Xr telnet 1 4482can also be used, but link encryption may be implemented in the future, so 4483.Xr telnet 1 4484should not be relied upon. 4485.It set speed Ar value 4486This sets the speed of the serial device. If speed is specified as 4487.Dq sync , 4488.Nm 4489treats the device as a synchronous device. 4490.Pp 4491Certain device types will know whether they should be specified as 4492synchronous or asynchronous. These devices will override incorrect 4493settings and log a warning to this effect. 4494.It set stopped Op Ar LCPseconds Op Ar CCPseconds 4495If this option is set, 4496.Nm 4497will time out after the given FSM (Finite State Machine) has been in 4498the stopped state for the given number of 4499.Dq seconds . 4500This option may be useful if the peer sends a terminate request, 4501but never actually closes the connection despite our sending a terminate 4502acknowledgement. This is also useful if you wish to 4503.Dq set openmode passive 4504and time out if the peer doesn't send a Configure Request within the 4505given time. Use 4506.Dq set log +lcp +ccp 4507to make 4508.Nm 4509log the appropriate state transitions. 4510.Pp 4511The default value is zero, where 4512.Nm 4513doesn't time out in the stopped state. 4514.Pp 4515This value should not be set to less than the openmode delay (see 4516.Dq set openmode 4517above). 4518.It set timeout Ar idleseconds Op Ar mintimeout 4519This command allows the setting of the idle timer. Refer to the 4520section titled 4521.Sx SETTING THE IDLE TIMER 4522for further details. 4523.Pp 4524If 4525.Ar mintimeout 4526is specified, 4527.Nm 4528will never idle out before the link has been up for at least that number 4529of seconds. 4530.It set urgent Xo 4531.Op tcp|udp 4532.Oo Op +|- Ns 4533.Ar port 4534.Oc No ... 4535.Xc 4536This command controls the ports that 4537.Nm 4538prioritizes when transmitting data. The default priority TCP ports 4539are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell), 4540543 (klogin) and 544 (kshell). There are no priority UDP ports by default. 4541See 4542.Xr services 5 4543for details. 4544.Pp 4545If neither 4546.Dq tcp 4547or 4548.Dq udp 4549are specified, 4550.Dq tcp 4551is assumed. 4552.Pp 4553If no 4554.Ar port Ns No s 4555are given, the priority port lists are cleared (although if 4556.Dq tcp 4557or 4558.Dq udp 4559is specified, only that list is cleared). If the first 4560.Ar port 4561argument is prefixed with a plus 4562.Pq Dq \&+ 4563or a minus 4564.Pq Dq \&- , 4565the current list is adjusted, otherwise the list is reassigned. 4566.Ar port Ns No s 4567prefixed with a plus or not prefixed at all are added to the list and 4568.Ar port Ns No s 4569prefixed with a minus are removed from the list. 4570.It set vj slotcomp on|off 4571This command tells 4572.Nm 4573whether it should attempt to negotiate VJ slot compression. By default, 4574slot compression is turned 4575.Ar on . 4576.It set vj slots Ar nslots 4577This command sets the initial number of slots that 4578.Nm 4579will try to negotiate with the peer when VJ compression is enabled (see the 4580.Sq enable 4581command above). It defaults to a value of 16. 4582.Ar Nslots 4583must be between 4584.Ar 4 4585and 4586.Ar 16 4587inclusive. 4588.El 4589.Pp 4590.It shell|! Op Ar command 4591If 4592.Ar command 4593is not specified a shell is invoked according to the 4594.Dv SHELL 4595environment variable. Otherwise, the given 4596.Ar command 4597is executed. Word replacement is done in the same way as for the 4598.Dq !bg 4599command as described above. 4600.Pp 4601Use of the ! character 4602requires a following space as with any of the other commands. You should 4603note that this command is executed in the foreground - 4604.Nm 4605will not continue running until this process has exited. Use the 4606.Dv bg 4607command if you wish processing to happen in the background. 4608.It show Ar var 4609This command allows the user to examine the following: 4610.Bl -tag -width XX 4611.It show bundle 4612Show the current bundle settings. 4613.It show ccp 4614Show the current CCP compression statistics. 4615.It show compress 4616Show the current VJ compression statistics. 4617.It show escape 4618Show the current escape characters. 4619.It show filter Op Ar name 4620List the current rules for the given filter. If 4621.Ar name 4622is not specified, all filters are shown. 4623.It show hdlc 4624Show the current HDLC statistics. 4625.It show help|? 4626Give a summary of available show commands. 4627.It show iface 4628Show the current interface information 4629.Pq the same \&as Dq iface show . 4630.It show ipcp 4631Show the current IPCP statistics. 4632.It show layers 4633Show the protocol layers currently in use. 4634.It show lcp 4635Show the current LCP statistics. 4636.It show Op data Ns Xo 4637.No link 4638.Xc 4639Show high level link information. 4640.It show links 4641Show a list of available logical links. 4642.It show log 4643Show the current log values. 4644.It show mem 4645Show current memory statistics. 4646.It show physical 4647Show low level link information. 4648.It show mp 4649Show Multi-link information. 4650.It show proto 4651Show current protocol totals. 4652.It show route 4653Show the current routing tables. 4654.It show stopped 4655Show the current stopped timeouts. 4656.It show timer 4657Show the active alarm timers. 4658.It show version 4659Show the current version number of 4660.Nm ppp . 4661.El 4662.Pp 4663.It term 4664Go into terminal mode. Characters typed at the keyboard are sent to 4665the device. Characters read from the device are displayed on the 4666screen. When a remote 4667.Em PPP 4668peer is detected, 4669.Nm 4670automatically enables Packet Mode and goes back into command mode. 4671.El 4672.Pp 4673.Sh MORE DETAILS 4674.Bl -bullet 4675.It 4676Read the example configuration files. They are a good source of information. 4677.It 4678Use 4679.Dq help , 4680.Dq nat ? , 4681.Dq enable ? , 4682.Dq set ? 4683and 4684.Dq show ? 4685to get online information about what's available. 4686.It 4687The following URLs contain useful information: 4688.Bl -bullet -compact 4689.It 4690http://www.FreeBSD.org/FAQ/userppp.html 4691.It 4692http://www.FreeBSD.org/handbook/userppp.html 4693.El 4694.Pp 4695.El 4696.Pp 4697.Sh FILES 4698.Nm 4699refers to four files: 4700.Pa ppp.conf , 4701.Pa ppp.linkup , 4702.Pa ppp.linkdown 4703and 4704.Pa ppp.secret . 4705These files are placed in the 4706.Pa /etc/ppp 4707directory. 4708.Bl -tag -width XX 4709.It Pa /etc/ppp/ppp.conf 4710System default configuration file. 4711.It Pa /etc/ppp/ppp.secret 4712An authorisation file for each system. 4713.It Pa /etc/ppp/ppp.linkup 4714A file to check when 4715.Nm 4716establishes a network level connection. 4717.It Pa /etc/ppp/ppp.linkdown 4718A file to check when 4719.Nm 4720closes a network level connection. 4721.It Pa /var/log/ppp.log 4722Logging and debugging information file. Note, this name is specified in 4723.Pa /etc/syslogd.conf . 4724See 4725.Xr syslog.conf 5 4726for further details. 4727.It Pa /var/spool/lock/LCK..* 4728tty port locking file. Refer to 4729.Xr uucplock 3 4730for further details. 4731.It Pa /var/run/tunN.pid 4732The process id (pid) of the 4733.Nm 4734program connected to the tunN device, where 4735.Sq N 4736is the number of the device. 4737.It Pa /var/run/ttyXX.if 4738The tun interface used by this port. Again, this file is only created in 4739.Fl background , 4740.Fl auto 4741and 4742.Fl ddial 4743modes. 4744.It Pa /etc/services 4745Get port number if port number is using service name. 4746.It Pa /var/run/ppp-authname-class-value 4747In multi-link mode, local domain sockets are created using the peer 4748authentication name 4749.Pq Sq authname , 4750the peer endpoint discriminator class 4751.Pq Sq class 4752and the peer endpoint discriminator value 4753.Pq Sq value . 4754As the endpoint discriminator value may be a binary value, it is turned 4755to HEX to determine the actual file name. 4756.Pp 4757This socket is used to pass links between different instances of 4758.Nm ppp . 4759.El 4760.Pp 4761.Sh SEE ALSO 4762.Xr at 1 , 4763.Xr ftp 1 , 4764.Xr gzip 1 , 4765.Xr hostname 1 , 4766.Xr login 1 , 4767.Xr tcpdump 1 , 4768.Xr telnet 1 , 4769.Xr libalias 3 , 4770.Xr syslog 3 , 4771.Xr uucplock 3 , 4772.Xr crontab 5 , 4773.Xr group 5 , 4774.Xr passwd 5 , 4775.Xr radius.conf 5 , 4776.Xr resolv.conf 5 , 4777.Xr syslog.conf 5 , 4778.Xr adduser 8 , 4779.Xr chat 8 , 4780.Xr getty 8 , 4781.Xr inetd 8 , 4782.Xr init 8 , 4783.Xr isdn 8 , 4784.Xr named 8 , 4785.Xr ping 8 , 4786.Xr pppctl 8 , 4787.Xr pppd 8 , 4788.Xr route 8 , 4789.Xr sshd 8 , 4790.Xr syslogd 8 , 4791.Xr traceroute 8 , 4792.Xr vipw 8 4793.Sh HISTORY 4794This program was originally written by 4795.An Toshiharu OHNO Aq tony-o@iij.ad.jp , 4796and was submitted to 4797.Fx 2.0.5 4798by 4799.An Atsushi Murai Aq amurai@spec.co.jp . 4800.Pp 4801It was substantially modified during 1997 by 4802.An Brian Somers Aq brian@Awfulhak.org , 4803and was ported to 4804.Ox 4805in November that year 4806(just after the 2.2 release). 4807.Pp 4808Most of the code was rewritten by 4809.An Brian Somers 4810in early 1998 when multi-link ppp support was added. 4811