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