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