ppp.8 revision 86754
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 86754 2001-11-22 01:44:23Z 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.It Supports IPV6CP (rfc 2023). 400An IPv6 connection can be made in addition to or instead of the normal 401IPv4 connection. 402.El 403.Sh PERMISSIONS 404.Nm 405is installed as user 406.Dv root 407and group 408.Dv network , 409with permissions 410.Dv 04554 . 411By default, 412.Nm 413will not run if the invoking user id is not zero. 414This may be overridden by using the 415.Dq allow users 416command in 417.Pa /etc/ppp/ppp.conf . 418When running as a normal user, 419.Nm 420switches to user id 0 in order to alter the system routing table, set up 421system lock files and read the ppp configuration files. 422All external commands (executed via the "shell" or "!bg" commands) are executed 423as the user id that invoked 424.Nm . 425Refer to the 426.Sq ID0 427logging facility if you're interested in what exactly is done as user id 428zero. 429.Sh GETTING STARTED 430When you first run 431.Nm 432you may need to deal with some initial configuration details. 433.Bl -bullet 434.It 435Your kernel must {include} a tunnel device (the GENERIC kernel includes 436one by default). 437If it doesn't, or if you require more than one tun 438interface, you'll need to rebuild your kernel with the following line in 439your kernel configuration file: 440.Pp 441.Dl pseudo-device tun N 442.Pp 443where 444.Ar N 445is the maximum number of 446.Em PPP 447connections you wish to support. 448.It 449Check your 450.Pa /dev 451directory for the tunnel device entries 452.Pa /dev/tunN , 453where 454.Sq N 455represents the number of the tun device, starting at zero. 456If they don't exist, you can create them by running "sh ./MAKEDEV tunN". 457This will create tun devices 0 through 458.Ar N . 459.It 460Make sure that your system has a group named 461.Dq network 462in the 463.Pa /etc/group 464file and that the group contains the names of all users expected to use 465.Nm . 466Refer to the 467.Xr group 5 468manual page for details. 469Each of these users must also be given access using the 470.Dq allow users 471command in 472.Pa /etc/ppp/ppp.conf . 473.It 474Create a log file. 475.Nm 476uses 477.Xr syslog 3 478to log information. 479A common log file name is 480.Pa /var/log/ppp.log . 481To make output go to this file, put the following lines in the 482.Pa /etc/syslog.conf 483file: 484.Bd -literal -offset indent 485!ppp 486*.*<TAB>/var/log/ppp.log 487.Ed 488.Pp 489It is possible to have more than one 490.Em PPP 491log file by creating a link to the 492.Nm 493executable: 494.Pp 495.Dl # cd /usr/sbin 496.Dl # ln ppp ppp0 497.Pp 498and using 499.Bd -literal -offset indent 500!ppp0 501*.*<TAB>/var/log/ppp0.log 502.Ed 503.Pp 504in 505.Pa /etc/syslog.conf . 506Don't forget to send a 507.Dv HUP 508signal to 509.Xr syslogd 8 510after altering 511.Pa /etc/syslog.conf . 512.It 513Although not strictly relevant to 514.Nm Ns No 's 515operation, you should configure your resolver so that it works correctly. 516This can be done by configuring a local DNS 517(using 518.Xr named 8 ) 519or by adding the correct 520.Sq nameserver 521lines to the file 522.Pa /etc/resolv.conf . 523Refer to the 524.Xr resolv.conf 5 525manual page for details. 526.Pp 527Alternatively, if the peer supports it, 528.Nm 529can be configured to ask the peer for the nameserver address(es) and to 530update 531.Pa /etc/resolv.conf 532automatically. 533Refer to the 534.Dq enable dns 535and 536.Dq resolv 537commands below for details. 538.El 539.Sh MANUAL DIALING 540In the following examples, we assume that your machine name is 541.Dv awfulhak . 542when you invoke 543.Nm 544(see 545.Sx PERMISSIONS 546above) with no arguments, you are presented with a prompt: 547.Bd -literal -offset indent 548ppp ON awfulhak> 549.Ed 550.Pp 551The 552.Sq ON 553part of your prompt should always be in upper case. 554If it is in lower case, it means that you must supply a password using the 555.Dq passwd 556command. 557This only ever happens if you connect to a running version of 558.Nm 559and have not authenticated yourself using the correct password. 560.Pp 561You can start by specifying the device name and speed: 562.Bd -literal -offset indent 563ppp ON awfulhak> set device /dev/cuaa0 564ppp ON awfulhak> set speed 38400 565.Ed 566.Pp 567Normally, hardware flow control (CTS/RTS) is used. 568However, under 569certain circumstances (as may happen when you are connected directly 570to certain PPP-capable terminal servers), this may result in 571.Nm 572hanging as soon as it tries to write data to your communications link 573as it is waiting for the CTS (clear to send) signal - which will never 574come. 575Thus, if you have a direct line and can't seem to make a 576connection, try turning CTS/RTS off with 577.Dq set ctsrts off . 578If you need to do this, check the 579.Dq set accmap 580description below too - you'll probably need to 581.Dq set accmap 000a0000 . 582.Pp 583Usually, parity is set to 584.Dq none , 585and this is 586.Nm Ns No 's 587default. 588Parity is a rather archaic error checking mechanism that is no 589longer used because modern modems do their own error checking, and most 590link-layer protocols (that's what 591.Nm 592is) use much more reliable checking mechanisms. 593Parity has a relatively 594huge overhead (a 12.5% increase in traffic) and as a result, it is always 595disabled 596(set to 597.Dq none ) 598when 599.Dv PPP 600is opened. 601However, some ISPs (Internet Service Providers) may use 602specific parity settings at connection time (before 603.Dv PPP 604is opened). 605Notably, Compuserve insist on even parity when logging in: 606.Bd -literal -offset indent 607ppp ON awfulhak> set parity even 608.Ed 609.Pp 610You can now see what your current device settings look like: 611.Bd -literal -offset indent 612ppp ON awfulhak> show physical 613Name: deflink 614 State: closed 615 Device: N/A 616 Link Type: interactive 617 Connect Count: 0 618 Queued Packets: 0 619 Phone Number: N/A 620 621Defaults: 622 Device List: /dev/cuaa0 623 Characteristics: 38400bps, cs8, even parity, CTS/RTS on 624 625Connect time: 0 secs 6260 octets in, 0 octets out 627Overall 0 bytes/sec 628ppp ON awfulhak> 629.Ed 630.Pp 631The term command can now be used to talk directly to the device: 632.Bd -literal -offset indent 633ppp ON awfulhak> term 634at 635OK 636atdt123456 637CONNECT 638login: myispusername 639Password: myisppassword 640Protocol: ppp 641.Ed 642.Pp 643When the peer starts to talk in 644.Em PPP , 645.Nm 646detects this automatically and returns to command mode. 647.Bd -literal -offset indent 648ppp ON awfulhak> # No link has been established 649Ppp ON awfulhak> # We've connected & finished LCP 650PPp ON awfulhak> # We've authenticated 651PPP ON awfulhak> # We've agreed IP numbers 652.Ed 653.Pp 654If it does not, it's probable that the peer is waiting for your end to 655start negotiating. 656To force 657.Nm 658to start sending 659.Em PPP 660configuration packets to the peer, use the 661.Dq ~p 662command to drop out of terminal mode and enter packet mode. 663.Pp 664If you never even receive a login prompt, it is quite likely that the 665peer wants to use PAP or CHAP authentication instead of using Unix-style 666login/password authentication. 667To set things up properly, drop back to 668the prompt and set your authentication name and key, then reconnect: 669.Bd -literal -offset indent 670~. 671ppp ON awfulhak> set authname myispusername 672ppp ON awfulhak> set authkey myisppassword 673ppp ON awfulhak> term 674at 675OK 676atdt123456 677CONNECT 678.Ed 679.Pp 680You may need to tell ppp to initiate negotiations with the peer here too: 681.Bd -literal -offset indent 682~p 683ppp ON awfulhak> # No link has been established 684Ppp ON awfulhak> # We've connected & finished LCP 685PPp ON awfulhak> # We've authenticated 686PPP ON awfulhak> # We've agreed IP numbers 687.Ed 688.Pp 689You are now connected! 690Note that 691.Sq PPP 692in the prompt has changed to capital letters to indicate that you have 693a peer connection. 694If only some of the three Ps go uppercase, wait until 695either everything is uppercase or lowercase. 696If they revert to lowercase, it means that 697.Nm 698couldn't successfully negotiate with the peer. 699A good first step for troubleshooting at this point would be to 700.Bd -literal -offset indent 701ppp ON awfulhak> set log local phase lcp ipcp 702.Ed 703.Pp 704and try again. 705Refer to the 706.Dq set log 707command description below for further details. 708If things fail at this point, 709it is quite important that you turn logging on and try again. 710It is also 711important that you note any prompt changes and report them to anyone trying 712to help you. 713.Pp 714When the link is established, the show command can be used to see how 715things are going: 716.Bd -literal -offset indent 717PPP ON awfulhak> show physical 718* Modem related information is shown here * 719PPP ON awfulhak> show ccp 720* CCP (compression) related information is shown here * 721PPP ON awfulhak> show lcp 722* LCP (line control) related information is shown here * 723PPP ON awfulhak> show ipcp 724* IPCP (IP) related information is shown here * 725PPP ON awfulhak> show ipv6cp 726* IPV6CP (IPv6) related information is shown here * 727PPP ON awfulhak> show link 728* Link (high level) related information is shown here * 729PPP ON awfulhak> show bundle 730* Logical (high level) connection related information is shown here * 731.Ed 732.Pp 733At this point, your machine has a host route to the peer. 734This means 735that you can only make a connection with the host on the other side 736of the link. 737If you want to add a default route entry (telling your 738machine to send all packets without another routing entry to the other 739side of the 740.Em PPP 741link), enter the following command: 742.Bd -literal -offset indent 743PPP ON awfulhak> add default HISADDR 744.Ed 745.Pp 746The string 747.Sq HISADDR 748represents the IP address of the connected peer. 749If the 750.Dq add 751command fails due to an existing route, you can overwrite the existing 752route using 753.Bd -literal -offset indent 754PPP ON awfulhak> add! default HISADDR 755.Ed 756.Pp 757This command can also be executed before actually making the connection. 758If a new IP address is negotiated at connection time, 759.Nm 760will update your default route accordingly. 761.Pp 762You can now use your network applications (ping, telnet, ftp etc.) 763in other windows or terminals on your machine. 764If you wish to reuse the current terminal, you can put 765.Nm 766into the background using your standard shell suspend and background 767commands (usually 768.Dq ^Z 769followed by 770.Dq bg ) . 771.Pp 772Refer to the 773.Sx PPP COMMAND LIST 774section for details on all available commands. 775.Sh AUTOMATIC DIALING 776To use automatic dialing, you must prepare some Dial and Login chat scripts. 777See the example definitions in 778.Pa /usr/share/examples/ppp/ppp.conf.sample 779(the format of 780.Pa /etc/ppp/ppp.conf 781is pretty simple). 782Each line contains one comment, inclusion, label or command: 783.Bl -bullet 784.It 785A line starting with a 786.Pq Dq # 787character is treated as a comment line. 788Leading whitespace are ignored when identifying comment lines. 789.It 790An inclusion is a line beginning with the word 791.Sq {!include} . 792It must have one argument - the file to {include}. 793You may wish to 794.Dq {!include} ~/.ppp.conf 795for compatibility with older versions of 796.Nm . 797.It 798A label name starts in the first column and is followed by 799a colon 800.Pq Dq \&: . 801.It 802A command line must contain a space or tab in the first column. 803.El 804.Pp 805The 806.Pa /etc/ppp/ppp.conf 807file should consist of at least a 808.Dq default 809section. 810This section is always executed. 811It should also contain 812one or more sections, named according to their purpose, for example, 813.Dq MyISP 814would represent your ISP, and 815.Dq ppp-in 816would represent an incoming 817.Nm 818configuration. 819You can now specify the destination label name when you invoke 820.Nm . 821Commands associated with the 822.Dq default 823label are executed, followed by those associated with the destination 824label provided. 825When 826.Nm 827is started with no arguments, the 828.Dq default 829section is still executed. 830The load command can be used to manually load a section from the 831.Pa /etc/ppp/ppp.conf 832file: 833.Bd -literal -offset indent 834ppp ON awfulhak> load MyISP 835.Ed 836.Pp 837Note, no action is taken by 838.Nm 839after a section is loaded, whether it's the result of passing a label on 840the command line or using the 841.Dq load 842command. 843Only the commands specified for that label in the configuration 844file are executed. 845However, when invoking 846.Nm 847with the 848.Fl background , 849.Fl ddial , 850or 851.Fl dedicated 852switches, the link mode tells 853.Nm 854to establish a connection. 855Refer to the 856.Dq set mode 857command below for further details. 858.Pp 859Once the connection is made, the 860.Sq ppp 861portion of the prompt will change to 862.Sq PPP : 863.Bd -literal -offset indent 864# ppp MyISP 865\&... 866ppp ON awfulhak> dial 867Ppp ON awfulhak> 868PPp ON awfulhak> 869PPP ON awfulhak> 870.Ed 871.Pp 872The Ppp prompt indicates that 873.Nm 874has entered the authentication phase. 875The PPp prompt indicates that 876.Nm 877has entered the network phase. 878The PPP prompt indicates that 879.Nm 880has successfully negotiated a network layer protocol and is in 881a usable state. 882.Pp 883If the 884.Pa /etc/ppp/ppp.linkup 885file is available, its contents are executed 886when the 887.Em PPP 888connection is established. 889See the provided 890.Dq pmdemand 891example in 892.Pa /usr/share/examples/ppp/ppp.conf.sample 893which runs a script in the background after the connection is established 894(refer to the 895.Dq shell 896and 897.Dq bg 898commands below for a description of possible substitution strings). 899Similarly, when a connection is closed, the contents of the 900.Pa /etc/ppp/ppp.linkdown 901file are executed. 902Both of these files have the same format as 903.Pa /etc/ppp/ppp.conf . 904.Pp 905In previous versions of 906.Nm , 907it was necessary to re-add routes such as the default route in the 908.Pa ppp.linkup 909file. 910.Nm 911supports 912.Sq sticky routes , 913where all routes that contain the 914.Dv HISADDR , 915.Dv MYADDR , 916.Dv HISADDR6 917or 918.Dv MYADDR6 919literals will automatically be updated when the values of these variables 920change. 921.Sh BACKGROUND DIALING 922If you want to establish a connection using 923.Nm 924non-interactively (such as from a 925.Xr crontab 5 926entry or an 927.Xr at 1 928job) you should use the 929.Fl background 930option. 931When 932.Fl background 933is specified, 934.Nm 935attempts to establish the connection immediately. 936If multiple phone 937numbers are specified, each phone number will be tried once. 938If the attempt fails, 939.Nm 940exits immediately with a non-zero exit code. 941If it succeeds, then 942.Nm 943becomes a daemon, and returns an exit status of zero to its caller. 944The daemon exits automatically if the connection is dropped by the 945remote system, or it receives a 946.Dv TERM 947signal. 948.Sh DIAL ON DEMAND 949Demand dialing is enabled with the 950.Fl auto 951or 952.Fl ddial 953options. 954You must also specify the destination label in 955.Pa /etc/ppp/ppp.conf 956to use. 957It must contain the 958.Dq set ifaddr 959command to {define} the remote peers IP address. 960(refer to 961.Pa /usr/share/examples/ppp/ppp.conf.sample ) 962.Bd -literal -offset indent 963# ppp -auto pmdemand 964.Ed 965.Pp 966When 967.Fl auto 968or 969.Fl ddial 970is specified, 971.Nm 972runs as a daemon but you can still configure or examine its 973configuration by using the 974.Dq set server 975command in 976.Pa /etc/ppp/ppp.conf , 977(for example, 978.Dq Li "set server +3000 mypasswd" ) 979and connecting to the diagnostic port as follows: 980.Bd -literal -offset indent 981# pppctl 3000 (assuming tun0) 982Password: 983PPP ON awfulhak> show who 984tcp (127.0.0.1:1028) * 985.Ed 986.Pp 987The 988.Dq show who 989command lists users that are currently connected to 990.Nm 991itself. 992If the diagnostic socket is closed or changed to a different 993socket, all connections are immediately dropped. 994.Pp 995In 996.Fl auto 997mode, when an outgoing packet is detected, 998.Nm 999will perform the dialing action (chat script) and try to connect 1000with the peer. 1001In 1002.Fl ddial 1003mode, the dialing action is performed any time the line is found 1004to be down. 1005If the connect fails, the default behaviour is to wait 30 seconds 1006and then attempt to connect when another outgoing packet is detected. 1007This behaviour can be changed using the 1008.Dq set redial 1009command: 1010.Pp 1011.No set redial Ar secs Ns Xo 1012.Oo + Ns Ar inc Ns 1013.Op - Ns Ar max Ns 1014.Oc Ns Op . Ns Ar next 1015.Op Ar attempts 1016.Xc 1017.Pp 1018.Bl -tag -width attempts -compact 1019.It Ar secs 1020is the number of seconds to wait before attempting 1021to connect again. 1022If the argument is the literal string 1023.Sq Li random , 1024the delay period is a random value between 1 and 30 seconds inclusive. 1025.It Ar inc 1026is the number of seconds that 1027.Ar secs 1028should be incremented each time a new dial attempt is made. 1029The timeout reverts to 1030.Ar secs 1031only after a successful connection is established. 1032The default value for 1033.Ar inc 1034is zero. 1035.It Ar max 1036is the maximum number of times 1037.Nm 1038should increment 1039.Ar secs . 1040The default value for 1041.Ar max 1042is 10. 1043.It Ar next 1044is the number of seconds to wait before attempting 1045to dial the next number in a list of numbers (see the 1046.Dq set phone 1047command). 1048The default is 3 seconds. 1049Again, if the argument is the literal string 1050.Sq Li random , 1051the delay period is a random value between 1 and 30 seconds. 1052.It Ar attempts 1053is the maximum number of times to try to connect for each outgoing packet 1054that triggers a dial. 1055The previous value is unchanged if this parameter is omitted. 1056If a value of zero is specified for 1057.Ar attempts , 1058.Nm 1059will keep trying until a connection is made. 1060.El 1061.Pp 1062So, for example: 1063.Bd -literal -offset indent 1064set redial 10.3 4 1065.Ed 1066.Pp 1067will attempt to connect 4 times for each outgoing packet that causes 1068a dial attempt with a 3 second delay between each number and a 10 second 1069delay after all numbers have been tried. 1070If multiple phone numbers 1071are specified, the total number of attempts is still 4 (it does not 1072attempt each number 4 times). 1073.Pp 1074Alternatively, 1075.Pp 1076.Bd -literal -offset indent 1077set redial 10+10-5.3 20 1078.Ed 1079.Pp 1080tells 1081.Nm 1082to attempt to connect 20 times. 1083After the first attempt, 1084.Nm 1085pauses for 10 seconds. 1086After the next attempt it pauses for 20 seconds 1087and so on until after the sixth attempt it pauses for 1 minute. 1088The next 14 pauses will also have a duration of one minute. 1089If 1090.Nm 1091connects, disconnects and fails to connect again, the timeout starts again 1092at 10 seconds. 1093.Pp 1094Modifying the dial delay is very useful when running 1095.Nm 1096in 1097.Fl auto 1098mode on both ends of the link. 1099If each end has the same timeout, 1100both ends wind up calling each other at the same time if the link 1101drops and both ends have packets queued. 1102At some locations, the serial link may not be reliable, and carrier 1103may be lost at inappropriate times. 1104It is possible to have 1105.Nm 1106redial should carrier be unexpectedly lost during a session. 1107.Bd -literal -offset indent 1108set reconnect timeout ntries 1109.Ed 1110.Pp 1111This command tells 1112.Nm 1113to re-establish the connection 1114.Ar ntries 1115times on loss of carrier with a pause of 1116.Ar timeout 1117seconds before each try. 1118For example, 1119.Bd -literal -offset indent 1120set reconnect 3 5 1121.Ed 1122.Pp 1123tells 1124.Nm 1125that on an unexpected loss of carrier, it should wait 1126.Ar 3 1127seconds before attempting to reconnect. 1128This may happen up to 1129.Ar 5 1130times before 1131.Nm 1132gives up. 1133The default value of ntries is zero (no reconnect). 1134Care should be taken with this option. 1135If the local timeout is slightly 1136longer than the remote timeout, the reconnect feature will always be 1137triggered (up to the given number of times) after the remote side 1138times out and hangs up. 1139NOTE: In this context, losing too many LQRs constitutes a loss of 1140carrier and will trigger a reconnect. 1141If the 1142.Fl background 1143flag is specified, all phone numbers are dialed at most once until 1144a connection is made. 1145The next number redial period specified with the 1146.Dq set redial 1147command is honoured, as is the reconnect tries value. 1148If your redial 1149value is less than the number of phone numbers specified, not all 1150the specified numbers will be tried. 1151To terminate the program, type 1152.Bd -literal -offset indent 1153PPP ON awfulhak> close 1154ppp ON awfulhak> quit all 1155.Ed 1156.Pp 1157A simple 1158.Dq quit 1159command will terminate the 1160.Xr pppctl 8 1161or 1162.Xr telnet 1 1163connection but not the 1164.Nm 1165program itself. 1166You must use 1167.Dq quit all 1168to terminate 1169.Nm 1170as well. 1171.Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1) 1172To handle an incoming 1173.Em PPP 1174connection request, follow these steps: 1175.Bl -enum 1176.It 1177Make sure the modem and (optionally) 1178.Pa /etc/rc.serial 1179is configured correctly. 1180.Bl -bullet -compact 1181.It 1182Use Hardware Handshake (CTS/RTS) for flow control. 1183.It 1184Modem should be set to NO echo back (ATE0) and NO results string (ATQ1). 1185.El 1186.Pp 1187.It 1188Edit 1189.Pa /etc/ttys 1190to enable a 1191.Xr getty 8 1192on the port where the modem is attached. 1193For example: 1194.Pp 1195.Dl ttyd1 Qo /usr/libexec/getty std.38400 Qc dialup on secure 1196.Pp 1197Don't forget to send a 1198.Dv HUP 1199signal to the 1200.Xr init 8 1201process to start the 1202.Xr getty 8 : 1203.Pp 1204.Dl # kill -HUP 1 1205.Pp 1206It is usually also necessary to train your modem to the same DTR speed 1207as the getty: 1208.Bd -literal -offset indent 1209# ppp 1210ppp ON awfulhak> set device /dev/cuaa1 1211ppp ON awfulhak> set speed 38400 1212ppp ON awfulhak> term 1213deflink: Entering terminal mode on /dev/cuaa1 1214Type `~?' for help 1215at 1216OK 1217at 1218OK 1219atz 1220OK 1221at 1222OK 1223~. 1224ppp ON awfulhak> quit 1225.Ed 1226.It 1227Create a 1228.Pa /usr/local/bin/ppplogin 1229file with the following contents: 1230.Bd -literal -offset indent 1231#! /bin/sh 1232exec /usr/sbin/ppp -direct incoming 1233.Ed 1234.Pp 1235Direct mode 1236.Pq Fl direct 1237lets 1238.Nm 1239work with stdin and stdout. 1240You can also use 1241.Xr pppctl 8 1242to connect to a configured diagnostic port, in the same manner as with 1243client-side 1244.Nm . 1245.Pp 1246Here, the 1247.Ar incoming 1248section must be set up in 1249.Pa /etc/ppp/ppp.conf . 1250.Pp 1251Make sure that the 1252.Ar incoming 1253section contains the 1254.Dq allow users 1255command as appropriate. 1256.It 1257Prepare an account for the incoming user. 1258.Bd -literal 1259ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin 1260.Ed 1261.Pp 1262Refer to the manual entries for 1263.Xr adduser 8 1264and 1265.Xr vipw 8 1266for details. 1267.It 1268Support for IPCP Domain Name Server and NetBIOS Name Server negotiation 1269can be enabled using the 1270.Dq accept dns 1271and 1272.Dq set nbns 1273commands. 1274Refer to their descriptions below. 1275.El 1276.Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2) 1277This method differs in that we use 1278.Nm 1279to authenticate the connection rather than 1280.Xr login 1 : 1281.Bl -enum 1282.It 1283Configure your default section in 1284.Pa /etc/gettytab 1285with automatic ppp recognition by specifying the 1286.Dq pp 1287capability: 1288.Bd -literal 1289default:\\ 1290 :pp=/usr/local/bin/ppplogin:\\ 1291 ..... 1292.Ed 1293.It 1294Configure your serial device(s), enable a 1295.Xr getty 8 1296and create 1297.Pa /usr/local/bin/ppplogin 1298as in the first three steps for method 1 above. 1299.It 1300Add either 1301.Dq enable chap 1302or 1303.Dq enable pap 1304(or both) 1305to 1306.Pa /etc/ppp/ppp.conf 1307under the 1308.Sq incoming 1309label (or whatever label 1310.Pa ppplogin 1311uses). 1312.It 1313Create an entry in 1314.Pa /etc/ppp/ppp.secret 1315for each incoming user: 1316.Bd -literal 1317Pfred<TAB>xxxx 1318Pgeorge<TAB>yyyy 1319.Ed 1320.El 1321.Pp 1322Now, as soon as 1323.Xr getty 8 1324detects a ppp connection (by recognising the HDLC frame headers), it runs 1325.Dq /usr/local/bin/ppplogin . 1326.Pp 1327It is 1328.Em VITAL 1329that either PAP or CHAP are enabled as above. 1330If they are not, you are 1331allowing anybody to establish ppp session with your machine 1332.Em without 1333a password, opening yourself up to all sorts of potential attacks. 1334.Sh AUTHENTICATING INCOMING CONNECTIONS 1335Normally, the receiver of a connection requires that the peer 1336authenticates itself. 1337This may be done using 1338.Xr login 1 , 1339but alternatively, you can use PAP or CHAP. 1340CHAP is the more secure of the two, but some clients may not support it. 1341Once you decide which you wish to use, add the command 1342.Sq enable chap 1343or 1344.Sq enable pap 1345to the relevant section of 1346.Pa ppp.conf . 1347.Pp 1348You must then configure the 1349.Pa /etc/ppp/ppp.secret 1350file. 1351This file contains one line per possible client, each line 1352containing up to five fields: 1353.Pp 1354.Ar name Ar key Oo 1355.Ar hisaddr Op Ar label Op Ar callback-number 1356.Oc 1357.Pp 1358The 1359.Ar name 1360and 1361.Ar key 1362specify the client username and password. 1363If 1364.Ar key 1365is 1366.Dq \&* 1367and PAP is being used, 1368.Nm 1369will look up the password database 1370.Pq Xr passwd 5 1371when authenticating. 1372If the client does not offer a suitable response based on any 1373.Ar name Ns No / Ns Ar key 1374combination in 1375.Pa ppp.secret , 1376authentication fails. 1377.Pp 1378If authentication is successful, 1379.Ar hisaddr 1380(if specified) 1381is used when negotiating IP numbers. 1382See the 1383.Dq set ifaddr 1384command for details. 1385.Pp 1386If authentication is successful and 1387.Ar label 1388is specified, the current system label is changed to match the given 1389.Ar label . 1390This will change the subsequent parsing of the 1391.Pa ppp.linkup 1392and 1393.Pa ppp.linkdown 1394files. 1395.Pp 1396If authentication is successful and 1397.Ar callback-number 1398is specified and 1399.Dq set callback 1400has been used in 1401.Pa ppp.conf , 1402the client will be called back on the given number. 1403If CBCP is being used, 1404.Ar callback-number 1405may also contain a list of numbers or a 1406.Dq \&* , 1407as if passed to the 1408.Dq set cbcp 1409command. 1410The value will be used in 1411.Nm Ns No 's 1412subsequent CBCP phase. 1413.Sh PPP OVER TCP and UDP (a.k.a Tunnelling) 1414Instead of running 1415.Nm 1416over a serial link, it is possible to 1417use a TCP connection instead by specifying the host, port and protocol as the 1418device: 1419.Pp 1420.Dl set device ui-gate:6669/tcp 1421.Pp 1422Instead of opening a serial device, 1423.Nm 1424will open a TCP connection to the given machine on the given 1425socket. 1426It should be noted however that 1427.Nm 1428doesn't use the telnet protocol and will be unable to negotiate 1429with a telnet server. 1430You should set up a port for receiving this 1431.Em PPP 1432connection on the receiving machine (ui-gate). 1433This is done by first updating 1434.Pa /etc/services 1435to name the service: 1436.Pp 1437.Dl ppp-in 6669/tcp # Incoming PPP connections over TCP 1438.Pp 1439and updating 1440.Pa /etc/inetd.conf 1441to tell 1442.Xr inetd 8 1443how to deal with incoming connections on that port: 1444.Pp 1445.Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in 1446.Pp 1447Don't forget to send a 1448.Dv HUP 1449signal to 1450.Xr inetd 8 1451after you've updated 1452.Pa /etc/inetd.conf . 1453Here, we use a label named 1454.Dq ppp-in . 1455The entry in 1456.Pa /etc/ppp/ppp.conf 1457on ui-gate (the receiver) should contain the following: 1458.Bd -literal -offset indent 1459ppp-in: 1460 set timeout 0 1461 set ifaddr 10.0.4.1 10.0.4.2 1462.Ed 1463.Pp 1464and the entry in 1465.Pa /etc/ppp/ppp.linkup 1466should contain: 1467.Bd -literal -offset indent 1468ppp-in: 1469 add 10.0.1.0/24 HISADDR 1470.Ed 1471.Pp 1472It is necessary to put the 1473.Dq add 1474command in 1475.Pa ppp.linkup 1476to ensure that the route is only added after 1477.Nm 1478has negotiated and assigned addresses to its interface. 1479.Pp 1480You may also want to enable PAP or CHAP for security. 1481To enable PAP, add the following line: 1482.Bd -literal -offset indent 1483 enable PAP 1484.Ed 1485.Pp 1486You'll also need to create the following entry in 1487.Pa /etc/ppp/ppp.secret : 1488.Bd -literal -offset indent 1489MyAuthName MyAuthPasswd 1490.Ed 1491.Pp 1492If 1493.Ar MyAuthPasswd 1494is a 1495.Dq * , 1496the password is looked up in the 1497.Xr passwd 5 1498database. 1499.Pp 1500The entry in 1501.Pa /etc/ppp/ppp.conf 1502on awfulhak (the initiator) should contain the following: 1503.Bd -literal -offset indent 1504ui-gate: 1505 set escape 0xff 1506 set device ui-gate:ppp-in/tcp 1507 set dial 1508 set timeout 30 1509 set log Phase Chat Connect hdlc LCP IPCP IPV6CP CCP tun 1510 set ifaddr 10.0.4.2 10.0.4.1 1511.Ed 1512.Pp 1513with the route setup in 1514.Pa /etc/ppp/ppp.linkup : 1515.Bd -literal -offset indent 1516ui-gate: 1517 add 10.0.2.0/24 HISADDR 1518.Ed 1519.Pp 1520Again, if you're enabling PAP, you'll also need this in the 1521.Pa /etc/ppp/ppp.conf 1522profile: 1523.Bd -literal -offset indent 1524 set authname MyAuthName 1525 set authkey MyAuthKey 1526.Ed 1527.Pp 1528We're assigning the address of 10.0.4.1 to ui-gate, and the address 152910.0.4.2 to awfulhak. 1530To open the connection, just type 1531.Pp 1532.Dl awfulhak # ppp -background ui-gate 1533.Pp 1534The result will be an additional "route" on awfulhak to the 153510.0.2.0/24 network via the TCP connection, and an additional 1536"route" on ui-gate to the 10.0.1.0/24 network. 1537The networks are effectively bridged - the underlying TCP 1538connection may be across a public network (such as the 1539Internet), and the 1540.Em PPP 1541traffic is conceptually encapsulated 1542(although not packet by packet) inside the TCP stream between 1543the two gateways. 1544.Pp 1545The major disadvantage of this mechanism is that there are two 1546"guaranteed delivery" mechanisms in place - the underlying TCP 1547stream and whatever protocol is used over the 1548.Em PPP 1549link - probably TCP again. 1550If packets are lost, both levels will 1551get in each others way trying to negotiate sending of the missing 1552packet. 1553.Pp 1554To avoid this overhead, it is also possible to do all this using 1555UDP instead of TCP as the transport by simply changing the protocol 1556from "tcp" to "udp". 1557When using UDP as a transport, 1558.Nm 1559will operate in synchronous mode. 1560This is another gain as the incoming 1561data does not have to be rearranged into packets. 1562.Pp 1563Care should be taken when adding a default route through a tunneled 1564setup like this. 1565It is quite common for the default route 1566(added in 1567.Pa /etc/ppp/ppp.linkup ) 1568to end up routing the link's TCP connection through the tunnel, 1569effectively garrotting the connection. 1570To avoid this, make sure you add a static route for the benefit of 1571the link: 1572.Bd -literal -offset indent 1573ui-gate: 1574 set escape 0xff 1575 set device ui-gate:ppp-in/tcp 1576 add ui-gate x.x.x.x 1577 ..... 1578.Ed 1579.Pp 1580where 1581.Dq x.x.x.x 1582is the IP number that your route to 1583.Dq ui-gate 1584would normally use. 1585.Pp 1586When routing your connection accross a public network such as the Internet, 1587it is preferable to encrypt the data. 1588This can be done with the help of the MPPE protocol, although currently this 1589means that you will not be able to also compress the traffic as MPPE is 1590implemented as a compression layer (thank Microsoft for this). 1591To enable MPPE encryption, add the following lines to 1592.Pa /etc/ppp/ppp.conf 1593on the server: 1594.Bd -literal -offset indent 1595 enable MSCHAPv2 1596 disable deflate pred1 1597 deny deflate pred1 1598.Ed 1599.Pp 1600ensuring that you've put the requisite entry in 1601.Pa /etc/ppp/ppp.secret 1602(MSCHAPv2 is challenge based, so 1603.Xr passwd 5 1604cannot be used) 1605.Pp 1606MSCHAPv2 and MPPE are accepted by default, so the client end should work 1607without any additional changes (although ensure you have 1608.Dq set authname 1609and 1610.Dq set authkey 1611in your profile). 1612.Sh NETWORK ADDRESS TRANSLATION (PACKET ALIASING) 1613The 1614.Fl nat 1615command line option enables network address translation (a.k.a. packet 1616aliasing). 1617This allows the 1618.Nm 1619host to act as a masquerading gateway for other computers over 1620a local area network. 1621Outgoing IP packets are NAT'd so that they appear to come from the 1622.Nm 1623host, and incoming packets are de-NAT'd so that they are routed 1624to the correct machine on the local area network. 1625NAT allows computers on private, unregistered subnets to have Internet 1626access, although they are invisible from the outside world. 1627In general, correct 1628.Nm 1629operation should first be verified with network address translation disabled. 1630Then, the 1631.Fl nat 1632option should be switched on, and network applications (web browser, 1633.Xr telnet 1 , 1634.Xr ftp 1 , 1635.Xr ping 8 , 1636.Xr traceroute 8 ) 1637should be checked on the 1638.Nm 1639host. 1640Finally, the same or similar applications should be checked on other 1641computers in the LAN. 1642If network applications work correctly on the 1643.Nm 1644host, but not on other machines in the LAN, then the masquerading 1645software is working properly, but the host is either not forwarding 1646or possibly receiving IP packets. 1647Check that IP forwarding is enabled in 1648.Pa /etc/rc.conf 1649and that other machines have designated the 1650.Nm 1651host as the gateway for the LAN. 1652.Sh PACKET FILTERING 1653This implementation supports packet filtering. 1654There are four kinds of 1655filters: the 1656.Em in 1657filter, the 1658.Em out 1659filter, the 1660.Em dial 1661filter and the 1662.Em alive 1663filter. 1664Here are the basics: 1665.Bl -bullet 1666.It 1667A filter definition has the following syntax: 1668.Pp 1669set filter 1670.Ar name 1671.Ar rule-no 1672.Ar action 1673.Op !\& 1674.Oo 1675.Op host 1676.Ar src_addr Ns Op / Ns Ar width 1677.Op Ar dst_addr Ns Op / Ns Ar width 1678.Oc 1679.Ar [ proto Op src Ar cmp port 1680.Op dst Ar cmp port 1681.Op estab 1682.Op syn 1683.Op finrst 1684.Op timeout Ar secs ] 1685.Bl -enum 1686.It 1687.Ar Name 1688should be one of 1689.Sq in , 1690.Sq out , 1691.Sq dial 1692or 1693.Sq alive . 1694.It 1695.Ar Rule-no 1696is a numeric value between 1697.Sq 0 1698and 1699.Sq 39 1700specifying the rule number. 1701Rules are specified in numeric order according to 1702.Ar rule-no , 1703but only if rule 1704.Sq 0 1705is defined. 1706.It 1707.Ar Action 1708may be specified as 1709.Sq permit 1710or 1711.Sq deny , 1712in which case, if a given packet matches the rule, the associated action 1713is taken immediately. 1714.Ar Action 1715can also be specified as 1716.Sq clear 1717to clear the action associated with that particular rule, or as a new 1718rule number greater than the current rule. 1719In this case, if a given 1720packet matches the current rule, the packet will next be matched against 1721the new rule number (rather than the next rule number). 1722.Pp 1723The 1724.Ar action 1725may optionally be followed with an exclamation mark 1726.Pq Dq !\& , 1727telling 1728.Nm 1729to reverse the sense of the following match. 1730.It 1731.Op Ar src_addr Ns Op / Ns Ar width 1732and 1733.Op Ar dst_addr Ns Op / Ns Ar width 1734are the source and destination IP number specifications. 1735If 1736.Op / Ns Ar width 1737is specified, it gives the number of relevant netmask bits, 1738allowing the specification of an address range. 1739.Pp 1740Either 1741.Ar src_addr 1742or 1743.Ar dst_addr 1744may be given the values 1745.Dv MYADDR , 1746.Dv HISADDR , 1747.Dv MYADDR6 1748or 1749.Dv HISADDR6 1750(refer to the description of the 1751.Dq bg 1752command for a description of these values). 1753When these values are used, 1754the filters will be updated any time the values change. 1755This is similar to the behaviour of the 1756.Dq add 1757command below. 1758.It 1759.Ar Proto 1760may be any protocol from 1761.Xr protocols 5 . 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 1892For IPv4, 1893.Nm 1894uses IPCP to negotiate IP addresses. 1895Each side of the connection 1896specifies the IP address that it's willing to use, and if the requested 1897IP address is acceptable then 1898.Nm 1899returns an ACK to the requester. 1900Otherwise, 1901.Nm 1902returns NAK to suggest that the peer use a different IP address. 1903When 1904both sides of the connection agree to accept the received request (and 1905send an ACK), IPCP is set to the open state and a network level connection 1906is established. 1907To control this IPCP behaviour, this implementation has the 1908.Dq set ifaddr 1909command for defining the local and remote IP address: 1910.Bd -ragged -offset indent 1911.No set ifaddr Oo Ar src_addr Ns 1912.Op / Ns Ar \&nn 1913.Oo Ar dst_addr Ns Op / Ns Ar \&nn 1914.Oo Ar netmask 1915.Op Ar trigger_addr 1916.Oc 1917.Oc 1918.Oc 1919.Ed 1920.Pp 1921where, 1922.Sq src_addr 1923is the IP address that the local side is willing to use, 1924.Sq dst_addr 1925is the IP address which the remote side should use and 1926.Sq netmask 1927is the netmask that should be used. 1928.Sq Src_addr 1929defaults to the current 1930.Xr hostname 1 , 1931.Sq dst_addr 1932defaults to 0.0.0.0, and 1933.Sq netmask 1934defaults to whatever mask is appropriate for 1935.Sq src_addr . 1936It is only possible to make 1937.Sq netmask 1938smaller than the default. 1939The usual value is 255.255.255.255, as 1940most kernels ignore the netmask of a POINTOPOINT interface. 1941.Pp 1942Some incorrect 1943.Em PPP 1944implementations require that the peer negotiates a specific IP 1945address instead of 1946.Sq src_addr . 1947If this is the case, 1948.Sq trigger_addr 1949may be used to specify this IP number. 1950This will not affect the 1951routing table unless the other side agrees with this proposed number. 1952.Bd -literal -offset indent 1953set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0 1954.Ed 1955.Pp 1956The above specification means: 1957.Pp 1958.Bl -bullet -compact 1959.It 1960I will first suggest that my IP address should be 0.0.0.0, but I 1961will only accept an address of 192.244.177.38. 1962.It 1963I strongly insist that the peer uses 192.244.177.2 as his own 1964address and won't permit the use of any IP address but 192.244.177.2. 1965When the peer requests another IP address, I will always suggest that 1966it uses 192.244.177.2. 1967.It 1968The routing table entry will have a netmask of 0xffffffff. 1969.El 1970.Pp 1971This is all fine when each side has a pre-determined IP address, however 1972it is often the case that one side is acting as a server which controls 1973all IP addresses and the other side should go along with it. 1974In order to allow more flexible behaviour, the 1975.Dq set ifaddr 1976command allows the user to specify IP addresses more loosely: 1977.Pp 1978.Dl set ifaddr 192.244.177.38/24 192.244.177.2/20 1979.Pp 1980A number followed by a slash 1981.Pq Dq / 1982represents the number of bits significant in the IP address. 1983The above example means: 1984.Pp 1985.Bl -bullet -compact 1986.It 1987I'd like to use 192.244.177.38 as my address if it is possible, but I'll 1988also accept any IP address between 192.244.177.0 and 192.244.177.255. 1989.It 1990I'd like to make him use 192.244.177.2 as his own address, but I'll also 1991permit him to use any IP address between 192.244.176.0 and 1992192.244.191.255. 1993.It 1994As you may have already noticed, 192.244.177.2 is equivalent to saying 1995192.244.177.2/32. 1996.It 1997As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no 1998preferred IP address and will obey the remote peers selection. 1999When using zero, no routing table entries will be made until a connection 2000is established. 2001.It 2002192.244.177.2/0 means that I'll accept/permit any IP address but I'll 2003suggest that 192.244.177.2 be used first. 2004.El 2005.Pp 2006When negotiating IPv6 addresses, no control is given to the user. 2007IPV6CP negotiation is fully automatic. 2008.Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER 2009The following steps should be taken when connecting to your ISP: 2010.Bl -enum 2011.It 2012Describe your providers phone number(s) in the dial script using the 2013.Dq set phone 2014command. 2015This command allows you to set multiple phone numbers for 2016dialing and redialing separated by either a pipe 2017.Pq Dq \&| 2018or a colon 2019.Pq Dq \&: : 2020.Bd -ragged -offset indent 2021.No set phone Ar telno Ns Xo 2022.Oo \&| Ns Ar backupnumber 2023.Oc Ns ... Ns Oo : Ns Ar nextnumber 2024.Oc Ns ... 2025.Xc 2026.Ed 2027.Pp 2028Numbers after the first in a pipe-separated list are only used if the 2029previous number was used in a failed dial or login script. 2030Numbers 2031separated by a colon are used sequentially, irrespective of what happened 2032as a result of using the previous number. 2033For example: 2034.Bd -literal -offset indent 2035set phone "1234567|2345678:3456789|4567890" 2036.Ed 2037.Pp 2038Here, the 1234567 number is attempted. 2039If the dial or login script fails, 2040the 2345678 number is used next time, but *only* if the dial or login script 2041fails. 2042On the dial after this, the 3456789 number is used. 2043The 4567890 2044number is only used if the dial or login script using the 3456789 fails. 2045If the login script of the 2345678 number fails, the next number is still the 20463456789 number. 2047As many pipes and colons can be used as are necessary 2048(although a given site would usually prefer to use either the pipe or the 2049colon, but not both). 2050The next number redial timeout is used between all numbers. 2051When the end of the list is reached, the normal redial period is 2052used before starting at the beginning again. 2053The selected phone number is substituted for the \\\\T string in the 2054.Dq set dial 2055command (see below). 2056.It 2057Set up your redial requirements using 2058.Dq set redial . 2059For example, if you have a bad telephone line or your provider is 2060usually engaged (not so common these days), you may want to specify 2061the following: 2062.Bd -literal -offset indent 2063set redial 10 4 2064.Ed 2065.Pp 2066This says that up to 4 phone calls should be attempted with a pause of 10 2067seconds before dialing the first number again. 2068.It 2069Describe your login procedure using the 2070.Dq set dial 2071and 2072.Dq set login 2073commands. 2074The 2075.Dq set dial 2076command is used to talk to your modem and establish a link with your 2077ISP, for example: 2078.Bd -literal -offset indent 2079set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" \e 2080 ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT" 2081.Ed 2082.Pp 2083This modem "chat" string means: 2084.Bl -bullet 2085.It 2086Abort if the string "BUSY" or "NO CARRIER" are received. 2087.It 2088Set the timeout to 4 seconds. 2089.It 2090Expect nothing. 2091.It 2092Send ATZ. 2093.It 2094Expect OK. 2095If that's not received within the 4 second timeout, send ATZ 2096and expect OK. 2097.It 2098Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from 2099above. 2100.It 2101Set the timeout to 60. 2102.It 2103Wait for the CONNECT string. 2104.El 2105.Pp 2106Once the connection is established, the login script is executed. 2107This script is written in the same style as the dial script, but care should 2108be taken to avoid having your password logged: 2109.Bd -literal -offset indent 2110set authkey MySecret 2111set login "TIMEOUT 15 login:-\\\\r-login: awfulhak \e 2112 word: \\\\P ocol: PPP HELLO" 2113.Ed 2114.Pp 2115This login "chat" string means: 2116.Bl -bullet 2117.It 2118Set the timeout to 15 seconds. 2119.It 2120Expect "login:". 2121If it's not received, send a carriage return and expect 2122"login:" again. 2123.It 2124Send "awfulhak" 2125.It 2126Expect "word:" (the tail end of a "Password:" prompt). 2127.It 2128Send whatever our current 2129.Ar authkey 2130value is set to. 2131.It 2132Expect "ocol:" (the tail end of a "Protocol:" prompt). 2133.It 2134Send "PPP". 2135.It 2136Expect "HELLO". 2137.El 2138.Pp 2139The 2140.Dq set authkey 2141command is logged specially. 2142When 2143.Ar command 2144or 2145.Ar chat 2146logging is enabled, the actual password is not logged; 2147.Sq ******** 2148is logged instead. 2149.Pp 2150Login scripts vary greatly between ISPs. 2151If you're setting one up for the first time, 2152.Em ENABLE CHAT LOGGING 2153so that you can see if your script is behaving as you expect. 2154.It 2155Use 2156.Dq set device 2157and 2158.Dq set speed 2159to specify your serial line and speed, for example: 2160.Bd -literal -offset indent 2161set device /dev/cuaa0 2162set speed 115200 2163.Ed 2164.Pp 2165Cuaa0 is the first serial port on 2166.Fx . 2167If you're running 2168.Nm 2169on 2170.Ox , 2171cua00 is the first. 2172A speed of 115200 should be specified 2173if you have a modem capable of bit rates of 28800 or more. 2174In general, the serial speed should be about four times the modem speed. 2175.It 2176Use the 2177.Dq set ifaddr 2178command to {define} the IP address. 2179.Bl -bullet 2180.It 2181If you know what IP address your provider uses, then use it as the remote 2182address (dst_addr), otherwise choose something like 10.0.0.2/0 (see below). 2183.It 2184If your provider has assigned a particular IP address to you, then use 2185it as your address (src_addr). 2186.It 2187If your provider assigns your address dynamically, choose a suitably 2188unobtrusive and unspecific IP number as your address. 218910.0.0.1/0 would be appropriate. 2190The bit after the / specifies how many bits of the 2191address you consider to be important, so if you wanted to insist on 2192something in the class C network 1.2.3.0, you could specify 1.2.3.1/24. 2193.It 2194If you find that your ISP accepts the first IP number that you suggest, 2195specify third and forth arguments of 2196.Dq 0.0.0.0 . 2197This will force your ISP to assign a number. 2198(The third argument will 2199be ignored as it is less restrictive than the default mask for your 2200.Sq src_addr ) . 2201.El 2202.Pp 2203An example for a connection where you don't know your IP number or your 2204ISPs IP number would be: 2205.Bd -literal -offset indent 2206set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0 2207.Ed 2208.Pp 2209.It 2210In most cases, your ISP will also be your default router. 2211If this is the case, add the line 2212.Bd -literal -offset indent 2213add default HISADDR 2214.Ed 2215.Pp 2216to 2217.Pa /etc/ppp/ppp.conf 2218(or to 2219.Pa /etc/ppp/ppp.linkup 2220for setups that don't use 2221.Fl auto 2222mode). 2223.Pp 2224This tells 2225.Nm 2226to add a default route to whatever the peer address is 2227(10.0.0.2 in this example). 2228This route is 2229.Sq sticky , 2230meaning that should the value of 2231.Dv HISADDR 2232change, the route will be updated accordingly. 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 iface-alias 2952Default: Enabled if 2953.Fl nat 2954is specified. 2955This option simply tells 2956.Nm 2957to add new interface addresses to the interface rather than replacing them. 2958The option can only be enabled if network address translation is enabled 2959.Pq Dq nat enable yes . 2960.Pp 2961With this option enabled, 2962.Nm 2963will pass traffic for old interface addresses through the NAT 2964ifdef({LOCALNAT},{engine,},{engine 2965(see 2966.Xr libalias 3 ) ,}) 2967resulting in the ability (in 2968.Fl auto 2969mode) to properly connect the process that caused the PPP link to 2970come up in the first place. 2971.Pp 2972Disabling NAT with 2973.Dq nat enable no 2974will also disable 2975.Sq iface-alias . 2976.It ipcp 2977Default: Enabled. 2978This option allows 2979.Nm 2980to attempt to negotiate IP control protocol capabilities and if 2981successful to exchange IP datagrams with the peer. 2982.It ipv6cp 2983Default: Enabled. 2984This option allows 2985.Nm 2986to attempt to negotiate IPv6 control protocol capabilities and if 2987successful to exchange IPv6 datagrams with the peer. 2988.It keep-session 2989Default: Disabled. 2990When 2991.Nm 2992runs as a Multi-link server, a different 2993.Nm 2994instance initially receives each connection. 2995After determining that 2996the link belongs to an already existing bundle (controlled by another 2997.Nm 2998invocation), 2999.Nm 3000will transfer the link to that process. 3001.Pp 3002If the link is a tty device or if this option is enabled, 3003.Nm 3004will not exit, but will change its process name to 3005.Dq session owner 3006and wait for the controlling 3007.Nm 3008to finish with the link and deliver a signal back to the idle process. 3009This prevents the confusion that results from 3010.Nm Ns No 's 3011parent considering the link resource available again. 3012.Pp 3013For tty devices that have entries in 3014.Pa /etc/ttys , 3015this is necessary to prevent another 3016.Xr getty 8 3017from being started, and for program links such as 3018.Xr sshd 8 , 3019it prevents 3020.Xr sshd 8 3021from exiting due to the death of its child. 3022As 3023.Nm 3024cannot determine its parents requirements (except for the tty case), this 3025option must be enabled manually depending on the circumstances. 3026.It loopback 3027Default: Enabled. 3028When 3029.Ar loopback 3030is enabled, 3031.Nm 3032will automatically loop back packets being sent 3033out with a destination address equal to that of the 3034.Em PPP 3035interface. 3036If disabled, 3037.Nm 3038will send the packet, probably resulting in an ICMP redirect from 3039the other end. 3040It is convenient to have this option enabled when 3041the interface is also the default route as it avoids the necessity 3042of a loopback route. 3043.It passwdauth 3044Default: Disabled. 3045Enabling this option will tell the PAP authentication 3046code to use the password database (see 3047.Xr passwd 5 ) 3048to authenticate the caller if they cannot be found in the 3049.Pa /etc/ppp/ppp.secret 3050file. 3051.Pa /etc/ppp/ppp.secret 3052is always checked first. 3053If you wish to use passwords from 3054.Xr passwd 5 , 3055but also to specify an IP number or label for a given client, use 3056.Dq \&* 3057as the client password in 3058.Pa /etc/ppp/ppp.secret . 3059.It proxy 3060Default: Disabled. 3061Enabling this option will tell 3062.Nm 3063to proxy ARP for the peer. 3064This means that 3065.Nm 3066will make an entry in the ARP table using 3067.Dv HISADDR 3068and the 3069.Dv MAC 3070address of the local network in which 3071.Dv HISADDR 3072appears. 3073This allows other machines connecteed to the LAN to talk to 3074the peer as if the peer itself was connected to the LAN. 3075The proxy entry cannot be made unless 3076.Dv HISADDR 3077is an address from a LAN. 3078.It proxyall 3079Default: Disabled. 3080Enabling this will tell 3081.Nm 3082to add proxy arp entries for every IP address in all class C or 3083smaller subnets routed via the tun interface. 3084.Pp 3085Proxy arp entries are only made for sticky routes that are added 3086using the 3087.Dq add 3088command. 3089No proxy arp entries are made for the interface address itself 3090(as created by the 3091.Dq set ifaddr 3092command). 3093.It sroutes 3094Default: Enabled. 3095When the 3096.Dq add 3097command is used with the 3098.Dv HISADDR , 3099.Dv MYADDR , 3100.Dv HISADDR6 3101or 3102.Dv MYADDR6 3103values, entries are stored in the 3104.Sq sticky route 3105list. 3106Each time these variables change, this list is re-applied to the routing table. 3107.Pp 3108Disabling this option will prevent the re-application of sticky routes, 3109although the 3110.Sq stick route 3111list will still be maintained. 3112.It Op tcp Ns Xo 3113.No mssfixup 3114.Xc 3115Default: Enabled. 3116This option tells 3117.Nm 3118to adjust TCP SYN packets so that the maximum receive segment 3119size is not greater than the amount allowed by the interface MTU. 3120.It throughput 3121Default: Enabled. 3122This option tells 3123.Nm 3124to gather throughput statistics. 3125Input and output is sampled over 3126a rolling 5 second window, and current, best and total figures are retained. 3127This data is output when the relevant 3128.Em PPP 3129layer shuts down, and is also available using the 3130.Dq show 3131command. 3132Throughput statistics are available at the 3133.Dq IPCP 3134and 3135.Dq physical 3136levels. 3137.It utmp 3138Default: Enabled. 3139Normally, when a user is authenticated using PAP or CHAP, and when 3140.Nm 3141is running in 3142.Fl direct 3143mode, an entry is made in the utmp and wtmp files for that user. 3144Disabling this option will tell 3145.Nm 3146not to make any utmp or wtmp entries. 3147This is usually only necessary if 3148you require the user to both login and authenticate themselves. 3149.El 3150.Pp 3151.It add Ns Xo 3152.Op !\& 3153.Ar dest Ns Op / Ns Ar nn 3154.Op Ar mask 3155.Op Ar gateway 3156.Xc 3157.Ar Dest 3158is the destination IP address. 3159The netmask is specified either as a number of bits with 3160.Ar /nn 3161or as an IP number using 3162.Ar mask . 3163.Ar 0 0 3164or simply 3165.Ar 0 3166with no mask refers to the default route. 3167It is also possible to use the literal name 3168.Sq default 3169instead of 3170.Ar 0 . 3171.Ar Gateway 3172is the next hop gateway to get to the given 3173.Ar dest 3174machine/network. 3175Refer to the 3176.Xr route 8 3177command for further details. 3178.Pp 3179It is possible to use the symbolic names 3180.Sq MYADDR , 3181.Sq HISADDR , 3182.Sq MYADDR6 3183or 3184.Sq HISADDR6 3185as the destination, and 3186.Sq HISADDR 3187or 3188.Sq HISADDR6 3189as the 3190.Ar gateway . 3191.Sq MYADDR 3192is replaced with the interface IP address, 3193.Sq HISADDR 3194is replaced with the interface IP destination (peer) address, 3195.Sq MYADDR6 3196is replaced with the interface IPv6 address, and 3197.Sq HISADDR6 3198is replaced with the interface IPv6 destination address, 3199.Pp 3200If the 3201.Ar add!\& 3202command is used 3203(note the trailing 3204.Dq !\& ) , 3205then if the route already exists, it will be updated as with the 3206.Sq route change 3207command (see 3208.Xr route 8 3209for further details). 3210.Pp 3211Routes that contain the 3212.Dq HISADDR , 3213.Dq MYADDR , 3214.Dq HISADDR6 , 3215.Dq MYADDR6 , 3216.Dq DNS0 , 3217or 3218.Dq DNS1 3219constants are considered 3220.Sq sticky . 3221They are stored in a list (use 3222.Dq show ncp 3223to see the list), and each time the value of one of these variables 3224changes, the appropriate routing table entries are updated. 3225This facility may be disabled using 3226.Dq disable sroutes . 3227.It allow Ar command Op Ar args 3228This command controls access to 3229.Nm 3230and its configuration files. 3231It is possible to allow user-level access, 3232depending on the configuration file label and on the mode that 3233.Nm 3234is being run in. 3235For example, you may wish to configure 3236.Nm 3237so that only user 3238.Sq fred 3239may access label 3240.Sq fredlabel 3241in 3242.Fl background 3243mode. 3244.Pp 3245User id 0 is immune to these commands. 3246.Bl -tag -width 2n 3247.It allow user Ns Xo 3248.Op s 3249.Ar logname Ns No ... 3250.Xc 3251By default, only user id 0 is allowed access to 3252.Nm . 3253If this command is used, all of the listed users are allowed access to 3254the section in which the 3255.Dq allow users 3256command is found. 3257The 3258.Sq default 3259section is always checked first (even though it is only ever automatically 3260loaded at startup). 3261.Dq allow users 3262commands are cumulative in a given section, but users allowed in any given 3263section override users allowed in the default section, so it's possible to 3264allow users access to everything except a given label by specifying default 3265users in the 3266.Sq default 3267section, and then specifying a new user list for that label. 3268.Pp 3269If user 3270.Sq * 3271is specified, access is allowed to all users. 3272.It allow mode Ns Xo 3273.Op s 3274.Ar mode Ns No ... 3275.Xc 3276By default, access using any 3277.Nm 3278mode is possible. 3279If this command is used, it restricts the access 3280.Ar modes 3281allowed to load the label under which this command is specified. 3282Again, as with the 3283.Dq allow users 3284command, each 3285.Dq allow modes 3286command overrides any previous settings, and the 3287.Sq default 3288section is always checked first. 3289.Pp 3290Possible modes are: 3291.Sq interactive , 3292.Sq auto , 3293.Sq direct , 3294.Sq dedicated , 3295.Sq ddial , 3296.Sq background 3297and 3298.Sq * . 3299.Pp 3300When running in multi-link mode, a section can be loaded if it allows 3301.Em any 3302of the currently existing line modes. 3303.El 3304.Pp 3305.It nat Ar command Op Ar args 3306This command allows the control of the network address translation (also 3307known as masquerading or IP aliasing) facilities that are built into 3308.Nm . 3309NAT is done on the external interface only, and is unlikely to make sense 3310if used with the 3311.Fl direct 3312flag. 3313.Pp 3314If nat is enabled on your system (it may be omitted at compile time), 3315the following commands are possible: 3316.Bl -tag -width 2n 3317.It nat enable yes|no 3318This command either switches network address translation on or turns it off. 3319The 3320.Fl nat 3321command line flag is synonymous with 3322.Dq nat enable yes . 3323.It nat addr Op Ar addr_local addr_alias 3324This command allows data for 3325.Ar addr_alias 3326to be redirected to 3327.Ar addr_local . 3328It is useful if you own a small number of real IP numbers that 3329you wish to map to specific machines behind your gateway. 3330.It nat deny_incoming yes|no 3331If set to yes, this command will refuse all incoming packets where an 3332aliasing link doesn't already exist. 3333ifdef({LOCALNAT},{},{Refer to the 3334.Sx CONCEPTUAL BACKGROUND 3335section of 3336.Xr libalias 3 3337for a description of what an 3338.Dq aliasing link 3339is. 3340})dnl 3341.Pp 3342It should be noted under what circumstances an aliasing link is 3343ifdef({LOCALNAT},{created.},{created by 3344.Xr libalias 3 .}) 3345It may be necessary to further protect your network from outside 3346connections using the 3347.Dq set filter 3348or 3349.Dq nat target 3350commands. 3351.It nat help|? 3352This command gives a summary of available nat commands. 3353.It nat log yes|no 3354This option causes various NAT statistics and information to 3355be logged to the file 3356.Pa /var/log/alias.log . 3357.It nat port Ar proto Ar targetIP Ns Xo 3358.No : Ns Ar targetPort Ns 3359.Oo 3360.No - Ns Ar targetPort 3361.Oc Ar aliasPort Ns 3362.Oo 3363.No - Ns Ar aliasPort 3364.Oc Oo Ar remoteIP : Ns 3365.Ar remotePort Ns 3366.Oo 3367.No - Ns Ar remotePort 3368.Oc Ns 3369.Oc 3370.Xc 3371This command causes incoming 3372.Ar proto 3373connections to 3374.Ar aliasPort 3375to be redirected to 3376.Ar targetPort 3377on 3378.Ar targetIP . 3379.Ar proto 3380is either 3381.Dq tcp 3382or 3383.Dq udp . 3384.Pp 3385A range of port numbers may be specified as shown above. 3386The ranges must be of the same size. 3387.Pp 3388If 3389.Ar remoteIP 3390is specified, only data coming from that IP number is redirected. 3391.Ar remotePort 3392must either be 3393.Dq 0 3394(indicating any source port) 3395or a range of ports the same size as the other ranges. 3396.Pp 3397This option is useful if you wish to run things like Internet phone on 3398machines behind your gateway, but is limited in that connections to only 3399one interior machine per source machine and target port are possible. 3400.It nat proto Ar proto localIP Oo 3401.Ar publicIP Op Ar remoteIP 3402.Oc 3403This command tells 3404.Nm 3405to redirect packets of protocol type 3406.Ar proto 3407(see 3408.Xr protocols 5 ) 3409to the internall address 3410.Ar localIP . 3411.Pp 3412If 3413.Ar publicIP 3414is specified, only packets destined for that address are matched, 3415otherwise the default alias address is used. 3416.Pp 3417If 3418.Ar remoteIP 3419is specified, only packets matching that source address are matched, 3420.Pp 3421This command is useful for redirecting tunnel endpoints to an internal machine, 3422for example: 3423.Pp 3424.Dl nat proto ipencap 10.0.0.1 3425.It "nat proxy cmd" Ar arg Ns No ... 3426This command tells 3427.Nm 3428to proxy certain connections, redirecting them to a given server. 3429ifdef({LOCALNAT},{},{Refer to the description of 3430.Fn PacketAliasProxyRule 3431in 3432.Xr libalias 3 3433for details of the available commands. 3434})dnl 3435.It nat punch_fw Op Ar base count 3436This command tells 3437.Nm 3438to punch holes in the firewall for FTP or IRC DCC connections. 3439This is done dynamically by installing termporary firewall rules which 3440allow a particular connection (and only that connection) to go through 3441the firewall. 3442The rules are removed once the corresponding connection terminates. 3443.Pp 3444A maximum of 3445.Ar count 3446rules starting from rule number 3447.Ar base 3448will be used for punching firewall holes. 3449The range will be cleared when the 3450.Dq nat punch_fw 3451command is run. 3452.Pp 3453If no arguments are given, firewall punching is disabled. 3454.It nat same_ports yes|no 3455When enabled, this command will tell the network address translation engine to 3456attempt to avoid changing the port number on outgoing packets. 3457This is useful 3458if you want to support protocols such as RPC and LPD which require 3459connections to come from a well known port. 3460.It nat target Op Ar address 3461Set the given target address or clear it if no address is given. 3462The target address is used 3463ifdef({LOCALNAT},{},{by libalias })dnl 3464to specify how to NAT incoming packets by default. 3465If a target address is not set or if 3466.Dq default 3467is given, packets are not altered and are allowed to route to the internal 3468network. 3469.Pp 3470The target address may be set to 3471.Dq MYADDR , 3472in which case 3473ifdef({LOCALNAT},{all packets will be redirected}, 3474{libalias will redirect all packets}) 3475to the interface address. 3476.It nat use_sockets yes|no 3477When enabled, this option tells the network address translation engine to 3478create a socket so that it can guarantee a correct incoming ftp data or 3479IRC connection. 3480.It nat unregistered_only yes|no 3481Only alter outgoing packets with an unregistered source address. 3482According to RFC 1918, unregistered source addresses 3483are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16. 3484.El 3485.Pp 3486These commands are also discussed in the file 3487.Pa README.nat 3488which comes with the source distribution. 3489.Pp 3490.It Op !\& Ns Xo 3491.No bg Ar command 3492.Xc 3493The given 3494.Ar command 3495is executed in the background with the following words replaced: 3496.Bl -tag -width PEER_ENDDISC 3497.It Li AUTHNAME 3498This is replaced with the local 3499.Ar authname 3500value. 3501See the 3502.Dq set authname 3503command below. 3504.It Li COMPILATIONDATE 3505This is replaced with the date on which 3506.Nm 3507was compiled. 3508.It Li DNS0 & DNS1 3509These are replaced with the primary and secondary nameserver IP numbers. 3510If nameservers are negotiated by IPCP, the values of these macros will change. 3511.It Li ENDDISC 3512This is replaced with the local endpoint discriminator value. 3513See the 3514.Dq set enddisc 3515command below. 3516.It Li HISADDR 3517This is replaced with the peers IP number. 3518.It Li HISADDR6 3519This is replaced with the peers IPv6 number. 3520.It Li INTERFACE 3521This is replaced with the name of the interface that's in use. 3522.It Li LABEL 3523This is replaced with the last label name used. 3524A label may be specified on the 3525.Nm 3526command line, via the 3527.Dq load 3528or 3529.Dq dial 3530commands and in the 3531.Pa ppp.secret 3532file. 3533.It Li MYADDR 3534This is replaced with the IP number assigned to the local interface. 3535.It Li MYADDR6 3536This is replaced with the IPv6 number assigned to the local interface. 3537.It Li PEER_ENDDISC 3538This is replaced with the value of the peers endpoint discriminator. 3539.It Li PROCESSID 3540This is replaced with the current process id. 3541.It Li VERSION 3542This is replaced with the current version number of 3543.Nm . 3544.It Li UPTIME 3545This is replaced with the bundle uptime in HH:MM:SS format. 3546.It Li USER 3547This is replaced with the username that has been authenticated with PAP or 3548CHAP. 3549Normally, this variable is assigned only in -direct mode. 3550This value is available irrespective of whether utmp logging is enabled. 3551.El 3552.Pp 3553These substitutions are also done by the 3554.Dq set proctitle , 3555.Dq ident 3556and 3557.Dq log 3558commands. 3559.Pp 3560If you wish to pause 3561.Nm 3562while the command executes, use the 3563.Dq shell 3564command instead. 3565.It clear physical|ipcp|ipv6 Op current|overall|peak... 3566Clear the specified throughput values at either the 3567.Dq physical , 3568.Dq ipcp 3569or 3570.Dq ipv6cp 3571level. 3572If 3573.Dq physical 3574is specified, context must be given (see the 3575.Dq link 3576command below). 3577If no second argument is given, all values are cleared. 3578.It clone Ar name Ns Xo 3579.Op \&, Ns Ar name Ns 3580.No ... 3581.Xc 3582Clone the specified link, creating one or more new links according to the 3583.Ar name 3584argument(s). 3585This command must be used from the 3586.Dq link 3587command below unless you've only got a single link (in which case that 3588link becomes the default). 3589Links may be removed using the 3590.Dq remove 3591command below. 3592.Pp 3593The default link name is 3594.Dq deflink . 3595.It close Op lcp|ccp Ns Op !\& 3596If no arguments are given, the relevant protocol layers will be brought 3597down and the link will be closed. 3598If 3599.Dq lcp 3600is specified, the LCP layer is brought down, but 3601.Nm 3602will not bring the link offline. 3603It is subsequently possible to use 3604.Dq term 3605(see below) 3606to talk to the peer machine if, for example, something like 3607.Dq slirp 3608is being used. 3609If 3610.Dq ccp 3611is specified, only the relevant compression layer is closed. 3612If the 3613.Dq !\& 3614is used, the compression layer will remain in the closed state, otherwise 3615it will re-enter the STOPPED state, waiting for the peer to initiate 3616further CCP negotiation. 3617In any event, this command does not disconnect the user from 3618.Nm 3619or exit 3620.Nm . 3621See the 3622.Dq quit 3623command below. 3624.It delete Ns Xo 3625.Op !\& 3626.Ar dest 3627.Xc 3628This command deletes the route with the given 3629.Ar dest 3630IP address. 3631If 3632.Ar dest 3633is specified as 3634.Sq ALL , 3635all non-direct entries in the routing table for the current interface, 3636and all 3637.Sq sticky route 3638entries are deleted. 3639If 3640.Ar dest 3641is specified as 3642.Sq default , 3643the default route is deleted. 3644.Pp 3645If the 3646.Ar delete!\& 3647command is used 3648(note the trailing 3649.Dq !\& ) , 3650.Nm 3651will not complain if the route does not already exist. 3652.It dial|call Op Ar label Ns Xo 3653.No ... 3654.Xc 3655This command is the equivalent of 3656.Dq load label 3657followed by 3658.Dq open , 3659and is provided for backwards compatibility. 3660.It down Op Ar lcp|ccp 3661Bring the relevant layer down ungracefully, as if the underlying layer 3662had become unavailable. 3663It's not considered polite to use this command on 3664a Finite State Machine that's in the OPEN state. 3665If no arguments are 3666supplied, the entire link is closed (or if no context is given, all links 3667are terminated). 3668If 3669.Sq lcp 3670is specified, the 3671.Em LCP 3672layer is terminated but the device is not brought offline and the link 3673is not closed. 3674If 3675.Sq ccp 3676is specified, only the relevant compression layer(s) are terminated. 3677.It help|? Op Ar command 3678Show a list of available commands. 3679If 3680.Ar command 3681is specified, show the usage string for that command. 3682.It ident Op Ar text Ns No ... 3683Identify the link to the peer using 3684.Ar text . 3685If 3686.Ar text 3687is empty, link identification is disabled. 3688It is possible to use any of the words described for the 3689.Ic bg 3690command above. 3691Refer to the 3692.Ic sendident 3693command for details of when 3694.Nm 3695identifies itself to the peer. 3696.It iface Ar command Op args 3697This command is used to control the interface used by 3698.Nm . 3699.Ar Command 3700may be one of the following: 3701.Bl -tag -width 2n 3702.It iface add Ns Xo 3703.Op !\& 3704.Ar addr Ns Op / Ns Ar bits 3705.Op Ar peer 3706.Xc 3707.It iface add Ns Xo 3708.Op !\& 3709.Ar addr 3710.Ar mask 3711.Ar peer 3712.Xc 3713Add the given 3714.Ar addr mask peer 3715combination to the interface. 3716Instead of specifying 3717.Ar mask , 3718.Ar /bits 3719can be used 3720(with no space between it and 3721.Ar addr ) . 3722If the given address already exists, the command fails unless the 3723.Dq !\& 3724is used - in which case the previous interface address entry is overwritten 3725with the new one, allowing a change of netmask or peer address. 3726.Pp 3727If only 3728.Ar addr 3729is specified, 3730.Ar bits 3731defaults to 3732.Dq 32 3733and 3734.Ar peer 3735defaults to 3736.Dq 255.255.255.255 . 3737This address (the broadcast address) is the only duplicate peer address that 3738.Nm 3739allows. 3740.It iface clear Op INET | INET6 3741If this command is used while 3742.Nm 3743is in the OPENED state or while in 3744.Fl auto 3745mode, all addresses except for the NCP negotiated address are deleted 3746from the interface. 3747If 3748.Nm 3749is not in the OPENED state and is not in 3750.Fl auto 3751mode, all interface addresses are deleted. 3752.Pp 3753If the INET or INET6 arguments are used, only addresses for that address 3754family are cleared. 3755.Pp 3756.It iface delete Ns Xo 3757.Op !\& Ns 3758.No |rm Ns Op !\& 3759.Ar addr 3760.Xc 3761This command deletes the given 3762.Ar addr 3763from the interface. 3764If the 3765.Dq !\& 3766is used, no error is given if the address isn't currently assigned to 3767the interface (and no deletion takes place). 3768.It iface show 3769Shows the current state and current addresses for the interface. 3770It is much the same as running 3771.Dq ifconfig INTERFACE . 3772.It iface help Op Ar sub-command 3773This command, when invoked without 3774.Ar sub-command , 3775will show a list of possible 3776.Dq iface 3777sub-commands and a brief synopsis for each. 3778When invoked with 3779.Ar sub-command , 3780only the synopsis for the given sub-command is shown. 3781.El 3782.It Op data Ns Xo 3783.No link 3784.Ar name Ns Op , Ns Ar name Ns 3785.No ... Ar command Op Ar args 3786.Xc 3787This command may prefix any other command if the user wishes to 3788specify which link the command should affect. 3789This is only applicable after multiple links have been created in Multi-link 3790mode using the 3791.Dq clone 3792command. 3793.Pp 3794.Ar Name 3795specifies the name of an existing link. 3796If 3797.Ar name 3798is a comma separated list, 3799.Ar command 3800is executed on each link. 3801If 3802.Ar name 3803is 3804.Dq * , 3805.Ar command 3806is executed on all links. 3807.It load Op Ar label Ns Xo 3808.No ... 3809.Xc 3810Load the given 3811.Ar label Ns No (s) 3812from the 3813.Pa ppp.conf 3814file. 3815If 3816.Ar label 3817is not given, the 3818.Ar default 3819label is used. 3820.Pp 3821Unless the 3822.Ar label 3823section uses the 3824.Dq set mode , 3825.Dq open 3826or 3827.Dq dial 3828commands, 3829.Nm 3830will not attempt to make an immediate connection. 3831.It log Ar word Op Ar word Ns No ... 3832Send the given word(s) to the log file with the prefix 3833.Dq LOG: . 3834Word substitutions are done as explained under the 3835.Dq !bg 3836command above. 3837.It open Op lcp|ccp|ipcp 3838This is the opposite of the 3839.Dq close 3840command. 3841All closed links are immediately brought up apart from second and subsequent 3842.Ar demand-dial 3843links - these will come up based on the 3844.Dq set autoload 3845command that has been used. 3846.Pp 3847If the 3848.Dq lcp 3849argument is used while the LCP layer is already open, LCP will be 3850renegotiated. 3851This allows various LCP options to be changed, after which 3852.Dq open lcp 3853can be used to put them into effect. 3854After renegotiating LCP, 3855any agreed authentication will also take place. 3856.Pp 3857If the 3858.Dq ccp 3859argument is used, the relevant compression layer is opened. 3860Again, if it is already open, it will be renegotiated. 3861.Pp 3862If the 3863.Dq ipcp 3864argument is used, the link will be brought up as normal, but if 3865IPCP is already open, it will be renegotiated and the network 3866interface will be reconfigured. 3867.Pp 3868It is probably not good practice to re-open the PPP state machines 3869like this as it's possible that the peer will not behave correctly. 3870It 3871.Em is 3872however useful as a way of forcing the CCP or VJ dictionaries to be reset. 3873.It passwd Ar pass 3874Specify the password required for access to the full 3875.Nm 3876command set. 3877This password is required when connecting to the diagnostic port (see the 3878.Dq set server 3879command). 3880.Ar Pass 3881is specified on the 3882.Dq set server 3883command line. 3884The value of 3885.Ar pass 3886is not logged when 3887.Ar command 3888logging is active, instead, the literal string 3889.Sq ******** 3890is logged. 3891.It quit|bye Op all 3892If 3893.Dq quit 3894is executed from the controlling connection or from a command file, 3895ppp will exit after closing all connections. 3896Otherwise, if the user 3897is connected to a diagnostic socket, the connection is simply dropped. 3898.Pp 3899If the 3900.Ar all 3901argument is given, 3902.Nm 3903will exit despite the source of the command after closing all existing 3904connections. 3905.It remove|rm 3906This command removes the given link. 3907It is only really useful in multi-link mode. 3908A link must be in the 3909.Dv CLOSED 3910state before it is removed. 3911.It rename|mv Ar name 3912This command renames the given link to 3913.Ar name . 3914It will fail if 3915.Ar name 3916is already used by another link. 3917.Pp 3918The default link name is 3919.Sq deflink . 3920Renaming it to 3921.Sq modem , 3922.Sq cuaa0 3923or 3924.Sq USR 3925may make the log file more readable. 3926.It resolv Ar command 3927This command controls 3928.Nm Ns No 's 3929manipulation of the 3930.Xr resolv.conf 5 3931file. 3932When 3933.Nm 3934starts up, it loads the contents of this file into memory and retains this 3935image for future use. 3936.Ar command 3937is one of the following: 3938.Bl -tag -width readonly 3939.It Em readonly 3940Treat 3941.Pa /etc/resolv.conf 3942as read only. 3943If 3944.Dq dns 3945is enabled, 3946.Nm 3947will still attempt to negotiate nameservers with the peer, making the results 3948available via the 3949.Dv DNS0 3950and 3951.Dv DNS1 3952macros. 3953This is the opposite of the 3954.Dq resolv writable 3955command. 3956.It Em reload 3957Reload 3958.Pa /etc/resolv.conf 3959into memory. 3960This may be necessary if for example a DHCP client overwrote 3961.Pa /etc/resolv.conf . 3962.It Em restore 3963Replace 3964.Pa /etc/resolv.conf 3965with the version originally read at startup or with the last 3966.Dq resolv reload 3967command. 3968This is sometimes a useful command to put in the 3969.Pa /etc/ppp/ppp.linkdown 3970file. 3971.It Em rewrite 3972Rewrite the 3973.Pa /etc/resolv.conf 3974file. 3975This command will work even if the 3976.Dq resolv readonly 3977command has been used. 3978It may be useful as a command in the 3979.Pa /etc/ppp/ppp.linkup 3980file if you wish to defer updating 3981.Pa /etc/resolv.conf 3982until after other commands have finished. 3983.It Em writable 3984Allow 3985.Nm 3986to update 3987.Pa /etc/resolv.conf 3988if 3989.Dq dns 3990is enabled and 3991.Nm 3992successfully negotiates a DNS. 3993This is the opposite of the 3994.Dq resolv readonly 3995command. 3996.El 3997.It save 3998This option is not (yet) implemented. 3999.It sendident 4000This command tells 4001.Nm 4002to identify itself to the peer. 4003The link must be in LCP state or higher. 4004If no identity has been set (via the 4005.Ic ident 4006command), 4007.Ic sendident 4008will fail. 4009.Pp 4010When an identity has been set, 4011.Nm 4012will automatically identify itself when it sends or receives a configure 4013reject, when negotiation fails or when LCP reaches the opened state. 4014.Pp 4015Received identification packets are logged to the LCP log (see 4016.Ic set log 4017for details) and are never responded to. 4018.It set Ns Xo 4019.Op up 4020.Ar var value 4021.Xc 4022This option allows the setting of any of the following variables: 4023.Bl -tag -width 2n 4024.It set accmap Ar hex-value 4025ACCMap stands for Asynchronous Control Character Map. 4026This is always 4027negotiated with the peer, and defaults to a value of 00000000 in hex. 4028This protocol is required to defeat hardware that depends on passing 4029certain characters from end to end (such as XON/XOFF etc). 4030.Pp 4031For the XON/XOFF scenario, use 4032.Dq set accmap 000a0000 . 4033.It set Op auth Ns Xo 4034.No key Ar value 4035.Xc 4036This sets the authentication key (or password) used in client mode 4037PAP or CHAP negotiation to the given value. 4038It also specifies the 4039password to be used in the dial or login scripts in place of the 4040.Sq \eP 4041sequence, preventing the actual password from being logged. 4042If 4043.Ar command 4044or 4045.Ar chat 4046logging is in effect, 4047.Ar value 4048is logged as 4049.Sq ******** 4050for security reasons. 4051.Pp 4052If the first character of 4053.Ar value 4054is an exclamation mark 4055.Pq Dq !\& , 4056.Nm 4057treats the remainder of the string as a program that must be executed 4058to determine the 4059.Dq authname 4060and 4061.Dq authkey 4062values. 4063.Pp 4064If the 4065.Dq !\& 4066is doubled up 4067(to 4068.Dq !! ) , 4069it is treated as a single literal 4070.Dq !\& , 4071otherwise, ignoring the 4072.Dq !\& , 4073.Ar value 4074is parsed as a program to execute in the same was as the 4075.Dq !bg 4076command above, substituting special names in the same manner. 4077Once executed, 4078.Nm 4079will feed the program three lines of input, each terminated by a newline 4080character: 4081.Bl -bullet 4082.It 4083The host name as sent in the CHAP challenge. 4084.It 4085The challenge string as sent in the CHAP challenge. 4086.It 4087The locally defined 4088.Dq authname . 4089.El 4090.Pp 4091Two lines of output are expected: 4092.Bl -bullet 4093.It 4094The 4095.Dq authname 4096to be sent with the CHAP response. 4097.It 4098The 4099.Dq authkey , 4100which is encrypted with the challenge and request id, the answer being sent 4101in the CHAP response packet. 4102.El 4103.Pp 4104When configuring 4105.Nm 4106in this manner, it's expected that the host challenge is a series of ASCII 4107digits or characters. 4108An encryption device or Secure ID card is usually 4109required to calculate the secret appropriate for the given challenge. 4110.It set authname Ar id 4111This sets the authentication id used in client mode PAP or CHAP negotiation. 4112.Pp 4113If used in 4114.Fl direct 4115mode with CHAP enabled, 4116.Ar id 4117is used in the initial authentication challenge and should normally be set to 4118the local machine name. 4119.It set autoload Xo 4120.Ar min-percent max-percent period 4121.Xc 4122These settings apply only in multi-link mode and default to zero, zero and 4123five respectively. 4124When more than one 4125.Ar demand-dial 4126(also known as 4127.Fl auto ) 4128mode link is available, only the first link is made active when 4129.Nm 4130first reads data from the tun device. 4131The next 4132.Ar demand-dial 4133link will be opened only when the current bundle throughput is at least 4134.Ar max-percent 4135percent of the total bundle bandwidth for 4136.Ar period 4137seconds. 4138When the current bundle throughput decreases to 4139.Ar min-percent 4140percent or less of the total bundle bandwidth for 4141.Ar period 4142seconds, a 4143.Ar demand-dial 4144link will be brought down as long as it's not the last active link. 4145.Pp 4146Bundle throughput is measured as the maximum of inbound and outbound 4147traffic. 4148.Pp 4149The default values cause 4150.Ar demand-dial 4151links to simply come up one at a time. 4152.Pp 4153Certain devices cannot determine their physical bandwidth, so it 4154is sometimes necessary to use the 4155.Dq set bandwidth 4156command (described below) to make 4157.Dq set autoload 4158work correctly. 4159.It set bandwidth Ar value 4160This command sets the connection bandwidth in bits per second. 4161.Ar value 4162must be greater than zero. 4163It is currently only used by the 4164.Dq set autoload 4165command above. 4166.It set callback Ar option Ns No ... 4167If no arguments are given, callback is disabled, otherwise, 4168.Nm 4169will request (or in 4170.Fl direct 4171mode, will accept) one of the given 4172.Ar option Ns No s . 4173In client mode, if an 4174.Ar option 4175is NAK'd 4176.Nm 4177will request a different 4178.Ar option , 4179until no options remain at which point 4180.Nm 4181will terminate negotiations (unless 4182.Dq none 4183is one of the specified 4184.Ar option ) . 4185In server mode, 4186.Nm 4187will accept any of the given protocols - but the client 4188.Em must 4189request one of them. 4190If you wish callback to be optional, you must {include} 4191.Ar none 4192as an option. 4193.Pp 4194The 4195.Ar option Ns No s 4196are as follows (in this order of preference): 4197.Pp 4198.Bl -tag -width Ds 4199.It auth 4200The callee is expected to decide the callback number based on 4201authentication. 4202If 4203.Nm 4204is the callee, the number should be specified as the fifth field of 4205the peers entry in 4206.Pa /etc/ppp/ppp.secret . 4207.It cbcp 4208Microsoft's callback control protocol is used. 4209See 4210.Dq set cbcp 4211below. 4212.Pp 4213If you wish to negotiate 4214.Ar cbcp 4215in client mode but also wish to allow the server to request no callback at 4216CBCP negotiation time, you must specify both 4217.Ar cbcp 4218and 4219.Ar none 4220as callback options. 4221.It E.164 *| Ns Xo 4222.Ar number Ns Op , Ns Ar number Ns 4223.No ... 4224.Xc 4225The caller specifies the 4226.Ar number . 4227If 4228.Nm 4229is the callee, 4230.Ar number 4231should be either a comma separated list of allowable numbers or a 4232.Dq \&* , 4233meaning any number is permitted. 4234If 4235.Nm 4236is the caller, only a single number should be specified. 4237.Pp 4238Note, this option is very unsafe when used with a 4239.Dq \&* 4240as a malicious caller can tell 4241.Nm 4242to call any (possibly international) number without first authenticating 4243themselves. 4244.It none 4245If the peer does not wish to do callback at all, 4246.Nm 4247will accept the fact and continue without callback rather than terminating 4248the connection. 4249This is required (in addition to one or more other callback 4250options) if you wish callback to be optional. 4251.El 4252.Pp 4253.It set cbcp Oo 4254.No *| Ns Ar number Ns Oo 4255.No , Ns Ar number Ns ...\& Oc 4256.Op Ar delay Op Ar retry 4257.Oc 4258If no arguments are given, CBCP (Microsoft's CallBack Control Protocol) 4259is disabled - ie, configuring CBCP in the 4260.Dq set callback 4261command will result in 4262.Nm 4263requesting no callback in the CBCP phase. 4264Otherwise, 4265.Nm 4266attempts to use the given phone 4267.Ar number Ns No (s). 4268.Pp 4269In server mode 4270.Pq Fl direct , 4271.Nm 4272will insist that the client uses one of these numbers, unless 4273.Dq \&* 4274is used in which case the client is expected to specify the number. 4275.Pp 4276In client mode, 4277.Nm 4278will attempt to use one of the given numbers (whichever it finds to 4279be agreeable with the peer), or if 4280.Dq \&* 4281is specified, 4282.Nm 4283will expect the peer to specify the number. 4284.It set cd Oo 4285.No off| Ns Ar seconds Ns Op !\& 4286.Oc 4287Normally, 4288.Nm 4289checks for the existence of carrier depending on the type of device 4290that has been opened: 4291.Bl -tag -width XXX -offset XXX 4292.It Terminal Devices 4293Carrier is checked one second after the login script is complete. 4294If it's not set, 4295.Nm 4296assumes that this is because the device doesn't support carrier (which 4297is true for most 4298.Dq laplink 4299NULL-modem cables), logs the fact and stops checking 4300for carrier. 4301.Pp 4302As ptys don't support the TIOCMGET ioctl, the tty device will switch all 4303carrier detection off when it detects that the device is a pty. 4304.It ISDN (i4b) Devices 4305Carrier is checked once per second for 6 seconds. 4306If it's not set after 4307the sixth second, the connection attempt is considered to have failed and 4308the device is closed. 4309Carrier is always required for i4b devices. 4310.It PPPoE (netgraph) Devices 4311Carrier is checked once per second for 5 seconds. 4312If it's not set after 4313the fifth second, the connection attempt is considered to have failed and 4314the device is closed. 4315Carrier is always required for PPPoE devices. 4316.El 4317.Pp 4318All other device types don't support carrier. 4319Setting a carrier value will 4320result in a warning when the device is opened. 4321.Pp 4322Some modems take more than one second after connecting to assert the carrier 4323signal. 4324If this delay isn't increased, this will result in 4325.Nm Ns No 's 4326inability to detect when the link is dropped, as 4327.Nm 4328assumes that the device isn't asserting carrier. 4329.Pp 4330The 4331.Dq set cd 4332command overrides the default carrier behaviour. 4333.Ar seconds 4334specifies the maximum number of seconds that 4335.Nm 4336should wait after the dial script has finished before deciding if 4337carrier is available or not. 4338.Pp 4339If 4340.Dq off 4341is specified, 4342.Nm 4343will not check for carrier on the device, otherwise 4344.Nm 4345will not proceed to the login script until either carrier is detected 4346or until 4347.Ar seconds 4348has elapsed, at which point 4349.Nm 4350assumes that the device will not set carrier. 4351.Pp 4352If no arguments are given, carrier settings will go back to their default 4353values. 4354.Pp 4355If 4356.Ar seconds 4357is followed immediately by an exclamation mark 4358.Pq Dq !\& , 4359.Nm 4360will 4361.Em require 4362carrier. 4363If carrier is not detected after 4364.Ar seconds 4365seconds, the link will be disconnected. 4366.It set choked Op Ar timeout 4367This sets the number of seconds that 4368.Nm 4369will keep a choked output queue before dropping all pending output packets. 4370If 4371.Ar timeout 4372is less than or equal to zero or if 4373.Ar timeout 4374isn't specified, it is set to the default value of 4375.Em 120 seconds . 4376.Pp 4377A choked output queue occurs when 4378.Nm 4379has read a certain number of packets from the local network for transmission, 4380but cannot send the data due to link failure (the peer is busy etc.). 4381.Nm 4382will not read packets indefinitely. 4383Instead, it reads up to 4384.Em 30 4385packets (or 4386.Em 30 No + 4387.Em nlinks No * 4388.Em 2 4389packets in multi-link mode), then stops reading the network interface 4390until either 4391.Ar timeout 4392seconds have passed or at least one packet has been sent. 4393.Pp 4394If 4395.Ar timeout 4396seconds pass, all pending output packets are dropped. 4397.It set ctsrts|crtscts on|off 4398This sets hardware flow control. 4399Hardware flow control is 4400.Ar on 4401by default. 4402.It set deflate Ar out-winsize Op Ar in-winsize 4403This sets the DEFLATE algorithms default outgoing and incoming window 4404sizes. 4405Both 4406.Ar out-winsize 4407and 4408.Ar in-winsize 4409must be values between 4410.Em 8 4411and 4412.Em 15 . 4413If 4414.Ar in-winsize 4415is specified, 4416.Nm 4417will insist that this window size is used and will not accept any other 4418values from the peer. 4419.It set dns Op Ar primary Op Ar secondary 4420This command specifies DNS overrides for the 4421.Dq accept dns 4422command. 4423Refer to the 4424.Dq accept 4425command description above for details. 4426This command does not affect the IP numbers requested using 4427.Dq enable dns . 4428.It set device|line Xo 4429.Ar value Ns No ... 4430.Xc 4431This sets the device(s) to which 4432.Nm 4433will talk to the given 4434.Dq value . 4435.Pp 4436All ISDN and serial device names are expected to begin with 4437.Pa /dev/ . 4438ISDN devices are usually called 4439.Pa i4brbchX 4440and serial devices are usually called 4441.Pa cuaXX . 4442.Pp 4443If 4444.Dq value 4445does not begin with 4446.Pa /dev/ , 4447it must either begin with an exclamation mark 4448.Pq Dq !\& , 4449be of the format 4450.No PPPoE: Ns Ar iface Ns Xo 4451.Op \&: Ns Ar provider Ns 4452.Xc 4453(on 4454.Xr netgraph 4 4455enabled systems), or be of the format 4456.Sm off 4457.Ar host : port Op /tcp|udp . 4458.Sm on 4459.Pp 4460If it begins with an exclamation mark, the rest of the device name is 4461treated as a program name, and that program is executed when the device 4462is opened. 4463Standard input, output and error are fed back to 4464.Nm 4465and are read and written as if they were a regular device. 4466.Pp 4467If a 4468.No PPPoE: Ns Ar iface Ns Xo 4469.Op \&: Ns Ar provider Ns 4470.Xc 4471specification is given, 4472.Nm 4473will attempt to create a 4474.Em PPP 4475over Ethernet connection using the given 4476.Ar iface 4477interface by using 4478.Xr netgraph 4 . 4479If 4480.Xr netgraph 4 4481is not available, 4482.Nm 4483will attempt to load it using 4484.Xr kldload 2 . 4485If this fails, an external program must be used such as the 4486.Xr pppoe 8 4487program available under 4488.Ox . 4489The given 4490.Ar provider 4491is passed as the service name in the PPPoE Discovery Initiation (PADI) 4492packet. 4493If no provider is given, an empty value will be used. 4494Refer to 4495.Xr netgraph 4 4496and 4497.Xr ng_pppoe 4 4498for further details. 4499.Pp 4500If a 4501.Ar host Ns No : Ns Ar port Ns Oo 4502.No /tcp|udp 4503.Oc 4504specification is given, 4505.Nm 4506will attempt to connect to the given 4507.Ar host 4508on the given 4509.Ar port . 4510If a 4511.Dq /tcp 4512or 4513.Dq /udp 4514suffix is not provided, the default is 4515.Dq /tcp . 4516Refer to the section on 4517.Em PPP OVER TCP and UDP 4518above for further details. 4519.Pp 4520If multiple 4521.Dq values 4522are specified, 4523.Nm 4524will attempt to open each one in turn until it succeeds or runs out of 4525devices. 4526.It set dial Ar chat-script 4527This specifies the chat script that will be used to dial the other 4528side. 4529See also the 4530.Dq set login 4531command below. 4532Refer to 4533.Xr chat 8 4534and to the example configuration files for details of the chat script 4535format. 4536It is possible to specify some special 4537.Sq values 4538in your chat script as follows: 4539.Bl -tag -width 2n 4540.It Li \ec 4541When used as the last character in a 4542.Sq send 4543string, this indicates that a newline should not be appended. 4544.It Li \ed 4545When the chat script encounters this sequence, it delays two seconds. 4546.It Li \ep 4547When the chat script encounters this sequence, it delays for one quarter of 4548a second. 4549.It Li \en 4550This is replaced with a newline character. 4551.It Li \er 4552This is replaced with a carriage return character. 4553.It Li \es 4554This is replaced with a space character. 4555.It Li \et 4556This is replaced with a tab character. 4557.It Li \eT 4558This is replaced by the current phone number (see 4559.Dq set phone 4560below). 4561.It Li \eP 4562This is replaced by the current 4563.Ar authkey 4564value (see 4565.Dq set authkey 4566above). 4567.It Li \eU 4568This is replaced by the current 4569.Ar authname 4570value (see 4571.Dq set authname 4572above). 4573.El 4574.Pp 4575Note that two parsers will examine these escape sequences, so in order to 4576have the 4577.Sq chat parser 4578see the escape character, it is necessary to escape it from the 4579.Sq command parser . 4580This means that in practice you should use two escapes, for example: 4581.Bd -literal -offset indent 4582set dial "... ATDT\\\\T CONNECT" 4583.Ed 4584.Pp 4585It is also possible to execute external commands from the chat script. 4586To do this, the first character of the expect or send string is an 4587exclamation mark 4588.Pq Dq !\& . 4589If a literal exclamation mark is required, double it up to 4590.Dq !!\& 4591and it will be treated as a single literal 4592.Dq !\& . 4593When the command is executed, standard input and standard output are 4594directed to the open device (see the 4595.Dq set device 4596command), and standard error is read by 4597.Nm 4598and substituted as the expect or send string. 4599If 4600.Nm 4601is running in interactive mode, file descriptor 3 is attached to 4602.Pa /dev/tty . 4603.Pp 4604For example (wrapped for readability): 4605.Bd -literal -offset indent 4606set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e 4607word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e 4608\\"!/bin/echo in\\" HELLO" 4609.Ed 4610.Pp 4611would result in the following chat sequence (output using the 4612.Sq set log local chat 4613command before dialing): 4614.Bd -literal -offset indent 4615Dial attempt 1 of 1 4616dial OK! 4617Chat: Expecting: 4618Chat: Sending: 4619Chat: Expecting: login:--login: 4620Chat: Wait for (5): login: 4621Chat: Sending: ppp 4622Chat: Expecting: word: 4623Chat: Wait for (5): word: 4624Chat: Sending: ppp 4625Chat: Expecting: !sh \\-c "echo \\-n label: >&2" 4626Chat: Exec: sh -c "echo -n label: >&2" 4627Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label: 4628Chat: Exec: /bin/echo in 4629Chat: Sending: 4630Chat: Expecting: HELLO 4631Chat: Wait for (5): HELLO 4632login OK! 4633.Ed 4634.Pp 4635Note (again) the use of the escape character, allowing many levels of 4636nesting. 4637Here, there are four parsers at work. 4638The first parses the original line, reading it as three arguments. 4639The second parses the third argument, reading it as 11 arguments. 4640At this point, it is 4641important that the 4642.Dq \&- 4643signs are escaped, otherwise this parser will see them as constituting 4644an expect-send-expect sequence. 4645When the 4646.Dq !\& 4647character is seen, the execution parser reads the first command as three 4648arguments, and then 4649.Xr sh 1 4650itself expands the argument after the 4651.Fl c . 4652As we wish to send the output back to the modem, in the first example 4653we redirect our output to file descriptor 2 (stderr) so that 4654.Nm 4655itself sends and logs it, and in the second example, we just output to stdout, 4656which is attached directly to the modem. 4657.Pp 4658This, of course means that it is possible to execute an entirely external 4659.Dq chat 4660command rather than using the internal one. 4661See 4662.Xr chat 8 4663for a good alternative. 4664.Pp 4665The external command that is executed is subjected to the same special 4666word expansions as the 4667.Dq !bg 4668command. 4669.It set enddisc Op label|IP|MAC|magic|psn value 4670This command sets our local endpoint discriminator. 4671If set prior to LCP negotiation, and if no 4672.Dq disable enddisc 4673command has been used, 4674.Nm 4675will send the information to the peer using the LCP endpoint discriminator 4676option. 4677The following discriminators may be set: 4678.Bl -tag -width indent 4679.It Li label 4680The current label is used. 4681.It Li IP 4682Our local IP number is used. 4683As LCP is negotiated prior to IPCP, it is 4684possible that the IPCP layer will subsequently change this value. 4685If 4686it does, the endpoint discriminator stays at the old value unless manually 4687reset. 4688.It Li MAC 4689This is similar to the 4690.Ar IP 4691option above, except that the MAC address associated with the local IP 4692number is used. 4693If the local IP number is not resident on any Ethernet 4694interface, the command will fail. 4695.Pp 4696As the local IP number defaults to whatever the machine host name is, 4697.Dq set enddisc mac 4698is usually done prior to any 4699.Dq set ifaddr 4700commands. 4701.It Li magic 4702A 20 digit random number is used. 4703Care should be taken when using magic numbers as restarting 4704.Nm 4705or creating a link using a different 4706.Nm 4707invocation will also use a different magic number and will therefore not 4708be recognised by the peer as belonging to the same bundle. 4709This makes it unsuitable for 4710.Fl direct 4711connections. 4712.It Li psn Ar value 4713The given 4714.Ar value 4715is used. 4716.Ar Value 4717should be set to an absolute public switched network number with the 4718country code first. 4719.El 4720.Pp 4721If no arguments are given, the endpoint discriminator is reset. 4722.It set escape Ar value... 4723This option is similar to the 4724.Dq set accmap 4725option above. 4726It allows the user to specify a set of characters that will be 4727.Sq escaped 4728as they travel across the link. 4729.It set filter dial|alive|in|out Ar rule-no Xo 4730.No permit|deny|clear| Ns Ar rule-no 4731.Op !\& 4732.Oo Op host 4733.Ar src_addr Ns Op / Ns Ar width 4734.Op Ar dst_addr Ns Op / Ns Ar width 4735.Oc [ Ns Ar proto 4736.Op src lt|eq|gt Ar port 4737.Op dst lt|eq|gt Ar port 4738.Op estab 4739.Op syn 4740.Op finrst 4741.Op timeout Ar secs ] 4742.Xc 4743.Nm 4744supports four filter sets. 4745The 4746.Em alive 4747filter specifies packets that keep the connection alive - resetting the 4748idle timer. 4749The 4750.Em dial 4751filter specifies packets that cause 4752.Nm 4753to dial when in 4754.Fl auto 4755mode. 4756The 4757.Em in 4758filter specifies packets that are allowed to travel 4759into the machine and the 4760.Em out 4761filter specifies packets that are allowed out of the machine. 4762.Pp 4763Filtering is done prior to any IP alterations that might be done by the 4764NAT engine on outgoing packets and after any IP alterations that might 4765be done by the NAT engine on incoming packets. 4766By default all empty filter sets allow all packets to pass. 4767Rules are processed in order according to 4768.Ar rule-no 4769(unless skipped by specifying a rule number as the 4770.Ar action ) . 4771Up to 40 rules may be given for each set. 4772If a packet doesn't match 4773any of the rules in a given set, it is discarded. 4774In the case of 4775.Em in 4776and 4777.Em out 4778filters, this means that the packet is dropped. 4779In the case of 4780.Em alive 4781filters it means that the packet will not reset the idle timer (even if 4782the 4783.Ar in Ns No / Ns Ar out 4784filter has a 4785.Dq timeout 4786value) and in the case of 4787.Em dial 4788filters it means that the packet will not trigger a dial. 4789A packet failing to trigger a dial will be dropped rather than queued. 4790Refer to the 4791section on 4792.Sx PACKET FILTERING 4793above for further details. 4794.It set hangup Ar chat-script 4795This specifies the chat script that will be used to reset the device 4796before it is closed. 4797It should not normally be necessary, but can 4798be used for devices that fail to reset themselves properly on close. 4799.It set help|? Op Ar command 4800This command gives a summary of available set commands, or if 4801.Ar command 4802is specified, the command usage is shown. 4803.It set ifaddr Oo Ar myaddr Ns 4804.Op / Ns Ar \&nn 4805.Oo Ar hisaddr Ns Op / Ns Ar \&nn 4806.Oo Ar netmask 4807.Op Ar triggeraddr 4808.Oc Oc 4809.Oc 4810This command specifies the IP addresses that will be used during 4811IPCP negotiation. 4812Addresses are specified using the format 4813.Pp 4814.Dl a.b.c.d/nn 4815.Pp 4816Where 4817.Dq a.b.c.d 4818is the preferred IP, but 4819.Ar nn 4820specifies how many bits of the address we will insist on. 4821If 4822.No / Ns Ar nn 4823is omitted, it defaults to 4824.Dq /32 4825unless the IP address is 0.0.0.0 in which case it defaults to 4826.Dq /0 . 4827.Pp 4828If you wish to assign a dynamic IP number to the peer, 4829.Ar hisaddr 4830may also be specified as a range of IP numbers in the format 4831.Bd -ragged -offset indent 4832.Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Xo 4833.Oc Ns Oo , Ns Ar \&IP Ns 4834.Op \&- Ns Ar \&IP Ns 4835.Oc Ns ... 4836.Xc 4837.Ed 4838.Pp 4839for example: 4840.Pp 4841.Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20 4842.Pp 4843will only negotiate 4844.Dq 10.0.0.1 4845as the local IP number, but may assign any of the given 10 IP 4846numbers to the peer. 4847If the peer requests one of these numbers, 4848and that number is not already in use, 4849.Nm 4850will grant the peers request. 4851This is useful if the peer wants 4852to re-establish a link using the same IP number as was previously 4853allocated (thus maintaining any existing tcp or udp connections). 4854.Pp 4855If the peer requests an IP number that's either outside 4856of this range or is already in use, 4857.Nm 4858will suggest a random unused IP number from the range. 4859.Pp 4860If 4861.Ar triggeraddr 4862is specified, it is used in place of 4863.Ar myaddr 4864in the initial IPCP negotiation. 4865However, only an address in the 4866.Ar myaddr 4867range will be accepted. 4868This is useful when negotiating with some 4869.Dv PPP 4870implementations that will not assign an IP number unless their peer 4871requests 4872.Dq 0.0.0.0 . 4873.Pp 4874It should be noted that in 4875.Fl auto 4876mode, 4877.Nm 4878will configure the interface immediately upon reading the 4879.Dq set ifaddr 4880line in the config file. 4881In any other mode, these values are just 4882used for IPCP negotiations, and the interface isn't configured 4883until the IPCP layer is up. 4884.Pp 4885Note that the 4886.Ar HISADDR 4887argument may be overridden by the third field in the 4888.Pa ppp.secret 4889file once the client has authenticated itself 4890(if PAP or CHAP are 4891.Dq enabled ) . 4892Refer to the 4893.Sx AUTHENTICATING INCOMING CONNECTIONS 4894section for details. 4895.Pp 4896In all cases, if the interface is already configured, 4897.Nm 4898will try to maintain the interface IP numbers so that any existing 4899bound sockets will remain valid. 4900.It set ifqueue Ar packets 4901Set the maximum number of packets that 4902.Nm 4903will read from the tunnel interface while data cannot be sent to any of 4904the available links. 4905This queue limit is necessary to flow control outgoing data as the tunnel 4906interface is likely to be far faster than the combined links available to 4907.Nm . 4908.Pp 4909If 4910.Ar packets 4911is set to a value less than the number of links, 4912.Nm 4913will read up to that value regardless. 4914This prevents any possible latency problems. 4915.Pp 4916The default value for 4917.Ar packets 4918is 4919.Dq 30 . 4920.It set ccpretry|ccpretries Oo Ar timeout 4921.Op Ar reqtries Op Ar trmtries 4922.Oc 4923.It set chapretry|chapretries Oo Ar timeout 4924.Op Ar reqtries 4925.Oc 4926.It set ipcpretry|ipcpretries Oo Ar timeout 4927.Op Ar reqtries Op Ar trmtries 4928.Oc 4929.It set lcpretry|lcpretries Oo Ar timeout 4930.Op Ar reqtries Op Ar trmtries 4931.Oc 4932.It set papretry|papretries Oo Ar timeout 4933.Op Ar reqtries 4934.Oc 4935These commands set the number of seconds that 4936.Nm 4937will wait before resending Finite State Machine (FSM) Request packets. 4938The default 4939.Ar timeout 4940for all FSMs is 3 seconds (which should suffice in most cases). 4941.Pp 4942If 4943.Ar reqtries 4944is specified, it tells 4945.Nm 4946how many configuration request attempts it should make while receiving 4947no reply from the peer before giving up. 4948The default is 5 attempts for 4949CCP, LCP and IPCP and 3 attempts for PAP and CHAP. 4950.Pp 4951If 4952.Ar trmtries 4953is specified, it tells 4954.Nm 4955how many terminate requests should be sent before giving up waiting for the 4956peers response. 4957The default is 3 attempts. 4958Authentication protocols are 4959not terminated and it is therefore invalid to specify 4960.Ar trmtries 4961for PAP or CHAP. 4962.Pp 4963In order to avoid negotiations with the peer that will never converge, 4964.Nm 4965will only send at most 3 times the configured number of 4966.Ar reqtries 4967in any given negotiation session before giving up and closing that layer. 4968.It set log Xo 4969.Op local 4970.Op +|- Ns 4971.Ar value Ns No ... 4972.Xc 4973This command allows the adjustment of the current log level. 4974Refer to the Logging Facility section for further details. 4975.It set login Ar chat-script 4976This 4977.Ar chat-script 4978compliments the dial-script. 4979If both are specified, the login 4980script will be executed after the dial script. 4981Escape sequences available in the dial script are also available here. 4982.It set logout Ar chat-script 4983This specifies the chat script that will be used to logout 4984before the hangup script is called. 4985It should not normally be necessary. 4986.It set lqrperiod Ar frequency 4987This command sets the 4988.Ar frequency 4989in seconds at which 4990.Em LQR 4991or 4992.Em ECHO LQR 4993packets are sent. 4994The default is 30 seconds. 4995You must also use the 4996.Dq enable lqr 4997command if you wish to send LQR requests to the peer. 4998.It set mode Ar interactive|auto|ddial|background 4999This command allows you to change the 5000.Sq mode 5001of the specified link. 5002This is normally only useful in multi-link mode, 5003but may also be used in uni-link mode. 5004.Pp 5005It is not possible to change a link that is 5006.Sq direct 5007or 5008.Sq dedicated . 5009.Pp 5010Note: If you issue the command 5011.Dq set mode auto , 5012and have network address translation enabled, it may be useful to 5013.Dq enable iface-alias 5014afterwards. 5015This will allow 5016.Nm 5017to do the necessary address translations to enable the process that 5018triggers the connection to connect once the link is up despite the 5019peer assigning us a new (dynamic) IP address. 5020.It set mppe Op 40|56|128|* Op stateless|stateful|* 5021This option selects the encryption parameters used when negotiation 5022MPPE. 5023MPPE can be disabled entirely with the 5024.Dq disable mppe 5025command. 5026If no arguments are given, 5027.Nm 5028will attempt to negotiate a stateful link with a 128 bit key, but 5029will agree to whatever the peer requests (including no encryption 5030at all). 5031.Pp 5032If any arguments are given, 5033.Nm 5034will 5035.Em insist 5036on using MPPE and will close the link if it's rejected by the peer. 5037.Pp 5038The first argument specifies the number of bits that 5039.Nm 5040should insist on during negotiations and the second specifies whether 5041.Nm 5042should insist on stateful or stateless mode. 5043In stateless mode, the 5044encryption dictionary is re-initialised with every packet according to 5045an encryption key that is changed with every packet. 5046In stateful mode, 5047the encryption dictionary is re-initialised every 256 packets or after 5048the loss of any data and the key is changed every 256 packets. 5049Stateless mode is less efficient but is better for unreliable transport 5050layers. 5051.It set mrru Op Ar value 5052Setting this option enables Multi-link PPP negotiations, also known as 5053Multi-link Protocol or MP. 5054There is no default MRRU (Maximum Reconstructed Receive Unit) value. 5055If no argument is given, multi-link mode is disabled. 5056.It set mru Xo 5057.Op max Ns Op imum 5058.Op Ar value 5059.Xc 5060The default MRU (Maximum Receive Unit) is 1500. 5061If it is increased, the other side *may* increase its MTU. 5062In theory there is no point in decreasing the MRU to below the default as the 5063.Em PPP 5064protocol says implementations *must* be able to accept packets of at 5065least 1500 octets. 5066.Pp 5067If the 5068.Dq maximum 5069keyword is used, 5070.Nm 5071will refuse to negotiate a higher value. 5072The maximum MRU can be set to 2048 at most. 5073Setting a maximum of less than 1500 violates the 5074.Em PPP 5075rfc, but may sometimes be necessary. 5076For example, 5077.Em PPPoE 5078imposes a maximum of 1492 due to hardware limitations. 5079.Pp 5080If no argument is given, 1500 is assumed. 5081A value must be given when 5082.Dq maximum 5083is specified. 5084.It set mtu Xo 5085.Op max Ns Op imum 5086.Op Ar value 5087.Xc 5088The default MTU is 1500. 5089At negotiation time, 5090.Nm 5091will accept whatever MRU the peer requests (assuming it's 5092not less than 296 bytes or greater than the assigned maximum). 5093If the MTU is set, 5094.Nm 5095will not accept MRU values less than 5096.Ar value . 5097When negotiations are complete, the MTU is used when writing to the 5098interface, even if the peer requested a higher value MRU. 5099This can be useful for 5100limiting your packet size (giving better bandwidth sharing at the expense 5101of more header data). 5102.Pp 5103If the 5104.Dq maximum 5105keyword is used, 5106.Nm 5107will refuse to negotiate a higher value. 5108The maximum MTU can be set to 2048 at most. 5109.Pp 5110If no 5111.Ar value 5112is given, 1500, or whatever the peer asks for is used. 5113A value must be given when 5114.Dq maximum 5115is specified. 5116.It set nbns Op Ar x.x.x.x Op Ar y.y.y.y 5117This option allows the setting of the Microsoft NetBIOS name server 5118values to be returned at the peers request. 5119If no values are given, 5120.Nm 5121will reject any such requests. 5122.It set openmode active|passive Op Ar delay 5123By default, 5124.Ar openmode 5125is always 5126.Ar active 5127with a one second 5128.Ar delay . 5129That is, 5130.Nm 5131will always initiate LCP/IPCP/CCP negotiation one second after the line 5132comes up. 5133If you want to wait for the peer to initiate negotiations, you 5134can use the value 5135.Ar passive . 5136If you want to initiate negotiations immediately or after more than one 5137second, the appropriate 5138.Ar delay 5139may be specified here in seconds. 5140.It set parity odd|even|none|mark 5141This allows the line parity to be set. 5142The default value is 5143.Ar none . 5144.It set phone Ar telno Ns Xo 5145.Oo \&| Ns Ar backupnumber 5146.Oc Ns ... Ns Oo : Ns Ar nextnumber 5147.Oc Ns ... 5148.Xc 5149This allows the specification of the phone number to be used in 5150place of the \\\\T string in the dial and login chat scripts. 5151Multiple phone numbers may be given separated either by a pipe 5152.Pq Dq \&| 5153or a colon 5154.Pq Dq \&: . 5155.Pp 5156Numbers after the pipe are only dialed if the dial or login 5157script for the previous number failed. 5158.Pp 5159Numbers after the colon are tried sequentially, irrespective of 5160the reason the line was dropped. 5161.Pp 5162If multiple numbers are given, 5163.Nm 5164will dial them according to these rules until a connection is made, retrying 5165the maximum number of times specified by 5166.Dq set redial 5167below. 5168In 5169.Fl background 5170mode, each number is attempted at most once. 5171.It set Op proc Ns Xo 5172.No title Op Ar value 5173.Xc 5174The current process title as displayed by 5175.Xr ps 1 5176is changed according to 5177.Ar value . 5178If 5179.Ar value 5180is not specified, the original process title is restored. 5181All the 5182word replacements done by the shell commands (see the 5183.Dq bg 5184command above) are done here too. 5185.Pp 5186Note, if USER is required in the process title, the 5187.Dq set proctitle 5188command must appear in 5189.Pa ppp.linkup , 5190as it is not known when the commands in 5191.Pa ppp.conf 5192are executed. 5193.It set radius Op Ar config-file 5194This command enables RADIUS support (if it's compiled in). 5195.Ar config-file 5196refers to the radius client configuration file as described in 5197.Xr radius.conf 5 . 5198If PAP or CHAP are 5199.Dq enable Ns No d , 5200.Nm 5201behaves as a 5202.Em \&N Ns No etwork 5203.Em \&A Ns No ccess 5204.Em \&S Ns No erver 5205and uses the configured RADIUS server to authenticate rather than 5206authenticating from the 5207.Pa ppp.secret 5208file or from the passwd database. 5209.Pp 5210If neither PAP or CHAP are enabled, 5211.Dq set radius 5212will do nothing. 5213.Pp 5214.Nm 5215uses the following attributes from the RADIUS reply: 5216.Bl -tag -width XXX -offset XXX 5217.It RAD_FRAMED_IP_ADDRESS 5218The peer IP address is set to the given value. 5219.It RAD_FRAMED_IP_NETMASK 5220The tun interface netmask is set to the given value. 5221.It RAD_FRAMED_MTU 5222If the given MTU is less than the peers MRU as agreed during LCP 5223negotiation, *and* it is less that any configured MTU (see the 5224.Dq set mru 5225command), the tun interface MTU is set to the given value. 5226.It RAD_FRAMED_COMPRESSION 5227If the received compression type is 5228.Dq 1 , 5229.Nm 5230will request VJ compression during IPCP negotiations despite any 5231.Dq disable vj 5232configuration command. 5233.It RAD_FRAMED_ROUTE 5234The received string is expected to be in the format 5235.Ar dest Ns Op / Ns Ar bits 5236.Ar gw 5237.Op Ar metrics . 5238Any specified metrics are ignored. 5239.Dv MYADDR 5240and 5241.Dv HISADDR 5242are understood as valid values for 5243.Ar dest 5244and 5245.Ar gw , 5246.Dq default 5247can be used for 5248.Ar dest 5249to sepcify the default route, and 5250.Dq 0.0.0.0 5251is understood to be the same as 5252.Dq default 5253for 5254.Ar dest 5255and 5256.Dv HISADDR 5257for 5258.Ar gw . 5259.Pp 5260For example, a returned value of 5261.Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400 5262would result in a routing table entry to the 1.2.3.0/24 network via 5263.Dv HISADDR 5264and a returned value of 5265.Dq 0.0.0.0 0.0.0.0 5266or 5267.Dq default HISADDR 5268would result in a default route to 5269.Dv HISADDR . 5270.Pp 5271All RADIUS routes are applied after any sticky routes are applied, making 5272RADIUS routes override configured routes. 5273This also applies for RADIUS routes that don't {include} the 5274.Dv MYADDR 5275or 5276.Dv HISADDR 5277keywords. 5278.Pp 5279.El 5280Values received from the RADIUS server may be viewed using 5281.Dq show bundle . 5282.It set reconnect Ar timeout ntries 5283Should the line drop unexpectedly (due to loss of CD or LQR 5284failure), a connection will be re-established after the given 5285.Ar timeout . 5286The line will be re-connected at most 5287.Ar ntries 5288times. 5289.Ar Ntries 5290defaults to zero. 5291A value of 5292.Ar random 5293for 5294.Ar timeout 5295will result in a variable pause, somewhere between 1 and 30 seconds. 5296.It set recvpipe Op Ar value 5297This sets the routing table RECVPIPE value. 5298The optimum value is just over twice the MTU value. 5299If 5300.Ar value 5301is unspecified or zero, the default kernel controlled value is used. 5302.It set redial Ar secs Ns Xo 5303.Oo + Ns Ar inc Ns 5304.Op - Ns Ar max Ns 5305.Oc Ns Op . Ns Ar next 5306.Op Ar attempts 5307.Xc 5308.Nm 5309can be instructed to attempt to redial 5310.Ar attempts 5311times. 5312If more than one phone number is specified (see 5313.Dq set phone 5314above), a pause of 5315.Ar next 5316is taken before dialing each number. 5317A pause of 5318.Ar secs 5319is taken before starting at the first number again. 5320A literal value of 5321.Dq Li random 5322may be used here in place of 5323.Ar secs 5324and 5325.Ar next , 5326causing a random delay of between 1 and 30 seconds. 5327.Pp 5328If 5329.Ar inc 5330is specified, its value is added onto 5331.Ar secs 5332each time 5333.Nm 5334tries a new number. 5335.Ar secs 5336will only be incremented at most 5337.Ar max 5338times. 5339.Ar max 5340defaults to 10. 5341.Pp 5342Note, the 5343.Ar secs 5344delay will be effective, even after 5345.Ar attempts 5346has been exceeded, so an immediate manual dial may appear to have 5347done nothing. 5348If an immediate dial is required, a 5349.Dq !\& 5350should immediately follow the 5351.Dq open 5352keyword. 5353See the 5354.Dq open 5355description above for further details. 5356.It set sendpipe Op Ar value 5357This sets the routing table SENDPIPE value. 5358The optimum value is just over twice the MTU value. 5359If 5360.Ar value 5361is unspecified or zero, the default kernel controlled value is used. 5362.It "set server|socket" Ar TcpPort Ns No \&| Ns Xo 5363.Ar LocalName Ns No |none|open|closed 5364.Op password Op Ar mask 5365.Xc 5366This command tells 5367.Nm 5368to listen on the given socket or 5369.Sq diagnostic port 5370for incoming command connections. 5371.Pp 5372The word 5373.Dq none 5374instructs 5375.Nm 5376to close any existing socket and clear the socket configuration. 5377The word 5378.Dq open 5379instructs 5380.Nm 5381to attempt to re-open the port. 5382The word 5383.Dq closed 5384instructs 5385.Nm 5386to close the open port. 5387.Pp 5388If you wish to specify a local domain socket, 5389.Ar LocalName 5390must be specified as an absolute file name, otherwise it is assumed 5391to be the name or number of a TCP port. 5392You may specify the octal umask to be used with a local domain socket. 5393Refer to 5394.Xr umask 2 5395for umask details. 5396Refer to 5397.Xr services 5 5398for details of how to translate TCP port names. 5399.Pp 5400You must also specify the password that must be entered by the client 5401(using the 5402.Dq passwd 5403variable above) when connecting to this socket. 5404If the password is 5405specified as an empty string, no password is required for connecting clients. 5406.Pp 5407When specifying a local domain socket, the first 5408.Dq %d 5409sequence found in the socket name will be replaced with the current 5410interface unit number. 5411This is useful when you wish to use the same 5412profile for more than one connection. 5413.Pp 5414In a similar manner TCP sockets may be prefixed with the 5415.Dq + 5416character, in which case the current interface unit number is added to 5417the port number. 5418.Pp 5419When using 5420.Nm 5421with a server socket, the 5422.Xr pppctl 8 5423command is the preferred mechanism of communications. 5424Currently, 5425.Xr telnet 1 5426can also be used, but link encryption may be implemented in the future, so 5427.Xr telnet 1 5428should be avoided. 5429.Pp 5430Note; 5431.Dv SIGUSR1 5432and 5433.Dv SIGUSR2 5434interact with the diagnostic socket. 5435.It set speed Ar value 5436This sets the speed of the serial device. 5437If speed is specified as 5438.Dq sync , 5439.Nm 5440treats the device as a synchronous device. 5441.Pp 5442Certain device types will know whether they should be specified as 5443synchronous or asynchronous. 5444These devices will override incorrect 5445settings and log a warning to this effect. 5446.It set stopped Op Ar LCPseconds Op Ar CCPseconds 5447If this option is set, 5448.Nm 5449will time out after the given FSM (Finite State Machine) has been in 5450the stopped state for the given number of 5451.Dq seconds . 5452This option may be useful if the peer sends a terminate request, 5453but never actually closes the connection despite our sending a terminate 5454acknowledgement. 5455This is also useful if you wish to 5456.Dq set openmode passive 5457and time out if the peer doesn't send a Configure Request within the 5458given time. 5459Use 5460.Dq set log +lcp +ccp 5461to make 5462.Nm 5463log the appropriate state transitions. 5464.Pp 5465The default value is zero, where 5466.Nm 5467doesn't time out in the stopped state. 5468.Pp 5469This value should not be set to less than the openmode delay (see 5470.Dq set openmode 5471above). 5472.It set timeout Ar idleseconds Op Ar mintimeout 5473This command allows the setting of the idle timer. 5474Refer to the section titled 5475.Sx SETTING THE IDLE TIMER 5476for further details. 5477.Pp 5478If 5479.Ar mintimeout 5480is specified, 5481.Nm 5482will never idle out before the link has been up for at least that number 5483of seconds. 5484.It set urgent Xo 5485.Op tcp|udp|none 5486.Oo Op +|- Ns 5487.Ar port 5488.Oc No ... 5489.Xc 5490This command controls the ports that 5491.Nm 5492prioritizes when transmitting data. 5493The default priority TCP ports 5494are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell), 5495543 (klogin) and 544 (kshell). 5496There are no priority UDP ports by default. 5497See 5498.Xr services 5 5499for details. 5500.Pp 5501If neither 5502.Dq tcp 5503or 5504.Dq udp 5505are specified, 5506.Dq tcp 5507is assumed. 5508.Pp 5509If no 5510.Ar port Ns No s 5511are given, the priority port lists are cleared (although if 5512.Dq tcp 5513or 5514.Dq udp 5515is specified, only that list is cleared). 5516If the first 5517.Ar port 5518argument is prefixed with a plus 5519.Pq Dq \&+ 5520or a minus 5521.Pq Dq \&- , 5522the current list is adjusted, otherwise the list is reassigned. 5523.Ar port Ns No s 5524prefixed with a plus or not prefixed at all are added to the list and 5525.Ar port Ns No s 5526prefixed with a minus are removed from the list. 5527.Pp 5528If 5529.Dq none 5530is specified, all priority port lists are disabled and even 5531.Dv IPTOS_LOWDELAY 5532packets are not prioritised. 5533.It set vj slotcomp on|off 5534This command tells 5535.Nm 5536whether it should attempt to negotiate VJ slot compression. 5537By default, slot compression is turned 5538.Ar on . 5539.It set vj slots Ar nslots 5540This command sets the initial number of slots that 5541.Nm 5542will try to negotiate with the peer when VJ compression is enabled (see the 5543.Sq enable 5544command above). 5545It defaults to a value of 16. 5546.Ar Nslots 5547must be between 5548.Ar 4 5549and 5550.Ar 16 5551inclusive. 5552.El 5553.Pp 5554.It shell|! Op Ar command 5555If 5556.Ar command 5557is not specified a shell is invoked according to the 5558.Dv SHELL 5559environment variable. 5560Otherwise, the given 5561.Ar command 5562is executed. 5563Word replacement is done in the same way as for the 5564.Dq !bg 5565command as described above. 5566.Pp 5567Use of the ! character 5568requires a following space as with any of the other commands. 5569You should note that this command is executed in the foreground; 5570.Nm 5571will not continue running until this process has exited. 5572Use the 5573.Dv bg 5574command if you wish processing to happen in the background. 5575.It show Ar var 5576This command allows the user to examine the following: 5577.Bl -tag -width 2n 5578.It show bundle 5579Show the current bundle settings. 5580.It show ccp 5581Show the current CCP compression statistics. 5582.It show compress 5583Show the current VJ compression statistics. 5584.It show escape 5585Show the current escape characters. 5586.It show filter Op Ar name 5587List the current rules for the given filter. 5588If 5589.Ar name 5590is not specified, all filters are shown. 5591.It show hdlc 5592Show the current HDLC statistics. 5593.It show help|? 5594Give a summary of available show commands. 5595.It show iface 5596Show the current interface information 5597(the same as 5598.Dq iface show ) . 5599.It show ipcp 5600Show the current IPCP statistics. 5601.It show layers 5602Show the protocol layers currently in use. 5603.It show lcp 5604Show the current LCP statistics. 5605.It show Op data Ns Xo 5606.No link 5607.Xc 5608Show high level link information. 5609.It show links 5610Show a list of available logical links. 5611.It show log 5612Show the current log values. 5613.It show mem 5614Show current memory statistics. 5615.It show ncp 5616Show the current NCP statistics. 5617.It show physical 5618Show low level link information. 5619.It show mp 5620Show Multi-link information. 5621.It show proto 5622Show current protocol totals. 5623.It show route 5624Show the current routing tables. 5625.It show stopped 5626Show the current stopped timeouts. 5627.It show timer 5628Show the active alarm timers. 5629.It show version 5630Show the current version number of 5631.Nm . 5632.El 5633.Pp 5634.It term 5635Go into terminal mode. 5636Characters typed at the keyboard are sent to the device. 5637Characters read from the device are displayed on the screen. 5638When a remote 5639.Em PPP 5640peer is detected, 5641.Nm 5642automatically enables Packet Mode and goes back into command mode. 5643.El 5644.Sh MORE DETAILS 5645.Bl -bullet 5646.It 5647Read the example configuration files. 5648They are a good source of information. 5649.It 5650Use 5651.Dq help , 5652.Dq nat \&? , 5653.Dq enable \&? , 5654.Dq set ?\& 5655and 5656.Dq show ?\& 5657to get online information about what's available. 5658.It 5659The following URLs contain useful information: 5660.Bl -bullet -compact 5661.It 5662http://www.FreeBSD.org/FAQ/userppp.html 5663.It 5664http://www.FreeBSD.org/handbook/userppp.html 5665.El 5666.Pp 5667.El 5668.Sh FILES 5669.Nm 5670refers to four files: 5671.Pa ppp.conf , 5672.Pa ppp.linkup , 5673.Pa ppp.linkdown 5674and 5675.Pa ppp.secret . 5676These files are placed in the 5677.Pa /etc/ppp 5678directory. 5679.Bl -tag -width 2n 5680.It Pa /etc/ppp/ppp.conf 5681System default configuration file. 5682.It Pa /etc/ppp/ppp.secret 5683An authorisation file for each system. 5684.It Pa /etc/ppp/ppp.linkup 5685A file to check when 5686.Nm 5687establishes a network level connection. 5688.It Pa /etc/ppp/ppp.linkdown 5689A file to check when 5690.Nm 5691closes a network level connection. 5692.It Pa /var/log/ppp.log 5693Logging and debugging information file. 5694Note, this name is specified in 5695.Pa /etc/syslog.conf . 5696See 5697.Xr syslog.conf 5 5698for further details. 5699.It Pa /var/spool/lock/LCK..* 5700tty port locking file. 5701Refer to 5702.Xr uucplock 3 5703for further details. 5704.It Pa /var/run/tunN.pid 5705The process id (pid) of the 5706.Nm 5707program connected to the tunN device, where 5708.Sq N 5709is the number of the device. 5710.It Pa /var/run/ttyXX.if 5711The tun interface used by this port. 5712Again, this file is only created in 5713.Fl background , 5714.Fl auto 5715and 5716.Fl ddial 5717modes. 5718.It Pa /etc/services 5719Get port number if port number is using service name. 5720.It Pa /var/run/ppp-authname-class-value 5721In multi-link mode, local domain sockets are created using the peer 5722authentication name 5723.Pq Sq authname , 5724the peer endpoint discriminator class 5725.Pq Sq class 5726and the peer endpoint discriminator value 5727.Pq Sq value . 5728As the endpoint discriminator value may be a binary value, it is turned 5729to HEX to determine the actual file name. 5730.Pp 5731This socket is used to pass links between different instances of 5732.Nm . 5733.El 5734.Sh SEE ALSO 5735.Xr at 1 , 5736.Xr ftp 1 , 5737.Xr gzip 1 , 5738.Xr hostname 1 , 5739.Xr login 1 , 5740.Xr tcpdump 1 , 5741.Xr telnet 1 , 5742.Xr kldload 2 , 5743ifdef({LOCALNAT},{},{.Xr libalias 3 , 5744})dnl 5745ifdef({LOCALRAD},{},{.Xr libradius 3 , 5746})dnl 5747.Xr syslog 3 , 5748.Xr uucplock 3 , 5749.Xr netgraph 4 , 5750.Xr ng_pppoe 4 , 5751.Xr crontab 5 , 5752.Xr group 5 , 5753.Xr passwd 5 , 5754.Xr protocols 5 , 5755.Xr radius.conf 5 , 5756.Xr resolv.conf 5 , 5757.Xr syslog.conf 5 , 5758.Xr adduser 8 , 5759.Xr chat 8 , 5760.Xr getty 8 , 5761.Xr inetd 8 , 5762.Xr init 8 , 5763.Xr isdn 8 , 5764.Xr named 8 , 5765.Xr ping 8 , 5766.Xr pppctl 8 , 5767.Xr pppd 8 , 5768.Xr pppoe 8 , 5769.Xr route 8 , 5770.Xr sshd 8 , 5771.Xr syslogd 8 , 5772.Xr traceroute 8 , 5773.Xr vipw 8 5774.Sh HISTORY 5775This program was originally written by 5776.An Toshiharu OHNO Aq tony-o@iij.ad.jp , 5777and was submitted to 5778.Fx 2.0.5 5779by 5780.An Atsushi Murai Aq amurai@spec.co.jp . 5781.Pp 5782It was substantially modified during 1997 by 5783.An Brian Somers Aq brian@Awfulhak.org , 5784and was ported to 5785.Ox 5786in November that year 5787(just after the 2.2 release). 5788.Pp 5789Most of the code was rewritten by 5790.An Brian Somers 5791in early 1998 when multi-link ppp support was added. 5792