1.\" $FreeBSD$ 2.Dd September 20, 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 compatibility) 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 ! 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: Enabled and Accepted. 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 Accepted. 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 Accepted. 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 Op tcp Ns Xo 3011.No mssfixup 3012.Xc 3013Default: Enabled. 3014This option tells 3015.Nm 3016to adjust outgoing TCP SYN packets so that the maximum receive segment 3017size is not greater than the amount allowed by the interface MTU. 3018.It throughput 3019Default: Enabled. 3020This option tells 3021.Nm 3022to gather throughput statistics. 3023Input and output is sampled over 3024a rolling 5 second window, and current, best and total figures are retained. 3025This data is output when the relevant 3026.Em PPP 3027layer shuts down, and is also available using the 3028.Dq show 3029command. 3030Throughput statistics are available at the 3031.Dq IPCP 3032and 3033.Dq physical 3034levels. 3035.It utmp 3036Default: Enabled. 3037Normally, when a user is authenticated using PAP or CHAP, and when 3038.Nm 3039is running in 3040.Fl direct 3041mode, an entry is made in the utmp and wtmp files for that user. 3042Disabling this option will tell 3043.Nm 3044not to make any utmp or wtmp entries. 3045This is usually only necessary if 3046you require the user to both login and authenticate themselves. 3047.It iface-alias 3048Default: Enabled if 3049.Fl nat 3050is specified. 3051This option simply tells 3052.Nm 3053to add new interface addresses to the interface rather than replacing them. 3054The option can only be enabled if network address translation is enabled 3055.Pq Dq nat enable yes . 3056.Pp 3057With this option enabled, 3058.Nm 3059will pass traffic for old interface addresses through the NAT engine 3060.Pq see Xr libalias 3 , 3061resulting in the ability (in 3062.Fl auto 3063mode) to properly connect the process that caused the PPP link to 3064come up in the first place. 3065.Pp 3066Disabling NAT with 3067.Dq nat enable no 3068will also disable 3069.Sq iface-alias . 3070.El 3071.Pp 3072.It add Ns Xo 3073.Op \&! 3074.Ar dest Ns Op / Ns Ar nn 3075.Op Ar mask 3076.Op Ar gateway 3077.Xc 3078.Ar Dest 3079is the destination IP address. 3080The netmask is specified either as a number of bits with 3081.Ar /nn 3082or as an IP number using 3083.Ar mask . 3084.Ar 0 0 3085or simply 3086.Ar 0 3087with no mask refers to the default route. 3088It is also possible to use the literal name 3089.Sq default 3090instead of 3091.Ar 0 . 3092.Ar Gateway 3093is the next hop gateway to get to the given 3094.Ar dest 3095machine/network. 3096Refer to the 3097.Xr route 8 3098command for further details. 3099.Pp 3100It is possible to use the symbolic names 3101.Sq MYADDR 3102or 3103.Sq HISADDR 3104as the destination, and 3105.Sq HISADDR 3106as the 3107.Ar gateway . 3108.Sq MYADDR 3109is replaced with the interface address and 3110.Sq HISADDR 3111is replaced with the interface destination (peer) address. 3112.Pp 3113If the 3114.Ar add!\& 3115command is used 3116.Pq note the trailing Dq \&! , 3117then if the route already exists, it will be updated as with the 3118.Sq route change 3119command (see 3120.Xr route 8 3121for further details). 3122.Pp 3123Routes that contain the 3124.Dq HISADDR , 3125.Dq MYADDR , 3126.Dq DNS0 , 3127or 3128.Dq DNS1 3129constants are considered 3130.Sq sticky . 3131They are stored in a list (use 3132.Dq show ipcp 3133to see the list), and each time the value of 3134.Dv HISADDR , 3135.Dv MYADDR , 3136.Dv DNS0 , 3137or 3138.Dv DNS1 3139changes, the appropriate routing table entries are updated. 3140This facility may be disabled using 3141.Dq disable sroutes . 3142.It allow Ar command Op Ar args 3143This command controls access to 3144.Nm 3145and its configuration files. 3146It is possible to allow user-level access, 3147depending on the configuration file label and on the mode that 3148.Nm 3149is being run in. 3150For example, you may wish to configure 3151.Nm 3152so that only user 3153.Sq fred 3154may access label 3155.Sq fredlabel 3156in 3157.Fl background 3158mode. 3159.Pp 3160User id 0 is immune to these commands. 3161.Bl -tag -width 2n 3162.It allow user Ns Xo 3163.Op s 3164.Ar logname Ns No ... 3165.Xc 3166By default, only user id 0 is allowed access to 3167.Nm . 3168If this command is used, all of the listed users are allowed access to 3169the section in which the 3170.Dq allow users 3171command is found. 3172The 3173.Sq default 3174section is always checked first (even though it is only ever automatically 3175loaded at startup). 3176.Dq allow users 3177commands are cumulative in a given section, but users allowed in any given 3178section override users allowed in the default section, so it's possible to 3179allow users access to everything except a given label by specifying default 3180users in the 3181.Sq default 3182section, and then specifying a new user list for that label. 3183.Pp 3184If user 3185.Sq * 3186is specified, access is allowed to all users. 3187.It allow mode Ns Xo 3188.Op s 3189.Ar mode Ns No ... 3190.Xc 3191By default, access using any 3192.Nm 3193mode is possible. 3194If this command is used, it restricts the access 3195.Ar modes 3196allowed to load the label under which this command is specified. 3197Again, as with the 3198.Dq allow users 3199command, each 3200.Dq allow modes 3201command overrides any previous settings, and the 3202.Sq default 3203section is always checked first. 3204.Pp 3205Possible modes are: 3206.Sq interactive , 3207.Sq auto , 3208.Sq direct , 3209.Sq dedicated , 3210.Sq ddial , 3211.Sq background 3212and 3213.Sq * . 3214.Pp 3215When running in multi-link mode, a section can be loaded if it allows 3216.Em any 3217of the currently existing line modes. 3218.El 3219.Pp 3220.It nat Ar command Op Ar args 3221This command allows the control of the network address translation (also 3222known as masquerading or IP aliasing) facilities that are built into 3223.Nm . 3224NAT is done on the external interface only, and is unlikely to make sense 3225if used with the 3226.Fl direct 3227flag. 3228.Pp 3229For backwards compatibility, the word 3230.Dq alias 3231may be used in place of 3232.Dq nat . 3233If nat is enabled on your system (it may be omitted at compile time), 3234the following commands are possible: 3235.Bl -tag -width 2n 3236.It nat enable yes|no 3237This command either switches network address translation on or turns it off. 3238The 3239.Fl nat 3240command line flag is synonymous with 3241.Dq nat enable yes . 3242.It nat addr Op Ar addr_local addr_alias 3243This command allows data for 3244.Ar addr_alias 3245to be redirected to 3246.Ar addr_local . 3247It is useful if you own a small number of real IP numbers that 3248you wish to map to specific machines behind your gateway. 3249.It nat deny_incoming yes|no 3250If set to yes, this command will refuse all incoming packets where an 3251aliasing link doesn't already exist. 3252Refer to the 3253.Sx CONCEPTUAL BACKGROUND 3254section of 3255.Xr libalias 3 3256for a description of what an 3257.Dq aliasing link 3258is. 3259.Pp 3260It should be noted under what circumstances an aliasing link is created by 3261.Xr libalias 3 . 3262It may be necessary to further protect your network from outside 3263connections using the 3264.Dq set filter 3265or 3266.Dq nat target 3267commands. 3268.It nat help|? 3269This command gives a summary of available nat commands. 3270.It nat log yes|no 3271This option causes various NAT statistics and information to 3272be logged to the file 3273.Pa /var/log/alias.log . 3274.It nat port Ar proto Ar targetIP Ns Xo 3275.No : Ns Ar targetPort Ns 3276.Oo 3277.No - Ns Ar targetPort 3278.Oc Ar aliasPort Ns 3279.Oo 3280.No - Ns Ar aliasPort 3281.Oc Oo Ar remoteIP : Ns 3282.Ar remotePort Ns 3283.Oo 3284.No - Ns Ar remotePort 3285.Oc Oc 3286.Xc 3287This command causes incoming 3288.Ar proto 3289connections to 3290.Ar aliasPort 3291to be redirected to 3292.Ar targetPort 3293on 3294.Ar targetIP . 3295.Ar proto 3296is either 3297.Dq tcp 3298or 3299.Dq udp . 3300.Pp 3301A range of port numbers may be specified as shown above. 3302The ranges must be of the same size. 3303.Pp 3304If 3305.Ar remoteIP 3306is specified, only data coming from that IP number is redirected. 3307.Ar remotePort 3308must either be 3309.Dq 0 3310.Pq indicating any source port 3311or a range of ports the same size as the other ranges. 3312.Pp 3313This option is useful if you wish to run things like Internet phone on 3314machines behind your gateway, but is limited in that connections to only 3315one interior machine per source machine and target port are possible. 3316.It "nat proxy cmd" Ar arg Ns No ... 3317This command tells 3318.Nm 3319to proxy certain connections, redirecting them to a given server. 3320Refer to the description of 3321.Fn PacketAliasProxyRule 3322in 3323.Xr libalias 3 3324for details of the available commands. 3325.It nat same_ports yes|no 3326When enabled, this command will tell the network address translation engine to 3327attempt to avoid changing the port number on outgoing packets. 3328This is useful 3329if you want to support protocols such as RPC and LPD which require 3330connections to come from a well known port. 3331.It nat target Op Ar address 3332Set the given target address or clear it if no address is given. 3333The target address is used by libalias to specify how to NAT incoming 3334packets by default. 3335If a target address is not set or if 3336.Dq default 3337is given, packets are not altered and are allowed to route to the internal 3338network. 3339.Pp 3340The target address may be set to 3341.Dq MYADDR , 3342in which case libalias will redirect all packets to the interface address. 3343.It nat use_sockets yes|no 3344When enabled, this option tells the network address translation engine to 3345create a socket so that it can guarantee a correct incoming ftp data or 3346IRC connection. 3347.It nat unregistered_only yes|no 3348Only alter outgoing packets with an unregistered source address. 3349According to RFC 1918, unregistered source addresses 3350are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16. 3351.El 3352.Pp 3353These commands are also discussed in the file 3354.Pa README.alias 3355which comes with the source distribution. 3356.Pp 3357.It Op \&! Ns Xo 3358.No bg Ar command 3359.Xc 3360The given 3361.Ar command 3362is executed in the background with the following words replaced: 3363.Bl -tag -width PEER_ENDDISC 3364.It Li AUTHNAME 3365This is replaced with the local 3366.Ar authname 3367value. 3368See the 3369.Dq set authname 3370command below. 3371.It Li COMPILATIONDATE 3372This is replaced with the date on which 3373.Nm 3374was compiled. 3375.It Li DNS0 & DNS1 3376These are replaced with the primary and secondary nameserver IP numbers. 3377If nameservers are negotiated by IPCP, the values of these macros will change. 3378.It Li ENDDISC 3379This is replaced with the local endpoint discriminator value. 3380See the 3381.Dq set enddisc 3382command below. 3383.It Li HISADDR 3384This is replaced with the peers IP number. 3385.It Li INTERFACE 3386This is replaced with the name of the interface that's in use. 3387.It Li LABEL 3388This is replaced with the last label name used. 3389A label may be specified on the 3390.Nm 3391command line, via the 3392.Dq load 3393or 3394.Dq dial 3395commands and in the 3396.Pa ppp.secret 3397file. 3398.It Li MYADDR 3399This is replaced with the IP number assigned to the local interface. 3400.It Li PEER_ENDDISC 3401This is replaced with the value of the peers endpoint discriminator. 3402.It Li PROCESSID 3403This is replaced with the current process id. 3404.It Li VERSION 3405This is replaced with the current version number of 3406.Nm . 3407.It Li USER 3408This is replaced with the username that has been authenticated with PAP or 3409CHAP. 3410Normally, this variable is assigned only in -direct mode. 3411This value is available irrespective of whether utmp logging is enabled. 3412.El 3413.Pp 3414These substitutions are also done by the 3415.Dq set proctitle 3416command. 3417.Pp 3418If you wish to pause 3419.Nm 3420while the command executes, use the 3421.Dq shell 3422command instead. 3423.It clear physical|ipcp Op current|overall|peak... 3424Clear the specified throughput values at either the 3425.Dq physical 3426or 3427.Dq ipcp 3428level. 3429If 3430.Dq physical 3431is specified, context must be given (see the 3432.Dq link 3433command below). 3434If no second argument is given, all values are cleared. 3435.It clone Ar name Ns Xo 3436.Op \&, Ns Ar name Ns 3437.No ... 3438.Xc 3439Clone the specified link, creating one or more new links according to the 3440.Ar name 3441argument(s). 3442This command must be used from the 3443.Dq link 3444command below unless you've only got a single link (in which case that 3445link becomes the default). 3446Links may be removed using the 3447.Dq remove 3448command below. 3449.Pp 3450The default link name is 3451.Dq deflink . 3452.It close Op lcp|ccp Ns Op \&! 3453If no arguments are given, the relevant protocol layers will be brought 3454down and the link will be closed. 3455If 3456.Dq lcp 3457is specified, the LCP layer is brought down, but 3458.Nm 3459will not bring the link offline. 3460It is subsequently possible to use 3461.Dq term 3462.Pq see below 3463to talk to the peer machine if, for example, something like 3464.Dq slirp 3465is being used. 3466If 3467.Dq ccp 3468is specified, only the relevant compression layer is closed. 3469If the 3470.Dq !\& 3471is used, the compression layer will remain in the closed state, otherwise 3472it will re-enter the STOPPED state, waiting for the peer to initiate 3473further CCP negotiation. 3474In any event, this command does not disconnect the user from 3475.Nm 3476or exit 3477.Nm . 3478See the 3479.Dq quit 3480command below. 3481.It delete Ns Xo 3482.Op \&! 3483.Ar dest 3484.Xc 3485This command deletes the route with the given 3486.Ar dest 3487IP address. 3488If 3489.Ar dest 3490is specified as 3491.Sq ALL , 3492all non-direct entries in the routing table for the current interface, 3493and all 3494.Sq sticky route 3495entries are deleted. 3496If 3497.Ar dest 3498is specified as 3499.Sq default , 3500the default route is deleted. 3501.Pp 3502If the 3503.Ar delete!\& 3504command is used 3505.Pq note the trailing Dq \&! , 3506.Nm 3507will not complain if the route does not already exist. 3508.It dial|call Op Ar label Ns Xo 3509.No ... 3510.Xc 3511This command is the equivalent of 3512.Dq load label 3513followed by 3514.Dq open , 3515and is provided for backwards compatibility. 3516.It down Op Ar lcp|ccp 3517Bring the relevant layer down ungracefully, as if the underlying layer 3518had become unavailable. 3519It's not considered polite to use this command on 3520a Finite State Machine that's in the OPEN state. 3521If no arguments are 3522supplied, the entire link is closed (or if no context is given, all links 3523are terminated). 3524If 3525.Sq lcp 3526is specified, the 3527.Em LCP 3528layer is terminated but the device is not brought offline and the link 3529is not closed. 3530If 3531.Sq ccp 3532is specified, only the relevant compression layer(s) are terminated. 3533.It help|? Op Ar command 3534Show a list of available commands. 3535If 3536.Ar command 3537is specified, show the usage string for that command. 3538.It ident Op Ar text Ns No ... 3539Identify the link to the peer using 3540.Ar text . 3541If 3542.Ar text 3543is empty, link identification is disabled. 3544It is possible to use any of the words described for the 3545.Ic bg 3546command above. 3547Refer to the 3548.Ic sendident 3549command for details of when 3550.Nm 3551identifies itself to the peer. 3552.It iface Ar command Op args 3553This command is used to control the interface used by 3554.Nm . 3555.Ar Command 3556may be one of the following: 3557.Bl -tag -width 2n 3558.It iface add Ns Xo 3559.Op \&! 3560.Ar addr Ns Op / Ns Ar bits 3561.Op Ar peer 3562.Xc 3563.It iface add Ns Xo 3564.Op \&! 3565.Ar addr 3566.Ar mask 3567.Ar peer 3568.Xc 3569Add the given 3570.Ar addr mask peer 3571combination to the interface. 3572Instead of specifying 3573.Ar mask , 3574.Ar /bits 3575can be used 3576.Pq with no space between \&it and Ar addr . 3577If the given address already exists, the command fails unless the 3578.Dq !\& 3579is used - in which case the previous interface address entry is overwritten 3580with the new one, allowing a change of netmask or peer address. 3581.Pp 3582If only 3583.Ar addr 3584is specified, 3585.Ar bits 3586defaults to 3587.Dq 32 3588and 3589.Ar peer 3590defaults to 3591.Dq 255.255.255.255 . 3592This address (the broadcast address) is the only duplicate peer address that 3593.Nm 3594allows. 3595.It iface clear 3596If this command is used while 3597.Nm 3598is in the OPENED state or while in 3599.Fl auto 3600mode, all addresses except for the IPCP negotiated address are deleted 3601from the interface. 3602If 3603.Nm 3604is not in the OPENED state and is not in 3605.Fl auto 3606mode, all interface addresses are deleted. 3607.Pp 3608.It iface delete Ns Xo 3609.Op !\& Ns 3610.No |rm Ns Op !\& 3611.Ar addr 3612.Xc 3613This command deletes the given 3614.Ar addr 3615from the interface. 3616If the 3617.Dq !\& 3618is used, no error is given if the address isn't currently assigned to 3619the interface (and no deletion takes place). 3620.It iface show 3621Shows the current state and current addresses for the interface. 3622It is much the same as running 3623.Dq ifconfig INTERFACE . 3624.It iface help Op Ar sub-command 3625This command, when invoked without 3626.Ar sub-command , 3627will show a list of possible 3628.Dq iface 3629sub-commands and a brief synopsis for each. 3630When invoked with 3631.Ar sub-command , 3632only the synopsis for the given sub-command is shown. 3633.El 3634.It Op data Ns Xo 3635.No link 3636.Ar name Ns Op , Ns Ar name Ns 3637.No ... Ar command Op Ar args 3638.Xc 3639This command may prefix any other command if the user wishes to 3640specify which link the command should affect. 3641This is only applicable after multiple links have been created in Multi-link 3642mode using the 3643.Dq clone 3644command. 3645.Pp 3646.Ar Name 3647specifies the name of an existing link. 3648If 3649.Ar name 3650is a comma separated list, 3651.Ar command 3652is executed on each link. 3653If 3654.Ar name 3655is 3656.Dq * , 3657.Ar command 3658is executed on all links. 3659.It load Op Ar label Ns Xo 3660.No ... 3661.Xc 3662Load the given 3663.Ar label Ns No (s) 3664from the 3665.Pa ppp.conf 3666file. 3667If 3668.Ar label 3669is not given, the 3670.Ar default 3671label is used. 3672.Pp 3673Unless the 3674.Ar label 3675section uses the 3676.Dq set mode , 3677.Dq open 3678or 3679.Dq dial 3680commands, 3681.Nm 3682will not attempt to make an immediate connection. 3683.It open Op lcp|ccp|ipcp 3684This is the opposite of the 3685.Dq close 3686command. 3687All closed links are immediately brought up apart from second and subsequent 3688.Ar demand-dial 3689links - these will come up based on the 3690.Dq set autoload 3691command that has been used. 3692.Pp 3693If the 3694.Dq lcp 3695argument is used while the LCP layer is already open, LCP will be 3696renegotiated. 3697This allows various LCP options to be changed, after which 3698.Dq open lcp 3699can be used to put them into effect. 3700After renegotiating LCP, 3701any agreed authentication will also take place. 3702.Pp 3703If the 3704.Dq ccp 3705argument is used, the relevant compression layer is opened. 3706Again, if it is already open, it will be renegotiated. 3707.Pp 3708If the 3709.Dq ipcp 3710argument is used, the link will be brought up as normal, but if 3711IPCP is already open, it will be renegotiated and the network 3712interface will be reconfigured. 3713.Pp 3714It is probably not good practice to re-open the PPP state machines 3715like this as it's possible that the peer will not behave correctly. 3716It 3717.Em is 3718however useful as a way of forcing the CCP or VJ dictionaries to be reset. 3719.It passwd Ar pass 3720Specify the password required for access to the full 3721.Nm 3722command set. 3723This password is required when connecting to the diagnostic port (see the 3724.Dq set server 3725command). 3726.Ar Pass 3727is specified on the 3728.Dq set server 3729command line. 3730The value of 3731.Ar pass 3732is not logged when 3733.Ar command 3734logging is active, instead, the literal string 3735.Sq ******** 3736is logged. 3737.It quit|bye Op all 3738If 3739.Dq quit 3740is executed from the controlling connection or from a command file, 3741ppp will exit after closing all connections. 3742Otherwise, if the user 3743is connected to a diagnostic socket, the connection is simply dropped. 3744.Pp 3745If the 3746.Ar all 3747argument is given, 3748.Nm 3749will exit despite the source of the command after closing all existing 3750connections. 3751.It remove|rm 3752This command removes the given link. 3753It is only really useful in multi-link mode. 3754A link must be in the 3755.Dv CLOSED 3756state before it is removed. 3757.It rename|mv Ar name 3758This command renames the given link to 3759.Ar name . 3760It will fail if 3761.Ar name 3762is already used by another link. 3763.Pp 3764The default link name is 3765.Sq deflink . 3766Renaming it to 3767.Sq modem , 3768.Sq cuaa0 3769or 3770.Sq USR 3771may make the log file more readable. 3772.It resolv Ar command 3773This command controls 3774.Nm Ns No 's 3775manipulation of the 3776.Xr resolv.conf 5 3777file. 3778When 3779.Nm 3780starts up, it loads the contents of this file into memory and retains this 3781image for future use. 3782.Ar command 3783is one of the following: 3784.Bl -tag -width readonly 3785.It Em readonly 3786Treat 3787.Pa /etc/resolv.conf 3788as read only. 3789If 3790.Dq dns 3791is enabled, 3792.Nm 3793will still attempt to negotiate nameservers with the peer, making the results 3794available via the 3795.Dv DNS0 3796and 3797.Dv DNS1 3798macros. 3799This is the opposite of the 3800.Dq resolv writable 3801command. 3802.It Em reload 3803Reload 3804.Pa /etc/resolv.conf 3805into memory. 3806This may be necessary if for example a DHCP client overwrote 3807.Pa /etc/resolv.conf . 3808.It Em restore 3809Replace 3810.Pa /etc/resolv.conf 3811with the version originally read at startup or with the last 3812.Dq resolv reload 3813command. 3814This is sometimes a useful command to put in the 3815.Pa /etc/ppp/ppp.linkdown 3816file. 3817.It Em rewrite 3818Rewrite the 3819.Pa /etc/resolv.conf 3820file. 3821This command will work even if the 3822.Dq resolv readonly 3823command has been used. 3824It may be useful as a command in the 3825.Pa /etc/ppp/ppp.linkup 3826file if you wish to defer updating 3827.Pa /etc/resolv.conf 3828until after other commands have finished. 3829.It Em writable 3830Allow 3831.Nm 3832to update 3833.Pa /etc/resolv.conf 3834if 3835.Dq dns 3836is enabled and 3837.Nm 3838successfully negotiates a DNS. 3839This is the opposite of the 3840.Dq resolv readonly 3841command. 3842.El 3843.It save 3844This option is not (yet) implemented. 3845.It sendident 3846This command tells 3847.Nm 3848to identify itself to the peer. 3849The link must be in LCP state or higher. 3850If no identity has been set (via the 3851.Ic ident 3852command), 3853.Ic sendident 3854will fail. 3855.Pp 3856When an identity has been set, 3857.Nm 3858will automatically identify itself when it sends or receives a configure 3859reject, when negotiation fails or when LCP reaches the opened state. 3860.Pp 3861Received identification packets are logged to the LCP log (see 3862.Ic set log 3863for details) and are never responded to. 3864.It set Ns Xo 3865.No Op up 3866.Ar var value 3867.Xc 3868This option allows the setting of any of the following variables: 3869.Bl -tag -width 2n 3870.It set accmap Ar hex-value 3871ACCMap stands for Asynchronous Control Character Map. 3872This is always 3873negotiated with the peer, and defaults to a value of 00000000 in hex. 3874This protocol is required to defeat hardware that depends on passing 3875certain characters from end to end (such as XON/XOFF etc). 3876.Pp 3877For the XON/XOFF scenario, use 3878.Dq set accmap 000a0000 . 3879.It set Op auth Ns Xo 3880.No key Ar value 3881.Xc 3882This sets the authentication key (or password) used in client mode 3883PAP or CHAP negotiation to the given value. 3884It also specifies the 3885password to be used in the dial or login scripts in place of the 3886.Sq \eP 3887sequence, preventing the actual password from being logged. 3888If 3889.Ar command 3890or 3891.Ar chat 3892logging is in effect, 3893.Ar value 3894is logged as 3895.Sq ******** 3896for security reasons. 3897.Pp 3898If the first character of 3899.Ar value 3900is an exclamation mark 3901.Pq Dq \&! , 3902.Nm 3903treats the remainder of the string as a program that must be executed 3904to determine the 3905.Dq authname 3906and 3907.Dq authkey 3908values. 3909.Pp 3910If the 3911.Dq !\& 3912is doubled up 3913.Pq to Dq \&!! , 3914it is treated as a single literal 3915.Dq \&! , 3916otherwise, ignoring the 3917.Dq \&! , 3918.Ar value 3919is parsed as a program to execute in the same was as the 3920.Dq !bg 3921command above, substituting special names in the same manner. 3922Once executed, 3923.Nm 3924will feed the program three lines of input, each terminated by a newline 3925character: 3926.Bl -bullet 3927.It 3928The host name as sent in the CHAP challenge. 3929.It 3930The challenge string as sent in the CHAP challenge. 3931.It 3932The locally defined 3933.Dq authname . 3934.El 3935.Pp 3936Two lines of output are expected: 3937.Bl -bullet 3938.It 3939The 3940.Dq authname 3941to be sent with the CHAP response. 3942.It 3943The 3944.Dq authkey , 3945which is encrypted with the challenge and request id, the answer being sent 3946in the CHAP response packet. 3947.El 3948.Pp 3949When configuring 3950.Nm 3951in this manner, it's expected that the host challenge is a series of ASCII 3952digits or characters. 3953An encryption device or Secure ID card is usually 3954required to calculate the secret appropriate for the given challenge. 3955.It set authname Ar id 3956This sets the authentication id used in client mode PAP or CHAP negotiation. 3957.Pp 3958If used in 3959.Fl direct 3960mode with CHAP enabled, 3961.Ar id 3962is used in the initial authentication challenge and should normally be set to 3963the local machine name. 3964.It set autoload Xo 3965.Ar min-percent max-percent period 3966.Xc 3967These settings apply only in multi-link mode and default to zero, zero and 3968five respectively. 3969When more than one 3970.Ar demand-dial 3971.Pq also known as Fl auto 3972mode link is available, only the first link is made active when 3973.Nm 3974first reads data from the tun device. 3975The next 3976.Ar demand-dial 3977link will be opened only when the current bundle throughput is at least 3978.Ar max-percent 3979percent of the total bundle bandwidth for 3980.Ar period 3981seconds. 3982When the current bundle throughput decreases to 3983.Ar min-percent 3984percent or less of the total bundle bandwidth for 3985.Ar period 3986seconds, a 3987.Ar demand-dial 3988link will be brought down as long as it's not the last active link. 3989.Pp 3990Bundle throughput is measured as the maximum of inbound and outbound 3991traffic. 3992.Pp 3993The default values cause 3994.Ar demand-dial 3995links to simply come up one at a time. 3996.Pp 3997Certain devices cannot determine their physical bandwidth, so it 3998is sometimes necessary to use the 3999.Dq set bandwidth 4000command (described below) to make 4001.Dq set autoload 4002work correctly. 4003.It set bandwidth Ar value 4004This command sets the connection bandwidth in bits per second. 4005.Ar value 4006must be greater than zero. 4007It is currently only used by the 4008.Dq set autoload 4009command above. 4010.It set callback Ar option Ns No ... 4011If no arguments are given, callback is disabled, otherwise, 4012.Nm 4013will request (or in 4014.Fl direct 4015mode, will accept) one of the given 4016.Ar option Ns No s . 4017In client mode, if an 4018.Ar option 4019is NAK'd 4020.Nm 4021will request a different 4022.Ar option , 4023until no options remain at which point 4024.Nm 4025will terminate negotiations (unless 4026.Dq none 4027is one of the specified 4028.Ar option Ns No ). 4029In server mode, 4030.Nm 4031will accept any of the given protocols - but the client 4032.Em must 4033request one of them. 4034If you wish callback to be optional, you must include 4035.Ar none 4036as an option. 4037.Pp 4038The 4039.Ar option Ns No s 4040are as follows (in this order of preference): 4041.Pp 4042.Bl -tag -width Ds 4043.It auth 4044The callee is expected to decide the callback number based on 4045authentication. 4046If 4047.Nm 4048is the callee, the number should be specified as the fifth field of 4049the peers entry in 4050.Pa /etc/ppp/ppp.secret . 4051.It cbcp 4052Microsoft's callback control protocol is used. 4053See 4054.Dq set cbcp 4055below. 4056.Pp 4057If you wish to negotiate 4058.Ar cbcp 4059in client mode but also wish to allow the server to request no callback at 4060CBCP negotiation time, you must specify both 4061.Ar cbcp 4062and 4063.Ar none 4064as callback options. 4065.It E.164 *| Ns Xo 4066.Ar number Ns Op , Ns Ar number Ns 4067.No ... 4068.Xc 4069The caller specifies the 4070.Ar number . 4071If 4072.Nm 4073is the callee, 4074.Ar number 4075should be either a comma separated list of allowable numbers or a 4076.Dq \&* , 4077meaning any number is permitted. 4078If 4079.Nm 4080is the caller, only a single number should be specified. 4081.Pp 4082Note, this option is very unsafe when used with a 4083.Dq \&* 4084as a malicious caller can tell 4085.Nm 4086to call any (possibly international) number without first authenticating 4087themselves. 4088.It none 4089If the peer does not wish to do callback at all, 4090.Nm 4091will accept the fact and continue without callback rather than terminating 4092the connection. 4093This is required (in addition to one or more other callback 4094options) if you wish callback to be optional. 4095.El 4096.Pp 4097.It set cbcp Oo Xo 4098.No *| Ns Ar number Ns No 4099.Oo 4100.No , Ns Ar number Ns 4101.Oc 4102.No ... 4103.Op Ar delay Op Ar retry 4104.Oc 4105.Xc 4106If no arguments are given, CBCP (Microsoft's CallBack Control Protocol) 4107is disabled - ie, configuring CBCP in the 4108.Dq set callback 4109command will result in 4110.Nm 4111requesting no callback in the CBCP phase. 4112Otherwise, 4113.Nm 4114attempts to use the given phone 4115.Ar number Ns No (s). 4116.Pp 4117In server mode 4118.Pq Fl direct , 4119.Nm 4120will insist that the client uses one of these numbers, unless 4121.Dq \&* 4122is used in which case the client is expected to specify the number. 4123.Pp 4124In client mode, 4125.Nm 4126will attempt to use one of the given numbers (whichever it finds to 4127be agreeable with the peer), or if 4128.Dq \&* 4129is specified, 4130.Nm 4131will expect the peer to specify the number. 4132.It set cd Oo 4133.No off| Ns Ar seconds Ns Op !\& 4134.Oc 4135Normally, 4136.Nm 4137checks for the existence of carrier depending on the type of device 4138that has been opened: 4139.Bl -tag -width XXX -offset XXX 4140.It Terminal Devices 4141Carrier is checked one second after the login script is complete. 4142If it's not set, 4143.Nm 4144assumes that this is because the device doesn't support carrier (which 4145is true for most 4146.Dq laplink 4147NULL-modem cables), logs the fact and stops checking 4148for carrier. 4149.Pp 4150As ptys don't support the TIOCMGET ioctl, the tty device will switch all 4151carrier detection off when it detects that the device is a pty. 4152.It ISDN (i4b) Devices 4153Carrier is checked once per second for 6 seconds. 4154If it's not set after 4155the sixth second, the connection attempt is considered to have failed and 4156the device is closed. 4157Carrier is always required for i4b devices. 4158.It PPPoE (netgraph) Devices 4159Carrier is checked once per second for 5 seconds. 4160If it's not set after 4161the fifth second, the connection attempt is considered to have failed and 4162the device is closed. 4163Carrier is always required for PPPoE devices. 4164.El 4165.Pp 4166All other device types don't support carrier. 4167Setting a carrier value will 4168result in a warning when the device is opened. 4169.Pp 4170Some modems take more than one second after connecting to assert the carrier 4171signal. 4172If this delay isn't increased, this will result in 4173.Nm Ns No 's 4174inability to detect when the link is dropped, as 4175.Nm 4176assumes that the device isn't asserting carrier. 4177.Pp 4178The 4179.Dq set cd 4180command overrides the default carrier behaviour. 4181.Ar seconds 4182specifies the maximum number of seconds that 4183.Nm 4184should wait after the dial script has finished before deciding if 4185carrier is available or not. 4186.Pp 4187If 4188.Dq off 4189is specified, 4190.Nm 4191will not check for carrier on the device, otherwise 4192.Nm 4193will not proceed to the login script until either carrier is detected 4194or until 4195.Ar seconds 4196has elapsed, at which point 4197.Nm 4198assumes that the device will not set carrier. 4199.Pp 4200If no arguments are given, carrier settings will go back to their default 4201values. 4202.Pp 4203If 4204.Ar seconds 4205is followed immediately by an exclamation mark 4206.Pq Dq \&! , 4207.Nm 4208will 4209.Em require 4210carrier. 4211If carrier is not detected after 4212.Ar seconds 4213seconds, the link will be disconnected. 4214.It set choked Op Ar timeout 4215This sets the number of seconds that 4216.Nm 4217will keep a choked output queue before dropping all pending output packets. 4218If 4219.Ar timeout 4220is less than or equal to zero or if 4221.Ar timeout 4222isn't specified, it is set to the default value of 4223.Em 120 seconds . 4224.Pp 4225A choked output queue occurs when 4226.Nm 4227has read a certain number of packets from the local network for transmission, 4228but cannot send the data due to link failure (the peer is busy etc.). 4229.Nm 4230will not read packets indefinitely. 4231Instead, it reads up to 4232.Em 30 4233packets (or 4234.Em 30 No + 4235.Em nlinks No * 4236.Em 2 4237packets in multi-link mode), then stops reading the network interface 4238until either 4239.Ar timeout 4240seconds have passed or at least one packet has been sent. 4241.Pp 4242If 4243.Ar timeout 4244seconds pass, all pending output packets are dropped. 4245.It set ctsrts|crtscts on|off 4246This sets hardware flow control. 4247Hardware flow control is 4248.Ar on 4249by default. 4250.It set deflate Ar out-winsize Op Ar in-winsize 4251This sets the DEFLATE algorithms default outgoing and incoming window 4252sizes. 4253Both 4254.Ar out-winsize 4255and 4256.Ar in-winsize 4257must be values between 4258.Em 8 4259and 4260.Em 15 . 4261If 4262.Ar in-winsize 4263is specified, 4264.Nm 4265will insist that this window size is used and will not accept any other 4266values from the peer. 4267.It set dns Op Ar primary Op Ar secondary 4268This command specifies DNS overrides for the 4269.Dq accept dns 4270command. 4271Refer to the 4272.Dq accept 4273command description above for details. 4274This command does not affect the IP numbers requested using 4275.Dq enable dns . 4276.It set device|line Xo 4277.Ar value Ns No ... 4278.Xc 4279This sets the device(s) to which 4280.Nm 4281will talk to the given 4282.Dq value . 4283.Pp 4284All ISDN and serial device names are expected to begin with 4285.Pa /dev/ . 4286ISDN devices are usually called 4287.Pa i4brbchX 4288and serial devices are usually called 4289.Pa cuaXX . 4290.Pp 4291If 4292.Dq value 4293does not begin with 4294.Pa /dev/ , 4295it must either begin with an exclamation mark 4296.Pq Dq \&! , 4297be of the format 4298.No PPPoE: Ns Ar iface Ns Xo 4299.Op \&: Ns Ar provider Ns 4300.Xc 4301or be of the format 4302.Sm off 4303.Ar host : port Op /tcp|udp . 4304.Sm on 4305.Pp 4306If it begins with an exclamation mark, the rest of the device name is 4307treated as a program name, and that program is executed when the device 4308is opened. 4309Standard input, output and error are fed back to 4310.Nm 4311and are read and written as if they were a regular device. 4312.Pp 4313If a 4314.No PPPoE: Ns Ar iface Ns Xo 4315.Op \&: Ns Ar provider Ns 4316.Xc 4317specification is given, 4318.Nm 4319will attempt to create a 4320.Em PPP 4321over Ethernet connection using the given 4322.Ar iface 4323interface by using 4324.Xr netgraph 4 . 4325If 4326.Xr netgraph 4 4327is not available, 4328.Nm 4329will attempt to loaded it using 4330.Xr kldload 2 . 4331If this fails, an external program must be used such as the 4332.Xr pppoe 8 4333program available under OpenBSD. 4334The given 4335.Ar provider 4336is passed as the service name in the PPPoE Discovery Initiation (PADI) 4337packet. 4338If no provider is given, an empty value will be used. 4339Refer to 4340.Xr netgraph 4 4341and 4342.Xr ng_pppoe 8 4343for further details. 4344.Pp 4345If a 4346.Ar host Ns No : Ns Ar port Ns Oo 4347.No /tcp|udp 4348.Oc 4349specification is given, 4350.Nm 4351will attempt to connect to the given 4352.Ar host 4353on the given 4354.Ar port . 4355If a 4356.Dq /tcp 4357or 4358.Dq /udp 4359suffix is not provided, the default is 4360.Dq /tcp . 4361Refer to the section on 4362.Em PPP OVER TCP and UDP 4363above for further details. 4364.Pp 4365If multiple 4366.Dq values 4367are specified, 4368.Nm 4369will attempt to open each one in turn until it succeeds or runs out of 4370devices. 4371.It set dial Ar chat-script 4372This specifies the chat script that will be used to dial the other 4373side. 4374See also the 4375.Dq set login 4376command below. 4377Refer to 4378.Xr chat 8 4379and to the example configuration files for details of the chat script 4380format. 4381It is possible to specify some special 4382.Sq values 4383in your chat script as follows: 4384.Bd -unfilled -offset indent 4385.It Li \ec 4386When used as the last character in a 4387.Sq send 4388string, this indicates that a newline should not be appended. 4389.It Li \ed 4390When the chat script encounters this sequence, it delays two seconds. 4391.It Li \ep 4392When the chat script encounters this sequence, it delays for one quarter of 4393a second. 4394.It Li \en 4395This is replaced with a newline character. 4396.It Li \er 4397This is replaced with a carriage return character. 4398.It Li \es 4399This is replaced with a space character. 4400.It Li \et 4401This is replaced with a tab character. 4402.It Li \eT 4403This is replaced by the current phone number (see 4404.Dq set phone 4405below). 4406.It Li \eP 4407This is replaced by the current 4408.Ar authkey 4409value (see 4410.Dq set authkey 4411above). 4412.It Li \eU 4413This is replaced by the current 4414.Ar authname 4415value (see 4416.Dq set authname 4417above). 4418.Ed 4419.Pp 4420Note that two parsers will examine these escape sequences, so in order to 4421have the 4422.Sq chat parser 4423see the escape character, it is necessary to escape it from the 4424.Sq command parser . 4425This means that in practice you should use two escapes, for example: 4426.Bd -literal -offset indent 4427set dial "... ATDT\\\\T CONNECT" 4428.Ed 4429.Pp 4430It is also possible to execute external commands from the chat script. 4431To do this, the first character of the expect or send string is an 4432exclamation mark 4433.Pq Dq \&! . 4434If a literal exclamation mark is required, double it up to 4435.Dq !!\& 4436and it will be treated as a single literal 4437.Dq \&! . 4438When the command is executed, standard input and standard output are 4439directed to the open device (see the 4440.Dq set device 4441command), and standard error is read by 4442.Nm 4443and substituted as the expect or send string. 4444If 4445.Nm 4446is running in interactive mode, file descriptor 3 is attached to 4447.Pa /dev/tty . 4448.Pp 4449For example (wrapped for readability): 4450.Bd -literal -offset indent 4451set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e 4452word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e 4453\\"!/bin/echo in\\" HELLO" 4454.Ed 4455.Pp 4456would result in the following chat sequence (output using the 4457.Sq set log local chat 4458command before dialing): 4459.Bd -literal -offset indent 4460Dial attempt 1 of 1 4461dial OK! 4462Chat: Expecting: 4463Chat: Sending: 4464Chat: Expecting: login:--login: 4465Chat: Wait for (5): login: 4466Chat: Sending: ppp 4467Chat: Expecting: word: 4468Chat: Wait for (5): word: 4469Chat: Sending: ppp 4470Chat: Expecting: !sh \\-c "echo \\-n label: >&2" 4471Chat: Exec: sh -c "echo -n label: >&2" 4472Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label: 4473Chat: Exec: /bin/echo in 4474Chat: Sending: 4475Chat: Expecting: HELLO 4476Chat: Wait for (5): HELLO 4477login OK! 4478.Ed 4479.Pp 4480Note (again) the use of the escape character, allowing many levels of 4481nesting. 4482Here, there are four parsers at work. 4483The first parses the original line, reading it as three arguments. 4484The second parses the third argument, reading it as 11 arguments. 4485At this point, it is 4486important that the 4487.Dq \&- 4488signs are escaped, otherwise this parser will see them as constituting 4489an expect-send-expect sequence. 4490When the 4491.Dq !\& 4492character is seen, the execution parser reads the first command as three 4493arguments, and then 4494.Xr sh 1 4495itself expands the argument after the 4496.Fl c . 4497As we wish to send the output back to the modem, in the first example 4498we redirect our output to file descriptor 2 (stderr) so that 4499.Nm 4500itself sends and logs it, and in the second example, we just output to stdout, 4501which is attached directly to the modem. 4502.Pp 4503This, of course means that it is possible to execute an entirely external 4504.Dq chat 4505command rather than using the internal one. 4506See 4507.Xr chat 8 4508for a good alternative. 4509.Pp 4510The external command that is executed is subjected to the same special 4511word expansions as the 4512.Dq !bg 4513command. 4514.It set enddisc Op label|IP|MAC|magic|psn value 4515This command sets our local endpoint discriminator. 4516If set prior to LCP negotiation, and if no 4517.Dq disable enddisc 4518command has been used, 4519.Nm 4520will send the information to the peer using the LCP endpoint discriminator 4521option. 4522The following discriminators may be set: 4523.Bd -unfilled -offset indent 4524.It Li label 4525The current label is used. 4526.It Li IP 4527Our local IP number is used. 4528As LCP is negotiated prior to IPCP, it is 4529possible that the IPCP layer will subsequently change this value. 4530If 4531it does, the endpoint discriminator stays at the old value unless manually 4532reset. 4533.It Li MAC 4534This is similar to the 4535.Ar IP 4536option above, except that the MAC address associated with the local IP 4537number is used. 4538If the local IP number is not resident on any Ethernet 4539interface, the command will fail. 4540.Pp 4541As the local IP number defaults to whatever the machine host name is, 4542.Dq set enddisc mac 4543is usually done prior to any 4544.Dq set ifaddr 4545commands. 4546.It Li magic 4547A 20 digit random number is used. 4548Care should be taken when using magic numbers as restarting 4549.Nm 4550or creating a link using a different 4551.Nm 4552invocation will also use a different magic number and will therefore not 4553be recognised by the peer as belonging to the same bundle. 4554This makes it unsuitable for 4555.Fl direct 4556connections. 4557.It Li psn Ar value 4558The given 4559.Ar value 4560is used. 4561.Ar Value 4562should be set to an absolute public switched network number with the 4563country code first. 4564.Ed 4565.Pp 4566If no arguments are given, the endpoint discriminator is reset. 4567.It set escape Ar value... 4568This option is similar to the 4569.Dq set accmap 4570option above. 4571It allows the user to specify a set of characters that will be 4572.Sq escaped 4573as they travel across the link. 4574.It set filter dial|alive|in|out Ar rule-no Xo 4575.No permit|deny|clear| Ns Ar rule-no 4576.Op !\& 4577.Oo Op host 4578.Ar src_addr Ns Op / Ns Ar width 4579.Op Ar dst_addr Ns Op / Ns Ar width 4580.Oc Oo tcp|udp|ospf|igmp|icmp Op src lt|eq|gt Ar port 4581.Op dst lt|eq|gt Ar port 4582.Op estab 4583.Op syn 4584.Op finrst 4585.Op timeout Ar secs 4586.Oc 4587.Xc 4588.Nm 4589supports four filter sets. 4590The 4591.Em alive 4592filter specifies packets that keep the connection alive - resetting the 4593idle timer. 4594The 4595.Em dial 4596filter specifies packets that cause 4597.Nm 4598to dial when in 4599.Fl auto 4600mode. 4601The 4602.Em in 4603filter specifies packets that are allowed to travel 4604into the machine and the 4605.Em out 4606filter specifies packets that are allowed out of the machine. 4607.Pp 4608Filtering is done prior to any IP alterations that might be done by the 4609NAT engine on outgoing packets and after any IP alterations that might 4610be done by the NAT engine on incoming packets. 4611By default all empty filter sets allow all packets to pass. 4612Rules are processed in order according to 4613.Ar rule-no 4614(unless skipped by specifying a rule number as the 4615.Ar action ) . 4616Up to 40 rules may be given for each set. 4617If a packet doesn't match 4618any of the rules in a given set, it is discarded. 4619In the case of 4620.Em in 4621and 4622.Em out 4623filters, this means that the packet is dropped. 4624In the case of 4625.Em alive 4626filters it means that the packet will not reset the idle timer (even if 4627the 4628.Ar in Ns No / Ns Ar out 4629filter has a 4630.Dq timeout 4631value) and in the case of 4632.Em dial 4633filters it means that the packet will not trigger a dial. 4634A packet failing to trigger a dial will be dropped rather than queued. 4635Refer to the 4636section on 4637.Sx PACKET FILTERING 4638above for further details. 4639.It set hangup Ar chat-script 4640This specifies the chat script that will be used to reset the device 4641before it is closed. 4642It should not normally be necessary, but can 4643be used for devices that fail to reset themselves properly on close. 4644.It set help|? Op Ar command 4645This command gives a summary of available set commands, or if 4646.Ar command 4647is specified, the command usage is shown. 4648.It set ifaddr Oo Ar myaddr Ns 4649.Op / Ns Ar \&nn 4650.Oo Ar hisaddr Ns Op / Ns Ar \&nn 4651.Oo Ar netmask 4652.Op Ar triggeraddr 4653.Oc Oc 4654.Oc 4655This command specifies the IP addresses that will be used during 4656IPCP negotiation. 4657Addresses are specified using the format 4658.Pp 4659.Dl a.b.c.d/nn 4660.Pp 4661Where 4662.Dq a.b.c.d 4663is the preferred IP, but 4664.Ar nn 4665specifies how many bits of the address we will insist on. 4666If 4667.No / Ns Ar nn 4668is omitted, it defaults to 4669.Dq /32 4670unless the IP address is 0.0.0.0 in which case it defaults to 4671.Dq /0 . 4672.Pp 4673If you wish to assign a dynamic IP number to the peer, 4674.Ar hisaddr 4675may also be specified as a range of IP numbers in the format 4676.Bd -literal -offset indent 4677.Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Xo 4678.Oc Oo , Ns Ar \&IP Ns 4679.Op \&- Ns Ar \&IP Ns 4680.Oc No ... 4681.Xc 4682.Ed 4683.Pp 4684for example: 4685.Pp 4686.Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20 4687.Pp 4688will only negotiate 4689.Dq 10.0.0.1 4690as the local IP number, but may assign any of the given 10 IP 4691numbers to the peer. 4692If the peer requests one of these numbers, 4693and that number is not already in use, 4694.Nm 4695will grant the peers request. 4696This is useful if the peer wants 4697to re-establish a link using the same IP number as was previously 4698allocated (thus maintaining any existing tcp or udp connections). 4699.Pp 4700If the peer requests an IP number that's either outside 4701of this range or is already in use, 4702.Nm 4703will suggest a random unused IP number from the range. 4704.Pp 4705If 4706.Ar triggeraddr 4707is specified, it is used in place of 4708.Ar myaddr 4709in the initial IPCP negotiation. 4710However, only an address in the 4711.Ar myaddr 4712range will be accepted. 4713This is useful when negotiating with some 4714.Dv PPP 4715implementations that will not assign an IP number unless their peer 4716requests 4717.Dq 0.0.0.0 . 4718.Pp 4719It should be noted that in 4720.Fl auto 4721mode, 4722.Nm 4723will configure the interface immediately upon reading the 4724.Dq set ifaddr 4725line in the config file. 4726In any other mode, these values are just 4727used for IPCP negotiations, and the interface isn't configured 4728until the IPCP layer is up. 4729.Pp 4730Note that the 4731.Ar HISADDR 4732argument may be overridden by the third field in the 4733.Pa ppp.secret 4734file once the client has authenticated itself 4735.Pq if PAP or CHAP are Dq enabled . 4736Refer to the 4737.Sx AUTHENTICATING INCOMING CONNECTIONS 4738section for details. 4739.Pp 4740In all cases, if the interface is already configured, 4741.Nm 4742will try to maintain the interface IP numbers so that any existing 4743bound sockets will remain valid. 4744.It set ifqueue Ar packets 4745Set the maximum number of packets that 4746.Nm 4747will read from the tunnel interface while data cannot be sent to any of 4748the available links. 4749This queue limit is necessary to flow control outgoing data as the tunnel 4750interface is likely to be far faster than the combined links available to 4751.Nm . 4752.Pp 4753If 4754.Ar packets 4755is set to a value less than the number of links, 4756.Nm 4757will read up to that value regardless. 4758This prevents any possible latency problems. 4759.Pp 4760The default value for 4761.Ar packets 4762is 4763.Dq 30 . 4764.It set ccpretry|ccpretries Oo Ar timeout 4765.Op Ar reqtries Op Ar trmtries 4766.Oc 4767.It set chapretry|chapretries Oo Ar timeout 4768.Op Ar reqtries 4769.Oc 4770.It set ipcpretry|ipcpretries Oo Ar timeout 4771.Op Ar reqtries Op Ar trmtries 4772.Oc 4773.It set lcpretry|lcpretries Oo Ar timeout 4774.Op Ar reqtries Op Ar trmtries 4775.Oc 4776.It set papretry|papretries Oo Ar timeout 4777.Op Ar reqtries 4778.Oc 4779These commands set the number of seconds that 4780.Nm 4781will wait before resending Finite State Machine (FSM) Request packets. 4782The default 4783.Ar timeout 4784for all FSMs is 3 seconds (which should suffice in most cases). 4785.Pp 4786If 4787.Ar reqtries 4788is specified, it tells 4789.Nm 4790how many configuration request attempts it should make while receiving 4791no reply from the peer before giving up. 4792The default is 5 attempts for 4793CCP, LCP and IPCP and 3 attempts for PAP and CHAP. 4794.Pp 4795If 4796.Ar trmtries 4797is specified, it tells 4798.Nm 4799how many terminate requests should be sent before giving up waiting for the 4800peers response. 4801The default is 3 attempts. 4802Authentication protocols are 4803not terminated and it is therefore invalid to specify 4804.Ar trmtries 4805for PAP or CHAP. 4806.Pp 4807In order to avoid negotiations with the peer that will never converge, 4808.Nm 4809will only send at most 3 times the configured number of 4810.Ar reqtries 4811in any given negotiation session before giving up and closing that layer. 4812.It set log Xo 4813.Op local 4814.Op +|- Ns 4815.Ar value Ns No ... 4816.Xc 4817This command allows the adjustment of the current log level. 4818Refer to the Logging Facility section for further details. 4819.It set login Ar chat-script 4820This 4821.Ar chat-script 4822compliments the dial-script. 4823If both are specified, the login 4824script will be executed after the dial script. 4825Escape sequences available in the dial script are also available here. 4826.It set logout Ar chat-script 4827This specifies the chat script that will be used to logout 4828before the hangup script is called. 4829It should not normally be necessary. 4830.It set lqrperiod Ar frequency 4831This command sets the 4832.Ar frequency 4833in seconds at which 4834.Em LQR 4835or 4836.Em ECHO LQR 4837packets are sent. 4838The default is 30 seconds. 4839You must also use the 4840.Dq enable lqr 4841command if you wish to send LQR requests to the peer. 4842.It set mode Ar interactive|auto|ddial|background 4843This command allows you to change the 4844.Sq mode 4845of the specified link. 4846This is normally only useful in multi-link mode, 4847but may also be used in uni-link mode. 4848.Pp 4849It is not possible to change a link that is 4850.Sq direct 4851or 4852.Sq dedicated . 4853.Pp 4854Note: If you issue the command 4855.Dq set mode auto , 4856and have network address translation enabled, it may be useful to 4857.Dq enable iface-alias 4858afterwards. 4859This will allow 4860.Nm 4861to do the necessary address translations to enable the process that 4862triggers the connection to connect once the link is up despite the 4863peer assigning us a new (dynamic) IP address. 4864.It set mppe {40|56|128} 4865This option selects particular key length. Default is 128. 4866.It set mrru Op Ar value 4867Setting this option enables Multi-link PPP negotiations, also known as 4868Multi-link Protocol or MP. 4869There is no default MRRU (Maximum Reconstructed Receive Unit) value. 4870If no argument is given, multi-link mode is disabled. 4871.It set mru Op Ar value 4872The default MRU (Maximum Receive Unit) is 1500. 4873If it is increased, the other side *may* increase its MTU. 4874There is no point in decreasing the MRU to below the default as the 4875.Em PPP 4876protocol *must* be able to accept packets of at least 1500 octets. 4877If no argument is given, 1500 is assumed. 4878.It set mtu Op Ar value 4879The default MTU is 1500. 4880At negotiation time, 4881.Nm 4882will accept whatever MRU or MRRU that the peer wants (assuming it's 4883not less than 296 bytes). 4884If the MTU is set, 4885.Nm 4886will not accept MRU/MRRU values less than 4887.Ar value . 4888When negotiations are complete, the MTU is assigned to the interface, even 4889if the peer requested a higher value MRU/MRRU. 4890This can be useful for 4891limiting your packet size (giving better bandwidth sharing at the expense 4892of more header data). 4893.Pp 4894If no 4895.Ar value 4896is given, 1500, or whatever the peer asks for is used. 4897.It set nbns Op Ar x.x.x.x Op Ar y.y.y.y 4898This option allows the setting of the Microsoft NetBIOS name server 4899values to be returned at the peers request. 4900If no values are given, 4901.Nm 4902will reject any such requests. 4903.It set openmode active|passive Op Ar delay 4904By default, 4905.Ar openmode 4906is always 4907.Ar active 4908with a one second 4909.Ar delay . 4910That is, 4911.Nm 4912will always initiate LCP/IPCP/CCP negotiation one second after the line 4913comes up. 4914If you want to wait for the peer to initiate negotiations, you 4915can use the value 4916.Ar passive . 4917If you want to initiate negotiations immediately or after more than one 4918second, the appropriate 4919.Ar delay 4920may be specified here in seconds. 4921.It set parity odd|even|none|mark 4922This allows the line parity to be set. 4923The default value is 4924.Ar none . 4925.It set phone Ar telno Ns Xo 4926.Oo \&| Ns Ar backupnumber 4927.Oc Ns ... Ns Oo : Ns Ar nextnumber 4928.Oc Ns ... 4929.Xc 4930This allows the specification of the phone number to be used in 4931place of the \\\\T string in the dial and login chat scripts. 4932Multiple phone numbers may be given separated either by a pipe 4933.Pq Dq \&| 4934or a colon 4935.Pq Dq \&: . 4936.Pp 4937Numbers after the pipe are only dialed if the dial or login 4938script for the previous number failed. 4939.Pp 4940Numbers after the colon are tried sequentially, irrespective of 4941the reason the line was dropped. 4942.Pp 4943If multiple numbers are given, 4944.Nm 4945will dial them according to these rules until a connection is made, retrying 4946the maximum number of times specified by 4947.Dq set redial 4948below. 4949In 4950.Fl background 4951mode, each number is attempted at most once. 4952.It set Op proc Ns Xo 4953.No title Op Ar value 4954.Xc 4955The current process title as displayed by 4956.Xr ps 1 4957is changed according to 4958.Ar value . 4959If 4960.Ar value 4961is not specified, the original process title is restored. 4962All the 4963word replacements done by the shell commands (see the 4964.Dq bg 4965command above) are done here too. 4966.Pp 4967Note, if USER is required in the process title, the 4968.Dq set proctitle 4969command must appear in 4970.Pa ppp.linkup , 4971as it is not known when the commands in 4972.Pa ppp.conf 4973are executed. 4974.It set radius Op Ar config-file 4975This command enables RADIUS support (if it's compiled in). 4976.Ar config-file 4977refers to the radius client configuration file as described in 4978.Xr radius.conf 5 . 4979If PAP or CHAP are 4980.Dq enable Ns No d , 4981.Nm 4982behaves as a 4983.Em \&N Ns No etwork 4984.Em \&A Ns No ccess 4985.Em \&S Ns No erver 4986and uses the configured RADIUS server to authenticate rather than 4987authenticating from the 4988.Pa ppp.secret 4989file or from the passwd database. 4990.Pp 4991If neither PAP or CHAP are enabled, 4992.Dq set radius 4993will do nothing. 4994.Pp 4995.Nm 4996uses the following attributes from the RADIUS reply: 4997.Bl -tag -width XXX -offset XXX 4998.It RAD_FRAMED_IP_ADDRESS 4999The peer IP address is set to the given value. 5000.It RAD_FRAMED_IP_NETMASK 5001The tun interface netmask is set to the given value. 5002.It RAD_FRAMED_MTU 5003If the given MTU is less than the peers MRU as agreed during LCP 5004negotiation, *and* it is less that any configured MTU (see the 5005.Dq set mru 5006command), the tun interface MTU is set to the given value. 5007.It RAD_FRAMED_COMPRESSION 5008If the received compression type is 5009.Dq 1 , 5010.Nm 5011will request VJ compression during IPCP negotiations despite any 5012.Dq disable vj 5013configuration command. 5014.It RAD_FRAMED_ROUTE 5015The received string is expected to be in the format 5016.Ar dest Ns Op / Ns Ar bits 5017.Ar gw 5018.Op Ar metrics . 5019Any specified metrics are ignored. 5020.Dv MYADDR 5021and 5022.Dv HISADDR 5023are understood as valid values for 5024.Ar dest 5025and 5026.Ar gw , 5027.Dq default 5028can be used for 5029.Ar dest 5030to sepcify the default route, and 5031.Dq 0.0.0.0 5032is understood to be the same as 5033.Dq default 5034for 5035.Ar dest 5036and 5037.Dv HISADDR 5038for 5039.Ar gw . 5040.Pp 5041For example, a returned value of 5042.Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400 5043would result in a routing table entry to the 1.2.3.0/24 network via 5044.Dv HISADDR 5045and a returned value of 5046.Dq 0.0.0.0 0.0.0.0 5047or 5048.Dq default HISADDR 5049would result in a default route to 5050.Dv HISADDR . 5051.Pp 5052All RADIUS routes are applied after any sticky routes are applied, making 5053RADIUS routes override configured routes. 5054This also applies for RADIUS routes that don't include the 5055.Dv MYADDR 5056or 5057.Dv HISADDR 5058keywords. 5059.Pp 5060.El 5061Values received from the RADIUS server may be viewed using 5062.Dq show bundle . 5063.It set reconnect Ar timeout ntries 5064Should the line drop unexpectedly (due to loss of CD or LQR 5065failure), a connection will be re-established after the given 5066.Ar timeout . 5067The line will be re-connected at most 5068.Ar ntries 5069times. 5070.Ar Ntries 5071defaults to zero. 5072A value of 5073.Ar random 5074for 5075.Ar timeout 5076will result in a variable pause, somewhere between 1 and 30 seconds. 5077.It set recvpipe Op Ar value 5078This sets the routing table RECVPIPE value. 5079The optimum value is just over twice the MTU value. 5080If 5081.Ar value 5082is unspecified or zero, the default kernel controlled value is used. 5083.It set redial Ar secs Ns Xo 5084.Oo + Ns Ar inc Ns 5085.Op - Ns Ar max Ns 5086.Oc Op . Ns Ar next 5087.Op Ar attempts 5088.Xc 5089.Nm 5090can be instructed to attempt to redial 5091.Ar attempts 5092times. 5093If more than one phone number is specified (see 5094.Dq set phone 5095above), a pause of 5096.Ar next 5097is taken before dialing each number. 5098A pause of 5099.Ar secs 5100is taken before starting at the first number again. 5101A literal value of 5102.Dq Li random 5103may be used here in place of 5104.Ar secs 5105and 5106.Ar next , 5107causing a random delay of between 1 and 30 seconds. 5108.Pp 5109If 5110.Ar inc 5111is specified, its value is added onto 5112.Ar secs 5113each time 5114.Nm 5115tries a new number. 5116.Ar secs 5117will only be incremented at most 5118.Ar max 5119times. 5120.Ar max 5121defaults to 10. 5122.Pp 5123Note, the 5124.Ar secs 5125delay will be effective, even after 5126.Ar attempts 5127has been exceeded, so an immediate manual dial may appear to have 5128done nothing. 5129If an immediate dial is required, a 5130.Dq !\& 5131should immediately follow the 5132.Dq open 5133keyword. 5134See the 5135.Dq open 5136description above for further details. 5137.It set sendpipe Op Ar value 5138This sets the routing table SENDPIPE value. 5139The optimum value is just over twice the MTU value. 5140If 5141.Ar value 5142is unspecified or zero, the default kernel controlled value is used. 5143.It set server|socket Ar TcpPort|LocalName|none password Op Ar mask 5144This command tells 5145.Nm 5146to listen on the given socket or 5147.Sq diagnostic port 5148for incoming command connections. 5149.Pp 5150The word 5151.Ar none 5152instructs 5153.Nm 5154to close any existing socket. 5155.Pp 5156If you wish to specify a local domain socket, 5157.Ar LocalName 5158must be specified as an absolute file name, otherwise it is assumed 5159to be the name or number of a TCP port. 5160You must specify the octal umask to be used with a local domain socket. 5161Refer to 5162.Xr umask 2 5163for umask details. 5164Refer to 5165.Xr services 5 5166for details of how to translate TCP port names. 5167.Pp 5168You must also specify the password that must be entered by the client 5169(using the 5170.Dq passwd 5171command above) when connecting to this socket. 5172If the password is 5173specified as an empty string, no password is required for connecting clients. 5174.Pp 5175When specifying a local domain socket, the first 5176.Dq %d 5177sequence found in the socket name will be replaced with the current 5178interface unit number. 5179This is useful when you wish to use the same 5180profile for more than one connection. 5181.Pp 5182In a similar manner TCP sockets may be prefixed with the 5183.Dq + 5184character, in which case the current interface unit number is added to 5185the port number. 5186.Pp 5187When using 5188.Nm 5189with a server socket, the 5190.Xr pppctl 8 5191command is the preferred mechanism of communications. 5192Currently, 5193.Xr telnet 1 5194can also be used, but link encryption may be implemented in the future, so 5195.Xr telnet 1 5196should not be relied upon. 5197.It set speed Ar value 5198This sets the speed of the serial device. 5199If speed is specified as 5200.Dq sync , 5201.Nm 5202treats the device as a synchronous device. 5203.Pp 5204Certain device types will know whether they should be specified as 5205synchronous or asynchronous. 5206These devices will override incorrect 5207settings and log a warning to this effect. 5208.It set stopped Op Ar LCPseconds Op Ar CCPseconds 5209If this option is set, 5210.Nm 5211will time out after the given FSM (Finite State Machine) has been in 5212the stopped state for the given number of 5213.Dq seconds . 5214This option may be useful if the peer sends a terminate request, 5215but never actually closes the connection despite our sending a terminate 5216acknowledgement. 5217This is also useful if you wish to 5218.Dq set openmode passive 5219and time out if the peer doesn't send a Configure Request within the 5220given time. 5221Use 5222.Dq set log +lcp +ccp 5223to make 5224.Nm 5225log the appropriate state transitions. 5226.Pp 5227The default value is zero, where 5228.Nm 5229doesn't time out in the stopped state. 5230.Pp 5231This value should not be set to less than the openmode delay (see 5232.Dq set openmode 5233above). 5234.It set timeout Ar idleseconds Op Ar mintimeout 5235This command allows the setting of the idle timer. 5236Refer to the section titled 5237.Sx SETTING THE IDLE TIMER 5238for further details. 5239.Pp 5240If 5241.Ar mintimeout 5242is specified, 5243.Nm 5244will never idle out before the link has been up for at least that number 5245of seconds. 5246.It set urgent Xo 5247.Op tcp|udp|none 5248.Oo Op +|- Ns 5249.Ar port 5250.Oc No ... 5251.Xc 5252This command controls the ports that 5253.Nm 5254prioritizes when transmitting data. 5255The default priority TCP ports 5256are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell), 5257543 (klogin) and 544 (kshell). 5258There are no priority UDP ports by default. 5259See 5260.Xr services 5 5261for details. 5262.Pp 5263If neither 5264.Dq tcp 5265or 5266.Dq udp 5267are specified, 5268.Dq tcp 5269is assumed. 5270.Pp 5271If no 5272.Ar port Ns No s 5273are given, the priority port lists are cleared (although if 5274.Dq tcp 5275or 5276.Dq udp 5277is specified, only that list is cleared). 5278If the first 5279.Ar port 5280argument is prefixed with a plus 5281.Pq Dq \&+ 5282or a minus 5283.Pq Dq \&- , 5284the current list is adjusted, otherwise the list is reassigned. 5285.Ar port Ns No s 5286prefixed with a plus or not prefixed at all are added to the list and 5287.Ar port Ns No s 5288prefixed with a minus are removed from the list. 5289.Pp 5290If 5291.Dq none 5292is specified, all priority port lists are disabled and even 5293.Dv IPTOS_LOWDELAY 5294packets are not prioritised. 5295.It set vj slotcomp on|off 5296This command tells 5297.Nm 5298whether it should attempt to negotiate VJ slot compression. 5299By default, slot compression is turned 5300.Ar on . 5301.It set vj slots Ar nslots 5302This command sets the initial number of slots that 5303.Nm 5304will try to negotiate with the peer when VJ compression is enabled (see the 5305.Sq enable 5306command above). 5307It defaults to a value of 16. 5308.Ar Nslots 5309must be between 5310.Ar 4 5311and 5312.Ar 16 5313inclusive. 5314.El 5315.Pp 5316.It shell|! Op Ar command 5317If 5318.Ar command 5319is not specified a shell is invoked according to the 5320.Dv SHELL 5321environment variable. 5322Otherwise, the given 5323.Ar command 5324is executed. 5325Word replacement is done in the same way as for the 5326.Dq !bg 5327command as described above. 5328.Pp 5329Use of the ! character 5330requires a following space as with any of the other commands. 5331You should note that this command is executed in the foreground; 5332.Nm 5333will not continue running until this process has exited. 5334Use the 5335.Dv bg 5336command if you wish processing to happen in the background. 5337.It show Ar var 5338This command allows the user to examine the following: 5339.Bl -tag -width 2n 5340.It show bundle 5341Show the current bundle settings. 5342.It show ccp 5343Show the current CCP compression statistics. 5344.It show compress 5345Show the current VJ compression statistics. 5346.It show escape 5347Show the current escape characters. 5348.It show filter Op Ar name 5349List the current rules for the given filter. 5350If 5351.Ar name 5352is not specified, all filters are shown. 5353.It show hdlc 5354Show the current HDLC statistics. 5355.It show help|? 5356Give a summary of available show commands. 5357.It show iface 5358Show the current interface information 5359.Pq the same \&as Dq iface show . 5360.It show ipcp 5361Show the current IPCP statistics. 5362.It show layers 5363Show the protocol layers currently in use. 5364.It show lcp 5365Show the current LCP statistics. 5366.It show Op data Ns Xo 5367.No link 5368.Xc 5369Show high level link information. 5370.It show links 5371Show a list of available logical links. 5372.It show log 5373Show the current log values. 5374.It show mem 5375Show current memory statistics. 5376.It show physical 5377Show low level link information. 5378.It show mp 5379Show Multi-link information. 5380.It show proto 5381Show current protocol totals. 5382.It show route 5383Show the current routing tables. 5384.It show stopped 5385Show the current stopped timeouts. 5386.It show timer 5387Show the active alarm timers. 5388.It show version 5389Show the current version number of 5390.Nm . 5391.El 5392.Pp 5393.It term 5394Go into terminal mode. 5395Characters typed at the keyboard are sent to the device. 5396Characters read from the device are displayed on the screen. 5397When a remote 5398.Em PPP 5399peer is detected, 5400.Nm 5401automatically enables Packet Mode and goes back into command mode. 5402.El 5403.Pp 5404.Sh MORE DETAILS 5405.Bl -bullet 5406.It 5407Read the example configuration files. 5408They are a good source of information. 5409.It 5410Use 5411.Dq help , 5412.Dq nat \&? , 5413.Dq enable \&? , 5414.Dq set ?\& 5415and 5416.Dq show ?\& 5417to get online information about what's available. 5418.It 5419The following URLs contain useful information: 5420.Bl -bullet -compact 5421.It 5422http://www.FreeBSD.org/FAQ/userppp.html 5423.It 5424http://www.FreeBSD.org/handbook/userppp.html 5425.El 5426.Pp 5427.El 5428.Pp 5429.Sh FILES 5430.Nm 5431refers to four files: 5432.Pa ppp.conf , 5433.Pa ppp.linkup , 5434.Pa ppp.linkdown 5435and 5436.Pa ppp.secret . 5437These files are placed in the 5438.Pa /etc/ppp 5439directory. 5440.Bl -tag -width 2n 5441.It Pa /etc/ppp/ppp.conf 5442System default configuration file. 5443.It Pa /etc/ppp/ppp.secret 5444An authorisation file for each system. 5445.It Pa /etc/ppp/ppp.linkup 5446A file to check when 5447.Nm 5448establishes a network level connection. 5449.It Pa /etc/ppp/ppp.linkdown 5450A file to check when 5451.Nm 5452closes a network level connection. 5453.It Pa /var/log/ppp.log 5454Logging and debugging information file. 5455Note, this name is specified in 5456.Pa /etc/syslogd.conf . 5457See 5458.Xr syslog.conf 5 5459for further details. 5460.It Pa /var/spool/lock/LCK..* 5461tty port locking file. 5462Refer to 5463.Xr uucplock 3 5464for further details. 5465.It Pa /var/run/tunN.pid 5466The process id (pid) of the 5467.Nm 5468program connected to the tunN device, where 5469.Sq N 5470is the number of the device. 5471.It Pa /var/run/ttyXX.if 5472The tun interface used by this port. 5473Again, this file is only created in 5474.Fl background , 5475.Fl auto 5476and 5477.Fl ddial 5478modes. 5479.It Pa /etc/services 5480Get port number if port number is using service name. 5481.It Pa /var/run/ppp-authname-class-value 5482In multi-link mode, local domain sockets are created using the peer 5483authentication name 5484.Pq Sq authname , 5485the peer endpoint discriminator class 5486.Pq Sq class 5487and the peer endpoint discriminator value 5488.Pq Sq value . 5489As the endpoint discriminator value may be a binary value, it is turned 5490to HEX to determine the actual file name. 5491.Pp 5492This socket is used to pass links between different instances of 5493.Nm . 5494.El 5495.Pp 5496.Sh SEE ALSO 5497.Xr at 1 , 5498.Xr ftp 1 , 5499.Xr gzip 1 , 5500.Xr hostname 1 , 5501.Xr login 1 , 5502.Xr tcpdump 1 , 5503.Xr telnet 1 , 5504.Xr kldload 2 , 5505.Xr libalias 3 , 5506.Xr syslog 3 , 5507.Xr uucplock 3 , 5508.Xr netgraph 4 , 5509.Xr crontab 5 , 5510.Xr group 5 , 5511.Xr passwd 5 , 5512.Xr radius.conf 5 , 5513.Xr resolv.conf 5 , 5514.Xr syslog.conf 5 , 5515.Xr adduser 8 , 5516.Xr chat 8 , 5517.Xr getty 8 , 5518.Xr inetd 8 , 5519.Xr init 8 , 5520.Xr isdn 8 , 5521.Xr named 8 , 5522.Xr ng_pppoe 8 , 5523.Xr ping 8 , 5524.Xr pppctl 8 , 5525.Xr pppd 8 , 5526.Xr pppoe 8 , 5527.Xr route 8 , 5528.Xr sshd 8 , 5529.Xr syslogd 8 , 5530.Xr traceroute 8 , 5531.Xr vipw 8 5532.Sh HISTORY 5533This program was originally written by 5534.An Toshiharu OHNO Aq tony-o@iij.ad.jp , 5535and was submitted to 5536.Fx 2.0.5 5537by 5538.An Atsushi Murai Aq amurai@spec.co.jp . 5539.Pp 5540It was substantially modified during 1997 by 5541.An Brian Somers Aq brian@Awfulhak.org , 5542and was ported to 5543.Ox 5544in November that year 5545(just after the 2.2 release). 5546.Pp 5547Most of the code was rewritten by 5548.An Brian Somers 5549in early 1998 when multi-link ppp support was added. 5550