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