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.12 2008/05/02 02:05:08 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 254.Pa ( ftp://ftp.microsoft.com/developr/rfc/cbcp.txt ) . 255.It Supports NAT or packet aliasing. 256Packet aliasing (a.k.a. IP masquerading) allows computers on a 257private, unregistered network to access the Internet. 258The 259.Em PPP 260host acts as a masquerading gateway. 261IP addresses as well as TCP and 262UDP port numbers are NAT'd for outgoing packets and de-NAT'd for 263returning packets. 264.It Supports background PPP connections. 265In background mode, if 266.Nm 267successfully establishes the connection, it will become a daemon. 268Otherwise, it will exit with an error. 269This allows the setup of 270scripts that wish to execute certain commands only if the connection 271is successfully established. 272.It Supports server-side PPP connections. 273In direct mode, 274.Nm 275acts as server which accepts incoming 276.Em PPP 277connections on stdin/stdout. 278.It "Supports PAP and CHAP (rfc 1994, 2433 and 2759) authentication. 279With PAP or CHAP, it is possible to skip the Unix style 280.Xr login 1 281procedure, and use the 282.Em PPP 283protocol for authentication instead. 284If the peer requests Microsoft CHAP authentication and 285.Nm 286is compiled with DES support, an appropriate MD4/DES response will be 287made. 288.It Supports RADIUS (rfc 2138 & 2548) authentication. 289An extension to PAP and CHAP, 290.Em \&R Ns No emote 291.Em \&A Ns No ccess 292.Em \&D Ns No ial 293.Em \&I Ns No n 294.Em \&U Ns No ser 295.Em \&S Ns No ervice 296allows authentication information to be stored in a central or 297distributed database along with various per-user framed connection 298characteristics. 299ifdef({LOCALRAD},{},{If 300.Xr libradius 3 301is available at compile time, 302.Nm 303will use it to make 304.Em RADIUS 305requests when configured to do so. 306})dnl 307.It Supports Proxy Arp. 308.Nm 309can be configured to make one or more proxy arp entries on behalf of 310the peer. 311This allows routing from the peer to the LAN without 312configuring each machine on that LAN. 313.It Supports packet filtering. 314User can {define} four kinds of filters: the 315.Em in 316filter for incoming packets, the 317.Em out 318filter for outgoing packets, the 319.Em dial 320filter to {define} a dialing trigger packet and the 321.Em alive 322filter for keeping a connection alive with the trigger packet. 323.It Tunnel driver supports bpf. 324The user can use 325.Xr tcpdump 1 326to check the packet flow over the 327.Em PPP 328link. 329.It Supports PPP over TCP and PPP over UDP. 330If a device name is specified as 331.Em host Ns No : Ns Em port Ns 332.Xo 333.Op / Ns tcp|udp , 334.Xc 335.Nm 336will open a TCP or UDP connection for transporting data rather than using a 337conventional serial device. 338UDP connections force 339.Nm 340into synchronous mode. 341.It Supports PPP over ISDN. 342If 343.Nm 344is given a raw B-channel i4b device to open as a link, it's able to talk 345to the 346.Xr isdnd 8 347daemon to establish an ISDN connection. 348.It Supports PPP over Ethernet (rfc 2516). 349If 350.Nm 351is given a device specification of the format 352.No PPPoE: Ns Ar iface Ns Xo 353.Op \&: Ns Ar provider Ns 354.Xc 355and if 356.Xr netgraph 4 357is available, 358.Nm 359will attempt talk 360.Em PPP 361over Ethernet to 362.Ar provider 363using the 364.Ar iface 365network interface. 366.Pp 367On systems that do not support 368.Xr netgraph 4 , 369an external program such as 370.Xr pppoe 8 371may be used. 372.It "Supports IETF draft Predictor-1 (rfc 1978) and DEFLATE (rfc 1979) compression." 373.Nm 374supports not only VJ-compression but also Predictor-1 and DEFLATE compression. 375Normally, a modem has built-in compression (e.g., v42.bis) and the system 376may receive higher data rates from it as a result of such compression. 377While this is generally a good thing in most other situations, this 378higher speed data imposes a penalty on the system by increasing the 379number of serial interrupts the system has to process in talking to the 380modem and also increases latency. 381Unlike VJ-compression, Predictor-1 and DEFLATE compression pre-compresses 382.Em all 383network traffic flowing through the link, thus reducing overheads to a 384minimum. 385.It Supports Microsoft's IPCP extensions (rfc 1877). 386Name Server Addresses and NetBIOS Name Server Addresses can be negotiated 387with clients using the Microsoft 388.Em PPP 389stack (i.e., Win95, WinNT) 390.It Supports Multi-link PPP (rfc 1990) 391It is possible to configure 392.Nm 393to open more than one physical connection to the peer, combining the 394bandwidth of all links for better throughput. 395.It Supports MPPE (draft-ietf-pppext-mppe) 396MPPE is Microsoft Point to Point Encryption scheme. 397It is possible to configure 398.Nm 399to participate in Microsoft's Windows VPN. 400For now, 401.Nm 402can only get encryption keys from CHAP 81 authentication. 403.Nm 404must be compiled with DES for MPPE to operate. 405.It Supports IPV6CP (rfc 2023). 406An IPv6 connection can be made in addition to or instead of the normal 407IPv4 connection. 408.El 409.Sh PERMISSIONS 410.Nm 411is installed as user 412.Dv root 413and group 414.Dv network , 415with permissions 416.Dv 04554 . 417By default, 418.Nm 419will not run if the invoking user id is not zero. 420This may be overridden by using the 421.Dq allow users 422command in 423.Pa /etc/ppp/ppp.conf . 424When running as a normal user, 425.Nm 426switches to user id 0 in order to alter the system routing table, set up 427system lock files and read the ppp configuration files. 428All external commands (executed via the "shell" or "!bg" commands) are executed 429as the user id that invoked 430.Nm . 431Refer to the 432.Sq ID0 433logging facility if you're interested in what exactly is done as user id 434zero. 435.Sh GETTING STARTED 436When you first run 437.Nm 438you may need to deal with some initial configuration details. 439.Bl -bullet 440.It 441Your kernel must {include} a tunnel device (the GENERIC kernel includes 442one by default). 443If it doesn't, or if you require more than one tun 444interface, you'll need to rebuild your kernel with the following line in 445your kernel configuration file: 446.Pp 447.Dl pseudo-device tun N 448.Pp 449where 450.Ar N 451is the maximum number of 452.Em PPP 453connections you wish to support. 454.It 455Check your 456.Pa /dev 457directory for the tunnel device entries 458.Pa /dev/tunN , 459where 460.Sq N 461represents the number of the tun device, starting at zero. 462If they don't exist, you can create them by running "sh ./MAKEDEV tunN". 463This will create tun devices 0 through 464.Ar N . 465.It 466Make sure that your system has a group named 467.Dq network 468in the 469.Pa /etc/group 470file and that the group contains the names of all users expected to use 471.Nm . 472Refer to the 473.Xr group 5 474manual page for details. 475Each of these users must also be given access using the 476.Dq allow users 477command in 478.Pa /etc/ppp/ppp.conf . 479.It 480Create a log file. 481.Nm 482uses 483.Xr syslog 3 484to log information. 485A common log file name is 486.Pa /var/log/ppp.log . 487To make output go to this file, put the following lines in the 488.Pa /etc/syslog.conf 489file: 490.Bd -literal -offset indent 491!ppp 492*.*<TAB>/var/log/ppp.log 493.Ed 494.Pp 495It is possible to have more than one 496.Em PPP 497log file by creating a link to the 498.Nm 499executable: 500.Pp 501.Dl # cd /usr/sbin 502.Dl # ln ppp ppp0 503.Pp 504and using 505.Bd -literal -offset indent 506!ppp0 507*.*<TAB>/var/log/ppp0.log 508.Ed 509.Pp 510in 511.Pa /etc/syslog.conf . 512Don't forget to send a 513.Dv HUP 514signal to 515.Xr syslogd 8 516after altering 517.Pa /etc/syslog.conf . 518.It 519Although not strictly relevant to 520.Nm Ns No 's 521operation, you should configure your resolver so that it works correctly. 522This can be done by configuring a local DNS 523(using 524.Xr named 8 ) 525or by adding the correct 526.Sq nameserver 527lines to the file 528.Pa /etc/resolv.conf . 529Refer to the 530.Xr resolv.conf 5 531manual page for details. 532.Pp 533Alternatively, if the peer supports it, 534.Nm 535can be configured to ask the peer for the nameserver address(es) and to 536update 537.Pa /etc/resolv.conf 538automatically. 539Refer to the 540.Dq enable dns 541and 542.Dq resolv 543commands below for details. 544.El 545.Sh MANUAL DIALING 546In the following examples, we assume that your machine name is 547.Dv awfulhak . 548when you invoke 549.Nm 550(see 551.Sx PERMISSIONS 552above) with no arguments, you are presented with a prompt: 553.Bd -literal -offset indent 554ppp ON awfulhak> 555.Ed 556.Pp 557The 558.Sq ON 559part of your prompt should always be in upper case. 560If it is in lower case, it means that you must supply a password using the 561.Dq passwd 562command. 563This only ever happens if you connect to a running version of 564.Nm 565and have not authenticated yourself using the correct password. 566.Pp 567You can start by specifying the device name and speed: 568.Bd -literal -offset indent 569ppp ON awfulhak> set device /dev/cuaa0 570ppp ON awfulhak> set speed 38400 571.Ed 572.Pp 573Normally, hardware flow control (CTS/RTS) is used. 574However, under 575certain circumstances (as may happen when you are connected directly 576to certain PPP-capable terminal servers), this may result in 577.Nm 578hanging as soon as it tries to write data to your communications link 579as it is waiting for the CTS (clear to send) signal - which will never 580come. 581Thus, if you have a direct line and can't seem to make a 582connection, try turning CTS/RTS off with 583.Dq set ctsrts off . 584If you need to do this, check the 585.Dq set accmap 586description below too - you'll probably need to 587.Dq set accmap 000a0000 . 588.Pp 589Usually, parity is set to 590.Dq none , 591and this is 592.Nm Ns No 's 593default. 594Parity is a rather archaic error checking mechanism that is no 595longer used because modern modems do their own error checking, and most 596link-layer protocols (that's what 597.Nm 598is) use much more reliable checking mechanisms. 599Parity has a relatively 600huge overhead (a 12.5% increase in traffic) and as a result, it is always 601disabled 602(set to 603.Dq none ) 604when 605.Dv PPP 606is opened. 607However, some ISPs (Internet Service Providers) may use 608specific parity settings at connection time (before 609.Dv PPP 610is opened). 611Notably, Compuserve insist on even parity when logging in: 612.Bd -literal -offset indent 613ppp ON awfulhak> set parity even 614.Ed 615.Pp 616You can now see what your current device settings look like: 617.Bd -literal -offset indent 618ppp ON awfulhak> show physical 619Name: deflink 620 State: closed 621 Device: N/A 622 Link Type: interactive 623 Connect Count: 0 624 Queued Packets: 0 625 Phone Number: N/A 626 627Defaults: 628 Device List: /dev/cuaa0 629 Characteristics: 38400bps, cs8, even parity, CTS/RTS on 630 631Connect time: 0 secs 6320 octets in, 0 octets out 633Overall 0 bytes/sec 634ppp ON awfulhak> 635.Ed 636.Pp 637The term command can now be used to talk directly to the device: 638.Bd -literal -offset indent 639ppp ON awfulhak> term 640at 641OK 642atdt123456 643CONNECT 644login: myispusername 645Password: myisppassword 646Protocol: ppp 647.Ed 648.Pp 649When the peer starts to talk in 650.Em PPP , 651.Nm 652detects this automatically and returns to command mode. 653.Bd -literal -offset indent 654ppp ON awfulhak> # No link has been established 655Ppp ON awfulhak> # We've connected & finished LCP 656PPp ON awfulhak> # We've authenticated 657PPP ON awfulhak> # We've agreed IP numbers 658.Ed 659.Pp 660If it does not, it's probable that the peer is waiting for your end to 661start negotiating. 662To force 663.Nm 664to start sending 665.Em PPP 666configuration packets to the peer, use the 667.Dq ~p 668command to drop out of terminal mode and enter packet mode. 669.Pp 670If you never even receive a login prompt, it is quite likely that the 671peer wants to use PAP or CHAP authentication instead of using Unix-style 672login/password authentication. 673To set things up properly, drop back to 674the prompt and set your authentication name and key, then reconnect: 675.Bd -literal -offset indent 676~. 677ppp ON awfulhak> set authname myispusername 678ppp ON awfulhak> set authkey myisppassword 679ppp ON awfulhak> term 680at 681OK 682atdt123456 683CONNECT 684.Ed 685.Pp 686You may need to tell ppp to initiate negotiations with the peer here too: 687.Bd -literal -offset indent 688~p 689ppp ON awfulhak> # No link has been established 690Ppp ON awfulhak> # We've connected & finished LCP 691PPp ON awfulhak> # We've authenticated 692PPP ON awfulhak> # We've agreed IP numbers 693.Ed 694.Pp 695You are now connected! 696Note that 697.Sq PPP 698in the prompt has changed to capital letters to indicate that you have 699a peer connection. 700If only some of the three Ps go uppercase, wait until 701either everything is uppercase or lowercase. 702If they revert to lowercase, it means that 703.Nm 704couldn't successfully negotiate with the peer. 705A good first step for troubleshooting at this point would be to 706.Bd -literal -offset indent 707ppp ON awfulhak> set log local phase lcp ipcp 708.Ed 709.Pp 710and try again. 711Refer to the 712.Dq set log 713command description below for further details. 714If things fail at this point, 715it is quite important that you turn logging on and try again. 716It is also 717important that you note any prompt changes and report them to anyone trying 718to help you. 719.Pp 720When the link is established, the show command can be used to see how 721things are going: 722.Bd -literal -offset indent 723PPP ON awfulhak> show physical 724* Modem related information is shown here * 725PPP ON awfulhak> show ccp 726* CCP (compression) related information is shown here * 727PPP ON awfulhak> show lcp 728* LCP (line control) related information is shown here * 729PPP ON awfulhak> show ipcp 730* IPCP (IP) related information is shown here * 731PPP ON awfulhak> show ipv6cp 732* IPV6CP (IPv6) related information is shown here * 733PPP ON awfulhak> show link 734* Link (high level) related information is shown here * 735PPP ON awfulhak> show bundle 736* Logical (high level) connection related information is shown here * 737.Ed 738.Pp 739At this point, your machine has a host route to the peer. 740This means 741that you can only make a connection with the host on the other side 742of the link. 743If you want to add a default route entry (telling your 744machine to send all packets without another routing entry to the other 745side of the 746.Em PPP 747link), enter the following command: 748.Bd -literal -offset indent 749PPP ON awfulhak> add default HISADDR 750.Ed 751.Pp 752The string 753.Sq HISADDR 754represents the IP address of the connected peer. 755If the 756.Dq add 757command fails due to an existing route, you can overwrite the existing 758route using 759.Bd -literal -offset indent 760PPP ON awfulhak> add! default HISADDR 761.Ed 762.Pp 763This command can also be executed before actually making the connection. 764If a new IP address is negotiated at connection time, 765.Nm 766will update your default route accordingly. 767.Pp 768You can now use your network applications (ping, telnet, ftp etc.) 769in other windows or terminals on your machine. 770If you wish to reuse the current terminal, you can put 771.Nm 772into the background using your standard shell suspend and background 773commands (usually 774.Dq ^Z 775followed by 776.Dq bg ) . 777.Pp 778Refer to the 779.Sx PPP COMMAND LIST 780section for details on all available commands. 781.Sh AUTOMATIC DIALING 782To use automatic dialing, you must prepare some Dial and Login chat scripts. 783See the example definitions in 784.Pa /usr/share/examples/ppp/ppp.conf.sample 785(the format of 786.Pa /etc/ppp/ppp.conf 787is pretty simple). 788Each line contains one comment, inclusion, label or command: 789.Bl -bullet 790.It 791A line starting with a 792.Pq Dq # 793character is treated as a comment line. 794Leading whitespace are ignored when identifying comment lines. 795.It 796An inclusion is a line beginning with the word 797.Sq {!include} . 798It must have one argument - the file to {include}. 799You may wish to 800.Dq {!include} ~/.ppp.conf 801for compatibility with older versions of 802.Nm . 803.It 804A label name starts in the first column and is followed by 805a colon 806.Pq Dq \&: . 807.It 808A command line must contain a space or tab in the first column. 809.El 810.Pp 811The 812.Pa /etc/ppp/ppp.conf 813file should consist of at least a 814.Dq default 815section. 816This section is always executed. 817It should also contain 818one or more sections, named according to their purpose, for example, 819.Dq MyISP 820would represent your ISP, and 821.Dq ppp-in 822would represent an incoming 823.Nm 824configuration. 825You can now specify the destination label name when you invoke 826.Nm . 827Commands associated with the 828.Dq default 829label are executed, followed by those associated with the destination 830label provided. 831When 832.Nm 833is started with no arguments, the 834.Dq default 835section is still executed. 836The load command can be used to manually load a section from the 837.Pa /etc/ppp/ppp.conf 838file: 839.Bd -literal -offset indent 840ppp ON awfulhak> load MyISP 841.Ed 842.Pp 843Note, no action is taken by 844.Nm 845after a section is loaded, whether it's the result of passing a label on 846the command line or using the 847.Dq load 848command. 849Only the commands specified for that label in the configuration 850file are executed. 851However, when invoking 852.Nm 853with the 854.Fl background , 855.Fl ddial , 856or 857.Fl dedicated 858switches, the link mode tells 859.Nm 860to establish a connection. 861Refer to the 862.Dq set mode 863command below for further details. 864.Pp 865Once the connection is made, the 866.Sq ppp 867portion of the prompt will change to 868.Sq PPP : 869.Bd -literal -offset indent 870# ppp MyISP 871\&... 872ppp ON awfulhak> dial 873Ppp ON awfulhak> 874PPp ON awfulhak> 875PPP ON awfulhak> 876.Ed 877.Pp 878The Ppp prompt indicates that 879.Nm 880has entered the authentication phase. 881The PPp prompt indicates that 882.Nm 883has entered the network phase. 884The PPP prompt indicates that 885.Nm 886has successfully negotiated a network layer protocol and is in 887a usable state. 888.Pp 889If the 890.Pa /etc/ppp/ppp.linkup 891file is available, its contents are executed 892when the 893.Em PPP 894connection is established. 895See the provided 896.Dq pmdemand 897example in 898.Pa /usr/share/examples/ppp/ppp.conf.sample 899which runs a script in the background after the connection is established 900(refer to the 901.Dq shell 902and 903.Dq bg 904commands below for a description of possible substitution strings). 905Similarly, when a connection is closed, the contents of the 906.Pa /etc/ppp/ppp.linkdown 907file are executed. 908Both of these files have the same format as 909.Pa /etc/ppp/ppp.conf . 910.Pp 911In previous versions of 912.Nm , 913it was necessary to re-add routes such as the default route in the 914.Pa ppp.linkup 915file. 916.Nm 917supports 918.Sq sticky routes , 919where all routes that contain the 920.Dv HISADDR , 921.Dv MYADDR , 922.Dv HISADDR6 923or 924.Dv MYADDR6 925literals will automatically be updated when the values of these variables 926change. 927.Sh BACKGROUND DIALING 928If you want to establish a connection using 929.Nm 930non-interactively (such as from a 931.Xr crontab 5 932entry or an 933.Xr at 1 934job) you should use the 935.Fl background 936option. 937When 938.Fl background 939is specified, 940.Nm 941attempts to establish the connection immediately. 942If multiple phone 943numbers are specified, each phone number will be tried once. 944If the attempt fails, 945.Nm 946exits immediately with a non-zero exit code. 947If it succeeds, then 948.Nm 949becomes a daemon, and returns an exit status of zero to its caller. 950The daemon exits automatically if the connection is dropped by the 951remote system, or it receives a 952.Dv TERM 953signal. 954.Sh DIAL ON DEMAND 955Demand dialing is enabled with the 956.Fl auto 957or 958.Fl ddial 959options. 960You must also specify the destination label in 961.Pa /etc/ppp/ppp.conf 962to use. 963It must contain the 964.Dq set ifaddr 965command to {define} the remote peers IP address. 966(refer to 967.Pa /usr/share/examples/ppp/ppp.conf.sample ) 968.Bd -literal -offset indent 969# ppp -auto pmdemand 970.Ed 971.Pp 972When 973.Fl auto 974or 975.Fl ddial 976is specified, 977.Nm 978runs as a daemon but you can still configure or examine its 979configuration by using the 980.Dq set server 981command in 982.Pa /etc/ppp/ppp.conf , 983(for example, 984.Dq Li "set server +3000 mypasswd" ) 985and connecting to the diagnostic port as follows: 986.Bd -literal -offset indent 987# pppctl 3000 (assuming tun0) 988Password: 989PPP ON awfulhak> show who 990tcp (127.0.0.1:1028) * 991.Ed 992.Pp 993The 994.Dq show who 995command lists users that are currently connected to 996.Nm 997itself. 998If the diagnostic socket is closed or changed to a different 999socket, all connections are immediately dropped. 1000.Pp 1001In 1002.Fl auto 1003mode, when an outgoing packet is detected, 1004.Nm 1005will perform the dialing action (chat script) and try to connect 1006with the peer. 1007In 1008.Fl ddial 1009mode, the dialing action is performed any time the line is found 1010to be down. 1011If the connect fails, the default behaviour is to wait 30 seconds 1012and then attempt to connect when another outgoing packet is detected. 1013This behaviour can be changed using the 1014.Dq set redial 1015command: 1016.Pp 1017.No set redial Ar secs Ns Xo 1018.Oo + Ns Ar inc Ns 1019.Op - Ns Ar max Ns 1020.Oc Ns Op . Ns Ar next 1021.Op Ar attempts 1022.Xc 1023.Pp 1024.Bl -tag -width attempts -compact 1025.It Ar secs 1026is the number of seconds to wait before attempting 1027to connect again. 1028If the argument is the literal string 1029.Sq Li random , 1030the delay period is a random value between 1 and 30 seconds inclusive. 1031.It Ar inc 1032is the number of seconds that 1033.Ar secs 1034should be incremented each time a new dial attempt is made. 1035The timeout reverts to 1036.Ar secs 1037only after a successful connection is established. 1038The default value for 1039.Ar inc 1040is zero. 1041.It Ar max 1042is the maximum number of times 1043.Nm 1044should increment 1045.Ar secs . 1046The default value for 1047.Ar max 1048is 10. 1049.It Ar next 1050is the number of seconds to wait before attempting 1051to dial the next number in a list of numbers (see the 1052.Dq set phone 1053command). 1054The default is 3 seconds. 1055Again, if the argument is the literal string 1056.Sq Li random , 1057the delay period is a random value between 1 and 30 seconds. 1058.It Ar attempts 1059is the maximum number of times to try to connect for each outgoing packet 1060that triggers a dial. 1061The previous value is unchanged if this parameter is omitted. 1062If a value of zero is specified for 1063.Ar attempts , 1064.Nm 1065will keep trying until a connection is made. 1066.El 1067.Pp 1068So, for example: 1069.Bd -literal -offset indent 1070set redial 10.3 4 1071.Ed 1072.Pp 1073will attempt to connect 4 times for each outgoing packet that causes 1074a dial attempt with a 3 second delay between each number and a 10 second 1075delay after all numbers have been tried. 1076If multiple phone numbers 1077are specified, the total number of attempts is still 4 (it does not 1078attempt each number 4 times). 1079.Pp 1080Alternatively, 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.d/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 across 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.Bd -literal -offset indent 2520mp: 2521 set timeout 0 2522 set log phase chat 2523 set device /dev/cuaa0 /dev/cuaa1 /dev/cuaa2 2524 set phone "123456789" 2525 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \\"\\" ATZ \e 2526 OK-AT-OK \\\\dATDT\\\\T TIMEOUT 45 CONNECT" 2527 set login 2528 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0 2529 set authname ppp 2530 set authkey ppppassword 2531 2532 set mrru 1500 2533 clone 1,2,3 # Create 3 new links - duplicates of the default 2534 link deflink remove # Delete the default link (called ``deflink'') 2535.Ed 2536.Pp 2537Note how all cloning is done at the end of the configuration. 2538Usually, the link will be configured first, then cloned. 2539If you wish all links 2540to be up all the time, you can add the following line to the end of your 2541configuration. 2542.Bd -literal -offset indent 2543 link 1,2,3 set mode ddial 2544.Ed 2545.Pp 2546If you want the links to dial on demand, this command could be used: 2547.Bd -literal -offset indent 2548 link * set mode auto 2549.Ed 2550.Pp 2551Links may be tied to specific names by removing the 2552.Dq set device 2553line above, and specifying the following after the 2554.Dq clone 2555command: 2556.Bd -literal -offset indent 2557 link 1 set device /dev/cuaa0 2558 link 2 set device /dev/cuaa1 2559 link 3 set device /dev/cuaa2 2560.Ed 2561.Pp 2562Use the 2563.Dq help 2564command to see which commands require context (using the 2565.Dq link 2566command), which have optional 2567context and which should not have any context. 2568.Pp 2569When 2570.Nm 2571has negotiated 2572.Em MULTI-LINK 2573mode with the peer, it creates a local domain socket in the 2574.Pa /var/run 2575directory. 2576This socket is used to pass link information (including 2577the actual link file descriptor) between different 2578.Nm 2579invocations. 2580This facilitates 2581.Nm Ns No 's 2582ability to be run from a 2583.Xr getty 8 2584or directly from 2585.Pa /etc/gettydefs 2586(using the 2587.Sq pp= 2588capability), without needing to have initial control of the serial 2589line. 2590Once 2591.Nm 2592negotiates multi-link mode, it will pass its open link to any 2593already running process. 2594If there is no already running process, 2595.Nm 2596will act as the master, creating the socket and listening for new 2597connections. 2598.Sh PPP COMMAND LIST 2599This section lists the available commands and their effect. 2600They are usable either from an interactive 2601.Nm 2602session, from a configuration file or from a 2603.Xr pppctl 8 2604or 2605.Xr telnet 1 2606session. 2607.Bl -tag -width 2n 2608.It accept|deny|enable|disable Ar option.... 2609These directives tell 2610.Nm 2611how to negotiate the initial connection with the peer. 2612Each 2613.Dq option 2614has a default of either accept or deny and enable or disable. 2615.Dq Accept 2616means that the option will be ACK'd if the peer asks for it. 2617.Dq Deny 2618means that the option will be NAK'd if the peer asks for it. 2619.Dq Enable 2620means that the option will be requested by us. 2621.Dq Disable 2622means that the option will not be requested by us. 2623.Pp 2624.Dq Option 2625may be one of the following: 2626.Bl -tag -width 2n 2627.It acfcomp 2628Default: Enabled and Accepted. 2629ACFComp stands for Address and Control Field Compression. 2630Non LCP packets will usually have an address 2631field of 0xff (the All-Stations address) and a control field of 26320x03 (the Unnumbered Information command). 2633If this option is 2634negotiated, these two bytes are simply not sent, thus minimising 2635traffic. 2636.Pp 2637See 2638.Pa rfc1662 2639for details. 2640.It chap Ns Op \&05 2641Default: Disabled and Accepted. 2642CHAP stands for Challenge Handshake Authentication Protocol. 2643Only one of CHAP and PAP (below) may be negotiated. 2644With CHAP, the authenticator sends a "challenge" message to its peer. 2645The peer uses a one-way hash function to encrypt the 2646challenge and sends the result back. 2647The authenticator does the same, and compares the results. 2648The advantage of this mechanism is that no 2649passwords are sent across the connection. 2650A challenge is made when the connection is first made. 2651Subsequent challenges may occur. 2652If you want to have your peer authenticate itself, you must 2653.Dq enable chap . 2654in 2655.Pa /etc/ppp/ppp.conf , 2656and have an entry in 2657.Pa /etc/ppp/ppp.secret 2658for the peer. 2659.Pp 2660When using CHAP as the client, you need only specify 2661.Dq AuthName 2662and 2663.Dq AuthKey 2664in 2665.Pa /etc/ppp/ppp.conf . 2666CHAP is accepted by default. 2667Some 2668.Em PPP 2669implementations use "MS-CHAP" rather than MD5 when encrypting the 2670challenge. 2671MS-CHAP is a combination of MD4 and DES. 2672If 2673.Nm 2674was built on a machine with DES libraries available, it will respond 2675to MS-CHAP authentication requests, but will never request them. 2676.It deflate 2677Default: Enabled and Accepted. 2678This option decides if deflate 2679compression will be used by the Compression Control Protocol (CCP). 2680This is the same algorithm as used by the 2681.Xr gzip 1 2682program. 2683Note: There is a problem negotiating 2684.Ar deflate 2685capabilities with 2686.Xr pppd 8 2687- a 2688.Em PPP 2689implementation available under many operating systems. 2690.Nm pppd 2691(version 2.3.1) incorrectly attempts to negotiate 2692.Ar deflate 2693compression using type 2694.Em 24 2695as the CCP configuration type rather than type 2696.Em 26 2697as specified in 2698.Pa rfc1979 . 2699Type 2700.Ar 24 2701is actually specified as 2702.Dq PPP Magna-link Variable Resource Compression 2703in 2704.Pa rfc1975 ! 2705.Nm 2706is capable of negotiating with 2707.Nm pppd , 2708but only if 2709.Dq deflate24 2710is 2711.Ar enable Ns No d 2712and 2713.Ar accept Ns No ed . 2714.It deflate24 2715Default: Disabled and Denied. 2716This is a variance of the 2717.Ar deflate 2718option, allowing negotiation with the 2719.Xr pppd 8 2720program. 2721Refer to the 2722.Ar deflate 2723section above for details. 2724It is disabled by default as it violates 2725.Pa rfc1975 . 2726.It dns 2727Default: Disabled and Denied. 2728This option allows DNS negotiation. 2729.Pp 2730If 2731.Dq enable Ns No d, 2732.Nm 2733will request that the peer confirms the entries in 2734.Pa /etc/resolv.conf . 2735If the peer NAKs our request (suggesting new IP numbers), 2736.Pa /etc/resolv.conf 2737is updated and another request is sent to confirm the new entries. 2738.Pp 2739If 2740.Dq accept Ns No ed, 2741.Nm 2742will answer any DNS queries requested by the peer rather than rejecting 2743them. 2744The answer is taken from 2745.Pa /etc/resolv.conf 2746unless the 2747.Dq set dns 2748command is used as an override. 2749.It enddisc 2750Default: Enabled and Accepted. 2751This option allows control over whether we 2752negotiate an endpoint discriminator. 2753We only send our discriminator if 2754.Dq set enddisc 2755is used and 2756.Ar enddisc 2757is enabled. 2758We reject the peers discriminator if 2759.Ar enddisc 2760is denied. 2761.It LANMan|chap80lm 2762Default: Disabled and Accepted. 2763The use of this authentication protocol 2764is discouraged as it partially violates the authentication protocol by 2765implementing two different mechanisms (LANMan & NT) under the guise of 2766a single CHAP type (0x80). 2767.Dq LANMan 2768uses a simple DES encryption mechanism and is the least secure of the 2769CHAP alternatives (although is still more secure than PAP). 2770.Pp 2771Refer to the 2772.Dq MSChap 2773description below for more details. 2774.It lqr 2775Default: Disabled and Accepted. 2776This option decides if Link Quality Requests will be sent or accepted. 2777LQR is a protocol that allows 2778.Nm 2779to determine that the link is down without relying on the modems 2780carrier detect. 2781When LQR is enabled, 2782.Nm 2783sends the 2784.Em QUALPROTO 2785option (see 2786.Dq set lqrperiod 2787below) as part of the LCP request. 2788If the peer agrees, both sides will 2789exchange LQR packets at the agreed frequency, allowing detailed link 2790quality monitoring by enabling LQM logging. 2791If the peer doesn't agree, 2792.Nm 2793will send ECHO LQR requests instead. 2794These packets pass no information of interest, but they 2795.Em MUST 2796be replied to by the peer. 2797.Pp 2798Whether using LQR or ECHO LQR, 2799.Nm 2800will abruptly drop the connection if 5 unacknowledged packets have been 2801sent rather than sending a 6th. 2802A message is logged at the 2803.Em PHASE 2804level, and any appropriate 2805.Dq reconnect 2806values are honoured as if the peer were responsible for dropping the 2807connection. 2808.It mppe 2809Default: Enabled and Accepted. 2810This is Microsoft Point to Point Encryption scheme. 2811MPPE key size can be 281240-, 56- and 128-bits. 2813Refer to 2814.Dq set mppe 2815command. 2816.It MSChapV2|chap81 2817Default: Disabled and Accepted. 2818It is very similar to standard CHAP (type 0x05) 2819except that it issues challenges of a fixed 16 bytes in length and uses a 2820combination of MD4, SHA-1 and DES to encrypt the challenge rather than using the 2821standard MD5 mechanism. 2822.It MSChap|chap80nt 2823Default: Disabled and Accepted. 2824The use of this authentication protocol 2825is discouraged as it partially violates the authentication protocol by 2826implementing two different mechanisms (LANMan & NT) under the guise of 2827a single CHAP type (0x80). 2828It is very similar to standard CHAP (type 0x05) 2829except that it issues challenges of a fixed 8 bytes in length and uses a 2830combination of MD4 and DES to encrypt the challenge rather than using the 2831standard MD5 mechanism. 2832CHAP type 0x80 for LANMan is also supported - see 2833.Dq enable LANMan 2834for details. 2835.Pp 2836Because both 2837.Dq LANMan 2838and 2839.Dq NT 2840use CHAP type 0x80, when acting as authenticator with both 2841.Dq enable Ns No d , 2842.Nm 2843will rechallenge the peer up to three times if it responds using the wrong 2844one of the two protocols. 2845This gives the peer a chance to attempt using both protocols. 2846.Pp 2847Conversely, when 2848.Nm 2849acts as the authenticatee with both protocols 2850.Dq accept Ns No ed , 2851the protocols are used alternately in response to challenges. 2852.Pp 2853Note: If only LANMan is enabled, 2854.Xr pppd 8 2855(version 2.3.5) misbehaves when acting as authenticatee. 2856It provides both 2857the NT and the LANMan answers, but also suggests that only the NT answer 2858should be used. 2859.It pap 2860Default: Disabled and Accepted. 2861PAP stands for Password Authentication Protocol. 2862Only one of PAP and CHAP (above) may be negotiated. 2863With PAP, the ID and Password are sent repeatedly to the peer until 2864authentication is acknowledged or the connection is terminated. 2865This is a rather poor security mechanism. 2866It is only performed when the connection is first established. 2867If you want to have your peer authenticate itself, you must 2868.Dq enable pap . 2869in 2870.Pa /etc/ppp/ppp.conf , 2871and have an entry in 2872.Pa /etc/ppp/ppp.secret 2873for the peer (although see the 2874.Dq passwdauth 2875and 2876.Dq set radius 2877options below). 2878.Pp 2879When using PAP as the client, you need only specify 2880.Dq AuthName 2881and 2882.Dq AuthKey 2883in 2884.Pa /etc/ppp/ppp.conf . 2885PAP is accepted by default. 2886.It pred1 2887Default: Enabled and Accepted. 2888This option decides if Predictor 1 2889compression will be used by the Compression Control Protocol (CCP). 2890.It protocomp 2891Default: Enabled and Accepted. 2892This option is used to negotiate 2893PFC (Protocol Field Compression), a mechanism where the protocol 2894field number is reduced to one octet rather than two. 2895.It shortseq 2896Default: Enabled and Accepted. 2897This option determines if 2898.Nm 2899will request and accept requests for short 2900(12 bit) 2901sequence numbers when negotiating multi-link mode. 2902This is only applicable if our MRRU is set (thus enabling multi-link). 2903.It vjcomp 2904Default: Enabled and Accepted. 2905This option determines if Van Jacobson header compression will be used. 2906.El 2907.Pp 2908The following options are not actually negotiated with the peer. 2909Therefore, accepting or denying them makes no sense. 2910.Bl -tag -width 2n 2911.It filter-decapsulation 2912Default: Disabled. 2913When this option is enabled, 2914.Nm 2915will examine UDP frames to see if they actually contain a 2916.Em PPP 2917frame as their payload. 2918If this is the case, all filters will operate on the payload rather 2919than the actual packet. 2920.Pp 2921This is useful if you want to send PPPoUDP traffic over a 2922.Em PPP 2923link, but want that link to do smart things with the real data rather than 2924the UDP wrapper. 2925.Pp 2926The UDP frame payload must not be compressed in any way, otherwise 2927.Nm 2928will not be able to interpret it. 2929It's therefore recommended that you 2930.Ic disable vj pred1 deflate 2931and 2932.Ic deny vj pred1 deflate 2933in the configuration for the 2934.Nm 2935invocation with the udp link. 2936.It idcheck 2937Default: Enabled. 2938When 2939.Nm 2940exchanges low-level LCP, CCP and IPCP configuration traffic, the 2941.Em Identifier 2942field of any replies is expected to be the same as that of the request. 2943By default, 2944.Nm 2945drops any reply packets that do not contain the expected identifier 2946field, reporting the fact at the respective log level. 2947If 2948.Ar idcheck 2949is disabled, 2950.Nm 2951will ignore the identifier field. 2952.It iface-alias 2953Default: Enabled if 2954.Fl nat 2955is specified. 2956This option simply tells 2957.Nm 2958to add new interface addresses to the interface rather than replacing them. 2959The option can only be enabled if network address translation is enabled 2960.Pq Dq nat enable yes . 2961.Pp 2962With this option enabled, 2963.Nm 2964will pass traffic for old interface addresses through the NAT 2965ifdef({LOCALNAT},{engine,},{engine 2966(see 2967.Xr libalias 3 ) ,}) 2968resulting in the ability (in 2969.Fl auto 2970mode) to properly connect the process that caused the PPP link to 2971come up in the first place. 2972.Pp 2973Disabling NAT with 2974.Dq nat enable no 2975will also disable 2976.Sq iface-alias . 2977.It ipcp 2978Default: Enabled. 2979This option allows 2980.Nm 2981to attempt to negotiate IP control protocol capabilities and if 2982successful to exchange IP datagrams with the peer. 2983.It ipv6cp 2984Default: Enabled. 2985This option allows 2986.Nm 2987to attempt to negotiate IPv6 control protocol capabilities and if 2988successful to exchange IPv6 datagrams with the peer. 2989.It keep-session 2990Default: Disabled. 2991When 2992.Nm 2993runs as a Multi-link server, a different 2994.Nm 2995instance initially receives each connection. 2996After determining that 2997the link belongs to an already existing bundle (controlled by another 2998.Nm 2999invocation), 3000.Nm 3001will transfer the link to that process. 3002.Pp 3003If the link is a tty device or if this option is enabled, 3004.Nm 3005will not exit, but will change its process name to 3006.Dq session owner 3007and wait for the controlling 3008.Nm 3009to finish with the link and deliver a signal back to the idle process. 3010This prevents the confusion that results from 3011.Nm Ns No 's 3012parent considering the link resource available again. 3013.Pp 3014For tty devices that have entries in 3015.Pa /etc/ttys , 3016this is necessary to prevent another 3017.Xr getty 8 3018from being started, and for program links such as 3019.Xr sshd 8 , 3020it prevents 3021.Xr sshd 8 3022from exiting due to the death of its child. 3023As 3024.Nm 3025cannot determine its parents requirements (except for the tty case), this 3026option must be enabled manually depending on the circumstances. 3027.It loopback 3028Default: Enabled. 3029When 3030.Ar loopback 3031is enabled, 3032.Nm 3033will automatically loop back packets being sent 3034out with a destination address equal to that of the 3035.Em PPP 3036interface. 3037If disabled, 3038.Nm 3039will send the packet, probably resulting in an ICMP redirect from 3040the other end. 3041It is convenient to have this option enabled when 3042the interface is also the default route as it avoids the necessity 3043of a loopback route. 3044.It passwdauth 3045Default: Disabled. 3046Enabling this option will tell the PAP authentication 3047code to use the password database (see 3048.Xr passwd 5 ) 3049to authenticate the caller if they cannot be found in the 3050.Pa /etc/ppp/ppp.secret 3051file. 3052.Pa /etc/ppp/ppp.secret 3053is always checked first. 3054If you wish to use passwords from 3055.Xr passwd 5 , 3056but also to specify an IP number or label for a given client, use 3057.Dq \&* 3058as the client password in 3059.Pa /etc/ppp/ppp.secret . 3060.It proxy 3061Default: Disabled. 3062Enabling this option will tell 3063.Nm 3064to proxy ARP for the peer. 3065This means that 3066.Nm 3067will make an entry in the ARP table using 3068.Dv HISADDR 3069and the 3070.Dv MAC 3071address of the local network in which 3072.Dv HISADDR 3073appears. 3074This allows other machines connected to the LAN to talk to 3075the peer as if the peer itself was connected to the LAN. 3076The proxy entry cannot be made unless 3077.Dv HISADDR 3078is an address from a LAN. 3079.It proxyall 3080Default: Disabled. 3081Enabling this will tell 3082.Nm 3083to add proxy arp entries for every IP address in all class C or 3084smaller subnets routed via the tun interface. 3085.Pp 3086Proxy arp entries are only made for sticky routes that are added 3087using the 3088.Dq add 3089command. 3090No proxy arp entries are made for the interface address itself 3091(as created by the 3092.Dq set ifaddr 3093command). 3094.It sroutes 3095Default: Enabled. 3096When the 3097.Dq add 3098command is used with the 3099.Dv HISADDR , 3100.Dv MYADDR , 3101.Dv HISADDR6 3102or 3103.Dv MYADDR6 3104values, entries are stored in the 3105.Sq sticky route 3106list. 3107Each time these variables change, this list is re-applied to the routing table. 3108.Pp 3109Disabling this option will prevent the re-application of sticky routes, 3110although the 3111.Sq stick route 3112list will still be maintained. 3113.It Op tcp Ns Xo 3114.No mssfixup 3115.Xc 3116Default: Enabled. 3117This option tells 3118.Nm 3119to adjust TCP SYN packets so that the maximum receive segment 3120size is not greater than the amount allowed by the interface MTU. 3121.It throughput 3122Default: Enabled. 3123This option tells 3124.Nm 3125to gather throughput statistics. 3126Input and output is sampled over 3127a rolling 5 second window, and current, best and total figures are retained. 3128This data is output when the relevant 3129.Em PPP 3130layer shuts down, and is also available using the 3131.Dq show 3132command. 3133Throughput statistics are available at the 3134.Dq IPCP 3135and 3136.Dq physical 3137levels. 3138.It utmp 3139Default: Enabled. 3140Normally, when a user is authenticated using PAP or CHAP, and when 3141.Nm 3142is running in 3143.Fl direct 3144mode, an entry is made in the utmp and wtmp files for that user. 3145Disabling this option will tell 3146.Nm 3147not to make any utmp or wtmp entries. 3148This is usually only necessary if 3149you require the user to both login and authenticate themselves. 3150.El 3151.Pp 3152.It add Ns Xo 3153.Op !\& 3154.Ar dest Ns Op / Ns Ar nn 3155.Op Ar mask 3156.Op Ar gateway 3157.Xc 3158.Ar Dest 3159is the destination IP address. 3160The netmask is specified either as a number of bits with 3161.Ar /nn 3162or as an IP number using 3163.Ar mask . 3164.Ar 0 0 3165or simply 3166.Ar 0 3167with no mask refers to the default route. 3168It is also possible to use the literal name 3169.Sq default 3170instead of 3171.Ar 0 . 3172.Ar Gateway 3173is the next hop gateway to get to the given 3174.Ar dest 3175machine/network. 3176Refer to the 3177.Xr route 8 3178command for further details. 3179.Pp 3180It is possible to use the symbolic names 3181.Sq MYADDR , 3182.Sq HISADDR , 3183.Sq MYADDR6 3184or 3185.Sq HISADDR6 3186as the destination, and 3187.Sq HISADDR 3188or 3189.Sq HISADDR6 3190as the 3191.Ar gateway . 3192.Sq MYADDR 3193is replaced with the interface IP address, 3194.Sq HISADDR 3195is replaced with the interface IP destination (peer) address, 3196.Sq MYADDR6 3197is replaced with the interface IPv6 address, and 3198.Sq HISADDR6 3199is replaced with the interface IPv6 destination address, 3200.Pp 3201If the 3202.Ar add!\& 3203command is used 3204(note the trailing 3205.Dq !\& ) , 3206then if the route already exists, it will be updated as with the 3207.Sq route change 3208command (see 3209.Xr route 8 3210for further details). 3211.Pp 3212Routes that contain the 3213.Dq HISADDR , 3214.Dq MYADDR , 3215.Dq HISADDR6 , 3216.Dq MYADDR6 , 3217.Dq DNS0 , 3218or 3219.Dq DNS1 3220constants are considered 3221.Sq sticky . 3222They are stored in a list (use 3223.Dq show ncp 3224to see the list), and each time the value of one of these variables 3225changes, the appropriate routing table entries are updated. 3226This facility may be disabled using 3227.Dq disable sroutes . 3228.It allow Ar command Op Ar args 3229This command controls access to 3230.Nm 3231and its configuration files. 3232It is possible to allow user-level access, 3233depending on the configuration file label and on the mode that 3234.Nm 3235is being run in. 3236For example, you may wish to configure 3237.Nm 3238so that only user 3239.Sq fred 3240may access label 3241.Sq fredlabel 3242in 3243.Fl background 3244mode. 3245.Pp 3246User id 0 is immune to these commands. 3247.Bl -tag -width 2n 3248.It allow user Ns Xo 3249.Op s 3250.Ar logname Ns No ... 3251.Xc 3252By default, only user id 0 is allowed access to 3253.Nm . 3254If this command is used, all of the listed users are allowed access to 3255the section in which the 3256.Dq allow users 3257command is found. 3258The 3259.Sq default 3260section is always checked first (even though it is only ever automatically 3261loaded at startup). 3262.Dq allow users 3263commands are cumulative in a given section, but users allowed in any given 3264section override users allowed in the default section, so it's possible to 3265allow users access to everything except a given label by specifying default 3266users in the 3267.Sq default 3268section, and then specifying a new user list for that label. 3269.Pp 3270If user 3271.Sq * 3272is specified, access is allowed to all users. 3273.It allow mode Ns Xo 3274.Op s 3275.Ar mode Ns No ... 3276.Xc 3277By default, access using any 3278.Nm 3279mode is possible. 3280If this command is used, it restricts the access 3281.Ar modes 3282allowed to load the label under which this command is specified. 3283Again, as with the 3284.Dq allow users 3285command, each 3286.Dq allow modes 3287command overrides any previous settings, and the 3288.Sq default 3289section is always checked first. 3290.Pp 3291Possible modes are: 3292.Sq interactive , 3293.Sq auto , 3294.Sq direct , 3295.Sq dedicated , 3296.Sq ddial , 3297.Sq background 3298and 3299.Sq * . 3300.Pp 3301When running in multi-link mode, a section can be loaded if it allows 3302.Em any 3303of the currently existing line modes. 3304.El 3305.Pp 3306.It nat Ar command Op Ar args 3307This command allows the control of the network address translation (also 3308known as masquerading or IP aliasing) facilities that are built into 3309.Nm . 3310NAT is done on the external interface only, and is unlikely to make sense 3311if used with the 3312.Fl direct 3313flag. 3314.Pp 3315If nat is enabled on your system (it may be omitted at compile time), 3316the following commands are possible: 3317.Bl -tag -width 2n 3318.It nat enable yes|no 3319This command either switches network address translation on or turns it off. 3320The 3321.Fl nat 3322command line flag is synonymous with 3323.Dq nat enable yes . 3324.It nat addr Op Ar addr_local addr_alias 3325This command allows data for 3326.Ar addr_alias 3327to be redirected to 3328.Ar addr_local . 3329It is useful if you own a small number of real IP numbers that 3330you wish to map to specific machines behind your gateway. 3331.It nat deny_incoming yes|no 3332If set to yes, this command will refuse all incoming packets where an 3333aliasing link doesn't already exist. 3334ifdef({LOCALNAT},{},{Refer to the 3335.Sx CONCEPTUAL BACKGROUND 3336section of 3337.Xr libalias 3 3338for a description of what an 3339.Dq aliasing link 3340is. 3341})dnl 3342.Pp 3343It should be noted under what circumstances an aliasing link is 3344ifdef({LOCALNAT},{created.},{created by 3345.Xr libalias 3 .}) 3346It may be necessary to further protect your network from outside 3347connections using the 3348.Dq set filter 3349or 3350.Dq nat target 3351commands. 3352.It nat help|? 3353This command gives a summary of available nat commands. 3354.It nat log yes|no 3355This option causes various NAT statistics and information to 3356be logged to the file 3357.Pa /var/log/alias.log . 3358.It nat port Ar proto Ar targetIP Ns Xo 3359.No : Ns Ar targetPort Ns 3360.Oo 3361.No - Ns Ar targetPort 3362.Oc Ar aliasPort Ns 3363.Oo 3364.No - Ns Ar aliasPort 3365.Oc Oo Ar remoteIP : Ns 3366.Ar remotePort Ns 3367.Oo 3368.No - Ns Ar remotePort 3369.Oc Ns 3370.Oc 3371.Xc 3372This command causes incoming 3373.Ar proto 3374connections to 3375.Ar aliasPort 3376to be redirected to 3377.Ar targetPort 3378on 3379.Ar targetIP . 3380.Ar proto 3381is either 3382.Dq tcp 3383or 3384.Dq udp . 3385.Pp 3386A range of port numbers may be specified as shown above. 3387The ranges must be of the same size. 3388.Pp 3389If 3390.Ar remoteIP 3391is specified, only data coming from that IP number is redirected. 3392.Ar remotePort 3393must either be 3394.Dq 0 3395(indicating any source port) 3396or a range of ports the same size as the other ranges. 3397.Pp 3398This option is useful if you wish to run things like Internet phone on 3399machines behind your gateway, but is limited in that connections to only 3400one interior machine per source machine and target port are possible. 3401.It nat proto Ar proto localIP Oo 3402.Ar publicIP Op Ar remoteIP 3403.Oc 3404This command tells 3405.Nm 3406to redirect packets of protocol type 3407.Ar proto 3408(see 3409.Xr protocols 5 ) 3410to the internal address 3411.Ar localIP . 3412.Pp 3413If 3414.Ar publicIP 3415is specified, only packets destined for that address are matched, 3416otherwise the default alias address is used. 3417.Pp 3418If 3419.Ar remoteIP 3420is specified, only packets matching that source address are matched, 3421.Pp 3422This command is useful for redirecting tunnel endpoints to an internal machine, 3423for example: 3424.Pp 3425.Dl nat proto ipencap 10.0.0.1 3426.It "nat proxy cmd" Ar arg Ns No ... 3427This command tells 3428.Nm 3429to proxy certain connections, redirecting them to a given server. 3430ifdef({LOCALNAT},{},{Refer to the description of 3431.Fn PacketAliasProxyRule 3432in 3433.Xr libalias 3 3434for details of the available commands. 3435})dnl 3436.It nat punch_fw Op Ar base count 3437This command tells 3438.Nm 3439to punch holes in the firewall for FTP or IRC DCC connections. 3440This is done dynamically by installing temporary firewall rules which 3441allow a particular connection (and only that connection) to go through 3442the firewall. 3443The rules are removed once the corresponding connection terminates. 3444.Pp 3445A maximum of 3446.Ar count 3447rules starting from rule number 3448.Ar base 3449will be used for punching firewall holes. 3450The range will be cleared when the 3451.Dq nat punch_fw 3452command is run. 3453.Pp 3454If no arguments are given, firewall punching is disabled. 3455.It nat same_ports yes|no 3456When enabled, this command will tell the network address translation engine to 3457attempt to avoid changing the port number on outgoing packets. 3458This is useful 3459if you want to support protocols such as RPC and LPD which require 3460connections to come from a well known port. 3461.It nat target Op Ar address 3462Set the given target address or clear it if no address is given. 3463The target address is used 3464ifdef({LOCALNAT},{},{by libalias })dnl 3465to specify how to NAT incoming packets by default. 3466If a target address is not set or if 3467.Dq default 3468is given, packets are not altered and are allowed to route to the internal 3469network. 3470.Pp 3471The target address may be set to 3472.Dq MYADDR , 3473in which case 3474ifdef({LOCALNAT},{all packets will be redirected}, 3475{libalias will redirect all packets}) 3476to the interface address. 3477.It nat use_sockets yes|no 3478When enabled, this option tells the network address translation engine to 3479create a socket so that it can guarantee a correct incoming ftp data or 3480IRC connection. 3481.It nat unregistered_only yes|no 3482Only alter outgoing packets with an unregistered source address. 3483According to RFC 1918, unregistered source addresses 3484are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16. 3485.El 3486.Pp 3487These commands are also discussed in the file 3488.Pa README.nat 3489which comes with the source distribution. 3490.Pp 3491.It Op !\& Ns Xo 3492.No bg Ar command 3493.Xc 3494The given 3495.Ar command 3496is executed in the background with the following words replaced: 3497.Bl -tag -width COMPILATIONDATE 3498.It Li AUTHNAME 3499This is replaced with the local 3500.Ar authname 3501value. 3502See the 3503.Dq set authname 3504command below. 3505.It Li COMPILATIONDATE 3506This is replaced with the date on which 3507.Nm 3508was compiled. 3509.It Li DNS0 & DNS1 3510These are replaced with the primary and secondary nameserver IP numbers. 3511If nameservers are negotiated by IPCP, the values of these macros will change. 3512.It Li ENDDISC 3513This is replaced with the local endpoint discriminator value. 3514See the 3515.Dq set enddisc 3516command below. 3517.It Li HISADDR 3518This is replaced with the peers IP number. 3519.It Li HISADDR6 3520This is replaced with the peers IPv6 number. 3521.It Li INTERFACE 3522This is replaced with the name of the interface that's in use. 3523.It Li IPOCTETSIN 3524This is replaced with the number of IP bytes received since the connection 3525was established. 3526.It Li IPOCTETSOUT 3527This is replaced with the number of IP bytes sent since the connection 3528was established. 3529.It Li IPPACKETSIN 3530This is replaced with the number of IP packets received since the connection 3531was established. 3532.It Li IPPACKETSOUT 3533This is replaced with the number of IP packets sent since the connection 3534was established. 3535.It Li IPV6OCTETSIN 3536This is replaced with the number of IPv6 bytes received since the connection 3537was established. 3538.It Li IPV6OCTETSOUT 3539This is replaced with the number of IPv6 bytes sent since the connection 3540was established. 3541.It Li IPV6PACKETSIN 3542This is replaced with the number of IPv6 packets received since the connection 3543was established. 3544.It Li IPV6PACKETSOUT 3545This is replaced with the number of IPv6 packets sent since the connection 3546was established. 3547.It Li LABEL 3548This is replaced with the last label name used. 3549A label may be specified on the 3550.Nm 3551command line, via the 3552.Dq load 3553or 3554.Dq dial 3555commands and in the 3556.Pa ppp.secret 3557file. 3558.It Li MYADDR 3559This is replaced with the IP number assigned to the local interface. 3560.It Li MYADDR6 3561This is replaced with the IPv6 number assigned to the local interface. 3562.It Li OCTETSIN 3563This is replaced with the number of bytes received since the connection 3564was established. 3565.It Li OCTETSOUT 3566This is replaced with the number of bytes sent since the connection 3567was established. 3568.It Li PACKETSIN 3569This is replaced with the number of packets received since the connection 3570was established. 3571.It Li PACKETSOUT 3572This is replaced with the number of packets sent since the connection 3573was established. 3574.It Li PEER_ENDDISC 3575This is replaced with the value of the peers endpoint discriminator. 3576.It Li PROCESSID 3577This is replaced with the current process id. 3578.It Li SOCKNAME 3579This is replaced with the name of the diagnostic socket. 3580.It Li UPTIME 3581This is replaced with the bundle uptime in HH:MM:SS format. 3582.It Li USER 3583This is replaced with the username that has been authenticated with PAP or 3584CHAP. 3585Normally, this variable is assigned only in -direct mode. 3586This value is available irrespective of whether utmp logging is enabled. 3587.It Li VERSION 3588This is replaced with the current version number of 3589.Nm . 3590.El 3591.Pp 3592These substitutions are also done by the 3593.Dq set proctitle , 3594.Dq ident 3595and 3596.Dq log 3597commands. 3598.Pp 3599If you wish to pause 3600.Nm 3601while the command executes, use the 3602.Dq shell 3603command instead. 3604.It clear physical|ipcp|ipv6 Op current|overall|peak... 3605Clear the specified throughput values at either the 3606.Dq physical , 3607.Dq ipcp 3608or 3609.Dq ipv6cp 3610level. 3611If 3612.Dq physical 3613is specified, context must be given (see the 3614.Dq link 3615command below). 3616If no second argument is given, all values are cleared. 3617.It clone Ar name Ns Xo 3618.Op \&, Ns Ar name Ns 3619.No ... 3620.Xc 3621Clone the specified link, creating one or more new links according to the 3622.Ar name 3623argument(s). 3624This command must be used from the 3625.Dq link 3626command below unless you've only got a single link (in which case that 3627link becomes the default). 3628Links may be removed using the 3629.Dq remove 3630command below. 3631.Pp 3632The default link name is 3633.Dq deflink . 3634.It close Op lcp|ccp Ns Op !\& 3635If no arguments are given, the relevant protocol layers will be brought 3636down and the link will be closed. 3637If 3638.Dq lcp 3639is specified, the LCP layer is brought down, but 3640.Nm 3641will not bring the link offline. 3642It is subsequently possible to use 3643.Dq term 3644(see below) 3645to talk to the peer machine if, for example, something like 3646.Dq slirp 3647is being used. 3648If 3649.Dq ccp 3650is specified, only the relevant compression layer is closed. 3651If the 3652.Dq !\& 3653is used, the compression layer will remain in the closed state, otherwise 3654it will re-enter the STOPPED state, waiting for the peer to initiate 3655further CCP negotiation. 3656In any event, this command does not disconnect the user from 3657.Nm 3658or exit 3659.Nm . 3660See the 3661.Dq quit 3662command below. 3663.It delete Ns Xo 3664.Op !\& 3665.Ar dest 3666.Xc 3667This command deletes the route with the given 3668.Ar dest 3669IP address. 3670If 3671.Ar dest 3672is specified as 3673.Sq ALL , 3674all non-direct entries in the routing table for the current interface, 3675and all 3676.Sq sticky route 3677entries are deleted. 3678If 3679.Ar dest 3680is specified as 3681.Sq default , 3682the default route is deleted. 3683.Pp 3684If the 3685.Ar delete!\& 3686command is used 3687(note the trailing 3688.Dq !\& ) , 3689.Nm 3690will not complain if the route does not already exist. 3691.It dial|call Op Ar label Ns Xo 3692.No ... 3693.Xc 3694This command is the equivalent of 3695.Dq load label 3696followed by 3697.Dq open , 3698and is provided for backwards compatibility. 3699.It down Op Ar lcp|ccp 3700Bring the relevant layer down ungracefully, as if the underlying layer 3701had become unavailable. 3702It's not considered polite to use this command on 3703a Finite State Machine that's in the OPEN state. 3704If no arguments are 3705supplied, the entire link is closed (or if no context is given, all links 3706are terminated). 3707If 3708.Sq lcp 3709is specified, the 3710.Em LCP 3711layer is terminated but the device is not brought offline and the link 3712is not closed. 3713If 3714.Sq ccp 3715is specified, only the relevant compression layer(s) are terminated. 3716.It help|? Op Ar command 3717Show a list of available commands. 3718If 3719.Ar command 3720is specified, show the usage string for that command. 3721.It ident Op Ar text Ns No ... 3722Identify the link to the peer using 3723.Ar text . 3724If 3725.Ar text 3726is empty, link identification is disabled. 3727It is possible to use any of the words described for the 3728.Ic bg 3729command above. 3730Refer to the 3731.Ic sendident 3732command for details of when 3733.Nm 3734identifies itself to the peer. 3735.It iface Ar command Op args 3736This command is used to control the interface used by 3737.Nm . 3738.Ar Command 3739may be one of the following: 3740.Bl -tag -width 2n 3741.It iface add Ns Xo 3742.Op !\& 3743.Ar addr Ns Op / Ns Ar bits 3744.Op Ar peer 3745.Xc 3746.It iface add Ns Xo 3747.Op !\& 3748.Ar addr 3749.Ar mask 3750.Ar peer 3751.Xc 3752Add the given 3753.Ar addr mask peer 3754combination to the interface. 3755Instead of specifying 3756.Ar mask , 3757.Ar /bits 3758can be used 3759(with no space between it and 3760.Ar addr ) . 3761If the given address already exists, the command fails unless the 3762.Dq !\& 3763is used - in which case the previous interface address entry is overwritten 3764with the new one, allowing a change of netmask or peer address. 3765.Pp 3766If only 3767.Ar addr 3768is specified, 3769.Ar bits 3770defaults to 3771.Dq 32 3772and 3773.Ar peer 3774defaults to 3775.Dq 255.255.255.255 . 3776This address (the broadcast address) is the only duplicate peer address that 3777.Nm 3778allows. 3779.It iface clear Op INET | INET6 3780If this command is used while 3781.Nm 3782is in the OPENED state or while in 3783.Fl auto 3784mode, all addresses except for the NCP negotiated address are deleted 3785from the interface. 3786If 3787.Nm 3788is not in the OPENED state and is not in 3789.Fl auto 3790mode, all interface addresses are deleted. 3791.Pp 3792If the INET or INET6 arguments are used, only addresses for that address 3793family are cleared. 3794.Pp 3795.It iface delete Ns Xo 3796.Op !\& Ns 3797.No |rm Ns Op !\& 3798.Ar addr 3799.Xc 3800This command deletes the given 3801.Ar addr 3802from the interface. 3803If the 3804.Dq !\& 3805is used, no error is given if the address isn't currently assigned to 3806the interface (and no deletion takes place). 3807.It iface show 3808Shows the current state and current addresses for the interface. 3809It is much the same as running 3810.Dq ifconfig INTERFACE . 3811.It iface help Op Ar sub-command 3812This command, when invoked without 3813.Ar sub-command , 3814will show a list of possible 3815.Dq iface 3816sub-commands and a brief synopsis for each. 3817When invoked with 3818.Ar sub-command , 3819only the synopsis for the given sub-command is shown. 3820.El 3821.It Op data Ns Xo 3822.No link 3823.Ar name Ns Op , Ns Ar name Ns 3824.No ... Ar command Op Ar args 3825.Xc 3826This command may prefix any other command if the user wishes to 3827specify which link the command should affect. 3828This is only applicable after multiple links have been created in Multi-link 3829mode using the 3830.Dq clone 3831command. 3832.Pp 3833.Ar Name 3834specifies the name of an existing link. 3835If 3836.Ar name 3837is a comma separated list, 3838.Ar command 3839is executed on each link. 3840If 3841.Ar name 3842is 3843.Dq * , 3844.Ar command 3845is executed on all links. 3846.It load Op Ar label Ns Xo 3847.No ... 3848.Xc 3849Load the given 3850.Ar label Ns No (s) 3851from the 3852.Pa ppp.conf 3853file. 3854If 3855.Ar label 3856is not given, the 3857.Ar default 3858label is used. 3859.Pp 3860Unless the 3861.Ar label 3862section uses the 3863.Dq set mode , 3864.Dq open 3865or 3866.Dq dial 3867commands, 3868.Nm 3869will not attempt to make an immediate connection. 3870.It log Ar word Ns No ... 3871Send the given word(s) to the log file with the prefix 3872.Dq LOG: . 3873Word substitutions are done as explained under the 3874.Dq !bg 3875command above. 3876.It open Op lcp|ccp|ipcp 3877This is the opposite of the 3878.Dq close 3879command. 3880All closed links are immediately brought up apart from second and subsequent 3881.Ar demand-dial 3882links - these will come up based on the 3883.Dq set autoload 3884command that has been used. 3885.Pp 3886If the 3887.Dq lcp 3888argument is used while the LCP layer is already open, LCP will be 3889renegotiated. 3890This allows various LCP options to be changed, after which 3891.Dq open lcp 3892can be used to put them into effect. 3893After renegotiating LCP, 3894any agreed authentication will also take place. 3895.Pp 3896If the 3897.Dq ccp 3898argument is used, the relevant compression layer is opened. 3899Again, if it is already open, it will be renegotiated. 3900.Pp 3901If the 3902.Dq ipcp 3903argument is used, the link will be brought up as normal, but if 3904IPCP is already open, it will be renegotiated and the network 3905interface will be reconfigured. 3906.Pp 3907It is probably not good practice to re-open the PPP state machines 3908like this as it's possible that the peer will not behave correctly. 3909It 3910.Em is 3911however useful as a way of forcing the CCP or VJ dictionaries to be reset. 3912.It passwd Ar pass 3913Specify the password required for access to the full 3914.Nm 3915command set. 3916This password is required when connecting to the diagnostic port (see the 3917.Dq set server 3918command). 3919.Ar Pass 3920is specified on the 3921.Dq set server 3922command line. 3923The value of 3924.Ar pass 3925is not logged when 3926.Ar command 3927logging is active, instead, the literal string 3928.Sq ******** 3929is logged. 3930.It quit|bye Op all 3931If 3932.Dq quit 3933is executed from the controlling connection or from a command file, 3934ppp will exit after closing all connections. 3935Otherwise, if the user 3936is connected to a diagnostic socket, the connection is simply dropped. 3937.Pp 3938If the 3939.Ar all 3940argument is given, 3941.Nm 3942will exit despite the source of the command after closing all existing 3943connections. 3944.It remove|rm 3945This command removes the given link. 3946It is only really useful in multi-link mode. 3947A link must be in the 3948.Dv CLOSED 3949state before it is removed. 3950.It rename|mv Ar name 3951This command renames the given link to 3952.Ar name . 3953It will fail if 3954.Ar name 3955is already used by another link. 3956.Pp 3957The default link name is 3958.Sq deflink . 3959Renaming it to 3960.Sq modem , 3961.Sq cuaa0 3962or 3963.Sq USR 3964may make the log file more readable. 3965.It resolv Ar command 3966This command controls 3967.Nm Ns No 's 3968manipulation of the 3969.Xr resolv.conf 5 3970file. 3971When 3972.Nm 3973starts up, it loads the contents of this file into memory and retains this 3974image for future use. 3975.Ar command 3976is one of the following: 3977.Bl -tag -width readonly 3978.It Em readonly 3979Treat 3980.Pa /etc/resolv.conf 3981as read only. 3982If 3983.Dq dns 3984is enabled, 3985.Nm 3986will still attempt to negotiate nameservers with the peer, making the results 3987available via the 3988.Dv DNS0 3989and 3990.Dv DNS1 3991macros. 3992This is the opposite of the 3993.Dq resolv writable 3994command. 3995.It Em reload 3996Reload 3997.Pa /etc/resolv.conf 3998into memory. 3999This may be necessary if for example a DHCP client overwrote 4000.Pa /etc/resolv.conf . 4001.It Em restore 4002Replace 4003.Pa /etc/resolv.conf 4004with the version originally read at startup or with the last 4005.Dq resolv reload 4006command. 4007This is sometimes a useful command to put in the 4008.Pa /etc/ppp/ppp.linkdown 4009file. 4010.It Em rewrite 4011Rewrite the 4012.Pa /etc/resolv.conf 4013file. 4014This command will work even if the 4015.Dq resolv readonly 4016command has been used. 4017It may be useful as a command in the 4018.Pa /etc/ppp/ppp.linkup 4019file if you wish to defer updating 4020.Pa /etc/resolv.conf 4021until after other commands have finished. 4022.It Em writable 4023Allow 4024.Nm 4025to update 4026.Pa /etc/resolv.conf 4027if 4028.Dq dns 4029is enabled and 4030.Nm 4031successfully negotiates a DNS. 4032This is the opposite of the 4033.Dq resolv readonly 4034command. 4035.El 4036.It save 4037This option is not (yet) implemented. 4038.It sendident 4039This command tells 4040.Nm 4041to identify itself to the peer. 4042The link must be in LCP state or higher. 4043If no identity has been set (via the 4044.Ic ident 4045command), 4046.Ic sendident 4047will fail. 4048.Pp 4049When an identity has been set, 4050.Nm 4051will automatically identify itself when it sends or receives a configure 4052reject, when negotiation fails or when LCP reaches the opened state. 4053.Pp 4054Received identification packets are logged to the LCP log (see 4055.Ic set log 4056for details) and are never responded to. 4057.It set Ns Xo 4058.Op up 4059.Ar var value 4060.Xc 4061This option allows the setting of any of the following variables: 4062.Bl -tag -width 2n 4063.It set accmap Ar hex-value 4064ACCMap stands for Asynchronous Control Character Map. 4065This is always 4066negotiated with the peer, and defaults to a value of 00000000 in hex. 4067This protocol is required to defeat hardware that depends on passing 4068certain characters from end to end (such as XON/XOFF etc). 4069.Pp 4070For the XON/XOFF scenario, use 4071.Dq set accmap 000a0000 . 4072.It set Op auth Ns Xo 4073.No key Ar value 4074.Xc 4075This sets the authentication key (or password) used in client mode 4076PAP or CHAP negotiation to the given value. 4077It also specifies the 4078password to be used in the dial or login scripts in place of the 4079.Sq \eP 4080sequence, preventing the actual password from being logged. 4081If 4082.Ar command 4083or 4084.Ar chat 4085logging is in effect, 4086.Ar value 4087is logged as 4088.Sq ******** 4089for security reasons. 4090.Pp 4091If the first character of 4092.Ar value 4093is an exclamation mark 4094.Pq Dq !\& , 4095.Nm 4096treats the remainder of the string as a program that must be executed 4097to determine the 4098.Dq authname 4099and 4100.Dq authkey 4101values. 4102.Pp 4103If the 4104.Dq !\& 4105is doubled up 4106(to 4107.Dq !! ) , 4108it is treated as a single literal 4109.Dq !\& , 4110otherwise, ignoring the 4111.Dq !\& , 4112.Ar value 4113is parsed as a program to execute in the same was as the 4114.Dq !bg 4115command above, substituting special names in the same manner. 4116Once executed, 4117.Nm 4118will feed the program three lines of input, each terminated by a newline 4119character: 4120.Bl -bullet 4121.It 4122The host name as sent in the CHAP challenge. 4123.It 4124The challenge string as sent in the CHAP challenge. 4125.It 4126The locally defined 4127.Dq authname . 4128.El 4129.Pp 4130Two lines of output are expected: 4131.Bl -bullet 4132.It 4133The 4134.Dq authname 4135to be sent with the CHAP response. 4136.It 4137The 4138.Dq authkey , 4139which is encrypted with the challenge and request id, the answer being sent 4140in the CHAP response packet. 4141.El 4142.Pp 4143When configuring 4144.Nm 4145in this manner, it's expected that the host challenge is a series of ASCII 4146digits or characters. 4147An encryption device or Secure ID card is usually 4148required to calculate the secret appropriate for the given challenge. 4149.It set authname Ar id 4150This sets the authentication id used in client mode PAP or CHAP negotiation. 4151.Pp 4152If used in 4153.Fl direct 4154mode with CHAP enabled, 4155.Ar id 4156is used in the initial authentication challenge and should normally be set to 4157the local machine name. 4158.It set autoload Xo 4159.Ar min-percent max-percent period 4160.Xc 4161These settings apply only in multi-link mode and default to zero, zero and 4162five respectively. 4163When more than one 4164.Ar demand-dial 4165(also known as 4166.Fl auto ) 4167mode link is available, only the first link is made active when 4168.Nm 4169first reads data from the tun device. 4170The next 4171.Ar demand-dial 4172link will be opened only when the current bundle throughput is at least 4173.Ar max-percent 4174percent of the total bundle bandwidth for 4175.Ar period 4176seconds. 4177When the current bundle throughput decreases to 4178.Ar min-percent 4179percent or less of the total bundle bandwidth for 4180.Ar period 4181seconds, a 4182.Ar demand-dial 4183link will be brought down as long as it's not the last active link. 4184.Pp 4185Bundle throughput is measured as the maximum of inbound and outbound 4186traffic. 4187.Pp 4188The default values cause 4189.Ar demand-dial 4190links to simply come up one at a time. 4191.Pp 4192Certain devices cannot determine their physical bandwidth, so it 4193is sometimes necessary to use the 4194.Dq set bandwidth 4195command (described below) to make 4196.Dq set autoload 4197work correctly. 4198.It set bandwidth Ar value 4199This command sets the connection bandwidth in bits per second. 4200.Ar value 4201must be greater than zero. 4202It is currently only used by the 4203.Dq set autoload 4204command above. 4205.It set callback Ar option Ns No ... 4206If no arguments are given, callback is disabled, otherwise, 4207.Nm 4208will request (or in 4209.Fl direct 4210mode, will accept) one of the given 4211.Ar option Ns No s . 4212In client mode, if an 4213.Ar option 4214is NAK'd 4215.Nm 4216will request a different 4217.Ar option , 4218until no options remain at which point 4219.Nm 4220will terminate negotiations (unless 4221.Dq none 4222is one of the specified 4223.Ar option ) . 4224In server mode, 4225.Nm 4226will accept any of the given protocols - but the client 4227.Em must 4228request one of them. 4229If you wish callback to be optional, you must {include} 4230.Ar none 4231as an option. 4232.Pp 4233The 4234.Ar option Ns No s 4235are as follows (in this order of preference): 4236.Bl -tag -width Ds 4237.It auth 4238The callee is expected to decide the callback number based on 4239authentication. 4240If 4241.Nm 4242is the callee, the number should be specified as the fifth field of 4243the peers entry in 4244.Pa /etc/ppp/ppp.secret . 4245.It cbcp 4246Microsoft's callback control protocol is used. 4247See 4248.Dq set cbcp 4249below. 4250.Pp 4251If you wish to negotiate 4252.Ar cbcp 4253in client mode but also wish to allow the server to request no callback at 4254CBCP negotiation time, you must specify both 4255.Ar cbcp 4256and 4257.Ar none 4258as callback options. 4259.It E.164 *| Ns Xo 4260.Ar number Ns Op , Ns Ar number Ns 4261.No ... 4262.Xc 4263The caller specifies the 4264.Ar number . 4265If 4266.Nm 4267is the callee, 4268.Ar number 4269should be either a comma separated list of allowable numbers or a 4270.Dq \&* , 4271meaning any number is permitted. 4272If 4273.Nm 4274is the caller, only a single number should be specified. 4275.Pp 4276Note, this option is very unsafe when used with a 4277.Dq \&* 4278as a malicious caller can tell 4279.Nm 4280to call any (possibly international) number without first authenticating 4281themselves. 4282.It none 4283If the peer does not wish to do callback at all, 4284.Nm 4285will accept the fact and continue without callback rather than terminating 4286the connection. 4287This is required (in addition to one or more other callback 4288options) if you wish callback to be optional. 4289.El 4290.Pp 4291.It set cbcp Oo 4292.No *| Ns Ar number Ns Oo 4293.No , Ns Ar number Ns ...\& Oc 4294.Op Ar delay Op Ar retry 4295.Oc 4296If no arguments are given, CBCP (Microsoft's CallBack Control Protocol) 4297is disabled - ie, configuring CBCP in the 4298.Dq set callback 4299command will result in 4300.Nm 4301requesting no callback in the CBCP phase. 4302Otherwise, 4303.Nm 4304attempts to use the given phone 4305.Ar number Ns No (s). 4306.Pp 4307In server mode 4308.Pq Fl direct , 4309.Nm 4310will insist that the client uses one of these numbers, unless 4311.Dq \&* 4312is used in which case the client is expected to specify the number. 4313.Pp 4314In client mode, 4315.Nm 4316will attempt to use one of the given numbers (whichever it finds to 4317be agreeable with the peer), or if 4318.Dq \&* 4319is specified, 4320.Nm 4321will expect the peer to specify the number. 4322.It set cd Oo 4323.No off| Ns Ar seconds Ns Op !\& 4324.Oc 4325Normally, 4326.Nm 4327checks for the existence of carrier depending on the type of device 4328that has been opened: 4329.Bl -tag -width XXX -offset XXX 4330.It Terminal Devices 4331Carrier is checked one second after the login script is complete. 4332If it's not set, 4333.Nm 4334assumes that this is because the device doesn't support carrier (which 4335is true for most 4336.Dq laplink 4337NULL-modem cables), logs the fact and stops checking 4338for carrier. 4339.Pp 4340As ptys don't support the 4341.Dv TIOCMGET 4342ioctl, the tty device will switch all 4343carrier detection off when it detects that the device is a pty. 4344.It ISDN (i4b) Devices 4345Carrier is checked once per second for 6 seconds. 4346If it's not set after 4347the sixth second, the connection attempt is considered to have failed and 4348the device is closed. 4349Carrier is always required for i4b devices. 4350.It PPPoE (netgraph) Devices 4351Carrier is checked once per second for 5 seconds. 4352If it's not set after 4353the fifth second, the connection attempt is considered to have failed and 4354the device is closed. 4355Carrier is always required for PPPoE devices. 4356.El 4357.Pp 4358All other device types don't support carrier. 4359Setting a carrier value will 4360result in a warning when the device is opened. 4361.Pp 4362Some modems take more than one second after connecting to assert the carrier 4363signal. 4364If this delay isn't increased, this will result in 4365.Nm Ns No 's 4366inability to detect when the link is dropped, as 4367.Nm 4368assumes that the device isn't asserting carrier. 4369.Pp 4370The 4371.Dq set cd 4372command overrides the default carrier behaviour. 4373.Ar seconds 4374specifies the maximum number of seconds that 4375.Nm 4376should wait after the dial script has finished before deciding if 4377carrier is available or not. 4378.Pp 4379If 4380.Dq off 4381is specified, 4382.Nm 4383will not check for carrier on the device, otherwise 4384.Nm 4385will not proceed to the login script until either carrier is detected 4386or until 4387.Ar seconds 4388has elapsed, at which point 4389.Nm 4390assumes that the device will not set carrier. 4391.Pp 4392If no arguments are given, carrier settings will go back to their default 4393values. 4394.Pp 4395If 4396.Ar seconds 4397is followed immediately by an exclamation mark 4398.Pq Dq !\& , 4399.Nm 4400will 4401.Em require 4402carrier. 4403If carrier is not detected after 4404.Ar seconds 4405seconds, the link will be disconnected. 4406.It set choked Op Ar timeout 4407This sets the number of seconds that 4408.Nm 4409will keep a choked output queue before dropping all pending output packets. 4410If 4411.Ar timeout 4412is less than or equal to zero or if 4413.Ar timeout 4414isn't specified, it is set to the default value of 4415.Em 120 seconds . 4416.Pp 4417A choked output queue occurs when 4418.Nm 4419has read a certain number of packets from the local network for transmission, 4420but cannot send the data due to link failure (the peer is busy etc.). 4421.Nm 4422will not read packets indefinitely. 4423Instead, it reads up to 4424.Em 30 4425packets (or 4426.Em 30 No + 4427.Em nlinks No * 4428.Em 2 4429packets in multi-link mode), then stops reading the network interface 4430until either 4431.Ar timeout 4432seconds have passed or at least one packet has been sent. 4433.Pp 4434If 4435.Ar timeout 4436seconds pass, all pending output packets are dropped. 4437.It set ctsrts|crtscts on|off 4438This sets hardware flow control. 4439Hardware flow control is 4440.Ar on 4441by default. 4442.It set deflate Ar out-winsize Op Ar in-winsize 4443This sets the DEFLATE algorithms default outgoing and incoming window 4444sizes. 4445Both 4446.Ar out-winsize 4447and 4448.Ar in-winsize 4449must be values between 4450.Em 8 4451and 4452.Em 15 . 4453If 4454.Ar in-winsize 4455is specified, 4456.Nm 4457will insist that this window size is used and will not accept any other 4458values from the peer. 4459.It set dns Op Ar primary Op Ar secondary 4460This command specifies DNS overrides for the 4461.Dq accept dns 4462command. 4463Refer to the 4464.Dq accept 4465command description above for details. 4466This command does not affect the IP numbers requested using 4467.Dq enable dns . 4468.It set device|line Xo 4469.Ar value Ns No ... 4470.Xc 4471This sets the device(s) to which 4472.Nm 4473will talk to the given 4474.Dq value . 4475.Pp 4476All ISDN and serial device names are expected to begin with 4477.Pa /dev/ . 4478ISDN devices are usually called 4479.Pa i4brbchX 4480and serial devices are usually called 4481.Pa cuaXX . 4482.Pp 4483If 4484.Dq value 4485does not begin with 4486.Pa /dev/ , 4487it must either begin with an exclamation mark 4488.Pq Dq !\& , 4489be of the format 4490.No PPPoE: Ns Ar iface Ns Xo 4491.Op \&: Ns Ar provider Ns 4492.Xc 4493(on 4494.Xr netgraph 4 4495enabled systems), or be of the format 4496.Sm off 4497.Ar host : port Op /tcp|udp . 4498.Sm on 4499.Pp 4500If it begins with an exclamation mark, the rest of the device name is 4501treated as a program name, and that program is executed when the device 4502is opened. 4503Standard input, output and error are fed back to 4504.Nm 4505and are read and written as if they were a regular device. 4506.Pp 4507If a 4508.No PPPoE: Ns Ar iface Ns Xo 4509.Op \&: Ns Ar provider Ns 4510.Xc 4511specification is given, 4512.Nm 4513will attempt to create a 4514.Em PPP 4515over Ethernet connection using the given 4516.Ar iface 4517interface by using 4518.Xr netgraph 4 . 4519If 4520.Xr netgraph 4 4521is not available, 4522.Nm 4523will attempt to load it using 4524.Xr kldload 2 . 4525If this fails, an external program must be used such as the 4526.Xr pppoe 8 4527program available under 4528.Ox . 4529The given 4530.Ar provider 4531is passed as the service name in the PPPoE Discovery Initiation (PADI) 4532packet. 4533If no provider is given, an empty value will be used. 4534.Pp 4535When a PPPoE connection is established, 4536.Nm 4537will place the name of the Access Concentrator in the environment variable 4538.Ev ACNAME . 4539.Pp 4540Refer to 4541.Xr netgraph 4 4542and 4543.Xr ng_pppoe 4 4544for further details. 4545.Pp 4546If a 4547.Ar host Ns No : Ns Ar port Ns Oo 4548.No /tcp|udp 4549.Oc 4550specification is given, 4551.Nm 4552will attempt to connect to the given 4553.Ar host 4554on the given 4555.Ar port . 4556If a 4557.Dq /tcp 4558or 4559.Dq /udp 4560suffix is not provided, the default is 4561.Dq /tcp . 4562Refer to the section on 4563.Em PPP OVER TCP and UDP 4564above for further details. 4565.Pp 4566If multiple 4567.Dq values 4568are specified, 4569.Nm 4570will attempt to open each one in turn until it succeeds or runs out of 4571devices. 4572.It set dial Ar chat-script 4573This specifies the chat script that will be used to dial the other 4574side. 4575See also the 4576.Dq set login 4577command below. 4578Refer to 4579.Xr chat 8 4580and to the example configuration files for details of the chat script 4581format. 4582It is possible to specify some special 4583.Sq values 4584in your chat script as follows: 4585.Bl -tag -width 2n 4586.It Li \ec 4587When used as the last character in a 4588.Sq send 4589string, this indicates that a newline should not be appended. 4590.It Li \ed 4591When the chat script encounters this sequence, it delays two seconds. 4592.It Li \ep 4593When the chat script encounters this sequence, it delays for one quarter of 4594a second. 4595.It Li \en 4596This is replaced with a newline character. 4597.It Li \er 4598This is replaced with a carriage return character. 4599.It Li \es 4600This is replaced with a space character. 4601.It Li \et 4602This is replaced with a tab character. 4603.It Li \eT 4604This is replaced by the current phone number (see 4605.Dq set phone 4606below). 4607.It Li \eP 4608This is replaced by the current 4609.Ar authkey 4610value (see 4611.Dq set authkey 4612above). 4613.It Li \eU 4614This is replaced by the current 4615.Ar authname 4616value (see 4617.Dq set authname 4618above). 4619.El 4620.Pp 4621Note that two parsers will examine these escape sequences, so in order to 4622have the 4623.Sq chat parser 4624see the escape character, it is necessary to escape it from the 4625.Sq command parser . 4626This means that in practice you should use two escapes, for example: 4627.Bd -literal -offset indent 4628set dial "... ATDT\\\\T CONNECT" 4629.Ed 4630.Pp 4631It is also possible to execute external commands from the chat script. 4632To do this, the first character of the expect or send string is an 4633exclamation mark 4634.Pq Dq !\& . 4635If a literal exclamation mark is required, double it up to 4636.Dq !!\& 4637and it will be treated as a single literal 4638.Dq !\& . 4639When the command is executed, standard input and standard output are 4640directed to the open device (see the 4641.Dq set device 4642command), and standard error is read by 4643.Nm 4644and substituted as the expect or send string. 4645If 4646.Nm 4647is running in interactive mode, file descriptor 3 is attached to 4648.Pa /dev/tty . 4649.Pp 4650For example (wrapped for readability): 4651.Bd -literal -offset indent 4652set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e 4653word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e 4654\\"!/bin/echo in\\" HELLO" 4655.Ed 4656.Pp 4657would result in the following chat sequence (output using the 4658.Sq set log local chat 4659command before dialing): 4660.Bd -literal -offset indent 4661Dial attempt 1 of 1 4662dial OK! 4663Chat: Expecting: 4664Chat: Sending: 4665Chat: Expecting: login:--login: 4666Chat: Wait for (5): login: 4667Chat: Sending: ppp 4668Chat: Expecting: word: 4669Chat: Wait for (5): word: 4670Chat: Sending: ppp 4671Chat: Expecting: !sh \\-c "echo \\-n label: >&2" 4672Chat: Exec: sh -c "echo -n label: >&2" 4673Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label: 4674Chat: Exec: /bin/echo in 4675Chat: Sending: 4676Chat: Expecting: HELLO 4677Chat: Wait for (5): HELLO 4678login OK! 4679.Ed 4680.Pp 4681Note (again) the use of the escape character, allowing many levels of 4682nesting. 4683Here, there are four parsers at work. 4684The first parses the original line, reading it as three arguments. 4685The second parses the third argument, reading it as 11 arguments. 4686At this point, it is 4687important that the 4688.Dq \&- 4689signs are escaped, otherwise this parser will see them as constituting 4690an expect-send-expect sequence. 4691When the 4692.Dq !\& 4693character is seen, the execution parser reads the first command as three 4694arguments, and then 4695.Xr sh 1 4696itself expands the argument after the 4697.Fl c . 4698As we wish to send the output back to the modem, in the first example 4699we redirect our output to file descriptor 2 (stderr) so that 4700.Nm 4701itself sends and logs it, and in the second example, we just output to stdout, 4702which is attached directly to the modem. 4703.Pp 4704This, of course means that it is possible to execute an entirely external 4705.Dq chat 4706command rather than using the internal one. 4707See 4708.Xr chat 8 4709for a good alternative. 4710.Pp 4711The external command that is executed is subjected to the same special 4712word expansions as the 4713.Dq !bg 4714command. 4715.It set enddisc Op label|IP|MAC|magic|psn value 4716This command sets our local endpoint discriminator. 4717If set prior to LCP negotiation, and if no 4718.Dq disable enddisc 4719command has been used, 4720.Nm 4721will send the information to the peer using the LCP endpoint discriminator 4722option. 4723The following discriminators may be set: 4724.Bl -tag -width indent 4725.It Li label 4726The current label is used. 4727.It Li IP 4728Our local IP number is used. 4729As LCP is negotiated prior to IPCP, it is 4730possible that the IPCP layer will subsequently change this value. 4731If 4732it does, the endpoint discriminator stays at the old value unless manually 4733reset. 4734.It Li MAC 4735This is similar to the 4736.Ar IP 4737option above, except that the MAC address associated with the local IP 4738number is used. 4739If the local IP number is not resident on any Ethernet 4740interface, the command will fail. 4741.Pp 4742As the local IP number defaults to whatever the machine host name is, 4743.Dq set enddisc mac 4744is usually done prior to any 4745.Dq set ifaddr 4746commands. 4747.It Li magic 4748A 20 digit random number is used. 4749Care should be taken when using magic numbers as restarting 4750.Nm 4751or creating a link using a different 4752.Nm 4753invocation will also use a different magic number and will therefore not 4754be recognised by the peer as belonging to the same bundle. 4755This makes it unsuitable for 4756.Fl direct 4757connections. 4758.It Li psn Ar value 4759The given 4760.Ar value 4761is used. 4762.Ar Value 4763should be set to an absolute public switched network number with the 4764country code first. 4765.El 4766.Pp 4767If no arguments are given, the endpoint discriminator is reset. 4768.It set escape Ar value... 4769This option is similar to the 4770.Dq set accmap 4771option above. 4772It allows the user to specify a set of characters that will be 4773.Sq escaped 4774as they travel across the link. 4775.It set filter dial|alive|in|out Ar rule-no Xo 4776.No permit|deny|clear| Ns Ar rule-no 4777.Op !\& 4778.Oo Op host 4779.Ar src_addr Ns Op / Ns Ar width 4780.Op Ar dst_addr Ns Op / Ns Ar width 4781.Oc [ Ns Ar proto 4782.Op src lt|eq|gt Ar port 4783.Op dst lt|eq|gt Ar port 4784.Op estab 4785.Op syn 4786.Op finrst 4787.Op timeout Ar secs ] 4788.Xc 4789.Nm 4790supports four filter sets. 4791The 4792.Em alive 4793filter specifies packets that keep the connection alive - resetting the 4794idle timer. 4795The 4796.Em dial 4797filter specifies packets that cause 4798.Nm 4799to dial when in 4800.Fl auto 4801mode. 4802The 4803.Em in 4804filter specifies packets that are allowed to travel 4805into the machine and the 4806.Em out 4807filter specifies packets that are allowed out of the machine. 4808.Pp 4809Filtering is done prior to any IP alterations that might be done by the 4810NAT engine on outgoing packets and after any IP alterations that might 4811be done by the NAT engine on incoming packets. 4812By default all empty filter sets allow all packets to pass. 4813Rules are processed in order according to 4814.Ar rule-no 4815(unless skipped by specifying a rule number as the 4816.Ar action ) . 4817Up to 40 rules may be given for each set. 4818If a packet doesn't match 4819any of the rules in a given set, it is discarded. 4820In the case of 4821.Em in 4822and 4823.Em out 4824filters, this means that the packet is dropped. 4825In the case of 4826.Em alive 4827filters it means that the packet will not reset the idle timer (even if 4828the 4829.Ar in Ns No / Ns Ar out 4830filter has a 4831.Dq timeout 4832value) and in the case of 4833.Em dial 4834filters it means that the packet will not trigger a dial. 4835A packet failing to trigger a dial will be dropped rather than queued. 4836Refer to the 4837section on 4838.Sx PACKET FILTERING 4839above for further details. 4840.It set hangup Ar chat-script 4841This specifies the chat script that will be used to reset the device 4842before it is closed. 4843It should not normally be necessary, but can 4844be used for devices that fail to reset themselves properly on close. 4845.It set help|? Op Ar command 4846This command gives a summary of available set commands, or if 4847.Ar command 4848is specified, the command usage is shown. 4849.It set ifaddr Oo Ar myaddr Ns 4850.Op / Ns Ar \&nn 4851.Oo Ar hisaddr Ns Op / Ns Ar \&nn 4852.Oo Ar netmask 4853.Op Ar triggeraddr 4854.Oc Oc 4855.Oc 4856This command specifies the IP addresses that will be used during 4857IPCP negotiation. 4858Addresses are specified using the format 4859.Pp 4860.Dl a.b.c.d/nn 4861.Pp 4862Where 4863.Dq a.b.c.d 4864is the preferred IP, but 4865.Ar nn 4866specifies how many bits of the address we will insist on. 4867If 4868.No / Ns Ar nn 4869is omitted, it defaults to 4870.Dq /32 4871unless the IP address is 0.0.0.0 in which case it defaults to 4872.Dq /0 . 4873.Pp 4874If you wish to assign a dynamic IP number to the peer, 4875.Ar hisaddr 4876may also be specified as a range of IP numbers in the format 4877.Bd -ragged -offset indent 4878.Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Xo 4879.Oc Ns Oo , Ns Ar \&IP Ns 4880.Op \&- Ns Ar \&IP Ns 4881.Oc Ns ... 4882.Xc 4883.Ed 4884.Pp 4885for example: 4886.Pp 4887.Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20 4888.Pp 4889will only negotiate 4890.Dq 10.0.0.1 4891as the local IP number, but may assign any of the given 10 IP 4892numbers to the peer. 4893If the peer requests one of these numbers, 4894and that number is not already in use, 4895.Nm 4896will grant the peers request. 4897This is useful if the peer wants 4898to re-establish a link using the same IP number as was previously 4899allocated (thus maintaining any existing tcp or udp connections). 4900.Pp 4901If the peer requests an IP number that's either outside 4902of this range or is already in use, 4903.Nm 4904will suggest a random unused IP number from the range. 4905.Pp 4906If 4907.Ar triggeraddr 4908is specified, it is used in place of 4909.Ar myaddr 4910in the initial IPCP negotiation. 4911However, only an address in the 4912.Ar myaddr 4913range will be accepted. 4914This is useful when negotiating with some 4915.Dv PPP 4916implementations that will not assign an IP number unless their peer 4917requests 4918.Dq 0.0.0.0 . 4919.Pp 4920It should be noted that in 4921.Fl auto 4922mode, 4923.Nm 4924will configure the interface immediately upon reading the 4925.Dq set ifaddr 4926line in the config file. 4927In any other mode, these values are just 4928used for IPCP negotiations, and the interface isn't configured 4929until the IPCP layer is up. 4930.Pp 4931Note that the 4932.Ar HISADDR 4933argument may be overridden by the third field in the 4934.Pa ppp.secret 4935file once the client has authenticated itself 4936(if PAP or CHAP are 4937.Dq enabled ) . 4938Refer to the 4939.Sx AUTHENTICATING INCOMING CONNECTIONS 4940section for details. 4941.Pp 4942In all cases, if the interface is already configured, 4943.Nm 4944will try to maintain the interface IP numbers so that any existing 4945bound sockets will remain valid. 4946.It set ifqueue Ar packets 4947Set the maximum number of packets that 4948.Nm 4949will read from the tunnel interface while data cannot be sent to any of 4950the available links. 4951This queue limit is necessary to flow control outgoing data as the tunnel 4952interface is likely to be far faster than the combined links available to 4953.Nm . 4954.Pp 4955If 4956.Ar packets 4957is set to a value less than the number of links, 4958.Nm 4959will read up to that value regardless. 4960This prevents any possible latency problems. 4961.Pp 4962The default value for 4963.Ar packets 4964is 4965.Dq 30 . 4966.It set ccpretry|ccpretries Oo Ar timeout 4967.Op Ar reqtries Op Ar trmtries 4968.Oc 4969.It set chapretry|chapretries Oo Ar timeout 4970.Op Ar reqtries 4971.Oc 4972.It set ipcpretry|ipcpretries Oo Ar timeout 4973.Op Ar reqtries Op Ar trmtries 4974.Oc 4975.It set ipv6cpretry|ipv6cpretries Oo Ar timeout 4976.Op Ar reqtries Op Ar trmtries 4977.Oc 4978.It set lcpretry|lcpretries Oo Ar timeout 4979.Op Ar reqtries Op Ar trmtries 4980.Oc 4981.It set papretry|papretries Oo Ar timeout 4982.Op Ar reqtries 4983.Oc 4984These commands set the number of seconds that 4985.Nm 4986will wait before resending Finite State Machine (FSM) Request packets. 4987The default 4988.Ar timeout 4989for all FSMs is 3 seconds (which should suffice in most cases). 4990.Pp 4991If 4992.Ar reqtries 4993is specified, it tells 4994.Nm 4995how many configuration request attempts it should make while receiving 4996no reply from the peer before giving up. 4997The default is 5 attempts for 4998CCP, LCP and IPCP and 3 attempts for PAP and CHAP. 4999.Pp 5000If 5001.Ar trmtries 5002is specified, it tells 5003.Nm 5004how many terminate requests should be sent before giving up waiting for the 5005peers response. 5006The default is 3 attempts. 5007Authentication protocols are 5008not terminated and it is therefore invalid to specify 5009.Ar trmtries 5010for PAP or CHAP. 5011.Pp 5012In order to avoid negotiations with the peer that will never converge, 5013.Nm 5014will only send at most 3 times the configured number of 5015.Ar reqtries 5016in any given negotiation session before giving up and closing that layer. 5017.It set log Xo 5018.Op local 5019.Op +|- Ns 5020.Ar value Ns No ... 5021.Xc 5022This command allows the adjustment of the current log level. 5023Refer to the Logging Facility section for further details. 5024.It set login Ar chat-script 5025This 5026.Ar chat-script 5027compliments the dial-script. 5028If both are specified, the login 5029script will be executed after the dial script. 5030Escape sequences available in the dial script are also available here. 5031.It set logout Ar chat-script 5032This specifies the chat script that will be used to logout 5033before the hangup script is called. 5034It should not normally be necessary. 5035.It set lqrperiod Ar frequency 5036This command sets the 5037.Ar frequency 5038in seconds at which 5039.Em LQR 5040or 5041.Em ECHO LQR 5042packets are sent. 5043The default is 30 seconds. 5044You must also use the 5045.Dq enable lqr 5046command if you wish to send LQR requests to the peer. 5047.It set mode Ar interactive|auto|ddial|background 5048This command allows you to change the 5049.Sq mode 5050of the specified link. 5051This is normally only useful in multi-link mode, 5052but may also be used in uni-link mode. 5053.Pp 5054It is not possible to change a link that is 5055.Sq direct 5056or 5057.Sq dedicated . 5058.Pp 5059Note: If you issue the command 5060.Dq set mode auto , 5061and have network address translation enabled, it may be useful to 5062.Dq enable iface-alias 5063afterwards. 5064This will allow 5065.Nm 5066to do the necessary address translations to enable the process that 5067triggers the connection to connect once the link is up despite the 5068peer assigning us a new (dynamic) IP address. 5069.It set mppe Op 40|56|128|* Op stateless|stateful|* 5070This option selects the encryption parameters used when negotiation 5071MPPE. 5072MPPE can be disabled entirely with the 5073.Dq disable mppe 5074command. 5075If no arguments are given, 5076.Nm 5077will attempt to negotiate a stateful link with a 128 bit key, but 5078will agree to whatever the peer requests (including no encryption 5079at all). 5080.Pp 5081If any arguments are given, 5082.Nm 5083will 5084.Em insist 5085on using MPPE and will close the link if it's rejected by the peer (Note; 5086this behaviour can be overridden by a configured RADIUS server). 5087.Pp 5088The first argument specifies the number of bits that 5089.Nm 5090should insist on during negotiations and the second specifies whether 5091.Nm 5092should insist on stateful or stateless mode. 5093In stateless mode, the 5094encryption dictionary is re-initialised with every packet according to 5095an encryption key that is changed with every packet. 5096In stateful mode, 5097the encryption dictionary is re-initialised every 256 packets or after 5098the loss of any data and the key is changed every 256 packets. 5099Stateless mode is less efficient but is better for unreliable transport 5100layers. 5101.It set mrru Op Ar value 5102Setting this option enables Multi-link PPP negotiations, also known as 5103Multi-link Protocol or MP. 5104There is no default MRRU (Maximum Reconstructed Receive Unit) value. 5105If no argument is given, multi-link mode is disabled. 5106.It set mru Xo 5107.Op max Ns Op imum 5108.Op Ar value 5109.Xc 5110The default MRU (Maximum Receive Unit) is 1500. 5111If it is increased, the other side *may* increase its MTU. 5112In theory there is no point in decreasing the MRU to below the default as the 5113.Em PPP 5114protocol says implementations *must* be able to accept packets of at 5115least 1500 octets. 5116.Pp 5117If the 5118.Dq maximum 5119keyword is used, 5120.Nm 5121will refuse to negotiate a higher value. 5122The maximum MRU can be set to 2048 at most. 5123Setting a maximum of less than 1500 violates the 5124.Em PPP 5125rfc, but may sometimes be necessary. 5126For example, 5127.Em PPPoE 5128imposes a maximum of 1492 due to hardware limitations. 5129.Pp 5130If no argument is given, 1500 is assumed. 5131A value must be given when 5132.Dq maximum 5133is specified. 5134.It set mtu Xo 5135.Op max Ns Op imum 5136.Op Ar value 5137.Xc 5138The default MTU is 1500. 5139At negotiation time, 5140.Nm 5141will accept whatever MRU the peer requests (assuming it's 5142not less than 296 bytes or greater than the assigned maximum). 5143If the MTU is set, 5144.Nm 5145will not accept MRU values less than 5146.Ar value . 5147When negotiations are complete, the MTU is used when writing to the 5148interface, even if the peer requested a higher value MRU. 5149This can be useful for 5150limiting your packet size (giving better bandwidth sharing at the expense 5151of more header data). 5152.Pp 5153If the 5154.Dq maximum 5155keyword is used, 5156.Nm 5157will refuse to negotiate a higher value. 5158The maximum MTU can be set to 2048 at most. 5159.Pp 5160If no 5161.Ar value 5162is given, 1500, or whatever the peer asks for is used. 5163A value must be given when 5164.Dq maximum 5165is specified. 5166.It set nbns Op Ar x.x.x.x Op Ar y.y.y.y 5167This option allows the setting of the Microsoft NetBIOS name server 5168values to be returned at the peers request. 5169If no values are given, 5170.Nm 5171will reject any such requests. 5172.It set openmode active|passive Op Ar delay 5173By default, 5174.Ar openmode 5175is always 5176.Ar active 5177with a one second 5178.Ar delay . 5179That is, 5180.Nm 5181will always initiate LCP/IPCP/CCP negotiation one second after the line 5182comes up. 5183If you want to wait for the peer to initiate negotiations, you 5184can use the value 5185.Ar passive . 5186If you want to initiate negotiations immediately or after more than one 5187second, the appropriate 5188.Ar delay 5189may be specified here in seconds. 5190.It set parity odd|even|none|mark 5191This allows the line parity to be set. 5192The default value is 5193.Ar none . 5194.It set phone Ar telno Ns Xo 5195.Oo \&| Ns Ar backupnumber 5196.Oc Ns ... Ns Oo : Ns Ar nextnumber 5197.Oc Ns ... 5198.Xc 5199This allows the specification of the phone number to be used in 5200place of the \\\\T string in the dial and login chat scripts. 5201Multiple phone numbers may be given separated either by a pipe 5202.Pq Dq \&| 5203or a colon 5204.Pq Dq \&: . 5205.Pp 5206Numbers after the pipe are only dialed if the dial or login 5207script for the previous number failed. 5208.Pp 5209Numbers after the colon are tried sequentially, irrespective of 5210the reason the line was dropped. 5211.Pp 5212If multiple numbers are given, 5213.Nm 5214will dial them according to these rules until a connection is made, retrying 5215the maximum number of times specified by 5216.Dq set redial 5217below. 5218In 5219.Fl background 5220mode, each number is attempted at most once. 5221.It set Op proc Ns Xo 5222.No title Op Ar value 5223.Xc 5224The current process title as displayed by 5225.Xr ps 1 5226is changed according to 5227.Ar value . 5228If 5229.Ar value 5230is not specified, the original process title is restored. 5231All the 5232word replacements done by the shell commands (see the 5233.Dq bg 5234command above) are done here too. 5235.Pp 5236Note, if USER is required in the process title, the 5237.Dq set proctitle 5238command must appear in 5239.Pa ppp.linkup , 5240as it is not known when the commands in 5241.Pa ppp.conf 5242are executed. 5243.It set radius Op Ar config-file 5244This command enables RADIUS support (if it's compiled in). 5245.Ar config-file 5246refers to the radius client configuration file as described in 5247.Xr radius.conf 5 . 5248If PAP, CHAP, MSCHAP or MSCHAPv2 are 5249.Dq enable Ns No d , 5250.Nm 5251behaves as a 5252.Em \&N Ns No etwork 5253.Em \&A Ns No ccess 5254.Em \&S Ns No erver 5255and uses the configured RADIUS server to authenticate rather than 5256authenticating from the 5257.Pa ppp.secret 5258file or from the passwd database. 5259.Pp 5260If none of PAP, CHAP, MSCHAP or MSCHAPv2 are enabled, 5261.Dq set radius 5262will do nothing. 5263.Pp 5264.Nm 5265uses the following attributes from the RADIUS reply: 5266.Bl -tag -width XXX -offset XXX 5267.It RAD_FRAMED_IP_ADDRESS 5268The peer IP address is set to the given value. 5269.It RAD_FRAMED_IP_NETMASK 5270The tun interface netmask is set to the given value. 5271.It RAD_FRAMED_MTU 5272If the given MTU is less than the peers MRU as agreed during LCP 5273negotiation, *and* it is less that any configured MTU (see the 5274.Dq set mru 5275command), the tun interface MTU is set to the given value. 5276.It RAD_FRAMED_COMPRESSION 5277If the received compression type is 5278.Dq 1 , 5279.Nm 5280will request VJ compression during IPCP negotiations despite any 5281.Dq disable vj 5282configuration command. 5283.It RAD_FILTER_ID 5284If this attribute is supplied, 5285.Nm 5286will attempt to use it as an additional label to load from the 5287.Pa ppp.linkup 5288and 5289.Pa ppp.linkdown 5290files. 5291The load will be attempted before (and in addition to) the normal 5292label search. 5293If the label doesn't exist, no action is taken and 5294.Nm 5295proceeds to the normal load using the current label. 5296.It RAD_FRAMED_ROUTE 5297The received string is expected to be in the format 5298.Ar dest Ns Op / Ns Ar bits 5299.Ar gw 5300.Op Ar metrics . 5301Any specified metrics are ignored. 5302.Dv MYADDR 5303and 5304.Dv HISADDR 5305are understood as valid values for 5306.Ar dest 5307and 5308.Ar gw , 5309.Dq default 5310can be used for 5311.Ar dest 5312to specify the default route, and 5313.Dq 0.0.0.0 5314is understood to be the same as 5315.Dq default 5316for 5317.Ar dest 5318and 5319.Dv HISADDR 5320for 5321.Ar gw . 5322.Pp 5323For example, a returned value of 5324.Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400 5325would result in a routing table entry to the 1.2.3.0/24 network via 5326.Dv HISADDR 5327and a returned value of 5328.Dq 0.0.0.0 0.0.0.0 5329or 5330.Dq default HISADDR 5331would result in a default route to 5332.Dv HISADDR . 5333.Pp 5334All RADIUS routes are applied after any sticky routes are applied, making 5335RADIUS routes override configured routes. 5336This also applies for RADIUS routes that don't {include} the 5337.Dv MYADDR 5338or 5339.Dv HISADDR 5340keywords. 5341.Pp 5342.It RAD_SESSION_TIMEOUT 5343If supplied, the client connection is closed after the given number of 5344seconds. 5345.It RAD_REPLY_MESSAGE 5346If supplied, this message is passed back to the peer as the authentication 5347SUCCESS text. 5348.It RAD_MICROSOFT_MS_CHAP_ERROR 5349If this 5350.Dv RAD_VENDOR_MICROSOFT 5351vendor specific attribute is supplied, it is passed back to the peer as the 5352authentication FAILURE text. 5353.It RAD_MICROSOFT_MS_CHAP2_SUCCESS 5354If this 5355.Dv RAD_VENDOR_MICROSOFT 5356vendor specific attribute is supplied and if MS-CHAPv2 authentication is 5357being used, it is passed back to the peer as the authentication SUCCESS text. 5358.It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY 5359If this 5360.Dv RAD_VENDOR_MICROSOFT 5361vendor specific attribute is supplied and has a value of 2 (Required), 5362.Nm 5363will insist that MPPE encryption is used (even if no 5364.Dq set mppe 5365configuration command has been given with arguments). 5366If it is supplied with a value of 1 (Allowed), encryption is made optional 5367(despite any 5368.Dq set mppe 5369configuration commands with arguments). 5370.It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES 5371If this 5372.Dv RAD_VENDOR_MICROSOFT 5373vendor specific attribute is supplied, bits 1 and 2 are examined. 5374If either or both are set, 40 bit and/or 128 bit (respectively) encryption 5375options are set, overriding any given first argument to the 5376.Dq set mppe 5377command. 5378Note, it is not currently possible for the RADIUS server to specify 56 bit 5379encryption. 5380.It RAD_MICROSOFT_MS_MPPE_RECV_KEY 5381If this 5382.Dv RAD_VENDOR_MICROSOFT 5383vendor specific attribute is supplied, it's value is used as the master 5384key for decryption of incoming data. When clients are authenticated using 5385MSCHAPv2, the RADIUS server MUST provide this attribute if inbound MPPE is 5386to function. 5387.It RAD_MICROSOFT_MS_MPPE_SEND_KEY 5388If this 5389.Dv RAD_VENDOR_MICROSOFT 5390vendor specific attribute is supplied, it's value is used as the master 5391key for encryption of outgoing data. When clients are authenticated using 5392MSCHAPv2, the RADIUS server MUST provide this attribute if outbound MPPE is 5393to function. 5394.El 5395.Pp 5396Values received from the RADIUS server may be viewed using 5397.Dq show bundle . 5398.It set reconnect Ar timeout ntries 5399Should the line drop unexpectedly (due to loss of CD or LQR 5400failure), a connection will be re-established after the given 5401.Ar timeout . 5402The line will be re-connected at most 5403.Ar ntries 5404times. 5405.Ar Ntries 5406defaults to zero. 5407A value of 5408.Ar random 5409for 5410.Ar timeout 5411will result in a variable pause, somewhere between 1 and 30 seconds. 5412.It set recvpipe Op Ar value 5413This sets the routing table RECVPIPE value. 5414The optimum value is just over twice the MTU value. 5415If 5416.Ar value 5417is unspecified or zero, the default kernel controlled value is used. 5418.It set redial Ar secs Ns Xo 5419.Oo + Ns Ar inc Ns 5420.Op - Ns Ar max Ns 5421.Oc Ns Op . Ns Ar next 5422.Op Ar attempts 5423.Xc 5424.Nm 5425can be instructed to attempt to redial 5426.Ar attempts 5427times. 5428If more than one phone number is specified (see 5429.Dq set phone 5430above), a pause of 5431.Ar next 5432is taken before dialing each number. 5433A pause of 5434.Ar secs 5435is taken before starting at the first number again. 5436A literal value of 5437.Dq Li random 5438may be used here in place of 5439.Ar secs 5440and 5441.Ar next , 5442causing a random delay of between 1 and 30 seconds. 5443.Pp 5444If 5445.Ar inc 5446is specified, its value is added onto 5447.Ar secs 5448each time 5449.Nm 5450tries a new number. 5451.Ar secs 5452will only be incremented at most 5453.Ar max 5454times. 5455.Ar max 5456defaults to 10. 5457.Pp 5458Note, the 5459.Ar secs 5460delay will be effective, even after 5461.Ar attempts 5462has been exceeded, so an immediate manual dial may appear to have 5463done nothing. 5464If an immediate dial is required, a 5465.Dq !\& 5466should immediately follow the 5467.Dq open 5468keyword. 5469See the 5470.Dq open 5471description above for further details. 5472.It set sendpipe Op Ar value 5473This sets the routing table SENDPIPE value. 5474The optimum value is just over twice the MTU value. 5475If 5476.Ar value 5477is unspecified or zero, the default kernel controlled value is used. 5478.It "set server|socket" Ar TcpPort Ns No \&| Ns Xo 5479.Ar LocalName Ns No |none|open|closed 5480.Op password Op Ar mask 5481.Xc 5482This command tells 5483.Nm 5484to listen on the given socket or 5485.Sq diagnostic port 5486for incoming command connections. 5487.Pp 5488The word 5489.Dq none 5490instructs 5491.Nm 5492to close any existing socket and clear the socket configuration. 5493The word 5494.Dq open 5495instructs 5496.Nm 5497to attempt to re-open the port. 5498The word 5499.Dq closed 5500instructs 5501.Nm 5502to close the open port. 5503.Pp 5504If you wish to specify a local domain socket, 5505.Ar LocalName 5506must be specified as an absolute file name, otherwise it is assumed 5507to be the name or number of a TCP port. 5508You may specify the octal umask to be used with a local domain socket. 5509Refer to 5510.Xr umask 2 5511for umask details. 5512Refer to 5513.Xr services 5 5514for details of how to translate TCP port names. 5515.Pp 5516You must also specify the password that must be entered by the client 5517(using the 5518.Dq passwd 5519variable above) when connecting to this socket. 5520If the password is 5521specified as an empty string, no password is required for connecting clients. 5522.Pp 5523When specifying a local domain socket, the first 5524.Dq %d 5525sequence found in the socket name will be replaced with the current 5526interface unit number. 5527This is useful when you wish to use the same 5528profile for more than one connection. 5529.Pp 5530In a similar manner TCP sockets may be prefixed with the 5531.Dq + 5532character, in which case the current interface unit number is added to 5533the port number. 5534.Pp 5535When using 5536.Nm 5537with a server socket, the 5538.Xr pppctl 8 5539command is the preferred mechanism of communications. 5540Currently, 5541.Xr telnet 1 5542can also be used, but link encryption may be implemented in the future, so 5543.Xr telnet 1 5544should be avoided. 5545.Pp 5546Note; 5547.Dv SIGUSR1 5548and 5549.Dv SIGUSR2 5550interact with the diagnostic socket. 5551.It set speed Ar value 5552This sets the speed of the serial device. 5553If speed is specified as 5554.Dq sync , 5555.Nm 5556treats the device as a synchronous device. 5557.Pp 5558Certain device types will know whether they should be specified as 5559synchronous or asynchronous. 5560These devices will override incorrect 5561settings and log a warning to this effect. 5562.It set stopped Op Ar LCPseconds Op Ar CCPseconds 5563If this option is set, 5564.Nm 5565will time out after the given FSM (Finite State Machine) has been in 5566the stopped state for the given number of 5567.Dq seconds . 5568This option may be useful if the peer sends a terminate request, 5569but never actually closes the connection despite our sending a terminate 5570acknowledgement. 5571This is also useful if you wish to 5572.Dq set openmode passive 5573and time out if the peer doesn't send a Configure Request within the 5574given time. 5575Use 5576.Dq set log +lcp +ccp 5577to make 5578.Nm 5579log the appropriate state transitions. 5580.Pp 5581The default value is zero, where 5582.Nm 5583doesn't time out in the stopped state. 5584.Pp 5585This value should not be set to less than the openmode delay (see 5586.Dq set openmode 5587above). 5588.It set timeout Ar idleseconds Op Ar mintimeout 5589This command allows the setting of the idle timer. 5590Refer to the section titled 5591.Sx SETTING THE IDLE TIMER 5592for further details. 5593.Pp 5594If 5595.Ar mintimeout 5596is specified, 5597.Nm 5598will never idle out before the link has been up for at least that number 5599of seconds. 5600.It set urgent Xo 5601.Op tcp|udp|none 5602.Oo Op +|- Ns 5603.Ar port 5604.Oc No ... 5605.Xc 5606This command controls the ports that 5607.Nm 5608prioritizes when transmitting data. 5609The default priority TCP ports 5610are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell), 5611543 (klogin) and 544 (kshell). 5612There are no priority UDP ports by default. 5613See 5614.Xr services 5 5615for details. 5616.Pp 5617If neither 5618.Dq tcp 5619or 5620.Dq udp 5621are specified, 5622.Dq tcp 5623is assumed. 5624.Pp 5625If no 5626.Ar port Ns No s 5627are given, the priority port lists are cleared (although if 5628.Dq tcp 5629or 5630.Dq udp 5631is specified, only that list is cleared). 5632If the first 5633.Ar port 5634argument is prefixed with a plus 5635.Pq Dq \&+ 5636or a minus 5637.Pq Dq \&- , 5638the current list is adjusted, otherwise the list is reassigned. 5639.Ar port Ns No s 5640prefixed with a plus or not prefixed at all are added to the list and 5641.Ar port Ns No s 5642prefixed with a minus are removed from the list. 5643.Pp 5644If 5645.Dq none 5646is specified, all priority port lists are disabled and even 5647.Dv IPTOS_LOWDELAY 5648packets are not prioritised. 5649.It set vj slotcomp on|off 5650This command tells 5651.Nm 5652whether it should attempt to negotiate VJ slot compression. 5653By default, slot compression is turned 5654.Ar on . 5655.It set vj slots Ar nslots 5656This command sets the initial number of slots that 5657.Nm 5658will try to negotiate with the peer when VJ compression is enabled (see the 5659.Sq enable 5660command above). 5661It defaults to a value of 16. 5662.Ar Nslots 5663must be between 5664.Ar 4 5665and 5666.Ar 16 5667inclusive. 5668.El 5669.Pp 5670.It shell|! Op Ar command 5671If 5672.Ar command 5673is not specified a shell is invoked according to the 5674.Dv SHELL 5675environment variable. 5676Otherwise, the given 5677.Ar command 5678is executed. 5679Word replacement is done in the same way as for the 5680.Dq !bg 5681command as described above. 5682.Pp 5683Use of the ! character 5684requires a following space as with any of the other commands. 5685You should note that this command is executed in the foreground; 5686.Nm 5687will not continue running until this process has exited. 5688Use the 5689.Dv bg 5690command if you wish processing to happen in the background. 5691.It show Ar var 5692This command allows the user to examine the following: 5693.Bl -tag -width 2n 5694.It show bundle 5695Show the current bundle settings. 5696.It show ccp 5697Show the current CCP compression statistics. 5698.It show compress 5699Show the current VJ compression statistics. 5700.It show escape 5701Show the current escape characters. 5702.It show filter Op Ar name 5703List the current rules for the given filter. 5704If 5705.Ar name 5706is not specified, all filters are shown. 5707.It show hdlc 5708Show the current HDLC statistics. 5709.It show help|? 5710Give a summary of available show commands. 5711.It show iface 5712Show the current interface information 5713(the same as 5714.Dq iface show ) . 5715.It show ipcp 5716Show the current IPCP statistics. 5717.It show layers 5718Show the protocol layers currently in use. 5719.It show lcp 5720Show the current LCP statistics. 5721.It show Op data Ns Xo 5722.No link 5723.Xc 5724Show high level link information. 5725.It show links 5726Show a list of available logical links. 5727.It show log 5728Show the current log values. 5729.It show mem 5730Show current memory statistics. 5731.It show ncp 5732Show the current NCP statistics. 5733.It show physical 5734Show low level link information. 5735.It show mp 5736Show Multi-link information. 5737.It show proto 5738Show current protocol totals. 5739.It show route 5740Show the current routing tables. 5741.It show stopped 5742Show the current stopped timeouts. 5743.It show timer 5744Show the active alarm timers. 5745.It show version 5746Show the current version number of 5747.Nm . 5748.El 5749.Pp 5750.It term 5751Go into terminal mode. 5752Characters typed at the keyboard are sent to the device. 5753Characters read from the device are displayed on the screen. 5754When a remote 5755.Em PPP 5756peer is detected, 5757.Nm 5758automatically enables Packet Mode and goes back into command mode. 5759.El 5760.Sh MORE DETAILS 5761.Bl -bullet 5762.It 5763Read the example configuration files. 5764They are a good source of information. 5765.It 5766Use 5767.Dq help , 5768.Dq nat \&? , 5769.Dq enable \&? , 5770.Dq set ?\& 5771and 5772.Dq show ?\& 5773to get online information about what's available. 5774.It 5775The following URLs contain useful information: 5776.Bl -bullet -compact 5777.It 5778.Pa http://www.dragonflybsd.org/docs/handbook/handbook-userppp/ 5779.El 5780.El 5781.Sh FILES 5782.Nm 5783refers to four files: 5784.Pa ppp.conf , 5785.Pa ppp.linkup , 5786.Pa ppp.linkdown 5787and 5788.Pa ppp.secret . 5789These files are placed in the 5790.Pa /etc/ppp 5791directory. 5792.Bl -tag -width 2n 5793.It Pa /etc/ppp/ppp.conf 5794System default configuration file. 5795.It Pa /etc/ppp/ppp.secret 5796An authorisation file for each system. 5797.It Pa /etc/ppp/ppp.linkup 5798A file to check when 5799.Nm 5800establishes a network level connection. 5801.It Pa /etc/ppp/ppp.linkdown 5802A file to check when 5803.Nm 5804closes a network level connection. 5805.It Pa /var/log/ppp.log 5806Logging and debugging information file. 5807Note, this name is specified in 5808.Pa /etc/syslog.conf . 5809See 5810.Xr syslog.conf 5 5811for further details. 5812.It Pa /var/spool/lock/LCK..* 5813tty port locking file. 5814Refer to 5815.Xr uucplock 3 5816for further details. 5817.It Pa /var/run/tunN.pid 5818The process id (pid) of the 5819.Nm 5820program connected to the tunN device, where 5821.Sq N 5822is the number of the device. 5823.It Pa /var/run/ttyXX.if 5824The tun interface used by this port. 5825Again, this file is only created in 5826.Fl background , 5827.Fl auto 5828and 5829.Fl ddial 5830modes. 5831.It Pa /etc/services 5832Get port number if port number is using service name. 5833.It Pa /var/run/ppp-authname-class-value 5834In multi-link mode, local domain sockets are created using the peer 5835authentication name 5836.Pq Sq authname , 5837the peer endpoint discriminator class 5838.Pq Sq class 5839and the peer endpoint discriminator value 5840.Pq Sq value . 5841As the endpoint discriminator value may be a binary value, it is turned 5842to HEX to determine the actual file name. 5843.Pp 5844This socket is used to pass links between different instances of 5845.Nm . 5846.El 5847.Sh SEE ALSO 5848.Xr at 1 , 5849.Xr ftp 1 , 5850.Xr gzip 1 , 5851.Xr hostname 1 , 5852.Xr login 1 , 5853.Xr tcpdump 1 , 5854.Xr telnet 1 , 5855.Xr kldload 2 , 5856ifdef({LOCALNAT},{},{.Xr libalias 3 , 5857})dnl 5858ifdef({LOCALRAD},{},{.Xr libradius 3 , 5859})dnl 5860.Xr syslog 3 , 5861.Xr uucplock 3 , 5862.Xr netgraph 4 , 5863.Xr ng_pppoe 4 , 5864.Xr crontab 5 , 5865.Xr group 5 , 5866.Xr passwd 5 , 5867.Xr protocols 5 , 5868.Xr radius.conf 5 , 5869.Xr resolv.conf 5 , 5870.Xr syslog.conf 5 , 5871.Xr adduser 8 , 5872.Xr chat 8 , 5873.Xr getty 8 , 5874.Xr inetd 8 , 5875.Xr init 8 , 5876.Xr isdnd 8 , 5877.Xr named 8 , 5878.Xr ping 8 , 5879.Xr pppctl 8 , 5880.Xr pppd 8 , 5881.Xr pppoe 8 , 5882.Xr route 8 , 5883.Xr sshd 8 , 5884.Xr syslogd 8 , 5885.Xr traceroute 8 , 5886.Xr vipw 8 5887.Sh HISTORY 5888This program was originally written by 5889.An Toshiharu OHNO Aq tony-o@iij.ad.jp , 5890and was submitted to 5891.Fx 2.0.5 5892by 5893.An Atsushi Murai Aq amurai@spec.co.jp . 5894.Pp 5895It was substantially modified during 1997 by 5896.An Brian Somers Aq brian@Awfulhak.org , 5897and was ported to 5898.Ox 5899in November that year 5900(just after the 2.2 release). 5901.Pp 5902Most of the code was rewritten by 5903.An Brian Somers 5904in early 1998 when multi-link ppp support was added. 5905