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