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 TIOCMGET ioctl, the tty device will switch all 4341carrier detection off when it detects that the device is a pty. 4342.It ISDN (i4b) Devices 4343Carrier is checked once per second for 6 seconds. 4344If it's not set after 4345the sixth second, the connection attempt is considered to have failed and 4346the device is closed. 4347Carrier is always required for i4b devices. 4348.It PPPoE (netgraph) Devices 4349Carrier is checked once per second for 5 seconds. 4350If it's not set after 4351the fifth second, the connection attempt is considered to have failed and 4352the device is closed. 4353Carrier is always required for PPPoE devices. 4354.El 4355.Pp 4356All other device types don't support carrier. 4357Setting a carrier value will 4358result in a warning when the device is opened. 4359.Pp 4360Some modems take more than one second after connecting to assert the carrier 4361signal. 4362If this delay isn't increased, this will result in 4363.Nm Ns No 's 4364inability to detect when the link is dropped, as 4365.Nm 4366assumes that the device isn't asserting carrier. 4367.Pp 4368The 4369.Dq set cd 4370command overrides the default carrier behaviour. 4371.Ar seconds 4372specifies the maximum number of seconds that 4373.Nm 4374should wait after the dial script has finished before deciding if 4375carrier is available or not. 4376.Pp 4377If 4378.Dq off 4379is specified, 4380.Nm 4381will not check for carrier on the device, otherwise 4382.Nm 4383will not proceed to the login script until either carrier is detected 4384or until 4385.Ar seconds 4386has elapsed, at which point 4387.Nm 4388assumes that the device will not set carrier. 4389.Pp 4390If no arguments are given, carrier settings will go back to their default 4391values. 4392.Pp 4393If 4394.Ar seconds 4395is followed immediately by an exclamation mark 4396.Pq Dq !\& , 4397.Nm 4398will 4399.Em require 4400carrier. 4401If carrier is not detected after 4402.Ar seconds 4403seconds, the link will be disconnected. 4404.It set choked Op Ar timeout 4405This sets the number of seconds that 4406.Nm 4407will keep a choked output queue before dropping all pending output packets. 4408If 4409.Ar timeout 4410is less than or equal to zero or if 4411.Ar timeout 4412isn't specified, it is set to the default value of 4413.Em 120 seconds . 4414.Pp 4415A choked output queue occurs when 4416.Nm 4417has read a certain number of packets from the local network for transmission, 4418but cannot send the data due to link failure (the peer is busy etc.). 4419.Nm 4420will not read packets indefinitely. 4421Instead, it reads up to 4422.Em 30 4423packets (or 4424.Em 30 No + 4425.Em nlinks No * 4426.Em 2 4427packets in multi-link mode), then stops reading the network interface 4428until either 4429.Ar timeout 4430seconds have passed or at least one packet has been sent. 4431.Pp 4432If 4433.Ar timeout 4434seconds pass, all pending output packets are dropped. 4435.It set ctsrts|crtscts on|off 4436This sets hardware flow control. 4437Hardware flow control is 4438.Ar on 4439by default. 4440.It set deflate Ar out-winsize Op Ar in-winsize 4441This sets the DEFLATE algorithms default outgoing and incoming window 4442sizes. 4443Both 4444.Ar out-winsize 4445and 4446.Ar in-winsize 4447must be values between 4448.Em 8 4449and 4450.Em 15 . 4451If 4452.Ar in-winsize 4453is specified, 4454.Nm 4455will insist that this window size is used and will not accept any other 4456values from the peer. 4457.It set dns Op Ar primary Op Ar secondary 4458This command specifies DNS overrides for the 4459.Dq accept dns 4460command. 4461Refer to the 4462.Dq accept 4463command description above for details. 4464This command does not affect the IP numbers requested using 4465.Dq enable dns . 4466.It set device|line Xo 4467.Ar value Ns No ... 4468.Xc 4469This sets the device(s) to which 4470.Nm 4471will talk to the given 4472.Dq value . 4473.Pp 4474All ISDN and serial device names are expected to begin with 4475.Pa /dev/ . 4476ISDN devices are usually called 4477.Pa i4brbchX 4478and serial devices are usually called 4479.Pa cuaXX . 4480.Pp 4481If 4482.Dq value 4483does not begin with 4484.Pa /dev/ , 4485it must either begin with an exclamation mark 4486.Pq Dq !\& , 4487be of the format 4488.No PPPoE: Ns Ar iface Ns Xo 4489.Op \&: Ns Ar provider Ns 4490.Xc 4491(on 4492.Xr netgraph 4 4493enabled systems), or be of the format 4494.Sm off 4495.Ar host : port Op /tcp|udp . 4496.Sm on 4497.Pp 4498If it begins with an exclamation mark, the rest of the device name is 4499treated as a program name, and that program is executed when the device 4500is opened. 4501Standard input, output and error are fed back to 4502.Nm 4503and are read and written as if they were a regular device. 4504.Pp 4505If a 4506.No PPPoE: Ns Ar iface Ns Xo 4507.Op \&: Ns Ar provider Ns 4508.Xc 4509specification is given, 4510.Nm 4511will attempt to create a 4512.Em PPP 4513over Ethernet connection using the given 4514.Ar iface 4515interface by using 4516.Xr netgraph 4 . 4517If 4518.Xr netgraph 4 4519is not available, 4520.Nm 4521will attempt to load it using 4522.Xr kldload 2 . 4523If this fails, an external program must be used such as the 4524.Xr pppoe 8 4525program available under 4526.Ox . 4527The given 4528.Ar provider 4529is passed as the service name in the PPPoE Discovery Initiation (PADI) 4530packet. 4531If no provider is given, an empty value will be used. 4532.Pp 4533When a PPPoE connection is established, 4534.Nm 4535will place the name of the Access Concentrator in the environment variable 4536.Ev ACNAME . 4537.Pp 4538Refer to 4539.Xr netgraph 4 4540and 4541.Xr ng_pppoe 4 4542for further details. 4543.Pp 4544If a 4545.Ar host Ns No : Ns Ar port Ns Oo 4546.No /tcp|udp 4547.Oc 4548specification is given, 4549.Nm 4550will attempt to connect to the given 4551.Ar host 4552on the given 4553.Ar port . 4554If a 4555.Dq /tcp 4556or 4557.Dq /udp 4558suffix is not provided, the default is 4559.Dq /tcp . 4560Refer to the section on 4561.Em PPP OVER TCP and UDP 4562above for further details. 4563.Pp 4564If multiple 4565.Dq values 4566are specified, 4567.Nm 4568will attempt to open each one in turn until it succeeds or runs out of 4569devices. 4570.It set dial Ar chat-script 4571This specifies the chat script that will be used to dial the other 4572side. 4573See also the 4574.Dq set login 4575command below. 4576Refer to 4577.Xr chat 8 4578and to the example configuration files for details of the chat script 4579format. 4580It is possible to specify some special 4581.Sq values 4582in your chat script as follows: 4583.Bl -tag -width 2n 4584.It Li \ec 4585When used as the last character in a 4586.Sq send 4587string, this indicates that a newline should not be appended. 4588.It Li \ed 4589When the chat script encounters this sequence, it delays two seconds. 4590.It Li \ep 4591When the chat script encounters this sequence, it delays for one quarter of 4592a second. 4593.It Li \en 4594This is replaced with a newline character. 4595.It Li \er 4596This is replaced with a carriage return character. 4597.It Li \es 4598This is replaced with a space character. 4599.It Li \et 4600This is replaced with a tab character. 4601.It Li \eT 4602This is replaced by the current phone number (see 4603.Dq set phone 4604below). 4605.It Li \eP 4606This is replaced by the current 4607.Ar authkey 4608value (see 4609.Dq set authkey 4610above). 4611.It Li \eU 4612This is replaced by the current 4613.Ar authname 4614value (see 4615.Dq set authname 4616above). 4617.El 4618.Pp 4619Note that two parsers will examine these escape sequences, so in order to 4620have the 4621.Sq chat parser 4622see the escape character, it is necessary to escape it from the 4623.Sq command parser . 4624This means that in practice you should use two escapes, for example: 4625.Bd -literal -offset indent 4626set dial "... ATDT\\\\T CONNECT" 4627.Ed 4628.Pp 4629It is also possible to execute external commands from the chat script. 4630To do this, the first character of the expect or send string is an 4631exclamation mark 4632.Pq Dq !\& . 4633If a literal exclamation mark is required, double it up to 4634.Dq !!\& 4635and it will be treated as a single literal 4636.Dq !\& . 4637When the command is executed, standard input and standard output are 4638directed to the open device (see the 4639.Dq set device 4640command), and standard error is read by 4641.Nm 4642and substituted as the expect or send string. 4643If 4644.Nm 4645is running in interactive mode, file descriptor 3 is attached to 4646.Pa /dev/tty . 4647.Pp 4648For example (wrapped for readability): 4649.Bd -literal -offset indent 4650set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e 4651word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e 4652\\"!/bin/echo in\\" HELLO" 4653.Ed 4654.Pp 4655would result in the following chat sequence (output using the 4656.Sq set log local chat 4657command before dialing): 4658.Bd -literal -offset indent 4659Dial attempt 1 of 1 4660dial OK! 4661Chat: Expecting: 4662Chat: Sending: 4663Chat: Expecting: login:--login: 4664Chat: Wait for (5): login: 4665Chat: Sending: ppp 4666Chat: Expecting: word: 4667Chat: Wait for (5): word: 4668Chat: Sending: ppp 4669Chat: Expecting: !sh \\-c "echo \\-n label: >&2" 4670Chat: Exec: sh -c "echo -n label: >&2" 4671Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label: 4672Chat: Exec: /bin/echo in 4673Chat: Sending: 4674Chat: Expecting: HELLO 4675Chat: Wait for (5): HELLO 4676login OK! 4677.Ed 4678.Pp 4679Note (again) the use of the escape character, allowing many levels of 4680nesting. 4681Here, there are four parsers at work. 4682The first parses the original line, reading it as three arguments. 4683The second parses the third argument, reading it as 11 arguments. 4684At this point, it is 4685important that the 4686.Dq \&- 4687signs are escaped, otherwise this parser will see them as constituting 4688an expect-send-expect sequence. 4689When the 4690.Dq !\& 4691character is seen, the execution parser reads the first command as three 4692arguments, and then 4693.Xr sh 1 4694itself expands the argument after the 4695.Fl c . 4696As we wish to send the output back to the modem, in the first example 4697we redirect our output to file descriptor 2 (stderr) so that 4698.Nm 4699itself sends and logs it, and in the second example, we just output to stdout, 4700which is attached directly to the modem. 4701.Pp 4702This, of course means that it is possible to execute an entirely external 4703.Dq chat 4704command rather than using the internal one. 4705See 4706.Xr chat 8 4707for a good alternative. 4708.Pp 4709The external command that is executed is subjected to the same special 4710word expansions as the 4711.Dq !bg 4712command. 4713.It set enddisc Op label|IP|MAC|magic|psn value 4714This command sets our local endpoint discriminator. 4715If set prior to LCP negotiation, and if no 4716.Dq disable enddisc 4717command has been used, 4718.Nm 4719will send the information to the peer using the LCP endpoint discriminator 4720option. 4721The following discriminators may be set: 4722.Bl -tag -width indent 4723.It Li label 4724The current label is used. 4725.It Li IP 4726Our local IP number is used. 4727As LCP is negotiated prior to IPCP, it is 4728possible that the IPCP layer will subsequently change this value. 4729If 4730it does, the endpoint discriminator stays at the old value unless manually 4731reset. 4732.It Li MAC 4733This is similar to the 4734.Ar IP 4735option above, except that the MAC address associated with the local IP 4736number is used. 4737If the local IP number is not resident on any Ethernet 4738interface, the command will fail. 4739.Pp 4740As the local IP number defaults to whatever the machine host name is, 4741.Dq set enddisc mac 4742is usually done prior to any 4743.Dq set ifaddr 4744commands. 4745.It Li magic 4746A 20 digit random number is used. 4747Care should be taken when using magic numbers as restarting 4748.Nm 4749or creating a link using a different 4750.Nm 4751invocation will also use a different magic number and will therefore not 4752be recognised by the peer as belonging to the same bundle. 4753This makes it unsuitable for 4754.Fl direct 4755connections. 4756.It Li psn Ar value 4757The given 4758.Ar value 4759is used. 4760.Ar Value 4761should be set to an absolute public switched network number with the 4762country code first. 4763.El 4764.Pp 4765If no arguments are given, the endpoint discriminator is reset. 4766.It set escape Ar value... 4767This option is similar to the 4768.Dq set accmap 4769option above. 4770It allows the user to specify a set of characters that will be 4771.Sq escaped 4772as they travel across the link. 4773.It set filter dial|alive|in|out Ar rule-no Xo 4774.No permit|deny|clear| Ns Ar rule-no 4775.Op !\& 4776.Oo Op host 4777.Ar src_addr Ns Op / Ns Ar width 4778.Op Ar dst_addr Ns Op / Ns Ar width 4779.Oc [ Ns Ar proto 4780.Op src lt|eq|gt Ar port 4781.Op dst lt|eq|gt Ar port 4782.Op estab 4783.Op syn 4784.Op finrst 4785.Op timeout Ar secs ] 4786.Xc 4787.Nm 4788supports four filter sets. 4789The 4790.Em alive 4791filter specifies packets that keep the connection alive - resetting the 4792idle timer. 4793The 4794.Em dial 4795filter specifies packets that cause 4796.Nm 4797to dial when in 4798.Fl auto 4799mode. 4800The 4801.Em in 4802filter specifies packets that are allowed to travel 4803into the machine and the 4804.Em out 4805filter specifies packets that are allowed out of the machine. 4806.Pp 4807Filtering is done prior to any IP alterations that might be done by the 4808NAT engine on outgoing packets and after any IP alterations that might 4809be done by the NAT engine on incoming packets. 4810By default all empty filter sets allow all packets to pass. 4811Rules are processed in order according to 4812.Ar rule-no 4813(unless skipped by specifying a rule number as the 4814.Ar action ) . 4815Up to 40 rules may be given for each set. 4816If a packet doesn't match 4817any of the rules in a given set, it is discarded. 4818In the case of 4819.Em in 4820and 4821.Em out 4822filters, this means that the packet is dropped. 4823In the case of 4824.Em alive 4825filters it means that the packet will not reset the idle timer (even if 4826the 4827.Ar in Ns No / Ns Ar out 4828filter has a 4829.Dq timeout 4830value) and in the case of 4831.Em dial 4832filters it means that the packet will not trigger a dial. 4833A packet failing to trigger a dial will be dropped rather than queued. 4834Refer to the 4835section on 4836.Sx PACKET FILTERING 4837above for further details. 4838.It set hangup Ar chat-script 4839This specifies the chat script that will be used to reset the device 4840before it is closed. 4841It should not normally be necessary, but can 4842be used for devices that fail to reset themselves properly on close. 4843.It set help|? Op Ar command 4844This command gives a summary of available set commands, or if 4845.Ar command 4846is specified, the command usage is shown. 4847.It set ifaddr Oo Ar myaddr Ns 4848.Op / Ns Ar \&nn 4849.Oo Ar hisaddr Ns Op / Ns Ar \&nn 4850.Oo Ar netmask 4851.Op Ar triggeraddr 4852.Oc Oc 4853.Oc 4854This command specifies the IP addresses that will be used during 4855IPCP negotiation. 4856Addresses are specified using the format 4857.Pp 4858.Dl a.b.c.d/nn 4859.Pp 4860Where 4861.Dq a.b.c.d 4862is the preferred IP, but 4863.Ar nn 4864specifies how many bits of the address we will insist on. 4865If 4866.No / Ns Ar nn 4867is omitted, it defaults to 4868.Dq /32 4869unless the IP address is 0.0.0.0 in which case it defaults to 4870.Dq /0 . 4871.Pp 4872If you wish to assign a dynamic IP number to the peer, 4873.Ar hisaddr 4874may also be specified as a range of IP numbers in the format 4875.Bd -ragged -offset indent 4876.Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Xo 4877.Oc Ns Oo , Ns Ar \&IP Ns 4878.Op \&- Ns Ar \&IP Ns 4879.Oc Ns ... 4880.Xc 4881.Ed 4882.Pp 4883for example: 4884.Pp 4885.Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20 4886.Pp 4887will only negotiate 4888.Dq 10.0.0.1 4889as the local IP number, but may assign any of the given 10 IP 4890numbers to the peer. 4891If the peer requests one of these numbers, 4892and that number is not already in use, 4893.Nm 4894will grant the peers request. 4895This is useful if the peer wants 4896to re-establish a link using the same IP number as was previously 4897allocated (thus maintaining any existing tcp or udp connections). 4898.Pp 4899If the peer requests an IP number that's either outside 4900of this range or is already in use, 4901.Nm 4902will suggest a random unused IP number from the range. 4903.Pp 4904If 4905.Ar triggeraddr 4906is specified, it is used in place of 4907.Ar myaddr 4908in the initial IPCP negotiation. 4909However, only an address in the 4910.Ar myaddr 4911range will be accepted. 4912This is useful when negotiating with some 4913.Dv PPP 4914implementations that will not assign an IP number unless their peer 4915requests 4916.Dq 0.0.0.0 . 4917.Pp 4918It should be noted that in 4919.Fl auto 4920mode, 4921.Nm 4922will configure the interface immediately upon reading the 4923.Dq set ifaddr 4924line in the config file. 4925In any other mode, these values are just 4926used for IPCP negotiations, and the interface isn't configured 4927until the IPCP layer is up. 4928.Pp 4929Note that the 4930.Ar HISADDR 4931argument may be overridden by the third field in the 4932.Pa ppp.secret 4933file once the client has authenticated itself 4934(if PAP or CHAP are 4935.Dq enabled ) . 4936Refer to the 4937.Sx AUTHENTICATING INCOMING CONNECTIONS 4938section for details. 4939.Pp 4940In all cases, if the interface is already configured, 4941.Nm 4942will try to maintain the interface IP numbers so that any existing 4943bound sockets will remain valid. 4944.It set ifqueue Ar packets 4945Set the maximum number of packets that 4946.Nm 4947will read from the tunnel interface while data cannot be sent to any of 4948the available links. 4949This queue limit is necessary to flow control outgoing data as the tunnel 4950interface is likely to be far faster than the combined links available to 4951.Nm . 4952.Pp 4953If 4954.Ar packets 4955is set to a value less than the number of links, 4956.Nm 4957will read up to that value regardless. 4958This prevents any possible latency problems. 4959.Pp 4960The default value for 4961.Ar packets 4962is 4963.Dq 30 . 4964.It set ccpretry|ccpretries Oo Ar timeout 4965.Op Ar reqtries Op Ar trmtries 4966.Oc 4967.It set chapretry|chapretries Oo Ar timeout 4968.Op Ar reqtries 4969.Oc 4970.It set ipcpretry|ipcpretries Oo Ar timeout 4971.Op Ar reqtries Op Ar trmtries 4972.Oc 4973.It set ipv6cpretry|ipv6cpretries Oo Ar timeout 4974.Op Ar reqtries Op Ar trmtries 4975.Oc 4976.It set lcpretry|lcpretries Oo Ar timeout 4977.Op Ar reqtries Op Ar trmtries 4978.Oc 4979.It set papretry|papretries Oo Ar timeout 4980.Op Ar reqtries 4981.Oc 4982These commands set the number of seconds that 4983.Nm 4984will wait before resending Finite State Machine (FSM) Request packets. 4985The default 4986.Ar timeout 4987for all FSMs is 3 seconds (which should suffice in most cases). 4988.Pp 4989If 4990.Ar reqtries 4991is specified, it tells 4992.Nm 4993how many configuration request attempts it should make while receiving 4994no reply from the peer before giving up. 4995The default is 5 attempts for 4996CCP, LCP and IPCP and 3 attempts for PAP and CHAP. 4997.Pp 4998If 4999.Ar trmtries 5000is specified, it tells 5001.Nm 5002how many terminate requests should be sent before giving up waiting for the 5003peers response. 5004The default is 3 attempts. 5005Authentication protocols are 5006not terminated and it is therefore invalid to specify 5007.Ar trmtries 5008for PAP or CHAP. 5009.Pp 5010In order to avoid negotiations with the peer that will never converge, 5011.Nm 5012will only send at most 3 times the configured number of 5013.Ar reqtries 5014in any given negotiation session before giving up and closing that layer. 5015.It set log Xo 5016.Op local 5017.Op +|- Ns 5018.Ar value Ns No ... 5019.Xc 5020This command allows the adjustment of the current log level. 5021Refer to the Logging Facility section for further details. 5022.It set login Ar chat-script 5023This 5024.Ar chat-script 5025compliments the dial-script. 5026If both are specified, the login 5027script will be executed after the dial script. 5028Escape sequences available in the dial script are also available here. 5029.It set logout Ar chat-script 5030This specifies the chat script that will be used to logout 5031before the hangup script is called. 5032It should not normally be necessary. 5033.It set lqrperiod Ar frequency 5034This command sets the 5035.Ar frequency 5036in seconds at which 5037.Em LQR 5038or 5039.Em ECHO LQR 5040packets are sent. 5041The default is 30 seconds. 5042You must also use the 5043.Dq enable lqr 5044command if you wish to send LQR requests to the peer. 5045.It set mode Ar interactive|auto|ddial|background 5046This command allows you to change the 5047.Sq mode 5048of the specified link. 5049This is normally only useful in multi-link mode, 5050but may also be used in uni-link mode. 5051.Pp 5052It is not possible to change a link that is 5053.Sq direct 5054or 5055.Sq dedicated . 5056.Pp 5057Note: If you issue the command 5058.Dq set mode auto , 5059and have network address translation enabled, it may be useful to 5060.Dq enable iface-alias 5061afterwards. 5062This will allow 5063.Nm 5064to do the necessary address translations to enable the process that 5065triggers the connection to connect once the link is up despite the 5066peer assigning us a new (dynamic) IP address. 5067.It set mppe Op 40|56|128|* Op stateless|stateful|* 5068This option selects the encryption parameters used when negotiation 5069MPPE. 5070MPPE can be disabled entirely with the 5071.Dq disable mppe 5072command. 5073If no arguments are given, 5074.Nm 5075will attempt to negotiate a stateful link with a 128 bit key, but 5076will agree to whatever the peer requests (including no encryption 5077at all). 5078.Pp 5079If any arguments are given, 5080.Nm 5081will 5082.Em insist 5083on using MPPE and will close the link if it's rejected by the peer (Note; 5084this behaviour can be overridden by a configured RADIUS server). 5085.Pp 5086The first argument specifies the number of bits that 5087.Nm 5088should insist on during negotiations and the second specifies whether 5089.Nm 5090should insist on stateful or stateless mode. 5091In stateless mode, the 5092encryption dictionary is re-initialised with every packet according to 5093an encryption key that is changed with every packet. 5094In stateful mode, 5095the encryption dictionary is re-initialised every 256 packets or after 5096the loss of any data and the key is changed every 256 packets. 5097Stateless mode is less efficient but is better for unreliable transport 5098layers. 5099.It set mrru Op Ar value 5100Setting this option enables Multi-link PPP negotiations, also known as 5101Multi-link Protocol or MP. 5102There is no default MRRU (Maximum Reconstructed Receive Unit) value. 5103If no argument is given, multi-link mode is disabled. 5104.It set mru Xo 5105.Op max Ns Op imum 5106.Op Ar value 5107.Xc 5108The default MRU (Maximum Receive Unit) is 1500. 5109If it is increased, the other side *may* increase its MTU. 5110In theory there is no point in decreasing the MRU to below the default as the 5111.Em PPP 5112protocol says implementations *must* be able to accept packets of at 5113least 1500 octets. 5114.Pp 5115If the 5116.Dq maximum 5117keyword is used, 5118.Nm 5119will refuse to negotiate a higher value. 5120The maximum MRU can be set to 2048 at most. 5121Setting a maximum of less than 1500 violates the 5122.Em PPP 5123rfc, but may sometimes be necessary. 5124For example, 5125.Em PPPoE 5126imposes a maximum of 1492 due to hardware limitations. 5127.Pp 5128If no argument is given, 1500 is assumed. 5129A value must be given when 5130.Dq maximum 5131is specified. 5132.It set mtu Xo 5133.Op max Ns Op imum 5134.Op Ar value 5135.Xc 5136The default MTU is 1500. 5137At negotiation time, 5138.Nm 5139will accept whatever MRU the peer requests (assuming it's 5140not less than 296 bytes or greater than the assigned maximum). 5141If the MTU is set, 5142.Nm 5143will not accept MRU values less than 5144.Ar value . 5145When negotiations are complete, the MTU is used when writing to the 5146interface, even if the peer requested a higher value MRU. 5147This can be useful for 5148limiting your packet size (giving better bandwidth sharing at the expense 5149of more header data). 5150.Pp 5151If the 5152.Dq maximum 5153keyword is used, 5154.Nm 5155will refuse to negotiate a higher value. 5156The maximum MTU can be set to 2048 at most. 5157.Pp 5158If no 5159.Ar value 5160is given, 1500, or whatever the peer asks for is used. 5161A value must be given when 5162.Dq maximum 5163is specified. 5164.It set nbns Op Ar x.x.x.x Op Ar y.y.y.y 5165This option allows the setting of the Microsoft NetBIOS name server 5166values to be returned at the peers request. 5167If no values are given, 5168.Nm 5169will reject any such requests. 5170.It set openmode active|passive Op Ar delay 5171By default, 5172.Ar openmode 5173is always 5174.Ar active 5175with a one second 5176.Ar delay . 5177That is, 5178.Nm 5179will always initiate LCP/IPCP/CCP negotiation one second after the line 5180comes up. 5181If you want to wait for the peer to initiate negotiations, you 5182can use the value 5183.Ar passive . 5184If you want to initiate negotiations immediately or after more than one 5185second, the appropriate 5186.Ar delay 5187may be specified here in seconds. 5188.It set parity odd|even|none|mark 5189This allows the line parity to be set. 5190The default value is 5191.Ar none . 5192.It set phone Ar telno Ns Xo 5193.Oo \&| Ns Ar backupnumber 5194.Oc Ns ... Ns Oo : Ns Ar nextnumber 5195.Oc Ns ... 5196.Xc 5197This allows the specification of the phone number to be used in 5198place of the \\\\T string in the dial and login chat scripts. 5199Multiple phone numbers may be given separated either by a pipe 5200.Pq Dq \&| 5201or a colon 5202.Pq Dq \&: . 5203.Pp 5204Numbers after the pipe are only dialed if the dial or login 5205script for the previous number failed. 5206.Pp 5207Numbers after the colon are tried sequentially, irrespective of 5208the reason the line was dropped. 5209.Pp 5210If multiple numbers are given, 5211.Nm 5212will dial them according to these rules until a connection is made, retrying 5213the maximum number of times specified by 5214.Dq set redial 5215below. 5216In 5217.Fl background 5218mode, each number is attempted at most once. 5219.It set Op proc Ns Xo 5220.No title Op Ar value 5221.Xc 5222The current process title as displayed by 5223.Xr ps 1 5224is changed according to 5225.Ar value . 5226If 5227.Ar value 5228is not specified, the original process title is restored. 5229All the 5230word replacements done by the shell commands (see the 5231.Dq bg 5232command above) are done here too. 5233.Pp 5234Note, if USER is required in the process title, the 5235.Dq set proctitle 5236command must appear in 5237.Pa ppp.linkup , 5238as it is not known when the commands in 5239.Pa ppp.conf 5240are executed. 5241.It set radius Op Ar config-file 5242This command enables RADIUS support (if it's compiled in). 5243.Ar config-file 5244refers to the radius client configuration file as described in 5245.Xr radius.conf 5 . 5246If PAP, CHAP, MSCHAP or MSCHAPv2 are 5247.Dq enable Ns No d , 5248.Nm 5249behaves as a 5250.Em \&N Ns No etwork 5251.Em \&A Ns No ccess 5252.Em \&S Ns No erver 5253and uses the configured RADIUS server to authenticate rather than 5254authenticating from the 5255.Pa ppp.secret 5256file or from the passwd database. 5257.Pp 5258If none of PAP, CHAP, MSCHAP or MSCHAPv2 are enabled, 5259.Dq set radius 5260will do nothing. 5261.Pp 5262.Nm 5263uses the following attributes from the RADIUS reply: 5264.Bl -tag -width XXX -offset XXX 5265.It RAD_FRAMED_IP_ADDRESS 5266The peer IP address is set to the given value. 5267.It RAD_FRAMED_IP_NETMASK 5268The tun interface netmask is set to the given value. 5269.It RAD_FRAMED_MTU 5270If the given MTU is less than the peers MRU as agreed during LCP 5271negotiation, *and* it is less that any configured MTU (see the 5272.Dq set mru 5273command), the tun interface MTU is set to the given value. 5274.It RAD_FRAMED_COMPRESSION 5275If the received compression type is 5276.Dq 1 , 5277.Nm 5278will request VJ compression during IPCP negotiations despite any 5279.Dq disable vj 5280configuration command. 5281.It RAD_FILTER_ID 5282If this attribute is supplied, 5283.Nm 5284will attempt to use it as an additional label to load from the 5285.Pa ppp.linkup 5286and 5287.Pa ppp.linkdown 5288files. 5289The load will be attempted before (and in addition to) the normal 5290label search. 5291If the label doesn't exist, no action is taken and 5292.Nm 5293proceeds to the normal load using the current label. 5294.It RAD_FRAMED_ROUTE 5295The received string is expected to be in the format 5296.Ar dest Ns Op / Ns Ar bits 5297.Ar gw 5298.Op Ar metrics . 5299Any specified metrics are ignored. 5300.Dv MYADDR 5301and 5302.Dv HISADDR 5303are understood as valid values for 5304.Ar dest 5305and 5306.Ar gw , 5307.Dq default 5308can be used for 5309.Ar dest 5310to specify the default route, and 5311.Dq 0.0.0.0 5312is understood to be the same as 5313.Dq default 5314for 5315.Ar dest 5316and 5317.Dv HISADDR 5318for 5319.Ar gw . 5320.Pp 5321For example, a returned value of 5322.Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400 5323would result in a routing table entry to the 1.2.3.0/24 network via 5324.Dv HISADDR 5325and a returned value of 5326.Dq 0.0.0.0 0.0.0.0 5327or 5328.Dq default HISADDR 5329would result in a default route to 5330.Dv HISADDR . 5331.Pp 5332All RADIUS routes are applied after any sticky routes are applied, making 5333RADIUS routes override configured routes. 5334This also applies for RADIUS routes that don't {include} the 5335.Dv MYADDR 5336or 5337.Dv HISADDR 5338keywords. 5339.Pp 5340.It RAD_SESSION_TIMEOUT 5341If supplied, the client connection is closed after the given number of 5342seconds. 5343.It RAD_REPLY_MESSAGE 5344If supplied, this message is passed back to the peer as the authentication 5345SUCCESS text. 5346.It RAD_MICROSOFT_MS_CHAP_ERROR 5347If this 5348.Dv RAD_VENDOR_MICROSOFT 5349vendor specific attribute is supplied, it is passed back to the peer as the 5350authentication FAILURE text. 5351.It RAD_MICROSOFT_MS_CHAP2_SUCCESS 5352If this 5353.Dv RAD_VENDOR_MICROSOFT 5354vendor specific attribute is supplied and if MS-CHAPv2 authentication is 5355being used, it is passed back to the peer as the authentication SUCCESS text. 5356.It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY 5357If this 5358.Dv RAD_VENDOR_MICROSOFT 5359vendor specific attribute is supplied and has a value of 2 (Required), 5360.Nm 5361will insist that MPPE encryption is used (even if no 5362.Dq set mppe 5363configuration command has been given with arguments). 5364If it is supplied with a value of 1 (Allowed), encryption is made optional 5365(despite any 5366.Dq set mppe 5367configuration commands with arguments). 5368.It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES 5369If this 5370.Dv RAD_VENDOR_MICROSOFT 5371vendor specific attribute is supplied, bits 1 and 2 are examined. 5372If either or both are set, 40 bit and/or 128 bit (respectively) encryption 5373options are set, overriding any given first argument to the 5374.Dq set mppe 5375command. 5376Note, it is not currently possible for the RADIUS server to specify 56 bit 5377encryption. 5378.It RAD_MICROSOFT_MS_MPPE_RECV_KEY 5379If this 5380.Dv RAD_VENDOR_MICROSOFT 5381vendor specific attribute is supplied, it's value is used as the master 5382key for decryption of incoming data. When clients are authenticated using 5383MSCHAPv2, the RADIUS server MUST provide this attribute if inbound MPPE is 5384to function. 5385.It RAD_MICROSOFT_MS_MPPE_SEND_KEY 5386If this 5387.Dv RAD_VENDOR_MICROSOFT 5388vendor specific attribute is supplied, it's value is used as the master 5389key for encryption of outgoing data. When clients are authenticated using 5390MSCHAPv2, the RADIUS server MUST provide this attribute if outbound MPPE is 5391to function. 5392.El 5393.Pp 5394Values received from the RADIUS server may be viewed using 5395.Dq show bundle . 5396.It set reconnect Ar timeout ntries 5397Should the line drop unexpectedly (due to loss of CD or LQR 5398failure), a connection will be re-established after the given 5399.Ar timeout . 5400The line will be re-connected at most 5401.Ar ntries 5402times. 5403.Ar Ntries 5404defaults to zero. 5405A value of 5406.Ar random 5407for 5408.Ar timeout 5409will result in a variable pause, somewhere between 1 and 30 seconds. 5410.It set recvpipe Op Ar value 5411This sets the routing table RECVPIPE value. 5412The optimum value is just over twice the MTU value. 5413If 5414.Ar value 5415is unspecified or zero, the default kernel controlled value is used. 5416.It set redial Ar secs Ns Xo 5417.Oo + Ns Ar inc Ns 5418.Op - Ns Ar max Ns 5419.Oc Ns Op . Ns Ar next 5420.Op Ar attempts 5421.Xc 5422.Nm 5423can be instructed to attempt to redial 5424.Ar attempts 5425times. 5426If more than one phone number is specified (see 5427.Dq set phone 5428above), a pause of 5429.Ar next 5430is taken before dialing each number. 5431A pause of 5432.Ar secs 5433is taken before starting at the first number again. 5434A literal value of 5435.Dq Li random 5436may be used here in place of 5437.Ar secs 5438and 5439.Ar next , 5440causing a random delay of between 1 and 30 seconds. 5441.Pp 5442If 5443.Ar inc 5444is specified, its value is added onto 5445.Ar secs 5446each time 5447.Nm 5448tries a new number. 5449.Ar secs 5450will only be incremented at most 5451.Ar max 5452times. 5453.Ar max 5454defaults to 10. 5455.Pp 5456Note, the 5457.Ar secs 5458delay will be effective, even after 5459.Ar attempts 5460has been exceeded, so an immediate manual dial may appear to have 5461done nothing. 5462If an immediate dial is required, a 5463.Dq !\& 5464should immediately follow the 5465.Dq open 5466keyword. 5467See the 5468.Dq open 5469description above for further details. 5470.It set sendpipe Op Ar value 5471This sets the routing table SENDPIPE value. 5472The optimum value is just over twice the MTU value. 5473If 5474.Ar value 5475is unspecified or zero, the default kernel controlled value is used. 5476.It "set server|socket" Ar TcpPort Ns No \&| Ns Xo 5477.Ar LocalName Ns No |none|open|closed 5478.Op password Op Ar mask 5479.Xc 5480This command tells 5481.Nm 5482to listen on the given socket or 5483.Sq diagnostic port 5484for incoming command connections. 5485.Pp 5486The word 5487.Dq none 5488instructs 5489.Nm 5490to close any existing socket and clear the socket configuration. 5491The word 5492.Dq open 5493instructs 5494.Nm 5495to attempt to re-open the port. 5496The word 5497.Dq closed 5498instructs 5499.Nm 5500to close the open port. 5501.Pp 5502If you wish to specify a local domain socket, 5503.Ar LocalName 5504must be specified as an absolute file name, otherwise it is assumed 5505to be the name or number of a TCP port. 5506You may specify the octal umask to be used with a local domain socket. 5507Refer to 5508.Xr umask 2 5509for umask details. 5510Refer to 5511.Xr services 5 5512for details of how to translate TCP port names. 5513.Pp 5514You must also specify the password that must be entered by the client 5515(using the 5516.Dq passwd 5517variable above) when connecting to this socket. 5518If the password is 5519specified as an empty string, no password is required for connecting clients. 5520.Pp 5521When specifying a local domain socket, the first 5522.Dq %d 5523sequence found in the socket name will be replaced with the current 5524interface unit number. 5525This is useful when you wish to use the same 5526profile for more than one connection. 5527.Pp 5528In a similar manner TCP sockets may be prefixed with the 5529.Dq + 5530character, in which case the current interface unit number is added to 5531the port number. 5532.Pp 5533When using 5534.Nm 5535with a server socket, the 5536.Xr pppctl 8 5537command is the preferred mechanism of communications. 5538Currently, 5539.Xr telnet 1 5540can also be used, but link encryption may be implemented in the future, so 5541.Xr telnet 1 5542should be avoided. 5543.Pp 5544Note; 5545.Dv SIGUSR1 5546and 5547.Dv SIGUSR2 5548interact with the diagnostic socket. 5549.It set speed Ar value 5550This sets the speed of the serial device. 5551If speed is specified as 5552.Dq sync , 5553.Nm 5554treats the device as a synchronous device. 5555.Pp 5556Certain device types will know whether they should be specified as 5557synchronous or asynchronous. 5558These devices will override incorrect 5559settings and log a warning to this effect. 5560.It set stopped Op Ar LCPseconds Op Ar CCPseconds 5561If this option is set, 5562.Nm 5563will time out after the given FSM (Finite State Machine) has been in 5564the stopped state for the given number of 5565.Dq seconds . 5566This option may be useful if the peer sends a terminate request, 5567but never actually closes the connection despite our sending a terminate 5568acknowledgement. 5569This is also useful if you wish to 5570.Dq set openmode passive 5571and time out if the peer doesn't send a Configure Request within the 5572given time. 5573Use 5574.Dq set log +lcp +ccp 5575to make 5576.Nm 5577log the appropriate state transitions. 5578.Pp 5579The default value is zero, where 5580.Nm 5581doesn't time out in the stopped state. 5582.Pp 5583This value should not be set to less than the openmode delay (see 5584.Dq set openmode 5585above). 5586.It set timeout Ar idleseconds Op Ar mintimeout 5587This command allows the setting of the idle timer. 5588Refer to the section titled 5589.Sx SETTING THE IDLE TIMER 5590for further details. 5591.Pp 5592If 5593.Ar mintimeout 5594is specified, 5595.Nm 5596will never idle out before the link has been up for at least that number 5597of seconds. 5598.It set urgent Xo 5599.Op tcp|udp|none 5600.Oo Op +|- Ns 5601.Ar port 5602.Oc No ... 5603.Xc 5604This command controls the ports that 5605.Nm 5606prioritizes when transmitting data. 5607The default priority TCP ports 5608are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell), 5609543 (klogin) and 544 (kshell). 5610There are no priority UDP ports by default. 5611See 5612.Xr services 5 5613for details. 5614.Pp 5615If neither 5616.Dq tcp 5617or 5618.Dq udp 5619are specified, 5620.Dq tcp 5621is assumed. 5622.Pp 5623If no 5624.Ar port Ns No s 5625are given, the priority port lists are cleared (although if 5626.Dq tcp 5627or 5628.Dq udp 5629is specified, only that list is cleared). 5630If the first 5631.Ar port 5632argument is prefixed with a plus 5633.Pq Dq \&+ 5634or a minus 5635.Pq Dq \&- , 5636the current list is adjusted, otherwise the list is reassigned. 5637.Ar port Ns No s 5638prefixed with a plus or not prefixed at all are added to the list and 5639.Ar port Ns No s 5640prefixed with a minus are removed from the list. 5641.Pp 5642If 5643.Dq none 5644is specified, all priority port lists are disabled and even 5645.Dv IPTOS_LOWDELAY 5646packets are not prioritised. 5647.It set vj slotcomp on|off 5648This command tells 5649.Nm 5650whether it should attempt to negotiate VJ slot compression. 5651By default, slot compression is turned 5652.Ar on . 5653.It set vj slots Ar nslots 5654This command sets the initial number of slots that 5655.Nm 5656will try to negotiate with the peer when VJ compression is enabled (see the 5657.Sq enable 5658command above). 5659It defaults to a value of 16. 5660.Ar Nslots 5661must be between 5662.Ar 4 5663and 5664.Ar 16 5665inclusive. 5666.El 5667.Pp 5668.It shell|! Op Ar command 5669If 5670.Ar command 5671is not specified a shell is invoked according to the 5672.Dv SHELL 5673environment variable. 5674Otherwise, the given 5675.Ar command 5676is executed. 5677Word replacement is done in the same way as for the 5678.Dq !bg 5679command as described above. 5680.Pp 5681Use of the ! character 5682requires a following space as with any of the other commands. 5683You should note that this command is executed in the foreground; 5684.Nm 5685will not continue running until this process has exited. 5686Use the 5687.Dv bg 5688command if you wish processing to happen in the background. 5689.It show Ar var 5690This command allows the user to examine the following: 5691.Bl -tag -width 2n 5692.It show bundle 5693Show the current bundle settings. 5694.It show ccp 5695Show the current CCP compression statistics. 5696.It show compress 5697Show the current VJ compression statistics. 5698.It show escape 5699Show the current escape characters. 5700.It show filter Op Ar name 5701List the current rules for the given filter. 5702If 5703.Ar name 5704is not specified, all filters are shown. 5705.It show hdlc 5706Show the current HDLC statistics. 5707.It show help|? 5708Give a summary of available show commands. 5709.It show iface 5710Show the current interface information 5711(the same as 5712.Dq iface show ) . 5713.It show ipcp 5714Show the current IPCP statistics. 5715.It show layers 5716Show the protocol layers currently in use. 5717.It show lcp 5718Show the current LCP statistics. 5719.It show Op data Ns Xo 5720.No link 5721.Xc 5722Show high level link information. 5723.It show links 5724Show a list of available logical links. 5725.It show log 5726Show the current log values. 5727.It show mem 5728Show current memory statistics. 5729.It show ncp 5730Show the current NCP statistics. 5731.It show physical 5732Show low level link information. 5733.It show mp 5734Show Multi-link information. 5735.It show proto 5736Show current protocol totals. 5737.It show route 5738Show the current routing tables. 5739.It show stopped 5740Show the current stopped timeouts. 5741.It show timer 5742Show the active alarm timers. 5743.It show version 5744Show the current version number of 5745.Nm . 5746.El 5747.Pp 5748.It term 5749Go into terminal mode. 5750Characters typed at the keyboard are sent to the device. 5751Characters read from the device are displayed on the screen. 5752When a remote 5753.Em PPP 5754peer is detected, 5755.Nm 5756automatically enables Packet Mode and goes back into command mode. 5757.El 5758.Sh MORE DETAILS 5759.Bl -bullet 5760.It 5761Read the example configuration files. 5762They are a good source of information. 5763.It 5764Use 5765.Dq help , 5766.Dq nat \&? , 5767.Dq enable \&? , 5768.Dq set ?\& 5769and 5770.Dq show ?\& 5771to get online information about what's available. 5772.It 5773The following URLs contain useful information: 5774.Bl -bullet -compact 5775.It 5776.Pa http://wiki.dragonflybsd.org/index.cgi/userppp.html 5777.El 5778.El 5779.Sh FILES 5780.Nm 5781refers to four files: 5782.Pa ppp.conf , 5783.Pa ppp.linkup , 5784.Pa ppp.linkdown 5785and 5786.Pa ppp.secret . 5787These files are placed in the 5788.Pa /etc/ppp 5789directory. 5790.Bl -tag -width 2n 5791.It Pa /etc/ppp/ppp.conf 5792System default configuration file. 5793.It Pa /etc/ppp/ppp.secret 5794An authorisation file for each system. 5795.It Pa /etc/ppp/ppp.linkup 5796A file to check when 5797.Nm 5798establishes a network level connection. 5799.It Pa /etc/ppp/ppp.linkdown 5800A file to check when 5801.Nm 5802closes a network level connection. 5803.It Pa /var/log/ppp.log 5804Logging and debugging information file. 5805Note, this name is specified in 5806.Pa /etc/syslog.conf . 5807See 5808.Xr syslog.conf 5 5809for further details. 5810.It Pa /var/spool/lock/LCK..* 5811tty port locking file. 5812Refer to 5813.Xr uucplock 3 5814for further details. 5815.It Pa /var/run/tunN.pid 5816The process id (pid) of the 5817.Nm 5818program connected to the tunN device, where 5819.Sq N 5820is the number of the device. 5821.It Pa /var/run/ttyXX.if 5822The tun interface used by this port. 5823Again, this file is only created in 5824.Fl background , 5825.Fl auto 5826and 5827.Fl ddial 5828modes. 5829.It Pa /etc/services 5830Get port number if port number is using service name. 5831.It Pa /var/run/ppp-authname-class-value 5832In multi-link mode, local domain sockets are created using the peer 5833authentication name 5834.Pq Sq authname , 5835the peer endpoint discriminator class 5836.Pq Sq class 5837and the peer endpoint discriminator value 5838.Pq Sq value . 5839As the endpoint discriminator value may be a binary value, it is turned 5840to HEX to determine the actual file name. 5841.Pp 5842This socket is used to pass links between different instances of 5843.Nm . 5844.El 5845.Sh SEE ALSO 5846.Xr at 1 , 5847.Xr ftp 1 , 5848.Xr gzip 1 , 5849.Xr hostname 1 , 5850.Xr login 1 , 5851.Xr tcpdump 1 , 5852.Xr telnet 1 , 5853.Xr kldload 2 , 5854ifdef({LOCALNAT},{},{.Xr libalias 3 , 5855})dnl 5856ifdef({LOCALRAD},{},{.Xr libradius 3 , 5857})dnl 5858.Xr syslog 3 , 5859.Xr uucplock 3 , 5860.Xr netgraph 4 , 5861.Xr ng_pppoe 4 , 5862.Xr crontab 5 , 5863.Xr group 5 , 5864.Xr passwd 5 , 5865.Xr protocols 5 , 5866.Xr radius.conf 5 , 5867.Xr resolv.conf 5 , 5868.Xr syslog.conf 5 , 5869.Xr adduser 8 , 5870.Xr chat 8 , 5871.Xr getty 8 , 5872.Xr inetd 8 , 5873.Xr init 8 , 5874.Xr isdnd 8 , 5875.Xr named 8 , 5876.Xr ping 8 , 5877.Xr pppctl 8 , 5878.Xr pppd 8 , 5879.Xr pppoe 8 , 5880.Xr route 8 , 5881.Xr sshd 8 , 5882.Xr syslogd 8 , 5883.Xr traceroute 8 , 5884.Xr vipw 8 5885.Sh HISTORY 5886This program was originally written by 5887.An Toshiharu OHNO Aq tony-o@iij.ad.jp , 5888and was submitted to 5889.Fx 2.0.5 5890by 5891.An Atsushi Murai Aq amurai@spec.co.jp . 5892.Pp 5893It was substantially modified during 1997 by 5894.An Brian Somers Aq brian@Awfulhak.org , 5895and was ported to 5896.Ox 5897in November that year 5898(just after the 2.2 release). 5899.Pp 5900Most of the code was rewritten by 5901.An Brian Somers 5902in early 1998 when multi-link ppp support was added. 5903