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