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