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