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