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. The proxy entry cannot be made unless 2653.Dv HISADDR 2654is an address from a LAN. 2655.It proxyall 2656Default: Disabled. Enabling this will tell 2657.Nm 2658to add proxy arp entries for every IP address in all class C or 2659smaller subnets routed via the tun interface. 2660.Pp 2661Proxy arp entries are only made for sticky routes that are added 2662using the 2663.Dq add 2664command. No proxy arp entries are made for the interface address itself 2665(as created by the 2666.Dq set ifaddr 2667command). 2668.It sroutes 2669Default: Enabled. When the 2670.Dq add 2671command is used with the 2672.Dv HISADDR 2673or 2674.Dv MYADDR 2675values, entries are stored in the 2676.Sq stick route 2677list. Each time 2678.Dv HISADDR 2679or 2680.Dv MYADDR 2681change, this list is re-applied to the routing table. 2682.Pp 2683Disabling this option will prevent the re-application of sticky routes, 2684although the 2685.Sq stick route 2686list will still be maintained. 2687.It throughput 2688Default: Enabled. This option tells 2689.Nm 2690to gather throughput statistics. Input and output is sampled over 2691a rolling 5 second window, and current, best and total figures are 2692retained. This data is output when the relevant 2693.Em PPP 2694layer shuts down, and is also available using the 2695.Dq show 2696command. Throughput statistics are available at the 2697.Dq IPCP 2698and 2699.Dq physical 2700levels. 2701.It utmp 2702Default: Enabled. Normally, when a user is authenticated using PAP or 2703CHAP, and when 2704.Nm 2705is running in 2706.Fl direct 2707mode, an entry is made in the utmp and wtmp files for that user. Disabling 2708this option will tell 2709.Nm 2710not to make any utmp or wtmp entries. This is usually only necessary if 2711you require the user to both login and authenticate themselves. 2712.It iface-alias 2713Default: Enabled if 2714.Fl nat 2715is specified. This option simply tells 2716.Nm 2717to add new interface addresses to the interface rather than replacing them. 2718The option can only be enabled if network address translation is enabled 2719.Pq Dq nat enable yes . 2720.Pp 2721With this option enabled, 2722.Nm 2723will pass traffic for old interface addresses through the NAT engine 2724.Pq see Xr libalias 3 , 2725resulting in the ability (in 2726.Fl auto 2727mode) to properly connect the process that caused the PPP link to 2728come up in the first place. 2729.Pp 2730Disabling NAT with 2731.Dq nat enable no 2732will also disable 2733.Sq iface-alias . 2734.El 2735.Pp 2736.It add Ns Xo 2737.Op \&! 2738.Ar dest Ns Op / Ns Ar nn 2739.Op Ar mask 2740.Op Ar gateway 2741.Xc 2742.Ar Dest 2743is the destination IP address. The netmask is specified either as a 2744number of bits with 2745.Ar /nn 2746or as an IP number using 2747.Ar mask . 2748.Ar 0 0 2749or simply 2750.Ar 0 2751with no mask refers to the default route. It is also possible to use the 2752literal name 2753.Sq default 2754instead of 2755.Ar 0 . 2756.Ar Gateway 2757is the next hop gateway to get to the given 2758.Ar dest 2759machine/network. Refer to the 2760.Xr route 8 2761command for further details. 2762.Pp 2763It is possible to use the symbolic names 2764.Sq MYADDR 2765or 2766.Sq HISADDR 2767as the destination, and 2768.Sq HISADDR 2769as the 2770.Ar gateway . 2771.Sq MYADDR 2772is replaced with the interface address and 2773.Sq HISADDR 2774is replaced with the interface destination (peer) address. 2775.Pp 2776If the 2777.Ar add! 2778command is used 2779.Pq note the trailing Dq \&! , 2780then if the route already exists, it will be updated as with the 2781.Sq route change 2782command (see 2783.Xr route 8 2784for further details). 2785.Pp 2786Routes that contain the 2787.Dq HISADDR , 2788.Dq MYADDR , 2789.Dq DNS0 , 2790or 2791.Dq DNS1 2792constants are considered 2793.Sq sticky . 2794They are stored in a list (use 2795.Dq show ipcp 2796to see the list), and each time the value of 2797.Dv HISADDR , 2798.Dv MYADDR , 2799.Dv DNS0 , 2800or 2801.Dv DNS1 2802changes, the appropriate routing table entries are updated. This facility 2803may be disabled using 2804.Dq disable sroutes . 2805.It allow Ar command Op Ar args 2806This command controls access to 2807.Nm 2808and its configuration files. It is possible to allow user-level access, 2809depending on the configuration file label and on the mode that 2810.Nm 2811is being run in. For example, you may wish to configure 2812.Nm 2813so that only user 2814.Sq fred 2815may access label 2816.Sq fredlabel 2817in 2818.Fl background 2819mode. 2820.Pp 2821User id 0 is immune to these commands. 2822.Bl -tag -width XX 2823.It allow user Ns Xo 2824.Op s 2825.Ar logname Ns No ... 2826.Xc 2827By default, only user id 0 is allowed access to 2828.Nm ppp . 2829If this command is used, all of the listed users are allowed access to 2830the section in which the 2831.Dq allow users 2832command is found. The 2833.Sq default 2834section is always checked first (even though it is only ever automatically 2835loaded at startup). Each successive 2836.Dq allow users 2837command overrides the previous one, so it's possible to allow users access 2838to everything except a given label by specifying default users in the 2839.Sq default 2840section, and then specifying a new user list for that label. 2841.Pp 2842If user 2843.Sq * 2844is specified, access is allowed to all users. 2845.It allow mode Ns Xo 2846.Op s 2847.Ar mode Ns No ... 2848.Xc 2849By default, access using any 2850.Nm 2851mode is possible. If this command is used, it restricts the access 2852.Ar modes 2853allowed to load the label under which this command is specified. 2854Again, as with the 2855.Dq allow users 2856command, each 2857.Dq allow modes 2858command overrides any previous settings, and the 2859.Sq default 2860section is always checked first. 2861.Pp 2862Possible modes are: 2863.Sq interactive , 2864.Sq auto , 2865.Sq direct , 2866.Sq dedicated , 2867.Sq ddial , 2868.Sq background 2869and 2870.Sq * . 2871.Pp 2872When running in multi-link mode, a section can be loaded if it allows 2873.Em any 2874of the currently existing line modes. 2875.El 2876.Pp 2877.It nat Ar command Op Ar args 2878This command allows the control of the network address translation (also 2879known as masquerading or IP aliasing) facilities that are built into 2880.Nm ppp . 2881NAT is done on the external interface only, and is unlikely to make sense 2882if used with the 2883.Fl direct 2884flag. 2885.Pp 2886For backwards compatibility, the word 2887.Dq alias 2888may be used in place of 2889.Dq nat . 2890If nat is enabled on your system (it may be omitted at compile time), 2891the following commands are possible: 2892.Bl -tag -width XX 2893.It nat enable yes|no 2894This command either switches network address translation on or turns it off. 2895The 2896.Fl nat 2897command line flag is synonymous with 2898.Dq nat enable yes . 2899.It nat addr Op Ar addr_local addr_alias 2900This command allows data for 2901.Ar addr_alias 2902to be redirected to 2903.Ar addr_local . 2904It is useful if you own a small number of real IP numbers that 2905you wish to map to specific machines behind your gateway. 2906.It nat deny_incoming yes|no 2907If set to yes, this command will refuse all incoming connections 2908by dropping the packets in much the same way as a firewall would. 2909.It nat help|? 2910This command gives a summary of available nat commands. 2911.It nat log yes|no 2912This option causes various NAT statistics and information to 2913be logged to the file 2914.Pa /var/log/alias.log . 2915This file name is likely to change in the near future. 2916.It nat port Ar proto Ar targetIP Ns Xo 2917.No : Ns Ar targetPort Ns 2918.Oo 2919.No - Ns Ar targetPort 2920.Oc Ar aliasPort Ns 2921.Oo 2922.No - Ns Ar aliasPort 2923.Oc Oo Ar remoteIP : Ns 2924.Ar remotePort Ns 2925.Oo 2926.No - Ns Ar remotePort 2927.Oc Oc 2928.Xc 2929This command causes incoming 2930.Ar proto 2931connections to 2932.Ar aliasPort 2933to be redirected to 2934.Ar targetPort 2935on 2936.Ar targetIP . 2937.Ar proto 2938is either 2939.Dq tcp 2940or 2941.Dq udp . 2942.Pp 2943A range of port numbers may be specified as shown above. The ranges 2944must be of the same size. 2945.Pp 2946If 2947.Ar remoteIP 2948is specified, only data coming from that IP number is redirected. 2949.Ar remotePort 2950must either be 2951.Dq 0 2952.Pq indicating any source port 2953or a range of ports the same size as the other ranges. 2954.Pp 2955This option is useful if you wish to run things like Internet phone on 2956machines behind your gateway, but is limited in that connections to only 2957one interior machine per source machine and target port are possible. 2958.It nat pptp Op Ar addr 2959This tells 2960.Nm 2961to translate any 2962.Em G Ns No eneral 2963.Em R Ns No outing 2964.Em E Ns No encapsulated 2965.Pq Dv IPPROTO_GRE 2966packets using 2967.Ar addr 2968rather than the local interface address. This allows the uses of the 2969.Em P Ns No oint 2970to 2971.Em P Ns No oint 2972.Em T Ns No unneling 2973.Em P Ns No rotocol 2974on a machine on the internal network. 2975.Pp 2976If 2977.Ar addr 2978is not specified, 2979.Dv PPTP 2980address translation is disabled. 2981.It "nat proxy cmd" Ar arg Ns No ... 2982This command tells 2983.Nm 2984to proxy certain connections, redirecting them to a given server. Refer 2985to the description of 2986.Fn PacketAliasProxyRule 2987in 2988.Xr libalias 3 2989for details of the available commands. 2990.It nat same_ports yes|no 2991When enabled, this command will tell the network address translation engine to 2992 attempt to avoid changing the port number on outgoing packets. This is useful 2993if you want to support protocols such as RPC and LPD which require 2994connections to come from a well known port. 2995.It nat target Op Ar address 2996Set the given target address or clear it if no address is given. The target 2997address is used by libalias to specify how to NAT incoming packets by default. 2998If a target address is not set, the alias address (that of the tun interface) 2999is used. 3000.Pp 3001The target address may be set to 3002.Dq default , 3003in which case libalias will not alter the destination address of new 3004incoming data. 3005.It nat use_sockets yes|no 3006When enabled, this option tells the network address translation engine to 3007create a socket so that it can guarantee a correct incoming ftp data or 3008IRC connection. 3009.It nat unregistered_only yes|no 3010Only alter outgoing packets with an unregistered source ad- 3011dress. According to RFC 1918, unregistered source addresses 3012are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16. 3013.El 3014.Pp 3015These commands are also discussed in the file 3016.Pa README.alias 3017which comes with the source distribution. 3018.Pp 3019.It Op \&! Ns Xo 3020.No bg Ar command 3021.Xc 3022The given 3023.Ar command 3024is executed in the background with the following words replaced: 3025.Bl -tag -width PEER_ENDDISC 3026.It Li AUTHNAME 3027This is replaced with the local 3028.Ar authname 3029value. See the 3030.Dq set authname 3031command below. 3032.It Li ENDDISC 3033This is replaced with the local endpoint discriminator value. See the 3034.Dq set enddisc 3035command below. 3036.It Li HISADDR 3037This is replaced with the peers IP number. 3038.It Li INTERFACE 3039This is replaced with the name of the interface that's in use. 3040.It Li LABEL 3041This is replaced with the last label name used. A label may be specified 3042on the 3043.Nm 3044command line, via the 3045.Dq load 3046or 3047.Dq dial 3048commands and in the 3049.Pa ppp.secret 3050file. 3051.It Li MYADDR 3052This is replaced with the IP number assigned to the local interface. 3053.It Li PEER_ENDDISC 3054This is replaced with the value of the peers endpoint discriminator. 3055.It Li PROCESSID 3056This is replaced with the current process id. 3057.It Li USER 3058This is replaced with the username that has been authenticated with PAP or 3059CHAP. Normally, this variable is assigned only in -direct mode. This value 3060is available irrespective of whether utmp logging is enabled. 3061.It Li DNS0 No " & " Li DNS1 3062These are replaced with the primary and secondary nameserver IP numbers. If 3063nameservers are negotiated by IPCP, the values of these macros will change. 3064.El 3065.Pp 3066These substitutions are also done by the 3067.Dq set proctitle 3068command. 3069.Pp 3070If you wish to pause 3071.Nm 3072while the command executes, use the 3073.Dq shell 3074command instead. 3075.It clear physical|ipcp Op current|overall|peak... 3076Clear the specified throughput values at either the 3077.Dq physical 3078or 3079.Dq ipcp 3080level. If 3081.Dq physical 3082is specified, context must be given (see the 3083.Dq link 3084command below). If no second argument is given, all values are 3085cleared. 3086.It clone Ar name Ns Xo 3087.Op \&, Ns Ar name Ns 3088.No ... 3089.Xc 3090Clone the specified link, creating one or more new links according to the 3091.Ar name 3092argument(s). This command must be used from the 3093.Dq link 3094command below unless you've only got a single link (in which case that 3095link becomes the default). Links may be removed using the 3096.Dq remove 3097command below. 3098.Pp 3099The default link name is 3100.Dq deflink . 3101.It close Op lcp|ccp Ns Op \&! 3102If no arguments are given, the relevant protocol layers will be brought 3103down and the link will be closed. If 3104.Dq lcp 3105is specified, the LCP layer is brought down, but 3106.Nm 3107will not bring the link offline. It is subsequently possible to use 3108.Dq term 3109.Pq see below 3110to talk to the peer machine if, for example, something like 3111.Dq slirp 3112is being used. If 3113.Dq ccp 3114is specified, only the relevant compression layer is closed. If the 3115.Dq \&! 3116is used, the compression layer will remain in the closed state, otherwise 3117it will re-enter the STOPPED state, waiting for the peer to initiate 3118further CCP negotiation. In any event, this command does not disconnect 3119the user from 3120.Nm 3121or exit 3122.Nm ppp . 3123See the 3124.Dq quit 3125command below. 3126.It delete Ns Xo 3127.Op \&! 3128.Ar dest 3129.Xc 3130This command deletes the route with the given 3131.Ar dest 3132IP address. If 3133.Ar dest 3134is specified as 3135.Sq ALL , 3136all non-direct entries in the routing table for the current interface, 3137and all 3138.Sq sticky route 3139entries are deleted. If 3140.Ar dest 3141is specified as 3142.Sq default , 3143the default route is deleted. 3144.Pp 3145If the 3146.Ar delete! 3147command is used 3148.Pq note the trailing Dq \&! , 3149.Nm 3150will not complain if the route does not already exist. 3151.It dial|call Op Ar label Ns Xo 3152.No ... 3153.Xc 3154This command is the equivalent of 3155.Dq load label 3156followed by 3157.Dq open , 3158and is provided for backwards compatibility. 3159.It down Op Ar lcp|ccp 3160Bring the relevant layer down ungracefully, as if the underlying layer 3161had become unavailable. It's not considered polite to use this command on 3162a Finite State Machine that's in the OPEN state. If no arguments are 3163supplied, the entire link is closed (or if no context is given, all links 3164are terminated). If 3165.Sq lcp 3166is specified, the 3167.Em LCP 3168layer is terminated but the device is not brought offline and the link 3169is not closed. If 3170.Sq ccp 3171is specified, only the relevant compression layer(s) are terminated. 3172.It help|? Op Ar command 3173Show a list of available commands. If 3174.Ar command 3175is specified, show the usage string for that command. 3176.It iface Ar command Op args 3177This command is used to control the interface used by 3178.Nm ppp . 3179.Ar Command 3180may be one of the following: 3181.Bl -tag -width XX 3182.It iface add Ns Xo 3183.Op \&! 3184.Ar addr Ns Op / Ns Ar bits 3185.Op Ar peer 3186.Xc 3187.It iface add Ns Xo 3188.Op \&! 3189.Ar addr 3190.Ar mask 3191.Ar peer 3192.Xc 3193Add the given 3194.Ar addr mask peer 3195combination to the interface. Instead of specifying 3196.Ar mask , 3197.Ar /bits 3198can be used 3199.Pq with no space between \&it and Ar addr . 3200If the given address already exists, the command fails unless the 3201.Dq \&! 3202is used - in which case the previous interface address entry is overwritten 3203with the new one, allowing a change of netmask or peer address. 3204.Pp 3205If only 3206.Ar addr 3207is specified, 3208.Ar bits 3209defaults to 3210.Dq 32 3211and 3212.Ar peer 3213defaults to 3214.Dq 255.255.255.255 . 3215This address (the broadcast address) is the only duplicate peer address that 3216.Nm 3217allows. 3218.It iface clear 3219If this command is used while 3220.Nm 3221is in the OPENED state or while in 3222.Fl auto 3223mode, all addresses except for the IPCP negotiated address are deleted 3224from the interface. If 3225.Nm 3226is not in the OPENED state and is not in 3227.Fl auto 3228mode, all interface addresses are deleted. 3229.Pp 3230.It iface delete Ns Xo 3231.Op \&! Ns 3232.No |rm Ns Op \&! 3233.Ar addr 3234.Xc 3235This command deletes the given 3236.Ar addr 3237from the interface. If the 3238.Dq \&! 3239is used, no error is given if the address isn't currently assigned to 3240the interface (and no deletion takes place). 3241.It iface show 3242Shows the current state and current addresses for the interface. It is 3243much the same as running 3244.Dq ifconfig INTERFACE . 3245.It iface help Op Ar sub-command 3246This command, when invoked without 3247.Ar sub-command , 3248will show a list of possible 3249.Dq iface 3250sub-commands and a brief synopsis for each. When invoked with 3251.Ar sub-command , 3252only the synopsis for the given sub-command is shown. 3253.El 3254.It Op data Ns Xo 3255.No link 3256.Ar name Ns Op , Ns Ar name Ns 3257.No ... Ar command Op Ar args 3258.Xc 3259This command may prefix any other command if the user wishes to 3260specify which link the command should affect. This is only 3261applicable after multiple links have been created in Multi-link 3262mode using the 3263.Dq clone 3264command. 3265.Pp 3266.Ar Name 3267specifies the name of an existing link. If 3268.Ar name 3269is a comma separated list, 3270.Ar command 3271is executed on each link. If 3272.Ar name 3273is 3274.Dq * , 3275.Ar command 3276is executed on all links. 3277.It load Op Ar label Ns Xo 3278.No ... 3279.Xc 3280Load the given 3281.Ar label Ns No (s) 3282from the 3283.Pa ppp.conf 3284file. If 3285.Ar label 3286is not given, the 3287.Ar default 3288label is used. 3289.Pp 3290Unless the 3291.Ar label 3292section uses the 3293.Dq set mode , 3294.Dq open 3295or 3296.Dq dial 3297commands, 3298.Nm 3299will not attempt to make an immediate connection. 3300.It open Op lcp|ccp|ipcp 3301This is the opposite of the 3302.Dq close 3303command. All closed links are immediately brought up apart from second 3304and subsequent 3305.Ar demand-dial 3306links - these will come up based on the 3307.Dq set autoload 3308command that has been used. 3309.Pp 3310If the 3311.Dq lcp 3312argument is used while the LCP layer is already open, LCP will be 3313renegotiated. This allows various LCP options to be changed, after which 3314.Dq open lcp 3315can be used to put them into effect. After renegotiating LCP, 3316any agreed authentication will also take place. 3317.Pp 3318If the 3319.Dq ccp 3320argument is used, the relevant compression layer is opened. Again, 3321if it is already open, it will be renegotiated. 3322.Pp 3323If the 3324.Dq ipcp 3325argument is used, the link will be brought up as normal, but if 3326IPCP is already open, it will be renegotiated and the network 3327interface will be reconfigured. 3328.Pp 3329It is probably not good practice to re-open the PPP state machines 3330like this as it's possible that the peer will not behave correctly. 3331It 3332.Em is 3333however useful as a way of forcing the CCP or VJ dictionaries to be reset. 3334.It passwd Ar pass 3335Specify the password required for access to the full 3336.Nm 3337command set. This password is required when connecting to the diagnostic 3338port (see the 3339.Dq set server 3340command). 3341.Ar Pass 3342is specified on the 3343.Dq set server 3344command line. The value of 3345.Ar pass 3346is not logged when 3347.Ar command 3348logging is active, instead, the literal string 3349.Sq ******** 3350is logged. 3351.It quit|bye Op all 3352If 3353.Dq quit 3354is executed from the controlling connection or from a command file, 3355ppp will exit after closing all connections. Otherwise, if the user 3356is connected to a diagnostic socket, the connection is simply dropped. 3357.Pp 3358If the 3359.Ar all 3360argument is given, 3361.Nm 3362will exit despite the source of the command after closing all existing 3363connections. 3364.It remove|rm 3365This command removes the given link. It is only really useful in 3366multi-link mode. A link must be 3367in the 3368.Dv CLOSED 3369state before it is removed. 3370.It rename|mv Ar name 3371This command renames the given link to 3372.Ar name . 3373It will fail if 3374.Ar name 3375is already used by another link. 3376.Pp 3377The default link name is 3378.Sq deflink . 3379Renaming it to 3380.Sq modem , 3381.Sq cuaa0 3382or 3383.Sq USR 3384may make the log file more readable. 3385.It resolv Ar command 3386This command controls 3387.Nm Ns No 's 3388manipulation of the 3389.Xr resolv.conf 5 3390file. When 3391.Nm 3392starts up, it loads the contents of this file into memory and retains this 3393image for future use. 3394.Ar command 3395is one of the following: 3396.Bl -tag -width readonly 3397.It Em readonly 3398Treat 3399.Pa /etc/resolv.conf 3400as read only. If 3401.Dq dns 3402is enabled, 3403.Nm 3404will still attempt to negotiate nameservers with the peer, making the results 3405available via the 3406.Dv DNS0 3407and 3408.Dv DNS1 3409macros. This is the opposite of the 3410.Dq resolv writable 3411command. 3412.It Em reload 3413Reload 3414.Pa /etc/resolv.conf 3415into memory. This may be necessary if for example a DHCP client overwrote 3416.Pa /etc/resolv.conf . 3417.It Em restore 3418Replace 3419.Pa /etc/resolv.conf 3420with the version originally read at startup or with the last 3421.Dq resolv reload 3422command. This is sometimes a useful command to put in the 3423.Pa /etc/ppp/ppp.linkdown 3424file. 3425.It Em rewrite 3426Rewrite the 3427.Pa /etc/resolv.conf 3428file. This command will work even if the 3429.Dq resolv readonly 3430command has been used. It may be useful as a command in the 3431.Pa /etc/ppp/ppp.linkup 3432file if you wish to defer updating 3433.Pa /etc/resolv.conf 3434until after other commands have finished. 3435.It Em writable 3436Allow 3437.Nm 3438to update 3439.Pa /etc/resolv.conf 3440if 3441.Dq dns 3442is enabled and 3443.Nm 3444successfully negotiates a DNS. This is the opposite of the 3445.Dq resolv readonly 3446command. 3447.El 3448.It save 3449This option is not (yet) implemented. 3450.It set Ns Xo 3451.No Op up 3452.Ar var value 3453.Xc 3454This option allows the setting of any of the following variables: 3455.Bl -tag -width XX 3456.It set accmap Ar hex-value 3457ACCMap stands for Asynchronous Control Character Map. This is always 3458negotiated with the peer, and defaults to a value of 00000000 in hex. 3459This protocol is required to defeat hardware that depends on passing 3460certain characters from end to end (such as XON/XOFF etc). 3461.Pp 3462For the XON/XOFF scenario, use 3463.Dq set accmap 000a0000 . 3464.It set Op auth Ns Xo 3465.No key Ar value 3466.Xc 3467This sets the authentication key (or password) used in client mode 3468PAP or CHAP negotiation to the given value. It also specifies the 3469password to be used in the dial or login scripts in place of the 3470.Sq \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\P 3471sequence, preventing the actual password from being logged. If 3472.Ar command 3473or 3474.Ar chat 3475logging is in effect, 3476.Ar value 3477is logged as 3478.Sq ******** 3479for security reasons. 3480.Pp 3481If the first character of 3482.Ar value 3483is an exclaimation mark 3484.Pq Dq \&! , 3485.Nm 3486treats the remainder of the string as a program that must be executed 3487to determine the 3488.Dq authname 3489and 3490.Dq authkey 3491values. 3492.Pp 3493Ignoring the 3494.Dq \&! , 3495.Ar value 3496is parsed as a program to execute in the same was as the 3497.Dq !bg 3498command above, substituting special names in the same manner. Once executed, 3499.Nm 3500will feed the program three lines of input, each terminated by a newline 3501character: 3502.Bl -bullet 3503.It 3504The host name as sent in the CHAP challenge. 3505.It 3506The challenge string as sent in the CHAP challenge. 3507.It 3508The locally defined 3509.Dq authname . 3510.El 3511.Pp 3512Two lines of output are expected: 3513.Bl -bullet 3514.It 3515The 3516.Dq authname 3517to be sent with the CHAP response. 3518.It 3519The 3520.Dq authkey , 3521which is encrypted with the challenge and request id, the answer being sent 3522in the CHAP response packet. 3523.El 3524.Pp 3525When configuring 3526.Nm 3527in this manner, it's expected that the host challenge is a series of ASCII 3528digits or characters. An encryption device or Secure ID card is usually 3529required to calculate the secret appropriate for the given challenge. 3530.It set authname Ar id 3531This sets the authentication id used in client mode PAP or CHAP negotiation. 3532.Pp 3533If used in 3534.Fl direct 3535mode with CHAP enabled, 3536.Ar id 3537is used in the initial authentication challenge and should normally be set to 3538the local machine name. 3539.It set autoload Xo 3540.Ar min-percent max-percent period 3541.Xc 3542These settings apply only in multi-link mode and default to zero, zero and 3543five respectively. 3544When more than one 3545.Ar demand-dial 3546.Pq also known as Fl auto 3547mode link is available, only the first link is made active when 3548.Nm 3549first reads data from the tun device. The next 3550.Ar demand-dial 3551link will be opened only when the current bundle throughput is at least 3552.Ar max-percent 3553percent of the total bundle bandwidth for 3554.Ar period 3555seconds. When the current bundle throughput decreases to 3556.Ar min-percent 3557percent or less of the total bundle bandwidth for 3558.Ar period 3559seconds, a 3560.Ar demand-dial 3561link will be brought down as long as it's not the last active 3562.Ar demand-dial 3563link. 3564.Pp 3565The default values cause 3566.Ar demand-dial 3567links to simply come up one at a time. 3568.Pp 3569Certain devices cannot determine their physical bandwidth, so it 3570is sometimes necessary to use the 3571.Dq set bandwidth 3572command (described below) to make 3573.Dq set autoload 3574work correctly. 3575.It set bandwidth Ar value 3576This command sets the connection bandwidth in bits per second. 3577.Ar value 3578must be greater than zero. It is currently only used by the 3579.Dq set autoload 3580command above. 3581.It set callback Ar option Ns No ... 3582If no arguments are given, callback is disabled, otherwise, 3583.Nm 3584will request (or in 3585.Fl direct 3586mode, will accept) one of the given 3587.Ar option Ns No s . 3588In client mode, if an 3589.Ar option 3590is NAK'd 3591.Nm 3592will request a different 3593.Ar option , 3594until no options remain at which point 3595.Nm 3596will terminate negotiations (unless 3597.Dq none 3598is one of the specified 3599.Ar option Ns No ). 3600In server mode, 3601.Nm 3602will accept any of the given protocols - but the client 3603.Em must 3604request one of them. If you wish callback to be optional, you must include 3605.Ar none 3606as an option. 3607.Pp 3608The 3609.Ar option Ns No s 3610are as follows (in this order of preference): 3611.Pp 3612.Bl -tag -width Ds 3613.It auth 3614The callee is expected to decide the callback number based on 3615authentication. If 3616.Nm 3617is the callee, the number should be specified as the fifth field of 3618the peers entry in 3619.Pa /etc/ppp/ppp.secret . 3620.It cbcp 3621Microsoft's callback control protocol is used. See 3622.Dq set cbcp 3623below. 3624.Pp 3625If you wish to negotiate 3626.Ar cbcp 3627in client mode but also wish to allow the server to request no callback at 3628CBCP negotiation time, you must specify both 3629.Ar cbcp 3630and 3631.Ar none 3632as callback options. 3633.It E.164 *| Ns Xo 3634.Ar number Ns Op , Ns Ar number Ns 3635.No ... 3636.Xc 3637The caller specifies the 3638.Ar number . 3639If 3640.Nm 3641is the callee, 3642.Ar number 3643should be either a comma separated list of allowable numbers or a 3644.Dq \&* , 3645meaning any number is permitted. If 3646.Nm 3647is the caller, only a single number should be specified. 3648.Pp 3649Note, this option is very unsafe when used with a 3650.Dq \&* 3651as a malicious caller can tell 3652.Nm 3653to call any (possibly international) number without first authenticating 3654themselves. 3655.It none 3656If the peer does not wish to do callback at all, 3657.Nm 3658will accept the fact and continue without callback rather than terminating 3659the connection. This is required (in addition to one or more other callback 3660options) if you wish callback to be optional. 3661.El 3662.Pp 3663.It set cbcp Oo Xo 3664.No *| Ns Ar number Ns No 3665.Oo 3666.No , Ns Ar number Ns 3667.Oc 3668.No ... 3669.Op Ar delay Op Ar retry 3670.Oc 3671.Xc 3672If no arguments are given, CBCP (Microsoft's CallBack Control Protocol) 3673is disabled - ie, configuring CBCP in the 3674.Dq set callback 3675command will result in 3676.Nm 3677requesting no callback in the CBCP phase. 3678Otherwise, 3679.Nm 3680attempts to use the given phone 3681.Ar number Ns No (s). 3682.Pp 3683In server mode 3684.Pq Fl direct , 3685.Nm 3686will insist that the client uses one of these numbers, unless 3687.Dq \&* 3688is used in which case the client is expected to specify the number. 3689.Pp 3690In client mode, 3691.Nm 3692will attempt to use one of the given numbers (whichever it finds to 3693be agreeable with the peer), or if 3694.Dq \&* 3695is specified, 3696.Nm 3697will expect the peer to specify the number. 3698.It set cd Oo 3699.No off| Ns Ar seconds Ns Op \&! 3700.Oc 3701Normally, 3702.Nm 3703checks for the existence of carrier depending on the type of device 3704that has been opened: 3705.Bl -tag -width XXX -offset XXX 3706.It Terminal Devices 3707Carrier is checked one second after the login script is complete. If it's 3708not set, 3709.Nm 3710assumes that this is because the device doesn't support carrier (which 3711is true for most 3712.Dq laplink 3713NULL-modem cables), logs the fact and stops checking 3714for carrier. 3715.Pp 3716As ptys don't support the TIOCMGET ioctl, the tty device will switch all 3717carrier detection off when it detects that the device is a pty. 3718.It ISDN (i4b) Devices 3719Carrier is checked once per second for 6 seconds. If it's not set after 3720the sixth second, the connection attempt is considered to have failed and 3721the device is closed. Carrier is always required for i4b devices. 3722.It PPPoE (netgraph) Devices 3723Carrier is checked once per second for 5 seconds. If it's not set after 3724the fifth second, the connection attempt is considered to have failed and 3725the device is closed. Carrier is always required for PPPoE devices. 3726.El 3727.Pp 3728All other device types don't support carrier. Setting a carrier value will 3729result in a warning when the device is opened. 3730.Pp 3731Some modems take more than one second after connecting to assert the carrier 3732signal. If this delay isn't increased, this will result in 3733.Nm Ns No 's 3734inability to detect when the link is dropped, as 3735.Nm 3736assumes that the device isn't asserting carrier. 3737.Pp 3738The 3739.Dq set cd 3740command overrides the default carrier behaviour. 3741.Ar seconds 3742specifies the maximum number of seconds that 3743.Nm 3744should wait after the dial script has finished before deciding if 3745carrier is available or not. 3746.Pp 3747If 3748.Dq off 3749is specified, 3750.Nm 3751will not check for carrier on the device, otherwise 3752.Nm 3753will not proceed to the login script until either carrier is detected 3754or until 3755.Ar seconds 3756has elapsed, at which point 3757.Nm 3758assumes that the device will not set carrier. 3759.Pp 3760If no arguments are given, carrier settings will go back to their default 3761values. 3762.Pp 3763If 3764.Ar seconds 3765is followed immediately by an exclaimation mark 3766.Pq Dq \&! , 3767.Nm 3768will 3769.Em require 3770carrier. If carrier is not detected after 3771.Ar seconds 3772seconds, the link will be disconnected. 3773.It set choked Op Ar timeout 3774This sets the number of seconds that 3775.Nm 3776will keep a choked output queue before dropping all pending output packets. 3777If 3778.Ar timeout 3779is less than or equal to zero or if 3780.Ar timeout 3781isn't specified, it is set to the default value of 3782.Em 120 seconds . 3783.Pp 3784A choked output queue occurs when 3785.Nm 3786has read a certain number of packets from the local network for transmission, 3787but cannot send the data due to link failure (the peer is busy etc.). 3788.Nm 3789will not read packets indefinitely. Instead, it reads up to 3790.Em 30 3791packets (or 3792.Em 30 No + 3793.Em nlinks No * 3794.Em 2 3795packets in multi-link mode), then stops reading the network interface 3796until either 3797.Ar timeout 3798seconds have passed or at least one packet has been sent. 3799.Pp 3800If 3801.Ar timeout 3802seconds pass, all pending output packets are dropped. 3803.It set ctsrts|crtscts on|off 3804This sets hardware flow control. Hardware flow control is 3805.Ar on 3806by default. 3807.It set deflate Ar out-winsize Op Ar in-winsize 3808This sets the DEFLATE algorithms default outgoing and incoming window 3809sizes. Both 3810.Ar out-winsize 3811and 3812.Ar in-winsize 3813must be values between 3814.Em 8 3815and 3816.Em 15 . 3817If 3818.Ar in-winsize 3819is specified, 3820.Nm 3821will insist that this window size is used and will not accept any other 3822values from the peer. 3823.It set dns Op Ar primary Op Ar secondary 3824This command specifies DNS overrides for the 3825.Dq accept dns 3826command. Refer to the 3827.Dq accept 3828command description above for details. This command does not affect the 3829IP numbers requested using 3830.Dq enable dns . 3831.It set device|line Xo 3832.Ar value Ns No ... 3833.Xc 3834This sets the device(s) to which 3835.Nm 3836will talk to the given 3837.Dq value . 3838.Pp 3839All ISDN and serial device names are expected to begin with 3840.Pa /dev/ . 3841ISDN devices are usually called 3842.Pa i4brbchX 3843and serial devices are usually called 3844.Pa cuaXX . 3845.Pp 3846If 3847.Dq value 3848does not begin with 3849.Pa /dev/ , 3850it must either begin with an exclamation mark 3851.Pq Dq \&! , 3852be of the format 3853.No PPPoE: Ns Ar iface Ns Xo 3854.Op \&: Ns Ar provider Ns 3855.Xc 3856or be of the format 3857.Ar host Ns No : Ns Ar port Ns Oo 3858.No /tcp|udp 3859.Oc . 3860.Pp 3861If it begins with an exclamation mark, the rest of the device name is 3862treated as a program name, and that program is executed when the device 3863is opened. Standard input, output and error are fed back to 3864.Nm 3865and are read and written as if they were a regular device. 3866.Pp 3867If a 3868.No PPPoE: Ns Ar iface Ns Xo 3869.Op \&: Ns Ar provider Ns 3870.Xc 3871specification is given, 3872.Nm 3873will attempt to create a 3874.Em PPP 3875over Ethernet connection using the given 3876.Ar iface 3877interface. The given 3878.Ar provider 3879is passed as the service name in the PPPoE Discovery Initiation (PADI) 3880packet. If no provider is given, an empty value will be used. Refer to 3881.Xr netgraph 4 3882and 3883.Xr ng_pppoe 8 3884for further details. 3885.Pp 3886If a 3887.Ar host Ns No : Ns Ar port Ns Oo 3888.No /tcp|udp 3889.Oc 3890specification is given, 3891.Nm 3892will attempt to connect to the given 3893.Ar host 3894on the given 3895.Ar port . 3896If a 3897.Dq /tcp 3898or 3899.Dq /udp 3900suffix is not provided, the default is 3901.Dq /tcp . 3902Refer to the section on 3903.Em PPP OVER TCP and UDP 3904above for further details. 3905.Pp 3906If multiple 3907.Dq values 3908are specified, 3909.Nm 3910will attempt to open each one in turn until it succeeds or runs out of 3911devices. 3912.It set dial Ar chat-script 3913This specifies the chat script that will be used to dial the other 3914side. See also the 3915.Dq set login 3916command below. Refer to 3917.Xr chat 8 3918and to the example configuration files for details of the chat script 3919format. 3920It is possible to specify some special 3921.Sq values 3922in your chat script as follows: 3923.Bd -unfilled -offset indent 3924.It Li \\\\\\\\\\\\\\\\c 3925When used as the last character in a 3926.Sq send 3927string, this indicates that a newline should not be appended. 3928.It Li \\\\\\\\\\\\\\\\d 3929When the chat script encounters this sequence, it delays two seconds. 3930.It Li \\\\\\\\\\\\\\\\p 3931When the chat script encounters this sequence, it delays for one quarter of 3932a second. 3933.It Li \\\\\\\\\\\\\\\\n 3934This is replaced with a newline character. 3935.It Li \\\\\\\\\\\\\\\\r 3936This is replaced with a carriage return character. 3937.It Li \\\\\\\\\\\\\\\\s 3938This is replaced with a space character. 3939.It Li \\\\\\\\\\\\\\\\t 3940This is replaced with a tab character. 3941.It Li \\\\\\\\\\\\\\\\T 3942This is replaced by the current phone number (see 3943.Dq set phone 3944below). 3945.It Li \\\\\\\\\\\\\\\\P 3946This is replaced by the current 3947.Ar authkey 3948value (see 3949.Dq set authkey 3950above). 3951.It Li \\\\\\\\\\\\\\\\U 3952This is replaced by the current 3953.Ar authname 3954value (see 3955.Dq set authname 3956above). 3957.Ed 3958.Pp 3959Note that two parsers will examine these escape sequences, so in order to 3960have the 3961.Sq chat parser 3962see the escape character, it is necessary to escape it from the 3963.Sq command parser . 3964This means that in practice you should use two escapes, for example: 3965.Bd -literal -offset indent 3966set dial "... ATDT\\\\T CONNECT" 3967.Ed 3968.Pp 3969It is also possible to execute external commands from the chat script. 3970To do this, the first character of the expect or send string is an 3971exclamation mark 3972.Pq Dq \&! . 3973When the command is executed, standard input and standard output are 3974directed to the open device (see the 3975.Dq set device 3976command), and standard error is read by 3977.Nm 3978and substituted as the expect or send string. If 3979.Nm 3980is running in interactive mode, file descriptor 3 is attached to 3981.Pa /dev/tty . 3982.Pp 3983For example (wrapped for readability); 3984.Bd -literal -offset indent 3985set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e 3986word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e 3987\\"!/bin/echo in\\" HELLO" 3988.Ed 3989.Pp 3990would result in the following chat sequence (output using the 3991.Sq set log local chat 3992command before dialing): 3993.Bd -literal -offset indent 3994Dial attempt 1 of 1 3995dial OK! 3996Chat: Expecting: 3997Chat: Sending: 3998Chat: Expecting: login:--login: 3999Chat: Wait for (5): login: 4000Chat: Sending: ppp 4001Chat: Expecting: word: 4002Chat: Wait for (5): word: 4003Chat: Sending: ppp 4004Chat: Expecting: !sh \\-c "echo \\-n label: >&2" 4005Chat: Exec: sh -c "echo -n label: >&2" 4006Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label: 4007Chat: Exec: /bin/echo in 4008Chat: Sending: 4009Chat: Expecting: HELLO 4010Chat: Wait for (5): HELLO 4011login OK! 4012.Ed 4013.Pp 4014Note (again) the use of the escape character, allowing many levels of 4015nesting. Here, there are four parsers at work. The first parses the 4016original line, reading it as three arguments. The second parses the 4017third argument, reading it as 11 arguments. At this point, it is 4018important that the 4019.Dq \&- 4020signs are escaped, otherwise this parser will see them as constituting 4021an expect-send-expect sequence. When the 4022.Dq \&! 4023character is seen, the execution parser reads the first command as three 4024arguments, and then 4025.Xr sh 1 4026itself expands the argument after the 4027.Fl c . 4028As we wish to send the output back to the modem, in the first example 4029we redirect our output to file descriptor 2 (stderr) so that 4030.Nm 4031itself sends and logs it, and in the second example, we just output to stdout, 4032which is attached directly to the modem. 4033.Pp 4034This, of course means that it is possible to execute an entirely external 4035.Dq chat 4036command rather than using the internal one. See 4037.Xr chat 8 4038for a good alternative. 4039.Pp 4040The external command that is executed is subjected to the same special 4041word expansions as the 4042.Dq !bg 4043command. 4044.It set enddisc Op label|IP|MAC|magic|psn value 4045This command sets our local endpoint discriminator. If set prior to 4046LCP negotiation, and if no 4047.Dq disable enddisc 4048command has been used, 4049.Nm 4050will send the information to the peer using the LCP endpoint discriminator 4051option. The following discriminators may be set: 4052.Bd -unfilled -offset indent 4053.It Li label 4054The current label is used. 4055.It Li IP 4056Our local IP number is used. As LCP is negotiated prior to IPCP, it is 4057possible that the IPCP layer will subsequently change this value. If 4058it does, the endpoint discriminator stays at the old value unless manually 4059reset. 4060.It Li MAC 4061This is similar to the 4062.Ar IP 4063option above, except that the MAC address associated with the local IP 4064number is used. If the local IP number is not resident on any Ethernet 4065interface, the command will fail. 4066.Pp 4067As the local IP number defaults to whatever the machine host name is, 4068.Dq set enddisc mac 4069is usually done prior to any 4070.Dq set ifaddr 4071commands. 4072.It Li magic 4073A 20 digit random number is used. Care should be taken when using magic 4074numbers as restarting 4075.Nm 4076or creating a link using a different 4077.Nm 4078invocation will also use a different magic number and will therefore not 4079be recognised by the peer as belonging to the same bundle. This makes it 4080unsuitable for 4081.Fl direct 4082connections. 4083.It Li psn Ar value 4084The given 4085.Ar value 4086is used. 4087.Ar Value 4088should be set to an absolute public switched network number with the 4089country code first. 4090.Ed 4091.Pp 4092If no arguments are given, the endpoint discriminator is reset. 4093.It set escape Ar value... 4094This option is similar to the 4095.Dq set accmap 4096option above. It allows the user to specify a set of characters that 4097will be 4098.Sq escaped 4099as they travel across the link. 4100.It set filter dial|alive|in|out Ar rule-no Xo 4101.No permit|deny|clear| Ns Ar rule-no 4102.Op \&! 4103.Oo Op host 4104.Ar src_addr Ns Op / Ns Ar width 4105.Op Ar dst_addr Ns Op / Ns Ar width 4106.Oc Oo tcp|udp|ospf|igmp|icmp Op src lt|eq|gt Ar port 4107.Op dst lt|eq|gt Ar port 4108.Op estab 4109.Op syn 4110.Op finrst 4111.Oc 4112.Xc 4113.Nm 4114supports four filter sets. The 4115.Em alive 4116filter specifies packets that keep the connection alive - resetting the 4117idle timer. The 4118.Em dial 4119filter specifies packets that cause 4120.Nm 4121to dial when in 4122.Fl auto 4123mode. The 4124.Em in 4125filter specifies packets that are allowed to travel 4126into the machine and the 4127.Em out 4128filter specifies packets that are allowed out of the machine. 4129.Pp 4130Filtering is done prior to any IP alterations that might be done by the 4131NAT engine on outgoing packets and after any IP alterations that might 4132be done by the NAT engine on incoming packets. By default all filter 4133sets allow all packets to pass. Rules are processed in order according to 4134.Ar rule-no 4135(unless skipped by specifying a rule number as the 4136.Ar action ) . 4137Up to 40 rules may be given for each set. If a packet doesn't match 4138any of the rules in a given set, it is discarded. In the case of 4139.Em in 4140and 4141.Em out 4142filters, this means that the packet is dropped. In the case of 4143.Em alive 4144filters it means that the packet will not reset the idle timer and in 4145the case of 4146.Em dial 4147filters it means that the packet will not trigger a dial. A packet failing 4148to trigger a dial will be dropped rather than queued. Refer to the 4149section on 4150.Sx PACKET FILTERING 4151above for further details. 4152.It set hangup Ar chat-script 4153This specifies the chat script that will be used to reset the device 4154before it is closed. It should not normally be necessary, but can 4155be used for devices that fail to reset themselves properly on close. 4156.It set help|? Op Ar command 4157This command gives a summary of available set commands, or if 4158.Ar command 4159is specified, the command usage is shown. 4160.It set ifaddr Oo Ar myaddr Ns 4161.Op / Ns Ar \&nn 4162.Oo Ar hisaddr Ns Op / Ns Ar \&nn 4163.Oo Ar netmask 4164.Op Ar triggeraddr 4165.Oc Oc 4166.Oc 4167This command specifies the IP addresses that will be used during 4168IPCP negotiation. Addresses are specified using the format 4169.Pp 4170.Dl a.b.c.d/nn 4171.Pp 4172Where 4173.Dq a.b.c.d 4174is the preferred IP, but 4175.Ar nn 4176specifies how many bits of the address we will insist on. If 4177.No / Ns Ar nn 4178is omitted, it defaults to 4179.Dq /32 4180unless the IP address is 0.0.0.0 in which case it defaults to 4181.Dq /0 . 4182.Pp 4183If you wish to assign a dynamic IP number to the peer, 4184.Ar hisaddr 4185may also be specified as a range of IP numbers in the format 4186.Bd -literal -offset indent 4187.Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Xo 4188.Oc Oo , Ns Ar \&IP Ns 4189.Op \&- Ns Ar \&IP Ns 4190.Oc No ... 4191.Xc 4192.Ed 4193.Pp 4194for example: 4195.Pp 4196.Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20 4197.Pp 4198will only negotiate 4199.Dq 10.0.0.1 4200as the local IP number, but may assign any of the given 10 IP 4201numbers to the peer. If the peer requests one of these numbers, 4202and that number is not already in use, 4203.Nm 4204will grant the peers request. This is useful if the peer wants 4205to re-establish a link using the same IP number as was previously 4206allocated (thus maintaining any existing tcp or udp connections). 4207.Pp 4208If the peer requests an IP number that's either outside 4209of this range or is already in use, 4210.Nm 4211will suggest a random unused IP number from the range. 4212.Pp 4213If 4214.Ar triggeraddr 4215is specified, it is used in place of 4216.Ar myaddr 4217in the initial IPCP negotiation. However, only an address in the 4218.Ar myaddr 4219range will be accepted. This is useful when negotiating with some 4220.Dv PPP 4221implementations that will not assign an IP number unless their peer 4222requests 4223.Dq 0.0.0.0 . 4224.Pp 4225It should be noted that in 4226.Fl auto 4227mode, 4228.Nm 4229will configure the interface immediately upon reading the 4230.Dq set ifaddr 4231line in the config file. In any other mode, these values are just 4232used for IPCP negotiations, and the interface isn't configured 4233until the IPCP layer is up. 4234.Pp 4235Note that the 4236.Ar HISADDR 4237argument may be overridden by the third field in the 4238.Pa ppp.secret 4239file once the client has authenticated itself 4240.Pq if PAP or CHAP are Dq enabled . 4241Refer to the 4242.Sx AUTHENTICATING INCOMING CONNECTIONS 4243section for details. 4244.Pp 4245In all cases, if the interface is already configured, 4246.Nm 4247will try to maintain the interface IP numbers so that any existing 4248bound sockets will remain valid. 4249.It set ccpretry|ccpretries Oo Ar timeout 4250.Op Ar reqtries Op Ar trmtries 4251.Oc 4252.It set chapretry|chapretries Oo Ar timeout 4253.Op Ar reqtries 4254.Oc 4255.It set ipcpretry|ipcpretries Oo Ar timeout 4256.Op Ar reqtries Op Ar trmtries 4257.Oc 4258.It set lcpretry|lcpretries Oo Ar timeout 4259.Op Ar reqtries Op Ar trmtries 4260.Oc 4261.It set papretry|papretries Oo Ar timeout 4262.Op Ar reqtries 4263.Oc 4264These commands set the number of seconds that 4265.Nm 4266will wait before resending Finite State Machine (FSM) Request packets. 4267The default 4268.Ar timeout 4269for all FSMs is 3 seconds (which should suffice in most cases). 4270.Pp 4271If 4272.Ar reqtries 4273is specified, it tells 4274.Nm 4275how many configuration request attempts it should make while receiving 4276no reply from the peer before giving up. The default is 5 attempts for 4277CCP, LCP and IPCP and 3 attempts for PAP and CHAP. 4278.Pp 4279If 4280.Ar trmtries 4281is specified, it tells 4282.Nm 4283how many terminate requests should be sent before giving up waiting for the 4284peers response. The default is 3 attempts. Authentication protocols are 4285not terminated and it is therefore invalid to specify 4286.Ar trmtries 4287for PAP or CHAP. 4288.Pp 4289In order to avoid negotiations with the peer that will never converge, 4290.Nm 4291will only send at most 3 times the configured number of 4292.Ar reqtries 4293in any given negotiation session before giving up and closing that layer. 4294.It set log Xo 4295.Op local 4296.Op +|- Ns 4297.Ar value Ns No ... 4298.Xc 4299This command allows the adjustment of the current log level. Refer 4300to the Logging Facility section for further details. 4301.It set login Ar chat-script 4302This 4303.Ar chat-script 4304compliments the dial-script. If both are specified, the login 4305script will be executed after the dial script. Escape sequences 4306available in the dial script are also available here. 4307.It set logout Ar chat-script 4308This specifies the chat script that will be used to logout 4309before the hangup script is called. It should not normally be necessary. 4310.It set lqrperiod Ar frequency 4311This command sets the 4312.Ar frequency 4313in seconds at which 4314.Em LQR 4315or 4316.Em ECHO LQR 4317packets are sent. The default is 30 seconds. You must also use the 4318.Dq enable lqr 4319command if you wish to send LQR requests to the peer. 4320.It set mode Ar interactive|auto|ddial|background 4321This command allows you to change the 4322.Sq mode 4323of the specified link. This is normally only useful in multi-link mode, 4324but may also be used in uni-link mode. 4325.Pp 4326It is not possible to change a link that is 4327.Sq direct 4328or 4329.Sq dedicated . 4330.Pp 4331Note: If you issue the command 4332.Dq set mode auto , 4333and have network address translation enabled, it may be useful to 4334.Dq enable iface-alias 4335afterwards. This will allow 4336.Nm 4337to do the necessary address translations to enable the process that 4338triggers the connection to connect once the link is up despite the 4339peer assigning us a new (dynamic) IP address. 4340.It set mrru Op Ar value 4341Setting this option enables Multi-link PPP negotiations, also known as 4342Multi-link Protocol or MP. There is no default MRRU (Maximum 4343Reconstructed Receive Unit) value. If no argument is given, multi-link 4344mode is disabled. 4345.It set mru Op Ar value 4346The default MRU (Maximum Receive Unit) is 1500. If it is increased, the 4347other side *may* increase its mtu. There is no point in decreasing the 4348MRU to below the default as the 4349.Em PPP 4350protocol *must* be able to accept packets of at least 1500 octets. If 4351no argument is given, 1500 is assumed. 4352.It set mtu Op Ar value 4353The default MTU is 1500. At negotiation time, 4354.Nm 4355will accept whatever MRU or MRRU that the peer wants (assuming it's 4356not less than 296 bytes). If the MTU is set, 4357.Nm 4358will not accept MRU/MRRU values less than 4359.Ar value . 4360When negotiations are complete, the MTU is assigned to the interface, even 4361if the peer requested a higher value MRU/MRRU. This can be useful for 4362limiting your packet size (giving better bandwidth sharing at the expense 4363of more header data). 4364.Pp 4365If no 4366.Ar value 4367is given, 1500, or whatever the peer asks for is used. 4368.It set nbns Op Ar x.x.x.x Op Ar y.y.y.y 4369This option allows the setting of the Microsoft NetBIOS name server 4370values to be returned at the peers request. If no values are given, 4371.Nm 4372will reject any such requests. 4373.It set openmode active|passive Op Ar delay 4374By default, 4375.Ar openmode 4376is always 4377.Ar active 4378with a one second 4379.Ar delay . 4380That is, 4381.Nm 4382will always initiate LCP/IPCP/CCP negotiation one second after the line 4383comes up. If you want to wait for the peer to initiate negotiations, you 4384can use the value 4385.Ar passive . 4386If you want to initiate negotiations immediately or after more than one 4387second, the appropriate 4388.Ar delay 4389may be specified here in seconds. 4390.It set parity odd|even|none|mark 4391This allows the line parity to be set. The default value is 4392.Ar none . 4393.It set phone Ar telno Ns Xo 4394.Oo \&| Ns Ar backupnumber 4395.Oc Ns ... Ns Oo : Ns Ar nextnumber 4396.Oc Ns ... 4397.Xc 4398This allows the specification of the phone number to be used in 4399place of the \\\\T string in the dial and login chat scripts. 4400Multiple phone numbers may be given separated either by a pipe 4401.Pq Dq \&| 4402or a colon 4403.Pq Dq \&: . 4404.Pp 4405Numbers after the pipe are only dialed if the dial or login 4406script for the previous number failed. 4407.Pp 4408Numbers after the colon are tried sequentially, irrespective of 4409the reason the line was dropped. 4410.Pp 4411If multiple numbers are given, 4412.Nm 4413will dial them according to these rules until a connection is made, retrying 4414the maximum number of times specified by 4415.Dq set redial 4416below. In 4417.Fl background 4418mode, each number is attempted at most once. 4419.It set Op proc Ns Xo 4420.No title Op Ar value 4421.Xc 4422The current process title as displayed by 4423.Xr ps 1 4424is changed according to 4425.Ar value . 4426If 4427.Ar value 4428is not specified, the original process title is restored. All the 4429word replacements done by the shell commands (see the 4430.Dq bg 4431command above) are done here too. 4432.Pp 4433Note, if USER is required in the process title, the 4434.Dq set proctitle 4435command must appear in 4436.Pa ppp.linkup , 4437as it is not known when the commands in 4438.Pa ppp.conf 4439are executed. 4440.It set radius Op Ar config-file 4441This command enables RADIUS support (if it's compiled in). 4442.Ar config-file 4443refers to the radius client configuration file as described in 4444.Xr radius.conf 5 . 4445If PAP or CHAP are 4446.Dq enable Ns No d , 4447.Nm 4448behaves as a 4449.Em \&N Ns No etwork 4450.Em \&A Ns No ccess 4451.Em \&S Ns No erver 4452and uses the configured RADIUS server to authenticate rather than 4453authenticating from the 4454.Pa ppp.secret 4455file or from the passwd database. 4456.Pp 4457If neither PAP or CHAP are enabled, 4458.Dq set radius 4459will do nothing. 4460.Pp 4461.Nm 4462uses the following attributes from the RADIUS reply: 4463.Bl -tag -width XXX -offset XXX 4464.It RAD_FRAMED_IP_ADDRESS 4465The peer IP address is set to the given value. 4466.It RAD_FRAMED_IP_NETMASK 4467The tun interface netmask is set to the given value. 4468.It RAD_FRAMED_MTU 4469If the given MTU is less than the peers MRU as agreed during LCP 4470negotiation, *and* it is less that any configured MTU (see the 4471.Dq set mru 4472command), the tun interface MTU is set to the given value. 4473.It RAD_FRAMED_COMPRESSION 4474If the received compression type is 4475.Dq 1 , 4476.Nm 4477will request VJ compression during IPCP negotiations despite any 4478.Dq disable vj 4479configuration command. 4480.It RAD_FRAMED_ROUTE 4481The received string is expected to be in the format 4482.Ar dest Ns Op / Ns Ar bits 4483.Ar gw 4484.Op Ar metrics . 4485Any specified metrics are ignored. 4486.Dv MYADDR 4487and 4488.Dv HISADDR 4489are understood as valid values for 4490.Ar dest 4491and 4492.Ar gw , 4493.Dq default 4494can be used for 4495.Ar dest 4496to sepcify the default route, and 4497.Dq 0.0.0.0 4498is understood to be the same as 4499.Dq default 4500for 4501.Ar dest 4502and 4503.Dv HISADDR 4504for 4505.Ar gw . 4506.Pp 4507For example, a returned value of 4508.Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400 4509would result in a routing table entry to the 1.2.3.0/24 network via 4510.Dv HISADDR 4511and a returned value of 4512.Dq 0.0.0.0 0.0.0.0 4513or 4514.Dq default HISADDR 4515would result in a default route to 4516.Dv HISADDR . 4517.Pp 4518All RADIUS routes are applied after any sticky routes are applied, making 4519RADIUS routes override configured routes. This also applies for RADIUS 4520routes that don't include the 4521.Dv MYADDR 4522or 4523.Dv HISADDR 4524keywords. 4525.Pp 4526.El 4527Values received from the RADIUS server may be viewed using 4528.Dq show bundle . 4529.It set reconnect Ar timeout ntries 4530Should the line drop unexpectedly (due to loss of CD or LQR 4531failure), a connection will be re-established after the given 4532.Ar timeout . 4533The line will be re-connected at most 4534.Ar ntries 4535times. 4536.Ar Ntries 4537defaults to zero. A value of 4538.Ar random 4539for 4540.Ar timeout 4541will result in a variable pause, somewhere between 1 and 30 seconds. 4542.It set recvpipe Op Ar value 4543This sets the routing table RECVPIPE value. The optimum value is 4544just over twice the MTU value. If 4545.Ar value 4546is unspecified or zero, the default kernel controlled value is used. 4547.It set redial Ar secs Ns Xo 4548.Oo + Ns Ar inc Ns 4549.Op - Ns Ar max Ns 4550.Oc Op . Ns Ar next 4551.Op Ar attempts 4552.Xc 4553.Nm 4554can be instructed to attempt to redial 4555.Ar attempts 4556times. If more than one phone number is specified (see 4557.Dq set phone 4558above), a pause of 4559.Ar next 4560is taken before dialing each number. A pause of 4561.Ar secs 4562is taken before starting at the first number again. A literal value of 4563.Dq Li random 4564may be used here in place of 4565.Ar secs 4566and 4567.Ar next , 4568causing a random delay of between 1 and 30 seconds. 4569.Pp 4570If 4571.Ar inc 4572is specified, its value is added onto 4573.Ar secs 4574each time 4575.Nm 4576tries a new number. 4577.Ar secs 4578will only be incremented at most 4579.Ar max 4580times. 4581.Ar max 4582defaults to 10. 4583.Pp 4584Note, the 4585.Ar secs 4586delay will be effective, even after 4587.Ar attempts 4588has been exceeded, so an immediate manual dial may appear to have 4589done nothing. If an immediate dial is required, a 4590.Dq \&! 4591should immediately follow the 4592.Dq open 4593keyword. See the 4594.Dq open 4595description above for further details. 4596.It set sendpipe Op Ar value 4597This sets the routing table SENDPIPE value. The optimum value is 4598just over twice the MTU value. If 4599.Ar value 4600is unspecified or zero, the default kernel controlled value is used. 4601.It set server|socket Ar TcpPort|LocalName|none password Op Ar mask 4602This command tells 4603.Nm 4604to listen on the given socket or 4605.Sq diagnostic port 4606for incoming command connections. 4607.Pp 4608The word 4609.Ar none 4610instructs 4611.Nm 4612to close any existing socket. 4613.Pp 4614If you wish to specify a local domain socket, 4615.Ar LocalName 4616must be specified as an absolute file name, otherwise it is assumed 4617to be the name or number of a TCP port. You must specify the octal umask 4618to be used with a local domain socket. Refer to 4619.Xr umask 2 4620for umask details. Refer to 4621.Xr services 5 4622for details of how to translate TCP port names. 4623.Pp 4624You must also specify the password that must be entered by the client 4625(using the 4626.Dq passwd 4627command above) when connecting to this socket. If the password is 4628specified as an empty string, no password is required for connecting clients. 4629.Pp 4630When specifying a local domain socket, the first 4631.Dq %d 4632sequence found in the socket name will be replaced with the current 4633interface unit number. This is useful when you wish to use the same 4634profile for more than one connection. 4635.Pp 4636In a similar manner TCP sockets may be prefixed with the 4637.Dq + 4638character, in which case the current interface unit number is added to 4639the port number. 4640.Pp 4641When using 4642.Nm 4643with a server socket, the 4644.Xr pppctl 8 4645command is the preferred mechanism of communications. Currently, 4646.Xr telnet 1 4647can also be used, but link encryption may be implemented in the future, so 4648.Xr telnet 1 4649should not be relied upon. 4650.It set speed Ar value 4651This sets the speed of the serial device. If speed is specified as 4652.Dq sync , 4653.Nm 4654treats the device as a synchronous device. 4655.Pp 4656Certain device types will know whether they should be specified as 4657synchronous or asynchronous. These devices will override incorrect 4658settings and log a warning to this effect. 4659.It set stopped Op Ar LCPseconds Op Ar CCPseconds 4660If this option is set, 4661.Nm 4662will time out after the given FSM (Finite State Machine) has been in 4663the stopped state for the given number of 4664.Dq seconds . 4665This option may be useful if the peer sends a terminate request, 4666but never actually closes the connection despite our sending a terminate 4667acknowledgement. This is also useful if you wish to 4668.Dq set openmode passive 4669and time out if the peer doesn't send a Configure Request within the 4670given time. Use 4671.Dq set log +lcp +ccp 4672to make 4673.Nm 4674log the appropriate state transitions. 4675.Pp 4676The default value is zero, where 4677.Nm 4678doesn't time out in the stopped state. 4679.Pp 4680This value should not be set to less than the openmode delay (see 4681.Dq set openmode 4682above). 4683.It set timeout Ar idleseconds Op Ar mintimeout 4684This command allows the setting of the idle timer. Refer to the 4685section titled 4686.Sx SETTING THE IDLE TIMER 4687for further details. 4688.Pp 4689If 4690.Ar mintimeout 4691is specified, 4692.Nm 4693will never idle out before the link has been up for at least that number 4694of seconds. 4695.It set urgent Xo 4696.Op tcp|udp 4697.Oo Op +|- Ns 4698.Ar port 4699.Oc No ... 4700.Xc 4701This command controls the ports that 4702.Nm 4703prioritizes when transmitting data. The default priority TCP ports 4704are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell), 4705543 (klogin) and 544 (kshell). There are no priority UDP ports by default. 4706See 4707.Xr services 5 4708for details. 4709.Pp 4710If neither 4711.Dq tcp 4712or 4713.Dq udp 4714are specified, 4715.Dq tcp 4716is assumed. 4717.Pp 4718If no 4719.Ar port Ns No s 4720are given, the priority port lists are cleared (although if 4721.Dq tcp 4722or 4723.Dq udp 4724is specified, only that list is cleared). If the first 4725.Ar port 4726argument is prefixed with a plus 4727.Pq Dq \&+ 4728or a minus 4729.Pq Dq \&- , 4730the current list is adjusted, otherwise the list is reassigned. 4731.Ar port Ns No s 4732prefixed with a plus or not prefixed at all are added to the list and 4733.Ar port Ns No s 4734prefixed with a minus are removed from the list. 4735.It set vj slotcomp on|off 4736This command tells 4737.Nm 4738whether it should attempt to negotiate VJ slot compression. By default, 4739slot compression is turned 4740.Ar on . 4741.It set vj slots Ar nslots 4742This command sets the initial number of slots that 4743.Nm 4744will try to negotiate with the peer when VJ compression is enabled (see the 4745.Sq enable 4746command above). It defaults to a value of 16. 4747.Ar Nslots 4748must be between 4749.Ar 4 4750and 4751.Ar 16 4752inclusive. 4753.El 4754.Pp 4755.It shell|! Op Ar command 4756If 4757.Ar command 4758is not specified a shell is invoked according to the 4759.Dv SHELL 4760environment variable. Otherwise, the given 4761.Ar command 4762is executed. Word replacement is done in the same way as for the 4763.Dq !bg 4764command as described above. 4765.Pp 4766Use of the ! character 4767requires a following space as with any of the other commands. You should 4768note that this command is executed in the foreground - 4769.Nm 4770will not continue running until this process has exited. Use the 4771.Dv bg 4772command if you wish processing to happen in the background. 4773.It show Ar var 4774This command allows the user to examine the following: 4775.Bl -tag -width XX 4776.It show bundle 4777Show the current bundle settings. 4778.It show ccp 4779Show the current CCP compression statistics. 4780.It show compress 4781Show the current VJ compression statistics. 4782.It show escape 4783Show the current escape characters. 4784.It show filter Op Ar name 4785List the current rules for the given filter. If 4786.Ar name 4787is not specified, all filters are shown. 4788.It show hdlc 4789Show the current HDLC statistics. 4790.It show help|? 4791Give a summary of available show commands. 4792.It show iface 4793Show the current interface information 4794.Pq the same \&as Dq iface show . 4795.It show ipcp 4796Show the current IPCP statistics. 4797.It show layers 4798Show the protocol layers currently in use. 4799.It show lcp 4800Show the current LCP statistics. 4801.It show Op data Ns Xo 4802.No link 4803.Xc 4804Show high level link information. 4805.It show links 4806Show a list of available logical links. 4807.It show log 4808Show the current log values. 4809.It show mem 4810Show current memory statistics. 4811.It show physical 4812Show low level link information. 4813.It show mp 4814Show Multi-link information. 4815.It show proto 4816Show current protocol totals. 4817.It show route 4818Show the current routing tables. 4819.It show stopped 4820Show the current stopped timeouts. 4821.It show timer 4822Show the active alarm timers. 4823.It show version 4824Show the current version number of 4825.Nm ppp . 4826.El 4827.Pp 4828.It term 4829Go into terminal mode. Characters typed at the keyboard are sent to 4830the device. Characters read from the device are displayed on the 4831screen. When a remote 4832.Em PPP 4833peer is detected, 4834.Nm 4835automatically enables Packet Mode and goes back into command mode. 4836.El 4837.Pp 4838.Sh MORE DETAILS 4839.Bl -bullet 4840.It 4841Read the example configuration files. They are a good source of information. 4842.It 4843Use 4844.Dq help , 4845.Dq nat ? , 4846.Dq enable ? , 4847.Dq set ? 4848and 4849.Dq show ? 4850to get online information about what's available. 4851.It 4852The following URLs contain useful information: 4853.Bl -bullet -compact 4854.It 4855http://www.FreeBSD.org/FAQ/userppp.html 4856.It 4857http://www.FreeBSD.org/handbook/userppp.html 4858.El 4859.Pp 4860.El 4861.Pp 4862.Sh FILES 4863.Nm 4864refers to four files: 4865.Pa ppp.conf , 4866.Pa ppp.linkup , 4867.Pa ppp.linkdown 4868and 4869.Pa ppp.secret . 4870These files are placed in the 4871.Pa /etc/ppp 4872directory. 4873.Bl -tag -width XX 4874.It Pa /etc/ppp/ppp.conf 4875System default configuration file. 4876.It Pa /etc/ppp/ppp.secret 4877An authorisation file for each system. 4878.It Pa /etc/ppp/ppp.linkup 4879A file to check when 4880.Nm 4881establishes a network level connection. 4882.It Pa /etc/ppp/ppp.linkdown 4883A file to check when 4884.Nm 4885closes a network level connection. 4886.It Pa /var/log/ppp.log 4887Logging and debugging information file. Note, this name is specified in 4888.Pa /etc/syslogd.conf . 4889See 4890.Xr syslog.conf 5 4891for further details. 4892.It Pa /var/spool/lock/LCK..* 4893tty port locking file. Refer to 4894.Xr uucplock 3 4895for further details. 4896.It Pa /var/run/tunN.pid 4897The process id (pid) of the 4898.Nm 4899program connected to the tunN device, where 4900.Sq N 4901is the number of the device. 4902.It Pa /var/run/ttyXX.if 4903The tun interface used by this port. Again, this file is only created in 4904.Fl background , 4905.Fl auto 4906and 4907.Fl ddial 4908modes. 4909.It Pa /etc/services 4910Get port number if port number is using service name. 4911.It Pa /var/run/ppp-authname-class-value 4912In multi-link mode, local domain sockets are created using the peer 4913authentication name 4914.Pq Sq authname , 4915the peer endpoint discriminator class 4916.Pq Sq class 4917and the peer endpoint discriminator value 4918.Pq Sq value . 4919As the endpoint discriminator value may be a binary value, it is turned 4920to HEX to determine the actual file name. 4921.Pp 4922This socket is used to pass links between different instances of 4923.Nm ppp . 4924.El 4925.Pp 4926.Sh SEE ALSO 4927.Xr at 1 , 4928.Xr ftp 1 , 4929.Xr gzip 1 , 4930.Xr hostname 1 , 4931.Xr login 1 , 4932.Xr tcpdump 1 , 4933.Xr telnet 1 , 4934.Xr libalias 3 , 4935.Xr syslog 3 , 4936.Xr uucplock 3 , 4937.Xr netgraph 4 , 4938.Xr crontab 5 , 4939.Xr group 5 , 4940.Xr passwd 5 , 4941.Xr radius.conf 5 , 4942.Xr resolv.conf 5 , 4943.Xr syslog.conf 5 , 4944.Xr adduser 8 , 4945.Xr chat 8 , 4946.Xr getty 8 , 4947.Xr inetd 8 , 4948.Xr init 8 , 4949.Xr isdn 8 , 4950.Xr named 8 , 4951.Xr ng_pppoe 8 , 4952.Xr ping 8 , 4953.Xr pppctl 8 , 4954.Xr pppd 8 , 4955.Xr route 8 , 4956.Xr sshd 8 , 4957.Xr syslogd 8 , 4958.Xr traceroute 8 , 4959.Xr vipw 8 4960.Sh HISTORY 4961This program was originally written by 4962.An Toshiharu OHNO Aq tony-o@iij.ad.jp , 4963and was submitted to 4964.Fx 2.0.5 4965by 4966.An Atsushi Murai Aq amurai@spec.co.jp . 4967.Pp 4968It was substantially modified during 1997 by 4969.An Brian Somers Aq brian@Awfulhak.org , 4970and was ported to 4971.Ox 4972in November that year 4973(just after the 2.2 release). 4974.Pp 4975Most of the code was rewritten by 4976.An Brian Somers 4977in early 1998 when multi-link ppp support was added. 4978