ppp.8 revision 138799
1185377Ssamchangequote({,})dnl 2185377Ssamchangecom(,)dnl 3185377Ssam.\" 4185377Ssam.\" Copyright (c) 2001 Brian Somers <brian@Awfulhak.org> 5185377Ssam.\" All rights reserved. 6185377Ssam.\" 7185377Ssam.\" Redistribution and use in source and binary forms, with or without 8185377Ssam.\" modification, are permitted provided that the following conditions 9185377Ssam.\" are met: 10185377Ssam.\" 1. Redistributions of source code must retain the above copyright 11185377Ssam.\" notice, this list of conditions and the following disclaimer. 12185377Ssam.\" 2. Redistributions in binary form must reproduce the above copyright 13185377Ssam.\" notice, this list of conditions and the following disclaimer in the 14185377Ssam.\" documentation and/or other materials provided with the distribution. 15185377Ssam.\" 16185377Ssam.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17188968Ssam.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18185377Ssam.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19185377Ssam.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20185377Ssam.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21185377Ssam.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22188968Ssam.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23185377Ssam.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24185377Ssam.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25185377Ssam.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26185377Ssam.\" SUCH DAMAGE. 27185377Ssam.\" 28185377Ssam.\" $FreeBSD: head/usr.sbin/ppp/ppp.8.m4 138799 2004-12-13 12:51:19Z brian $ 29185377Ssam.\" 30185377Ssam.Dd July 20, 2004 31185377Ssam.Dt PPP 8 32185377Ssam.Os 33185377Ssam.Sh NAME 34188979Ssam.Nm ppp 35188979Ssam.Nd Point to Point Protocol (a.k.a. user-ppp) 36185377Ssam.Sh SYNOPSIS 37185377Ssam.Nm 38185377Ssam.Op Fl Va mode 39185377Ssam.Op Fl nat 40185377Ssam.Op Fl quiet 41185377Ssam.Op Fl unit Ns Ar N 42185377Ssam.Op Ar system ... 43225431Sadrian.Sh DESCRIPTION 44185377SsamThis is a user process 45185377Ssam.Em PPP 46185377Ssamsoftware package. 47188976SsamNormally, 48188976Ssam.Em PPP 49188976Ssamis implemented as a part of the kernel (e.g., as managed by 50234692Sadrian.Xr pppd 8 ) 51188976Ssamand it's thus somewhat hard to debug and/or modify its behaviour. 52234692SadrianHowever, in this implementation 53234692Sadrian.Em PPP 54234692Sadrianis done as a user process with the help of the 55234692Sadriantunnel device driver (tun). 56234692Sadrian.Pp 57234692SadrianThe 58234692Sadrian.Fl nat 59234692Sadrianflag does the equivalent of a 60234692Sadrian.Dq nat enable yes , 61234692Sadrianenabling 62234692Sadrian.Nm Ns No 's 63234692Sadriannetwork address translation features. 64234692SadrianThis allows 65234692Sadrian.Nm 66234692Sadrianto act as a NAT or masquerading engine for all machines on an internal 67234692SadrianLAN. 68234692Sadrianifdef({LOCALNAT},{},{Refer to 69234692Sadrian.Xr libalias 3 70234692Sadrianfor details on the technical side of the NAT engine. 71188976Ssam})dnl 72234692SadrianRefer to the 73234692Sadrian.Sx NETWORK ADDRESS TRANSLATION (PACKET ALIASING) 74234692Sadriansection of this manual page for details on how to configure NAT in 75234692Sadrian.Nm . 76234692Sadrian.Pp 77234692SadrianThe 78234692Sadrian.Fl quiet 79188976Ssamflag tells 80234692Sadrian.Nm 81234692Sadrianto be silent at startup rather than displaying the mode and interface 82234692Sadrianto standard output. 83234692Sadrian.Pp 84234692SadrianThe 85234692Sadrian.Fl unit 86234692Sadrianflag tells 87188976Ssam.Nm 88188976Ssamto only attempt to open 89188976Ssam.Pa /dev/tun Ns Ar N . 90234692SadrianNormally, 91234692Sadrian.Nm 92234692Sadrianwill start with a value of 0 for 93234692Sadrian.Ar N , 94234692Sadrianand keep trying to open a tunnel device by incrementing the value of 95234692Sadrian.Ar N 96234692Sadrianby one each time until it succeeds. 97234692SadrianIf it fails three times in a row 98234692Sadrianbecause the device file is missing, it gives up. 99185377Ssam.Pp 100185377SsamThe following 101234692Sadrian.Va mode Ns No s 102221163Sadrianare understood by 103221163Sadrian.Nm : 104221163Sadrian.Bl -tag -width XXX -offset XXX 105221163Sadrian.It Fl auto 106221163Sadrian.Nm 107221163Sadrianopens the tun interface, configures it then goes into the background. 108221163SadrianThe link isn't brought up until outgoing data is detected on the tun 109221163Sadrianinterface at which point 110221163Sadrian.Nm 111221163Sadrianattempts to bring up the link. 112221163SadrianPackets received (including the first one) while 113221163Sadrian.Nm 114221163Sadrianis trying to bring the link up will remain queued for a default of 115221163Sadrian2 minutes. 116221163SadrianSee the 117221163Sadrian.Dq set choked 118221163Sadriancommand below. 119221163Sadrian.Pp 120221163SadrianIn 121221163Sadrian.Fl auto 122221163Sadrianmode, at least one 123221163Sadrian.Dq system 124221163Sadrianmust be given on the command line (see below) and a 125221163Sadrian.Dq set ifaddr 126240445Sadrianmust be done in the system profile that specifies a peer IP address to 127240445Sadrianuse when configuring the interface. 128240445SadrianSomething like 129240445Sadrian.Dq 10.0.0.1/0 130240445Sadrianis usually appropriate. 131240445SadrianSee the 132185377Ssam.Dq pmdemand 133225125Sadriansystem in 134225125Sadrian.Pa /usr/share/examples/ppp/ppp.conf.sample 135225125Sadrianfor an example. 136225125Sadrian.It Fl background 137225125SadrianHere, 138225125Sadrian.Nm 139225125Sadrianattempts to establish a connection with the peer immediately. 140185377SsamIf it succeeds, 141185377Ssam.Nm 142185377Ssamgoes into the background and the parent process returns an exit code 143185377Ssamof 0. 144185377SsamIf it fails, 145185377Ssam.Nm 146185377Ssamexits with a non-zero result. 147185377Ssam.It Fl foreground 148234692SadrianIn foreground mode, 149185377Ssam.Nm 150185377Ssamattempts to establish a connection with the peer immediately, but never 151185377Ssambecomes a daemon. 152185377SsamThe link is created in background mode. 153185377SsamThis is useful if you wish to control 154185377Ssam.Nm Ns No 's 155185377Ssaminvocation from another process. 156185377Ssam.It Fl direct 157185377SsamThis is used for communicating over an already established connection, 158185377Ssamusually when receiving incoming connections accepted by 159185377Ssam.Xr getty 8 . 160185377Ssam.Nm 161185377Ssamignores the 162185377Ssam.Dq set device 163185377Ssamline and uses descriptor 0 as the link. 164185377Ssam.Nm 165185377Ssamwill also ignore any configured chat scripts unless the 166185377Ssam.Dq force-scripts 167185377Ssamoption has been enabled. 168185377Ssam.Pp 169185377SsamIf callback is configured, 170185377Ssam.Nm 171185377Ssamwill use the 172185377Ssam.Dq set device 173185377Ssaminformation when dialing back. 174185377Ssam.It Fl dedicated 175185377SsamThis option is designed for machines connected with a dedicated 176185377Ssamwire. 177185377Ssam.Nm 178185377Ssamwill always keep the device open and will ignore any configured 179185377Ssamchat scripts unless the 180185377Ssam.Dq force-scripts 181185377Ssamoption has been enabled. 182244943Sadrian.It Fl ddial 183185377SsamThis mode is equivalent to 184208711Srpaulo.Fl auto 185185377Ssammode except that 186185377Ssam.Nm 187185377Ssamwill bring the link back up any time it's dropped for any reason. 188185377Ssam.It Fl interactive 189185377SsamThis is a no-op, and gives the same behaviour as if none of the above 190185377Ssammodes have been specified. 191185377Ssam.Nm 192185377Ssamloads any sections specified on the command line then provides an 193185377Ssaminteractive prompt. 194185377Ssam.El 195185377Ssam.Pp 196185377SsamOne or more configuration entries or systems 197185377Ssam(as specified in 198185377Ssam.Pa /etc/ppp/ppp.conf ) 199185377Ssammay also be specified on the command line. 200185377Ssam.Nm 201185377Ssamwill read the 202185377Ssam.Dq default 203185377Ssamsystem from 204185377Ssam.Pa /etc/ppp/ppp.conf 205185377Ssamat startup, followed by each of the systems specified on the command line. 206185377Ssam.Sh Major Features 207185377Ssam.Bl -diag 208185377Ssam.It Provides an interactive user interface. 209185377SsamUsing its command mode, the user can 210185377Ssameasily enter commands to establish the connection with the remote end, check 211185377Ssamthe status of connection and close the connection. 212185377SsamAll functions can also be optionally password protected for security. 213185377Ssam.It Supports both manual and automatic dialing. 214185377SsamInteractive mode has a 215185377Ssam.Dq term 216185377Ssamcommand which enables you to talk to the device directly. 217185377SsamWhen you are connected to the remote peer and it starts to talk 218185377Ssam.Em PPP , 219185377Ssam.Nm 220185377Ssamdetects it and switches to packet mode automatically. 221185377SsamOnce you have 222185377Ssamdetermined the proper sequence for connecting with the remote host, you 223185377Ssamcan write a chat script to {define} the necessary dialing and login 224185377Ssamprocedure for later convenience. 225185377Ssam.It Supports on-demand dialup capability. 226185377SsamBy using 227185377Ssam.Fl auto 228185377Ssammode, 229185377Ssam.Nm 230185377Ssamwill act as a daemon and wait for a packet to be sent over the 231185377Ssam.Em PPP 232185377Ssamlink. 233185377SsamWhen this happens, the daemon automatically dials and establishes the 234185377Ssamconnection. 235185377SsamIn almost the same manner 236185377Ssam.Fl ddial 237185377Ssammode (direct-dial mode) also automatically dials and establishes the 238185377Ssamconnection. 239185377SsamHowever, it differs in that it will dial the remote site 240185377Ssamany time it detects the link is down, even if there are no packets to be 241221479Sadriansent. 242221479SadrianThis mode is useful for full-time connections where we worry less 243221479Sadrianabout line charges and more about being connected full time. 244221479SadrianA third 245221479Sadrian.Fl dedicated 246221479Sadrianmode is also available. 247185377SsamThis mode is targeted at a dedicated link between two machines. 248185377Ssam.Nm 249185377Ssamwill never voluntarily quit from dedicated mode - you must send it the 250185377Ssam.Dq quit all 251185377Ssamcommand via its diagnostic socket. 252185377SsamA 253185377Ssam.Dv SIGHUP 254185377Ssamwill force an LCP renegotiation, and a 255185377Ssam.Dv SIGTERM 256185377Ssamwill force it to exit. 257185377Ssam.It Supports client callback. 258228834Sadrian.Nm 259228834Sadriancan use either the standard LCP callback protocol or the Microsoft 260228834SadrianCallBack Control Protocol (ftp://ftp.microsoft.com/developr/rfc/cbcp.txt). 261185377Ssam.It Supports NAT or packet aliasing. 262185377SsamPacket aliasing (a.k.a.\& IP masquerading) allows computers on a 263236009Sadrianprivate, unregistered network to access the Internet. 264236009SadrianThe 265236009Sadrian.Em PPP 266188979Ssamhost acts as a masquerading gateway. 267188979SsamIP addresses as well as TCP and 268188979SsamUDP port numbers are NAT'd for outgoing packets and de-NAT'd for 269188979Ssamreturning packets. 270236009Sadrian.It Supports background PPP connections. 271236009SadrianIn background mode, if 272188979Ssam.Nm 273188979Ssamsuccessfully establishes the connection, it will become a daemon. 274233885SadrianOtherwise, it will exit with an error. 275188979SsamThis allows the setup of 276188979Ssamscripts that wish to execute certain commands only if the connection 277188979Ssamis successfully established. 278188979Ssam.It Supports server-side PPP connections. 279185377SsamIn direct mode, 280185377Ssam.Nm 281185377Ssamacts as server which accepts incoming 282185377Ssam.Em PPP 283185377Ssamconnections on stdin/stdout. 284185377Ssam.It "Supports PAP and CHAP (rfc 1994, 2433 and 2759) authentication. 285185377SsamWith PAP or CHAP, it is possible to skip the Unix style 286185377Ssam.Xr login 1 287222301Sadrianprocedure, and use the 288222301Sadrian.Em PPP 289222301Sadrianprotocol for authentication instead. 290222301SadrianIf the peer requests Microsoft CHAP authentication and 291185377Ssam.Nm 292185377Ssamis compiled with DES support, an appropriate MD4/DES response will be 293185377Ssammade. 294185377Ssam.It Supports RADIUS (rfc 2138 & 2548) authentication. 295185377SsamAn extension to PAP and CHAP, 296185377Ssam.Em \&R Ns No emote 297185377Ssam.Em \&A Ns No ccess 298185377Ssam.Em \&D Ns No ial 299185377Ssam.Em \&I Ns No n 300185377Ssam.Em \&U Ns No ser 301185377Ssam.Em \&S Ns No ervice 302185377Ssamallows authentication information to be stored in a central or 303185377Ssamdistributed database along with various per-user framed connection 304185377Ssamcharacteristics. 305185377Ssamifdef({LOCALRAD},{},{If 306185377Ssam.Xr libradius 3 307185377Ssamis available at compile time, 308185377Ssam.Nm 309185377Ssamwill use it to make 310225925Sadrian.Em RADIUS 311185377Ssamrequests when configured to do so. 312185377Ssam})dnl 313185377Ssam.It Supports Proxy Arp. 314185377Ssam.Nm 315185377Ssamcan be configured to make one or more proxy arp entries on behalf of 316185377Ssamthe peer. 317185377SsamThis allows routing from the peer to the LAN without 318208711Srpauloconfiguring each machine on that LAN. 319208711Srpaulo.It Supports packet filtering. 320226759SadrianUser can {define} four kinds of filters: the 321226759Sadrian.Em in 322226759Sadrianfilter for incoming packets, the 323226759Sadrian.Em out 324226759Sadrianfilter for outgoing packets, the 325226759Sadrian.Em dial 326226759Sadrianfilter to {define} a dialing trigger packet and the 327208711Srpaulo.Em alive 328185377Ssamfilter for keeping a connection alive with the trigger packet. 329185377Ssam.It Tunnel driver supports bpf. 330185377SsamThe user can use 331185377Ssam.Xr tcpdump 1 332185377Ssamto check the packet flow over the 333185377Ssam.Em PPP 334185377Ssamlink. 335185377Ssam.It Supports PPP over TCP and PPP over UDP. 336185377SsamIf a device name is specified as 337185377Ssam.Em host Ns No : Ns Em port Ns 338185377Ssam.Xo 339185377Ssam.Op / Ns tcp|udp , 340185377Ssam.Xc 341185377Ssam.Nm 342185377Ssamwill open a TCP or UDP connection for transporting data rather than using a 343185377Ssamconventional serial device. 344185377SsamUDP connections force 345185377Ssam.Nm 346185377Ssaminto synchronous mode. 347185377Ssam.It Supports PPP over ISDN. 348185377SsamIf 349185377Ssam.Nm 350185377Ssamis given a raw B-channel i4b device to open as a link, it's able to talk 351185377Ssamto the 352185377Ssam.Xr isdnd 8 353185377Ssamdaemon to establish an ISDN connection. 354185377Ssam.It Supports PPP over Ethernet (rfc 2516). 355185377SsamIf 356185377Ssam.Nm 357185377Ssamis given a device specification of the format 358185377Ssam.No PPPoE: Ns Ar iface Ns Xo 359185377Ssam.Op \&: Ns Ar provider Ns 360185377Ssam.Xc 361185377Ssamand if 362185377Ssam.Xr netgraph 4 363185377Ssamis available, 364185377Ssam.Nm 365185377Ssamwill attempt talk 366185377Ssam.Em PPP 367185377Ssamover Ethernet to 368185377Ssam.Ar provider 369185377Ssamusing the 370185377Ssam.Ar iface 371185377Ssamnetwork interface. 372185377Ssam.Pp 373188976SsamOn systems that do not support 374188976Ssam.Xr netgraph 4 , 375188976Ssaman external program such as 376188976Ssam.Xr pppoed 8 377188976Ssammay be used. 378188976Ssam.It "Supports IETF draft Predictor-1 (rfc 1978) and DEFLATE (rfc 1979) compression." 379188976Ssam.Nm 380188976Ssamsupports not only VJ-compression but also Predictor-1 and DEFLATE compression. 381188976SsamNormally, a modem has built-in compression (e.g., v42.bis) and the system 382188976Ssammay receive higher data rates from it as a result of such compression. 383188976SsamWhile this is generally a good thing in most other situations, this 384188976Ssamhigher speed data imposes a penalty on the system by increasing the 385188976Ssamnumber of serial interrupts the system has to process in talking to the 386188976Ssammodem and also increases latency. 387188976SsamUnlike VJ-compression, Predictor-1 and DEFLATE compression pre-compresses 388185377Ssam.Em all 389185377Ssamnetwork traffic flowing through the link, thus reducing overheads to a 390185377Ssamminimum. 391185377Ssam.It Supports Microsoft's IPCP extensions (rfc 1877). 392221163SadrianName Server Addresses and NetBIOS Name Server Addresses can be negotiated 393221163Sadrianwith clients using the Microsoft 394221163Sadrian.Em PPP 395221163Sadrianstack (i.e., Win95, WinNT) 396185377Ssam.It Supports Multi-link PPP (rfc 1990) 397185377SsamIt is possible to configure 398185377Ssam.Nm 399185377Ssamto open more than one physical connection to the peer, combining the 400185377Ssambandwidth of all links for better throughput. 401185377Ssam.It Supports MPPE (draft-ietf-pppext-mppe) 402185377SsamMPPE is Microsoft Point to Point Encryption scheme. 403185377SsamIt is possible to configure 404185377Ssam.Nm 405185377Ssamto participate in Microsoft's Windows VPN. 406185377SsamFor now, 407185377Ssam.Nm 408185377Ssamcan only get encryption keys from CHAP 81 authentication. 409185377Ssam.Nm 410185377Ssammust be compiled with DES for MPPE to operate. 411221163Sadrian.It Supports IPV6CP (rfc 2023). 412221163SadrianAn IPv6 connection can be made in addition to or instead of the normal 413221163SadrianIPv4 connection. 414185377Ssam.El 415221163Sadrian.Sh PERMISSIONS 416185377Ssam.Nm 417185377Ssamis installed as user 418185377Ssam.Dv root 419185377Ssamand group 420185377Ssam.Dv network , 421185377Ssamwith permissions 422185377Ssam.Dv 04554 . 423185377SsamBy default, 424185377Ssam.Nm 425185377Ssamwill not run if the invoking user id is not zero. 426185377SsamThis may be overridden by using the 427185377Ssam.Dq allow users 428185377Ssamcommand in 429185377Ssam.Pa /etc/ppp/ppp.conf . 430185377SsamWhen running as a normal user, 431185377Ssam.Nm 432221806Sadrianswitches to user id 0 in order to alter the system routing table, set up 433221806Sadriansystem lock files and read the ppp configuration files. 434221806SadrianAll external commands (executed via the "shell" or "!bg" commands) are executed 435221806Sadrianas the user id that invoked 436221806Sadrian.Nm . 437221806SadrianRefer to the 438221806Sadrian.Sq ID0 439185377Ssamlogging facility if you're interested in what exactly is done as user id 440185377Ssamzero. 441185377Ssam.Sh GETTING STARTED 442185377SsamWhen you first run 443185377Ssam.Nm 444185377Ssamyou may need to deal with some initial configuration details. 445185377Ssam.Bl -bullet 446185377Ssam.It 447185377SsamYour kernel must {include} a tunnel device (the GENERIC kernel includes 448185377Ssamone by default). 449185377SsamIf it doesn't, or if you require more than one tun 450185377Ssaminterface, you'll need to rebuild your kernel with the following line in 451185377Ssamyour kernel configuration file: 452185377Ssam.Pp 453185377Ssam.Dl pseudo-device tun N 454185377Ssam.Pp 455185377Ssamwhere 456185377Ssam.Ar N 457185377Ssamis the maximum number of 458185377Ssam.Em PPP 459218420Sadrianconnections you wish to support. 460218420Sadrian.It 461218420SadrianCheck your 462218420Sadrian.Pa /dev 463185377Ssamdirectory for the tunnel device entries 464185377Ssam.Pa /dev/tunN , 465185377Ssamwhere 466185377Ssam.Sq N 467185377Ssamrepresents the number of the tun device, starting at zero. 468185377SsamIf they don't exist, you can create them by running "sh ./MAKEDEV tunN". 469185377SsamThis will create tun devices 0 through 470185377Ssam.Ar N . 471185377Ssam.It 472185377SsamMake sure that your system has a group named 473203159Srpaulo.Dq network 474203159Srpauloin the 475203159Srpaulo.Pa /etc/group 476185377Ssamfile and that the group contains the names of all users expected to use 477225125Sadrian.Nm . 478185377SsamRefer to the 479185377Ssam.Xr group 5 480185377Ssammanual page for details. 481185377SsamEach of these users must also be given access using the 482185377Ssam.Dq allow users 483185377Ssamcommand in 484185377Ssam.Pa /etc/ppp/ppp.conf . 485185377Ssam.It 486185377SsamCreate a log file. 487185377Ssam.Nm 488185377Ssamuses 489185377Ssam.Xr syslog 3 490185377Ssamto log information. 491185377SsamA common log file name is 492185377Ssam.Pa /var/log/ppp.log . 493185377SsamTo make output go to this file, put the following lines in the 494185377Ssam.Pa /etc/syslog.conf 495185377Ssamfile: 496185377Ssam.Bd -literal -offset indent 497185377Ssam!ppp 498185377Ssam*.*<TAB>/var/log/ppp.log 499185377Ssam.Ed 500185377Ssam.Pp 501185377SsamIt is possible to have more than one 502185377Ssam.Em PPP 503185377Ssamlog file by creating a link to the 504185377Ssam.Nm 505185377Ssamexecutable: 506185377Ssam.Pp 507185377Ssam.Dl # cd /usr/sbin 508185377Ssam.Dl # ln ppp ppp0 509185377Ssam.Pp 510185377Ssamand using 511185377Ssam.Bd -literal -offset indent 512185377Ssam!ppp0 513185377Ssam*.*<TAB>/var/log/ppp0.log 514185377Ssam.Ed 515185377Ssam.Pp 516185377Ssamin 517185377Ssam.Pa /etc/syslog.conf . 518185377SsamDon't forget to send a 519234692Sadrian.Dv HUP 520234692Sadriansignal to 521185377Ssam.Xr syslogd 8 522185377Ssamafter altering 523185377Ssam.Pa /etc/syslog.conf . 524185377Ssam.It 525219978SadrianAlthough not strictly relevant to 526219978Sadrian.Nm Ns No 's 527221617Sadrianoperation, you should configure your resolver so that it works correctly. 528221617SadrianThis can be done by configuring a local DNS 529221617Sadrian(using 530221617Sadrian.Xr named 8 ) 531221617Sadrianor by adding the correct 532221617Sadrian.Sq nameserver 533222301Sadrianlines to the file 534208711Srpaulo.Pa /etc/resolv.conf . 535219217SadrianRefer to the 536208711Srpaulo.Xr resolv.conf 5 537222301Sadrianmanual page for details. 538222301Sadrian.Pp 539222301SadrianAlternatively, if the peer supports it, 540222301Sadrian.Nm 541222301Sadriancan be configured to ask the peer for the nameserver address(es) and to 542222301Sadrianupdate 543222301Sadrian.Pa /etc/resolv.conf 544222301Sadrianautomatically. 545222301SadrianRefer to the 546222301Sadrian.Dq enable dns 547222301Sadrianand 548222301Sadrian.Dq resolv 549222301Sadriancommands below for details. 550185377Ssam.El 551185377Ssam.Sh MANUAL DIALING 552185377SsamIn the following examples, we assume that your machine name is 553185377Ssam.Dv awfulhak . 554185377Ssamwhen you invoke 555185377Ssam.Nm 556185377Ssam(see 557185377Ssam.Sx PERMISSIONS 558185377Ssamabove) with no arguments, you are presented with a prompt: 559185377Ssam.Bd -literal -offset indent 560188976Ssamppp ON awfulhak> 561188976Ssam.Ed 562188976Ssam.Pp 563188976SsamThe 564188976Ssam.Sq ON 565188976Ssampart of your prompt should always be in upper case. 566228834SadrianIf it is in lower case, it means that you must supply a password using the 567228834Sadrian.Dq passwd 568188976Ssamcommand. 569188976SsamThis only ever happens if you connect to a running version of 570188976Ssam.Nm 571188976Ssamand have not authenticated yourself using the correct password. 572188976Ssam.Pp 573188976SsamYou can start by specifying the device name and speed: 574188976Ssam.Bd -literal -offset indent 575188976Ssamppp ON awfulhak> set device /dev/cuad0 576188976Ssamppp ON awfulhak> set speed 38400 577188976Ssam.Ed 578208711Srpaulo.Pp 579208711SrpauloNormally, hardware flow control (CTS/RTS) is used. 580185377SsamHowever, under 581185377Ssamcertain circumstances (as may happen when you are connected directly 582185377Ssamto certain PPP-capable terminal servers), this may result in 583185377Ssam.Nm 584203159Srpaulohanging as soon as it tries to write data to your communications link 585185377Ssamas it is waiting for the CTS (clear to send) signal - which will never 586222301Sadriancome. 587222301SadrianThus, if you have a direct line and can't seem to make a 588222301Sadrianconnection, try turning CTS/RTS off with 589222301Sadrian.Dq set ctsrts off . 590222301SadrianIf you need to do this, check the 591222301Sadrian.Dq set accmap 592222301Sadriandescription below too - you'll probably need to 593222301Sadrian.Dq set accmap 000a0000 . 594222301Sadrian.Pp 595222301SadrianUsually, parity is set to 596222301Sadrian.Dq none , 597185377Ssamand this is 598185377Ssam.Nm Ns No 's 599185377Ssamdefault. 600185377SsamParity is a rather archaic error checking mechanism that is no 601185377Ssamlonger used because modern modems do their own error checking, and most 602185377Ssamlink-layer protocols (that's what 603185377Ssam.Nm 604185377Ssamis) use much more reliable checking mechanisms. 605221573SadrianParity has a relatively 606221573Sadrianhuge overhead (a 12.5% increase in traffic) and as a result, it is always 607221573Sadriandisabled 608221573Sadrian(set to 609221573Sadrian.Dq none ) 610221573Sadrianwhen 611221573Sadrian.Dv PPP 612221573Sadrianis opened. 613221573SadrianHowever, some ISPs (Internet Service Providers) may use 614221573Sadrianspecific parity settings at connection time (before 615221573Sadrian.Dv PPP 616185377Ssamis opened). 617185377SsamNotably, Compuserve insist on even parity when logging in: 618185377Ssam.Bd -literal -offset indent 619185377Ssamppp ON awfulhak> set parity even 620185377Ssam.Ed 621185377Ssam.Pp 622185377SsamYou can now see what your current device settings look like: 623185377Ssam.Bd -literal -offset indent 624185377Ssamppp ON awfulhak> show physical 625185377SsamName: deflink 626221608Sadrian State: closed 627221608Sadrian Device: N/A 628221608Sadrian Link Type: interactive 629185377Ssam Connect Count: 0 630221573Sadrian Queued Packets: 0 631221573Sadrian Phone Number: N/A 632221573Sadrian 633221573SadrianDefaults: 634185377Ssam Device List: /dev/cuad0 635185377Ssam Characteristics: 38400bps, cs8, even parity, CTS/RTS on 636185377Ssam 637185377SsamConnect time: 0 secs 638185377Ssam0 octets in, 0 octets out 639185377SsamOverall 0 bytes/sec 640185377Ssamppp ON awfulhak> 641185377Ssam.Ed 642185377Ssam.Pp 643185377SsamThe term command can now be used to talk directly to the device: 644185377Ssam.Bd -literal -offset indent 645185377Ssamppp ON awfulhak> term 646185377Ssamat 647185377SsamOK 648185377Ssamatdt123456 649221573SadrianCONNECT 650221573Sadrianlogin: myispusername 651221573SadrianPassword: myisppassword 652221573SadrianProtocol: ppp 653221573Sadrian.Ed 654221573Sadrian.Pp 655221573SadrianWhen the peer starts to talk in 656221573Sadrian.Em PPP , 657221573Sadrian.Nm 658185377Ssamdetects this automatically and returns to command mode. 659185377Ssam.Bd -literal -offset indent 660185377Ssamppp ON awfulhak> # No link has been established 661221573SadrianPpp ON awfulhak> # We've connected & finished LCP 662221573SadrianPPp ON awfulhak> # We've authenticated 663219217SadrianPPP ON awfulhak> # We've agreed IP numbers 664221163Sadrian.Ed 665185377Ssam.Pp 666185377SsamIf it does not, it's probable that the peer is waiting for your end to 667185377Ssamstart negotiating. 668185377SsamTo force 669185377Ssam.Nm 670185377Ssamto start sending 671185377Ssam.Em PPP 672185377Ssamconfiguration packets to the peer, use the 673203159Srpaulo.Dq ~p 674203159Srpaulocommand to drop out of terminal mode and enter packet mode. 675222301Sadrian.Pp 676227408SadrianIf you never even receive a login prompt, it is quite likely that the 677227408Sadrianpeer wants to use PAP or CHAP authentication instead of using Unix-style 678227408Sadrianlogin/password authentication. 679227408SadrianTo set things up properly, drop back to 680185377Ssamthe prompt and set your authentication name and key, then reconnect: 681221480Sadrian.Bd -literal -offset indent 682217881Sadrian~. 683217881Sadrianppp ON awfulhak> set authname myispusername 684217881Sadrianppp ON awfulhak> set authkey myisppassword 685217881Sadrianppp ON awfulhak> term 686185377Ssamat 687221480SadrianOK 688221573Sadrianatdt123456 689221480SadrianCONNECT 690221480Sadrian.Ed 691185377Ssam.Pp 692221480SadrianYou may need to tell ppp to initiate negotiations with the peer here too: 693221573Sadrian.Bd -literal -offset indent 694221480Sadrian~p 695185377Ssamppp ON awfulhak> # No link has been established 696221480SadrianPpp ON awfulhak> # We've connected & finished LCP 697221480SadrianPPp ON awfulhak> # We've authenticated 698221163SadrianPPP ON awfulhak> # We've agreed IP numbers 699221163Sadrian.Ed 700221480Sadrian.Pp 701221163SadrianYou are now connected! 702221163SadrianNote that 703221480Sadrian.Sq PPP 704221480Sadrianin the prompt has changed to capital letters to indicate that you have 705185377Ssama peer connection. 706185377SsamIf only some of the three Ps go uppercase, wait until 707221480Sadrianeither everything is uppercase or lowercase. 708185377SsamIf they revert to lowercase, it means that 709185377Ssam.Nm 710221480Sadriancouldn't successfully negotiate with the peer. 711185377SsamA good first step for troubleshooting at this point would be to 712185377Ssam.Bd -literal -offset indent 713185377Ssamppp ON awfulhak> set log local phase lcp ipcp 714185377Ssam.Ed 715221480Sadrian.Pp 716221480Sadrianand try again. 717185377SsamRefer to the 718185377Ssam.Dq set log 719221480Sadriancommand description below for further details. 720185377SsamIf things fail at this point, 721185377Ssamit is quite important that you turn logging on and try again. 722221480SadrianIt is also 723185377Ssamimportant that you note any prompt changes and report them to anyone trying 724185377Ssamto help you. 725221666Sadrian.Pp 726221480SadrianWhen the link is established, the show command can be used to see how 727185377Ssamthings are going: 728221480Sadrian.Bd -literal -offset indent 729221480SadrianPPP ON awfulhak> show physical 730221480Sadrian* Modem related information is shown here * 731185377SsamPPP ON awfulhak> show ccp 732221480Sadrian* CCP (compression) related information is shown here * 733221480SadrianPPP ON awfulhak> show lcp 734185377Ssam* LCP (line control) related information is shown here * 735185377SsamPPP ON awfulhak> show ipcp 736221480Sadrian* IPCP (IP) related information is shown here * 737185377SsamPPP ON awfulhak> show ipv6cp 738185377Ssam* IPV6CP (IPv6) related information is shown here * 739221480SadrianPPP ON awfulhak> show link 740203159Srpaulo* Link (high level) related information is shown here * 741203159SrpauloPPP ON awfulhak> show bundle 742203159Srpaulo* Logical (high level) connection related information is shown here * 743221480Sadrian.Ed 744203159Srpaulo.Pp 745221480SadrianAt this point, your machine has a host route to the peer. 746221480SadrianThis means 747221480Sadrianthat you can only make a connection with the host on the other side 748221480Sadrianof the link. 749203159SrpauloIf you want to add a default route entry (telling your 750203159Srpaulomachine to send all packets without another routing entry to the other 751203959Srpauloside of the 752221480Sadrian.Em PPP 753203159Srpaulolink), enter the following command: 754221480Sadrian.Bd -literal -offset indent 755221480SadrianPPP ON awfulhak> add default HISADDR 756221480Sadrian.Ed 757221480Sadrian.Pp 758218061SadrianThe string 759218061Sadrian.Sq HISADDR 760218061Sadrianrepresents the IP address of the connected peer. 761218061SadrianIf the 762222300Sadrian.Dq add 763222300Sadriancommand fails due to an existing route, you can overwrite the existing 764222300Sadrianroute using: 765227408Sadrian.Bd -literal -offset indent 766227408SadrianPPP ON awfulhak> add! default HISADDR 767227408Sadrian.Ed 768227408Sadrian.Pp 769222300SadrianThis command can also be executed before actually making the connection. 770222300SadrianIf a new IP address is negotiated at connection time, 771222300Sadrian.Nm 772222300Sadrianwill update your default route accordingly. 773222300Sadrian.Pp 774222300SadrianYou can now use your network applications (ping, telnet, ftp, etc.) 775222300Sadrianin other windows or terminals on your machine. 776222300SadrianIf you wish to reuse the current terminal, you can put 777222300Sadrian.Nm 778222300Sadrianinto the background using your standard shell suspend and background 779222300Sadriancommands (usually 780222300Sadrian.Dq ^Z 781222300Sadrianfollowed by 782222300Sadrian.Dq bg ) . 783222300Sadrian.Pp 784222300SadrianRefer to the 785222300Sadrian.Sx PPP COMMAND LIST 786222300Sadriansection for details on all available commands. 787222300Sadrian.Sh AUTOMATIC DIALING 788222300SadrianTo use automatic dialing, you must prepare some Dial and Login chat scripts. 789222300SadrianSee the example definitions in 790219217Sadrian.Pa /usr/share/examples/ppp/ppp.conf.sample 791219217Sadrian(the format of 792219217Sadrian.Pa /etc/ppp/ppp.conf 793185377Ssamis pretty simple). 794Each line contains one comment, inclusion, label or command: 795.Bl -bullet 796.It 797A line starting with a 798.Pq Dq # 799character is treated as a comment line. 800Leading whitespace are ignored when identifying comment lines. 801.It 802An inclusion is a line beginning with the word 803.Sq {!include} . 804It must have one argument - the file to {include}. 805You may wish to 806.Dq {!include} ~/.ppp.conf 807for compatibility with older versions of 808.Nm . 809.It 810A label name starts in the first column and is followed by 811a colon 812.Pq Dq \&: . 813.It 814A command line must contain a space or tab in the first column. 815.El 816.Pp 817The 818.Pa /etc/ppp/ppp.conf 819file should consist of at least a 820.Dq default 821section. 822This section is always executed. 823It should also contain 824one or more sections, named according to their purpose, for example, 825.Dq MyISP 826would represent your ISP, and 827.Dq ppp-in 828would represent an incoming 829.Nm 830configuration. 831You can now specify the destination label name when you invoke 832.Nm . 833Commands associated with the 834.Dq default 835label are executed, followed by those associated with the destination 836label provided. 837When 838.Nm 839is started with no arguments, the 840.Dq default 841section is still executed. 842The load command can be used to manually load a section from the 843.Pa /etc/ppp/ppp.conf 844file: 845.Bd -literal -offset indent 846ppp ON awfulhak> load MyISP 847.Ed 848.Pp 849Note, no action is taken by 850.Nm 851after a section is loaded, whether it's the result of passing a label on 852the command line or using the 853.Dq load 854command. 855Only the commands specified for that label in the configuration 856file are executed. 857However, when invoking 858.Nm 859with the 860.Fl background , 861.Fl ddial , 862or 863.Fl dedicated 864switches, the link mode tells 865.Nm 866to establish a connection. 867Refer to the 868.Dq set mode 869command below for further details. 870.Pp 871Once the connection is made, the 872.Sq ppp 873portion of the prompt will change to 874.Sq PPP : 875.Bd -literal -offset indent 876# ppp MyISP 877\&... 878ppp ON awfulhak> dial 879Ppp ON awfulhak> 880PPp ON awfulhak> 881PPP ON awfulhak> 882.Ed 883.Pp 884The Ppp prompt indicates that 885.Nm 886has entered the authentication phase. 887The PPp prompt indicates that 888.Nm 889has entered the network phase. 890The PPP prompt indicates that 891.Nm 892has successfully negotiated a network layer protocol and is in 893a usable state. 894.Pp 895If the 896.Pa /etc/ppp/ppp.linkup 897file is available, its contents are executed 898when the 899.Em PPP 900connection is established. 901See the provided 902.Dq pmdemand 903example in 904.Pa /usr/share/examples/ppp/ppp.conf.sample 905which runs a script in the background after the connection is established 906(refer to the 907.Dq shell 908and 909.Dq bg 910commands below for a description of possible substitution strings). 911Similarly, when a connection is closed, the contents of the 912.Pa /etc/ppp/ppp.linkdown 913file are executed. 914Both of these files have the same format as 915.Pa /etc/ppp/ppp.conf . 916.Pp 917In previous versions of 918.Nm , 919it was necessary to re-add routes such as the default route in the 920.Pa ppp.linkup 921file. 922.Nm 923supports 924.Sq sticky routes , 925where all routes that contain the 926.Dv HISADDR , 927.Dv MYADDR , 928.Dv HISADDR6 929or 930.Dv MYADDR6 931literals will automatically be updated when the values of these variables 932change. 933.Sh BACKGROUND DIALING 934If you want to establish a connection using 935.Nm 936non-interactively (such as from a 937.Xr crontab 5 938entry or an 939.Xr at 1 940job) you should use the 941.Fl background 942option. 943When 944.Fl background 945is specified, 946.Nm 947attempts to establish the connection immediately. 948If multiple phone 949numbers are specified, each phone number will be tried once. 950If the attempt fails, 951.Nm 952exits immediately with a non-zero exit code. 953If it succeeds, then 954.Nm 955becomes a daemon, and returns an exit status of zero to its caller. 956The daemon exits automatically if the connection is dropped by the 957remote system, or it receives a 958.Dv TERM 959signal. 960.Sh DIAL ON DEMAND 961Demand dialing is enabled with the 962.Fl auto 963or 964.Fl ddial 965options. 966You must also specify the destination label in 967.Pa /etc/ppp/ppp.conf 968to use. 969It must contain the 970.Dq set ifaddr 971command to {define} the remote peers IP address. 972(refer to 973.Pa /usr/share/examples/ppp/ppp.conf.sample ) 974.Bd -literal -offset indent 975# ppp -auto pmdemand 976.Ed 977.Pp 978When 979.Fl auto 980or 981.Fl ddial 982is specified, 983.Nm 984runs as a daemon but you can still configure or examine its 985configuration by using the 986.Dq set server 987command in 988.Pa /etc/ppp/ppp.conf , 989(for example, 990.Dq Li "set server +3000 mypasswd" ) 991and connecting to the diagnostic port as follows: 992.Bd -literal -offset indent 993# pppctl 3000 (assuming tun0) 994Password: 995PPP ON awfulhak> show who 996tcp (127.0.0.1:1028) * 997.Ed 998.Pp 999The 1000.Dq show who 1001command lists users that are currently connected to 1002.Nm 1003itself. 1004If the diagnostic socket is closed or changed to a different 1005socket, all connections are immediately dropped. 1006.Pp 1007In 1008.Fl auto 1009mode, when an outgoing packet is detected, 1010.Nm 1011will perform the dialing action (chat script) and try to connect 1012with the peer. 1013In 1014.Fl ddial 1015mode, the dialing action is performed any time the line is found 1016to be down. 1017If the connect fails, the default behaviour is to wait 30 seconds 1018and then attempt to connect when another outgoing packet is detected. 1019This behaviour can be changed using the 1020.Dq set redial 1021command: 1022.Pp 1023.No set redial Ar secs Ns Xo 1024.Oo + Ns Ar inc Ns 1025.Op - Ns Ar max Ns 1026.Oc Ns Op . Ns Ar next 1027.Op Ar attempts 1028.Xc 1029.Pp 1030.Bl -tag -width attempts -compact 1031.It Ar secs 1032is the number of seconds to wait before attempting 1033to connect again. 1034If the argument is the literal string 1035.Sq Li random , 1036the delay period is a random value between 1 and 30 seconds inclusive. 1037.It Ar inc 1038is the number of seconds that 1039.Ar secs 1040should be incremented each time a new dial attempt is made. 1041The timeout reverts to 1042.Ar secs 1043only after a successful connection is established. 1044The default value for 1045.Ar inc 1046is zero. 1047.It Ar max 1048is the maximum number of times 1049.Nm 1050should increment 1051.Ar secs . 1052The default value for 1053.Ar max 1054is 10. 1055.It Ar next 1056is the number of seconds to wait before attempting 1057to dial the next number in a list of numbers (see the 1058.Dq set phone 1059command). 1060The default is 3 seconds. 1061Again, if the argument is the literal string 1062.Sq Li random , 1063the delay period is a random value between 1 and 30 seconds. 1064.It Ar attempts 1065is the maximum number of times to try to connect for each outgoing packet 1066that triggers a dial. 1067The previous value is unchanged if this parameter is omitted. 1068If a value of zero is specified for 1069.Ar attempts , 1070.Nm 1071will keep trying until a connection is made. 1072.El 1073.Pp 1074So, for example: 1075.Bd -literal -offset indent 1076set redial 10.3 4 1077.Ed 1078.Pp 1079will attempt to connect 4 times for each outgoing packet that causes 1080a dial attempt with a 3 second delay between each number and a 10 second 1081delay after all numbers have been tried. 1082If multiple phone numbers 1083are specified, the total number of attempts is still 4 (it does not 1084attempt each number 4 times). 1085.Pp 1086Alternatively, 1087.Pp 1088.Bd -literal -offset indent 1089set redial 10+10-5.3 20 1090.Ed 1091.Pp 1092tells 1093.Nm 1094to attempt to connect 20 times. 1095After the first attempt, 1096.Nm 1097pauses for 10 seconds. 1098After the next attempt it pauses for 20 seconds 1099and so on until after the sixth attempt it pauses for 1 minute. 1100The next 14 pauses will also have a duration of one minute. 1101If 1102.Nm 1103connects, disconnects and fails to connect again, the timeout starts again 1104at 10 seconds. 1105.Pp 1106Modifying the dial delay is very useful when running 1107.Nm 1108in 1109.Fl auto 1110mode on both ends of the link. 1111If each end has the same timeout, 1112both ends wind up calling each other at the same time if the link 1113drops and both ends have packets queued. 1114At some locations, the serial link may not be reliable, and carrier 1115may be lost at inappropriate times. 1116It is possible to have 1117.Nm 1118redial should carrier be unexpectedly lost during a session. 1119.Bd -literal -offset indent 1120set reconnect timeout ntries 1121.Ed 1122.Pp 1123This command tells 1124.Nm 1125to re-establish the connection 1126.Ar ntries 1127times on loss of carrier with a pause of 1128.Ar timeout 1129seconds before each try. 1130For example, 1131.Bd -literal -offset indent 1132set reconnect 3 5 1133.Ed 1134.Pp 1135tells 1136.Nm 1137that on an unexpected loss of carrier, it should wait 1138.Ar 3 1139seconds before attempting to reconnect. 1140This may happen up to 1141.Ar 5 1142times before 1143.Nm 1144gives up. 1145The default value of ntries is zero (no reconnect). 1146Care should be taken with this option. 1147If the local timeout is slightly 1148longer than the remote timeout, the reconnect feature will always be 1149triggered (up to the given number of times) after the remote side 1150times out and hangs up. 1151NOTE: In this context, losing too many LQRs constitutes a loss of 1152carrier and will trigger a reconnect. 1153If the 1154.Fl background 1155flag is specified, all phone numbers are dialed at most once until 1156a connection is made. 1157The next number redial period specified with the 1158.Dq set redial 1159command is honoured, as is the reconnect tries value. 1160If your redial 1161value is less than the number of phone numbers specified, not all 1162the specified numbers will be tried. 1163To terminate the program, type 1164.Bd -literal -offset indent 1165PPP ON awfulhak> close 1166ppp ON awfulhak> quit all 1167.Ed 1168.Pp 1169A simple 1170.Dq quit 1171command will terminate the 1172.Xr pppctl 8 1173or 1174.Xr telnet 1 1175connection but not the 1176.Nm 1177program itself. 1178You must use 1179.Dq quit all 1180to terminate 1181.Nm 1182as well. 1183.Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1) 1184To handle an incoming 1185.Em PPP 1186connection request, follow these steps: 1187.Bl -enum 1188.It 1189Make sure the modem and (optionally) 1190.Pa /etc/rc.serial 1191is configured correctly. 1192.Bl -bullet -compact 1193.It 1194Use Hardware Handshake (CTS/RTS) for flow control. 1195.It 1196Modem should be set to NO echo back (ATE0) and NO results string (ATQ1). 1197.El 1198.Pp 1199.It 1200Edit 1201.Pa /etc/ttys 1202to enable a 1203.Xr getty 8 1204on the port where the modem is attached. 1205For example: 1206.Pp 1207.Dl ttyd1 Qo /usr/libexec/getty std.38400 Qc dialup on secure 1208.Pp 1209Don't forget to send a 1210.Dv HUP 1211signal to the 1212.Xr init 8 1213process to start the 1214.Xr getty 8 : 1215.Pp 1216.Dl # kill -HUP 1 1217.Pp 1218It is usually also necessary to train your modem to the same DTR speed 1219as the getty: 1220.Bd -literal -offset indent 1221# ppp 1222ppp ON awfulhak> set device /dev/cuad1 1223ppp ON awfulhak> set speed 38400 1224ppp ON awfulhak> term 1225deflink: Entering terminal mode on /dev/cuad1 1226Type `~?' for help 1227at 1228OK 1229at 1230OK 1231atz 1232OK 1233at 1234OK 1235~. 1236ppp ON awfulhak> quit 1237.Ed 1238.It 1239Create a 1240.Pa /usr/local/bin/ppplogin 1241file with the following contents: 1242.Bd -literal -offset indent 1243#! /bin/sh 1244exec /usr/sbin/ppp -direct incoming 1245.Ed 1246.Pp 1247Direct mode 1248.Pq Fl direct 1249lets 1250.Nm 1251work with stdin and stdout. 1252You can also use 1253.Xr pppctl 8 1254to connect to a configured diagnostic port, in the same manner as with 1255client-side 1256.Nm . 1257.Pp 1258Here, the 1259.Ar incoming 1260section must be set up in 1261.Pa /etc/ppp/ppp.conf . 1262.Pp 1263Make sure that the 1264.Ar incoming 1265section contains the 1266.Dq allow users 1267command as appropriate. 1268.It 1269Prepare an account for the incoming user. 1270.Bd -literal 1271ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin 1272.Ed 1273.Pp 1274Refer to the manual entries for 1275.Xr adduser 8 1276and 1277.Xr vipw 8 1278for details. 1279.It 1280Support for IPCP Domain Name Server and NetBIOS Name Server negotiation 1281can be enabled using the 1282.Dq accept dns 1283and 1284.Dq set nbns 1285commands. 1286Refer to their descriptions below. 1287.El 1288.Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2) 1289This method differs in that we use 1290.Nm 1291to authenticate the connection rather than 1292.Xr login 1 : 1293.Bl -enum 1294.It 1295Configure your default section in 1296.Pa /etc/gettytab 1297with automatic ppp recognition by specifying the 1298.Dq pp 1299capability: 1300.Bd -literal 1301default:\\ 1302 :pp=/usr/local/bin/ppplogin:\\ 1303 ..... 1304.Ed 1305.It 1306Configure your serial device(s), enable a 1307.Xr getty 8 1308and create 1309.Pa /usr/local/bin/ppplogin 1310as in the first three steps for method 1 above. 1311.It 1312Add either 1313.Dq enable chap 1314or 1315.Dq enable pap 1316(or both) 1317to 1318.Pa /etc/ppp/ppp.conf 1319under the 1320.Sq incoming 1321label (or whatever label 1322.Pa ppplogin 1323uses). 1324.It 1325Create an entry in 1326.Pa /etc/ppp/ppp.secret 1327for each incoming user: 1328.Bd -literal 1329Pfred<TAB>xxxx 1330Pgeorge<TAB>yyyy 1331.Ed 1332.El 1333.Pp 1334Now, as soon as 1335.Xr getty 8 1336detects a ppp connection (by recognising the HDLC frame headers), it runs 1337.Dq /usr/local/bin/ppplogin . 1338.Pp 1339It is 1340.Em VITAL 1341that either PAP or CHAP are enabled as above. 1342If they are not, you are 1343allowing anybody to establish a ppp session with your machine 1344.Em without 1345a password, opening yourself up to all sorts of potential attacks. 1346.Sh AUTHENTICATING INCOMING CONNECTIONS 1347Normally, the receiver of a connection requires that the peer 1348authenticates itself. 1349This may be done using 1350.Xr login 1 , 1351but alternatively, you can use PAP or CHAP. 1352CHAP is the more secure of the two, but some clients may not support it. 1353Once you decide which you wish to use, add the command 1354.Sq enable chap 1355or 1356.Sq enable pap 1357to the relevant section of 1358.Pa ppp.conf . 1359.Pp 1360You must then configure the 1361.Pa /etc/ppp/ppp.secret 1362file. 1363This file contains one line per possible client, each line 1364containing up to five fields: 1365.Pp 1366.Ar name Ar key Oo 1367.Ar hisaddr Op Ar label Op Ar callback-number 1368.Oc 1369.Pp 1370The 1371.Ar name 1372and 1373.Ar key 1374specify the client username and password. 1375If 1376.Ar key 1377is 1378.Dq \&* 1379and PAP is being used, 1380.Nm 1381will look up the password database 1382.Pq Xr passwd 5 1383when authenticating. 1384If the client does not offer a suitable response based on any 1385.Ar name Ns No / Ns Ar key 1386combination in 1387.Pa ppp.secret , 1388authentication fails. 1389.Pp 1390If authentication is successful, 1391.Ar hisaddr 1392(if specified) 1393is used when negotiating IP numbers. 1394See the 1395.Dq set ifaddr 1396command for details. 1397.Pp 1398If authentication is successful and 1399.Ar label 1400is specified, the current system label is changed to match the given 1401.Ar label . 1402This will change the subsequent parsing of the 1403.Pa ppp.linkup 1404and 1405.Pa ppp.linkdown 1406files. 1407.Pp 1408If authentication is successful and 1409.Ar callback-number 1410is specified and 1411.Dq set callback 1412has been used in 1413.Pa ppp.conf , 1414the client will be called back on the given number. 1415If CBCP is being used, 1416.Ar callback-number 1417may also contain a list of numbers or a 1418.Dq \&* , 1419as if passed to the 1420.Dq set cbcp 1421command. 1422The value will be used in 1423.Nm Ns No 's 1424subsequent CBCP phase. 1425.Sh PPP OVER TCP and UDP (a.k.a Tunnelling) 1426Instead of running 1427.Nm 1428over a serial link, it is possible to 1429use a TCP connection instead by specifying the host, port and protocol as the 1430device: 1431.Pp 1432.Dl set device ui-gate:6669/tcp 1433.Pp 1434Instead of opening a serial device, 1435.Nm 1436will open a TCP connection to the given machine on the given 1437socket. 1438It should be noted however that 1439.Nm 1440doesn't use the telnet protocol and will be unable to negotiate 1441with a telnet server. 1442You should set up a port for receiving this 1443.Em PPP 1444connection on the receiving machine (ui-gate). 1445This is done by first updating 1446.Pa /etc/services 1447to name the service: 1448.Pp 1449.Dl ppp-in 6669/tcp # Incoming PPP connections over TCP 1450.Pp 1451and updating 1452.Pa /etc/inetd.conf 1453to tell 1454.Xr inetd 8 1455how to deal with incoming connections on that port: 1456.Pp 1457.Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in 1458.Pp 1459Don't forget to send a 1460.Dv HUP 1461signal to 1462.Xr inetd 8 1463after you've updated 1464.Pa /etc/inetd.conf . 1465Here, we use a label named 1466.Dq ppp-in . 1467The entry in 1468.Pa /etc/ppp/ppp.conf 1469on ui-gate (the receiver) should contain the following: 1470.Bd -literal -offset indent 1471ppp-in: 1472 set timeout 0 1473 set ifaddr 10.0.4.1 10.0.4.2 1474.Ed 1475.Pp 1476and the entry in 1477.Pa /etc/ppp/ppp.linkup 1478should contain: 1479.Bd -literal -offset indent 1480ppp-in: 1481 add 10.0.1.0/24 HISADDR 1482.Ed 1483.Pp 1484It is necessary to put the 1485.Dq add 1486command in 1487.Pa ppp.linkup 1488to ensure that the route is only added after 1489.Nm 1490has negotiated and assigned addresses to its interface. 1491.Pp 1492You may also want to enable PAP or CHAP for security. 1493To enable PAP, add the following line: 1494.Bd -literal -offset indent 1495 enable PAP 1496.Ed 1497.Pp 1498You'll also need to create the following entry in 1499.Pa /etc/ppp/ppp.secret : 1500.Bd -literal -offset indent 1501MyAuthName MyAuthPasswd 1502.Ed 1503.Pp 1504If 1505.Ar MyAuthPasswd 1506is a 1507.Dq * , 1508the password is looked up in the 1509.Xr passwd 5 1510database. 1511.Pp 1512The entry in 1513.Pa /etc/ppp/ppp.conf 1514on awfulhak (the initiator) should contain the following: 1515.Bd -literal -offset indent 1516ui-gate: 1517 set escape 0xff 1518 set device ui-gate:ppp-in/tcp 1519 set dial 1520 set timeout 30 1521 set log Phase Chat Connect hdlc LCP IPCP IPV6CP CCP tun 1522 set ifaddr 10.0.4.2 10.0.4.1 1523.Ed 1524.Pp 1525with the route setup in 1526.Pa /etc/ppp/ppp.linkup : 1527.Bd -literal -offset indent 1528ui-gate: 1529 add 10.0.2.0/24 HISADDR 1530.Ed 1531.Pp 1532Again, if you're enabling PAP, you'll also need this in the 1533.Pa /etc/ppp/ppp.conf 1534profile: 1535.Bd -literal -offset indent 1536 set authname MyAuthName 1537 set authkey MyAuthKey 1538.Ed 1539.Pp 1540We're assigning the address of 10.0.4.1 to ui-gate, and the address 154110.0.4.2 to awfulhak. 1542To open the connection, just type 1543.Pp 1544.Dl awfulhak # ppp -background ui-gate 1545.Pp 1546The result will be an additional "route" on awfulhak to the 154710.0.2.0/24 network via the TCP connection, and an additional 1548"route" on ui-gate to the 10.0.1.0/24 network. 1549The networks are effectively bridged - the underlying TCP 1550connection may be across a public network (such as the 1551Internet), and the 1552.Em PPP 1553traffic is conceptually encapsulated 1554(although not packet by packet) inside the TCP stream between 1555the two gateways. 1556.Pp 1557The major disadvantage of this mechanism is that there are two 1558"guaranteed delivery" mechanisms in place - the underlying TCP 1559stream and whatever protocol is used over the 1560.Em PPP 1561link - probably TCP again. 1562If packets are lost, both levels will 1563get in each others way trying to negotiate sending of the missing 1564packet. 1565.Pp 1566To avoid this overhead, it is also possible to do all this using 1567UDP instead of TCP as the transport by simply changing the protocol 1568from "tcp" to "udp". 1569When using UDP as a transport, 1570.Nm 1571will operate in synchronous mode. 1572This is another gain as the incoming 1573data does not have to be rearranged into packets. 1574.Pp 1575Care should be taken when adding a default route through a tunneled 1576setup like this. 1577It is quite common for the default route 1578(added in 1579.Pa /etc/ppp/ppp.linkup ) 1580to end up routing the link's TCP connection through the tunnel, 1581effectively garrotting the connection. 1582To avoid this, make sure you add a static route for the benefit of 1583the link: 1584.Bd -literal -offset indent 1585ui-gate: 1586 set escape 0xff 1587 set device ui-gate:ppp-in/tcp 1588 add ui-gate x.x.x.x 1589 ..... 1590.Ed 1591.Pp 1592where 1593.Dq x.x.x.x 1594is the IP number that your route to 1595.Dq ui-gate 1596would normally use. 1597.Pp 1598When routing your connection accross a public network such as the Internet, 1599it is preferable to encrypt the data. 1600This can be done with the help of the MPPE protocol, although currently this 1601means that you will not be able to also compress the traffic as MPPE is 1602implemented as a compression layer (thank Microsoft for this). 1603To enable MPPE encryption, add the following lines to 1604.Pa /etc/ppp/ppp.conf 1605on the server: 1606.Bd -literal -offset indent 1607 enable MSCHAPv2 1608 disable deflate pred1 1609 deny deflate pred1 1610.Ed 1611.Pp 1612ensuring that you've put the requisite entry in 1613.Pa /etc/ppp/ppp.secret 1614(MSCHAPv2 is challenge based, so 1615.Xr passwd 5 1616cannot be used) 1617.Pp 1618MSCHAPv2 and MPPE are accepted by default, so the client end should work 1619without any additional changes (although ensure you have 1620.Dq set authname 1621and 1622.Dq set authkey 1623in your profile). 1624.Sh NETWORK ADDRESS TRANSLATION (PACKET ALIASING) 1625The 1626.Fl nat 1627command line option enables network address translation (a.k.a.\& packet 1628aliasing). 1629This allows the 1630.Nm 1631host to act as a masquerading gateway for other computers over 1632a local area network. 1633Outgoing IP packets are NAT'd so that they appear to come from the 1634.Nm 1635host, and incoming packets are de-NAT'd so that they are routed 1636to the correct machine on the local area network. 1637NAT allows computers on private, unregistered subnets to have Internet 1638access, although they are invisible from the outside world. 1639In general, correct 1640.Nm 1641operation should first be verified with network address translation disabled. 1642Then, the 1643.Fl nat 1644option should be switched on, and network applications (web browser, 1645.Xr telnet 1 , 1646.Xr ftp 1 , 1647.Xr ping 8 , 1648.Xr traceroute 8 ) 1649should be checked on the 1650.Nm 1651host. 1652Finally, the same or similar applications should be checked on other 1653computers in the LAN. 1654If network applications work correctly on the 1655.Nm 1656host, but not on other machines in the LAN, then the masquerading 1657software is working properly, but the host is either not forwarding 1658or possibly receiving IP packets. 1659Check that IP forwarding is enabled in 1660.Pa /etc/rc.conf 1661and that other machines have designated the 1662.Nm 1663host as the gateway for the LAN. 1664.Sh PACKET FILTERING 1665This implementation supports packet filtering. 1666There are four kinds of 1667filters: the 1668.Em in 1669filter, the 1670.Em out 1671filter, the 1672.Em dial 1673filter and the 1674.Em alive 1675filter. 1676Here are the basics: 1677.Bl -bullet 1678.It 1679A filter definition has the following syntax: 1680.Pp 1681set filter 1682.Ar name 1683.Ar rule-no 1684.Ar action 1685.Op !\& 1686.Oo 1687.Op host 1688.Ar src_addr Ns Op / Ns Ar width 1689.Op Ar dst_addr Ns Op / Ns Ar width 1690.Oc 1691.Ar [ proto Op src Ar cmp port 1692.Op dst Ar cmp port 1693.Op estab 1694.Op syn 1695.Op finrst 1696.Op timeout Ar secs ] 1697.Bl -enum 1698.It 1699.Ar Name 1700should be one of 1701.Sq in , 1702.Sq out , 1703.Sq dial 1704or 1705.Sq alive . 1706.It 1707.Ar Rule-no 1708is a numeric value between 1709.Sq 0 1710and 1711.Sq 39 1712specifying the rule number. 1713Rules are specified in numeric order according to 1714.Ar rule-no , 1715but only if rule 1716.Sq 0 1717is defined. 1718.It 1719.Ar Action 1720may be specified as 1721.Sq permit 1722or 1723.Sq deny , 1724in which case, if a given packet matches the rule, the associated action 1725is taken immediately. 1726.Ar Action 1727can also be specified as 1728.Sq clear 1729to clear the action associated with that particular rule, or as a new 1730rule number greater than the current rule. 1731In this case, if a given 1732packet matches the current rule, the packet will next be matched against 1733the new rule number (rather than the next rule number). 1734.Pp 1735The 1736.Ar action 1737may optionally be followed with an exclamation mark 1738.Pq Dq !\& , 1739telling 1740.Nm 1741to reverse the sense of the following match. 1742.It 1743.Op Ar src_addr Ns Op / Ns Ar width 1744and 1745.Op Ar dst_addr Ns Op / Ns Ar width 1746are the source and destination IP number specifications. 1747If 1748.Op / Ns Ar width 1749is specified, it gives the number of relevant netmask bits, 1750allowing the specification of an address range. 1751.Pp 1752Either 1753.Ar src_addr 1754or 1755.Ar dst_addr 1756may be given the values 1757.Dv MYADDR , 1758.Dv HISADDR , 1759.Dv MYADDR6 1760or 1761.Dv HISADDR6 1762(refer to the description of the 1763.Dq bg 1764command for a description of these values). 1765When these values are used, 1766the filters will be updated any time the values change. 1767This is similar to the behaviour of the 1768.Dq add 1769command below. 1770.It 1771.Ar Proto 1772may be any protocol from 1773.Xr protocols 5 . 1774.It 1775.Ar Cmp 1776is one of 1777.Sq \< , 1778.Sq \&eq 1779or 1780.Sq \> , 1781meaning less-than, equal and greater-than respectively. 1782.Ar Port 1783can be specified as a numeric port or by service name from 1784.Pa /etc/services . 1785.It 1786The 1787.Sq estab , 1788.Sq syn , 1789and 1790.Sq finrst 1791flags are only allowed when 1792.Ar proto 1793is set to 1794.Sq tcp , 1795and represent the TH_ACK, TH_SYN and TH_FIN or TH_RST TCP flags respectively. 1796.It 1797The timeout value adjusts the current idle timeout to at least 1798.Ar secs 1799seconds. 1800If a timeout is given in the alive filter as well as in the in/out 1801filter, the in/out value is used. 1802If no timeout is given, the default timeout (set using 1803.Ic set timeout 1804and defaulting to 180 seconds) is used. 1805.El 1806.Pp 1807.It 1808Each filter can hold up to 40 rules, starting from rule 0. 1809The entire rule set is not effective until rule 0 is defined, 1810i.e., the default is to allow everything through. 1811.It 1812If no rule in a defined set of rules matches a packet, that packet will 1813be discarded (blocked). 1814If there are no rules in a given filter, the packet will be permitted. 1815.It 1816It's possible to filter based on the payload of UDP frames where those 1817frames contain a 1818.Em PROTO_IP 1819.Em PPP 1820frame header. 1821See the 1822.Ar filter-decapsulation 1823option below for further details. 1824.It 1825Use 1826.Dq set filter Ar name No -1 1827to flush all rules. 1828.El 1829.Pp 1830See 1831.Pa /usr/share/examples/ppp/ppp.conf.sample . 1832.Sh SETTING THE IDLE TIMER 1833To check/set the idle timer, use the 1834.Dq show bundle 1835and 1836.Dq set timeout 1837commands: 1838.Bd -literal -offset indent 1839ppp ON awfulhak> set timeout 600 1840.Ed 1841.Pp 1842The timeout period is measured in seconds, the default value for which 1843is 180 seconds 1844(or 3 min). 1845To disable the idle timer function, use the command 1846.Bd -literal -offset indent 1847ppp ON awfulhak> set timeout 0 1848.Ed 1849.Pp 1850In 1851.Fl ddial 1852and 1853.Fl dedicated 1854modes, the idle timeout is ignored. 1855In 1856.Fl auto 1857mode, when the idle timeout causes the 1858.Em PPP 1859session to be 1860closed, the 1861.Nm 1862program itself remains running. 1863Another trigger packet will cause it to attempt to re-establish the link. 1864.Sh PREDICTOR-1 and DEFLATE COMPRESSION 1865.Nm 1866supports both Predictor type 1 and deflate compression. 1867By default, 1868.Nm 1869will attempt to use (or be willing to accept) both compression protocols 1870when the peer agrees 1871(or requests them). 1872The deflate protocol is preferred by 1873.Nm . 1874Refer to the 1875.Dq disable 1876and 1877.Dq deny 1878commands if you wish to disable this functionality. 1879.Pp 1880It is possible to use a different compression algorithm in each direction 1881by using only one of 1882.Dq disable deflate 1883and 1884.Dq deny deflate 1885(assuming that the peer supports both algorithms). 1886.Pp 1887By default, when negotiating DEFLATE, 1888.Nm 1889will use a window size of 15. 1890Refer to the 1891.Dq set deflate 1892command if you wish to change this behaviour. 1893.Pp 1894A special algorithm called DEFLATE24 is also available, and is disabled 1895and denied by default. 1896This is exactly the same as DEFLATE except that 1897it uses CCP ID 24 to negotiate. 1898This allows 1899.Nm 1900to successfully negotiate DEFLATE with 1901.Nm pppd 1902version 2.3.*. 1903.Sh CONTROLLING IP ADDRESS 1904For IPv4, 1905.Nm 1906uses IPCP to negotiate IP addresses. 1907Each side of the connection 1908specifies the IP address that it's willing to use, and if the requested 1909IP address is acceptable then 1910.Nm 1911returns an ACK to the requester. 1912Otherwise, 1913.Nm 1914returns NAK to suggest that the peer use a different IP address. 1915When 1916both sides of the connection agree to accept the received request (and 1917send an ACK), IPCP is set to the open state and a network level connection 1918is established. 1919To control this IPCP behaviour, this implementation has the 1920.Dq set ifaddr 1921command for defining the local and remote IP address: 1922.Bd -ragged -offset indent 1923.No set ifaddr Oo Ar src_addr Ns 1924.Op / Ns Ar \&nn 1925.Oo Ar dst_addr Ns Op / Ns Ar \&nn 1926.Oo Ar netmask 1927.Op Ar trigger_addr 1928.Oc 1929.Oc 1930.Oc 1931.Ed 1932.Pp 1933where, 1934.Sq src_addr 1935is the IP address that the local side is willing to use, 1936.Sq dst_addr 1937is the IP address which the remote side should use and 1938.Sq netmask 1939is the netmask that should be used. 1940.Sq Src_addr 1941defaults to the current 1942.Xr hostname 1 , 1943.Sq dst_addr 1944defaults to 0.0.0.0, and 1945.Sq netmask 1946defaults to whatever mask is appropriate for 1947.Sq src_addr . 1948It is only possible to make 1949.Sq netmask 1950smaller than the default. 1951The usual value is 255.255.255.255, as 1952most kernels ignore the netmask of a POINTOPOINT interface. 1953.Pp 1954Some incorrect 1955.Em PPP 1956implementations require that the peer negotiates a specific IP 1957address instead of 1958.Sq src_addr . 1959If this is the case, 1960.Sq trigger_addr 1961may be used to specify this IP number. 1962This will not affect the 1963routing table unless the other side agrees with this proposed number. 1964.Bd -literal -offset indent 1965set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0 1966.Ed 1967.Pp 1968The above specification means: 1969.Pp 1970.Bl -bullet -compact 1971.It 1972I will first suggest that my IP address should be 0.0.0.0, but I 1973will only accept an address of 192.244.177.38. 1974.It 1975I strongly insist that the peer uses 192.244.177.2 as his own 1976address and won't permit the use of any IP address but 192.244.177.2. 1977When the peer requests another IP address, I will always suggest that 1978it uses 192.244.177.2. 1979.It 1980The routing table entry will have a netmask of 0xffffffff. 1981.El 1982.Pp 1983This is all fine when each side has a pre-determined IP address, however 1984it is often the case that one side is acting as a server which controls 1985all IP addresses and the other side should go along with it. 1986In order to allow more flexible behaviour, the 1987.Dq set ifaddr 1988command allows the user to specify IP addresses more loosely: 1989.Pp 1990.Dl set ifaddr 192.244.177.38/24 192.244.177.2/20 1991.Pp 1992A number followed by a slash 1993.Pq Dq / 1994represents the number of bits significant in the IP address. 1995The above example means: 1996.Pp 1997.Bl -bullet -compact 1998.It 1999I'd like to use 192.244.177.38 as my address if it is possible, but I'll 2000also accept any IP address between 192.244.177.0 and 192.244.177.255. 2001.It 2002I'd like to make him use 192.244.177.2 as his own address, but I'll also 2003permit him to use any IP address between 192.244.176.0 and 2004192.244.191.255. 2005.It 2006As you may have already noticed, 192.244.177.2 is equivalent to saying 2007192.244.177.2/32. 2008.It 2009As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no 2010preferred IP address and will obey the remote peers selection. 2011When using zero, no routing table entries will be made until a connection 2012is established. 2013.It 2014192.244.177.2/0 means that I'll accept/permit any IP address but I'll 2015suggest that 192.244.177.2 be used first. 2016.El 2017.Pp 2018When negotiating IPv6 addresses, no control is given to the user. 2019IPV6CP negotiation is fully automatic. 2020.Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER 2021The following steps should be taken when connecting to your ISP: 2022.Bl -enum 2023.It 2024Describe your providers phone number(s) in the dial script using the 2025.Dq set phone 2026command. 2027This command allows you to set multiple phone numbers for 2028dialing and redialing separated by either a pipe 2029.Pq Dq \&| 2030or a colon 2031.Pq Dq \&: : 2032.Bd -ragged -offset indent 2033.No set phone Ar telno Ns Xo 2034.Oo \&| Ns Ar backupnumber 2035.Oc Ns ... Ns Oo : Ns Ar nextnumber 2036.Oc Ns ... 2037.Xc 2038.Ed 2039.Pp 2040Numbers after the first in a pipe-separated list are only used if the 2041previous number was used in a failed dial or login script. 2042Numbers 2043separated by a colon are used sequentially, irrespective of what happened 2044as a result of using the previous number. 2045For example: 2046.Bd -literal -offset indent 2047set phone "1234567|2345678:3456789|4567890" 2048.Ed 2049.Pp 2050Here, the 1234567 number is attempted. 2051If the dial or login script fails, 2052the 2345678 number is used next time, but *only* if the dial or login script 2053fails. 2054On the dial after this, the 3456789 number is used. 2055The 4567890 2056number is only used if the dial or login script using the 3456789 fails. 2057If the login script of the 2345678 number fails, the next number is still the 20583456789 number. 2059As many pipes and colons can be used as are necessary 2060(although a given site would usually prefer to use either the pipe or the 2061colon, but not both). 2062The next number redial timeout is used between all numbers. 2063When the end of the list is reached, the normal redial period is 2064used before starting at the beginning again. 2065The selected phone number is substituted for the \\\\T string in the 2066.Dq set dial 2067command (see below). 2068.It 2069Set up your redial requirements using 2070.Dq set redial . 2071For example, if you have a bad telephone line or your provider is 2072usually engaged (not so common these days), you may want to specify 2073the following: 2074.Bd -literal -offset indent 2075set redial 10 4 2076.Ed 2077.Pp 2078This says that up to 4 phone calls should be attempted with a pause of 10 2079seconds before dialing the first number again. 2080.It 2081Describe your login procedure using the 2082.Dq set dial 2083and 2084.Dq set login 2085commands. 2086The 2087.Dq set dial 2088command is used to talk to your modem and establish a link with your 2089ISP, for example: 2090.Bd -literal -offset indent 2091set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" \e 2092 ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT" 2093.Ed 2094.Pp 2095This modem "chat" string means: 2096.Bl -bullet 2097.It 2098Abort if the string "BUSY" or "NO CARRIER" are received. 2099.It 2100Set the timeout to 4 seconds. 2101.It 2102Expect nothing. 2103.It 2104Send ATZ. 2105.It 2106Expect OK. 2107If that's not received within the 4 second timeout, send ATZ 2108and expect OK. 2109.It 2110Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from 2111above. 2112.It 2113Set the timeout to 60. 2114.It 2115Wait for the CONNECT string. 2116.El 2117.Pp 2118Once the connection is established, the login script is executed. 2119This script is written in the same style as the dial script, but care should 2120be taken to avoid having your password logged: 2121.Bd -literal -offset indent 2122set authkey MySecret 2123set login "TIMEOUT 15 login:-\\\\r-login: awfulhak \e 2124 word: \\\\P ocol: PPP HELLO" 2125.Ed 2126.Pp 2127This login "chat" string means: 2128.Bl -bullet 2129.It 2130Set the timeout to 15 seconds. 2131.It 2132Expect "login:". 2133If it's not received, send a carriage return and expect 2134"login:" again. 2135.It 2136Send "awfulhak" 2137.It 2138Expect "word:" (the tail end of a "Password:" prompt). 2139.It 2140Send whatever our current 2141.Ar authkey 2142value is set to. 2143.It 2144Expect "ocol:" (the tail end of a "Protocol:" prompt). 2145.It 2146Send "PPP". 2147.It 2148Expect "HELLO". 2149.El 2150.Pp 2151The 2152.Dq set authkey 2153command is logged specially. 2154When 2155.Ar command 2156or 2157.Ar chat 2158logging is enabled, the actual password is not logged; 2159.Sq ******** 2160is logged instead. 2161.Pp 2162Login scripts vary greatly between ISPs. 2163If you're setting one up for the first time, 2164.Em ENABLE CHAT LOGGING 2165so that you can see if your script is behaving as you expect. 2166.It 2167Use 2168.Dq set device 2169and 2170.Dq set speed 2171to specify your serial line and speed, for example: 2172.Bd -literal -offset indent 2173set device /dev/cuad0 2174set speed 115200 2175.Ed 2176.Pp 2177Cuad0 is the first serial port on 2178.Fx . 2179If you're running 2180.Nm 2181on 2182.Ox , 2183cua00 is the first. 2184A speed of 115200 should be specified 2185if you have a modem capable of bit rates of 28800 or more. 2186In general, the serial speed should be about four times the modem speed. 2187.It 2188Use the 2189.Dq set ifaddr 2190command to {define} the IP address. 2191.Bl -bullet 2192.It 2193If you know what IP address your provider uses, then use it as the remote 2194address (dst_addr), otherwise choose something like 10.0.0.2/0 (see below). 2195.It 2196If your provider has assigned a particular IP address to you, then use 2197it as your address (src_addr). 2198.It 2199If your provider assigns your address dynamically, choose a suitably 2200unobtrusive and unspecific IP number as your address. 220110.0.0.1/0 would be appropriate. 2202The bit after the / specifies how many bits of the 2203address you consider to be important, so if you wanted to insist on 2204something in the class C network 1.2.3.0, you could specify 1.2.3.1/24. 2205.It 2206If you find that your ISP accepts the first IP number that you suggest, 2207specify third and forth arguments of 2208.Dq 0.0.0.0 . 2209This will force your ISP to assign a number. 2210(The third argument will 2211be ignored as it is less restrictive than the default mask for your 2212.Sq src_addr ) . 2213.El 2214.Pp 2215An example for a connection where you don't know your IP number or your 2216ISPs IP number would be: 2217.Bd -literal -offset indent 2218set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0 2219.Ed 2220.Pp 2221.It 2222In most cases, your ISP will also be your default router. 2223If this is the case, add the line 2224.Bd -literal -offset indent 2225add default HISADDR 2226.Ed 2227.Pp 2228to 2229.Pa /etc/ppp/ppp.conf 2230(or to 2231.Pa /etc/ppp/ppp.linkup 2232for setups that don't use 2233.Fl auto 2234mode). 2235.Pp 2236This tells 2237.Nm 2238to add a default route to whatever the peer address is 2239(10.0.0.2 in this example). 2240This route is 2241.Sq sticky , 2242meaning that should the value of 2243.Dv HISADDR 2244change, the route will be updated accordingly. 2245.It 2246If your provider requests that you use PAP/CHAP authentication methods, add 2247the next lines to your 2248.Pa /etc/ppp/ppp.conf 2249file: 2250.Bd -literal -offset indent 2251set authname MyName 2252set authkey MyPassword 2253.Ed 2254.Pp 2255Both are accepted by default, so 2256.Nm 2257will provide whatever your ISP requires. 2258.Pp 2259It should be noted that a login script is rarely (if ever) required 2260when PAP or CHAP are in use. 2261.It 2262Ask your ISP to authenticate your nameserver address(es) with the line 2263.Bd -literal -offset indent 2264enable dns 2265.Ed 2266.Pp 2267Do 2268.Em NOT 2269do this if you are running a local DNS unless you also either use 2270.Dq resolv readonly 2271or have 2272.Dq resolv restore 2273in 2274.Pa /etc/ppp/ppp.linkdown , 2275as 2276.Nm 2277will simply circumvent its use by entering some nameserver lines in 2278.Pa /etc/resolv.conf . 2279.El 2280.Pp 2281Please refer to 2282.Pa /usr/share/examples/ppp/ppp.conf.sample 2283and 2284.Pa /usr/share/examples/ppp/ppp.linkup.sample 2285for some real examples. 2286The pmdemand label should be appropriate for most ISPs. 2287.Sh LOGGING FACILITY 2288.Nm 2289is able to generate the following log info either via 2290.Xr syslog 3 2291or directly to the screen: 2292.Pp 2293.Bl -tag -width XXXXXXXXX -offset XXX -compact 2294.It Li All 2295Enable all logging facilities. 2296This generates a lot of log. 2297The most common use of 'all' is as a basis, where you remove some facilities 2298after enabling 'all' ('debug' and 'timer' are usually best disabled.) 2299.It Li Async 2300Dump async level packet in hex. 2301.It Li CBCP 2302Generate CBCP (CallBack Control Protocol) logs. 2303.It Li CCP 2304Generate a CCP packet trace. 2305.It Li Chat 2306Generate 2307.Sq dial , 2308.Sq login , 2309.Sq logout 2310and 2311.Sq hangup 2312chat script trace logs. 2313.It Li Command 2314Log commands executed either from the command line or any of the configuration 2315files. 2316.It Li Connect 2317Log Chat lines containing the string "CONNECT". 2318.It Li Debug 2319Log debug information. 2320.It Li DNS 2321Log DNS QUERY packets. 2322.It Li Filter 2323Log packets permitted by the dial filter and denied by any filter. 2324.It Li HDLC 2325Dump HDLC packet in hex. 2326.It Li ID0 2327Log all function calls specifically made as user id 0. 2328.It Li IPCP 2329Generate an IPCP packet trace. 2330.It Li LCP 2331Generate an LCP packet trace. 2332.It Li LQM 2333Generate LQR reports. 2334.It Li Phase 2335Phase transition log output. 2336.It Li Physical 2337Dump physical level packet in hex. 2338.It Li Radius 2339Dump RADIUS information. 2340RADIUS information resulting from the link coming up or down is logged at 2341.Dq Phase 2342level unless 2343.Dq Radius 2344logging is enabled. 2345This log level is most useful for monitoring RADIUS alive information. 2346.It Li Sync 2347Dump sync level packet in hex. 2348.It Li TCP/IP 2349Dump all TCP/IP packets. 2350.It Li Timer 2351Log timer manipulation. 2352.It Li TUN 2353Include the tun device on each log line. 2354.It Li Warning 2355Output to the terminal device. 2356If there is currently no terminal, 2357output is sent to the log file using syslogs 2358.Dv LOG_WARNING . 2359.It Li Error 2360Output to both the terminal device 2361and the log file using syslogs 2362.Dv LOG_ERROR . 2363.It Li Alert 2364Output to the log file using 2365.Dv LOG_ALERT . 2366.El 2367.Pp 2368The 2369.Dq set log 2370command allows you to set the logging output level. 2371Multiple levels can be specified on a single command line. 2372The default is equivalent to 2373.Dq set log Phase . 2374.Pp 2375It is also possible to log directly to the screen. 2376The syntax is the same except that the word 2377.Dq local 2378should immediately follow 2379.Dq set log . 2380The default is 2381.Dq set log local 2382(i.e., only the un-maskable warning, error and alert output). 2383.Pp 2384If The first argument to 2385.Dq set log Op local 2386begins with a 2387.Sq + 2388or a 2389.Sq - 2390character, the current log levels are 2391not cleared, for example: 2392.Bd -literal -offset indent 2393PPP ON awfulhak> set log phase 2394PPP ON awfulhak> show log 2395Log: Phase Warning Error Alert 2396Local: Warning Error Alert 2397PPP ON awfulhak> set log +tcp/ip -warning 2398PPP ON awfulhak> set log local +command 2399PPP ON awfulhak> show log 2400Log: Phase TCP/IP Warning Error Alert 2401Local: Command Warning Error Alert 2402.Ed 2403.Pp 2404Log messages of level Warning, Error and Alert are not controllable 2405using 2406.Dq set log Op local . 2407.Pp 2408The 2409.Ar Warning 2410level is special in that it will not be logged if it can be displayed 2411locally. 2412.Sh SIGNAL HANDLING 2413.Nm 2414deals with the following signals: 2415.Bl -tag -width "USR2" 2416.It INT 2417Receipt of this signal causes the termination of the current connection 2418(if any). 2419This will cause 2420.Nm 2421to exit unless it is in 2422.Fl auto 2423or 2424.Fl ddial 2425mode. 2426.It HUP, TERM & QUIT 2427These signals tell 2428.Nm 2429to exit. 2430.It USR1 2431This signal, tells 2432.Nm 2433to re-open any existing server socket, dropping all existing diagnostic 2434connections. 2435Sockets that couldn't previously be opened will be retried. 2436.It USR2 2437This signal, tells 2438.Nm 2439to close any existing server socket, dropping all existing diagnostic 2440connections. 2441.Dv SIGUSR1 2442can still be used to re-open the socket. 2443.El 2444.Sh MULTI-LINK PPP 2445If you wish to use more than one physical link to connect to a 2446.Em PPP 2447peer, that peer must also understand the 2448.Em MULTI-LINK PPP 2449protocol. 2450Refer to RFC 1990 for specification details. 2451.Pp 2452The peer is identified using a combination of his 2453.Dq endpoint discriminator 2454and his 2455.Dq authentication id . 2456Either or both of these may be specified. 2457It is recommended that 2458at least one is specified, otherwise there is no way of ensuring that 2459all links are actually connected to the same peer program, and some 2460confusing lock-ups may result. 2461Locally, these identification variables are specified using the 2462.Dq set enddisc 2463and 2464.Dq set authname 2465commands. 2466The 2467.Sq authname 2468(and 2469.Sq authkey ) 2470must be agreed in advance with the peer. 2471.Pp 2472Multi-link capabilities are enabled using the 2473.Dq set mrru 2474command (set maximum reconstructed receive unit). 2475Once multi-link is enabled, 2476.Nm 2477will attempt to negotiate a multi-link connection with the peer. 2478.Pp 2479By default, only one 2480.Sq link 2481is available 2482(called 2483.Sq deflink ) . 2484To create more links, the 2485.Dq clone 2486command is used. 2487This command will clone existing links, where all 2488characteristics are the same except: 2489.Bl -enum 2490.It 2491The new link has its own name as specified on the 2492.Dq clone 2493command line. 2494.It 2495The new link is an 2496.Sq interactive 2497link. 2498Its mode may subsequently be changed using the 2499.Dq set mode 2500command. 2501.It 2502The new link is in a 2503.Sq closed 2504state. 2505.El 2506.Pp 2507A summary of all available links can be seen using the 2508.Dq show links 2509command. 2510.Pp 2511Once a new link has been created, command usage varies. 2512All link specific commands must be prefixed with the 2513.Dq link Ar name 2514command, specifying on which link the command is to be applied. 2515When only a single link is available, 2516.Nm 2517is smart enough not to require the 2518.Dq link Ar name 2519prefix. 2520.Pp 2521Some commands can still be used without specifying a link - resulting 2522in an operation at the 2523.Sq bundle 2524level. 2525For example, once two or more links are available, the command 2526.Dq show ccp 2527will show CCP configuration and statistics at the multi-link level, and 2528.Dq link deflink show ccp 2529will show the same information at the 2530.Dq deflink 2531link level. 2532.Pp 2533Armed with this information, the following configuration might be used: 2534.Pp 2535.Bd -literal -offset indent 2536mp: 2537 set timeout 0 2538 set log phase chat 2539 set device /dev/cuad0 /dev/cuad1 /dev/cuad2 2540 set phone "123456789" 2541 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \\"\\" ATZ \e 2542 OK-AT-OK \\\\dATDT\\\\T TIMEOUT 45 CONNECT" 2543 set login 2544 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0 2545 set authname ppp 2546 set authkey ppppassword 2547 2548 set mrru 1500 2549 clone 1,2,3 # Create 3 new links - duplicates of the default 2550 link deflink remove # Delete the default link (called ``deflink'') 2551.Ed 2552.Pp 2553Note how all cloning is done at the end of the configuration. 2554Usually, the link will be configured first, then cloned. 2555If you wish all links 2556to be up all the time, you can add the following line to the end of your 2557configuration. 2558.Pp 2559.Bd -literal -offset indent 2560 link 1,2,3 set mode ddial 2561.Ed 2562.Pp 2563If you want the links to dial on demand, this command could be used: 2564.Pp 2565.Bd -literal -offset indent 2566 link * set mode auto 2567.Ed 2568.Pp 2569Links may be tied to specific names by removing the 2570.Dq set device 2571line above, and specifying the following after the 2572.Dq clone 2573command: 2574.Pp 2575.Bd -literal -offset indent 2576 link 1 set device /dev/cuad0 2577 link 2 set device /dev/cuad1 2578 link 3 set device /dev/cuad2 2579.Ed 2580.Pp 2581Use the 2582.Dq help 2583command to see which commands require context (using the 2584.Dq link 2585command), which have optional 2586context and which should not have any context. 2587.Pp 2588When 2589.Nm 2590has negotiated 2591.Em MULTI-LINK 2592mode with the peer, it creates a local domain socket in the 2593.Pa /var/run 2594directory. 2595This socket is used to pass link information (including 2596the actual link file descriptor) between different 2597.Nm 2598invocations. 2599This facilitates 2600.Nm Ns No 's 2601ability to be run from a 2602.Xr getty 8 2603or directly from 2604.Pa /etc/gettydefs 2605(using the 2606.Sq pp= 2607capability), without needing to have initial control of the serial 2608line. 2609Once 2610.Nm 2611negotiates multi-link mode, it will pass its open link to any 2612already running process. 2613If there is no already running process, 2614.Nm 2615will act as the master, creating the socket and listening for new 2616connections. 2617.Sh PPP COMMAND LIST 2618This section lists the available commands and their effect. 2619They are usable either from an interactive 2620.Nm 2621session, from a configuration file or from a 2622.Xr pppctl 8 2623or 2624.Xr telnet 1 2625session. 2626.Bl -tag -width 2n 2627.It accept|deny|enable|disable Ar option.... 2628These directives tell 2629.Nm 2630how to negotiate the initial connection with the peer. 2631Each 2632.Dq option 2633has a default of either accept or deny and enable or disable. 2634.Dq Accept 2635means that the option will be ACK'd if the peer asks for it. 2636.Dq Deny 2637means that the option will be NAK'd if the peer asks for it. 2638.Dq Enable 2639means that the option will be requested by us. 2640.Dq Disable 2641means that the option will not be requested by us. 2642.Pp 2643.Dq Option 2644may be one of the following: 2645.Bl -tag -width 2n 2646.It acfcomp 2647Default: Enabled and Accepted. 2648ACFComp stands for Address and Control Field Compression. 2649Non LCP packets will usually have an address 2650field of 0xff (the All-Stations address) and a control field of 26510x03 (the Unnumbered Information command). 2652If this option is 2653negotiated, these two bytes are simply not sent, thus minimising 2654traffic. 2655.Pp 2656See 2657.Pa rfc1662 2658for details. 2659.It chap Ns Op \&05 2660Default: Disabled and Accepted. 2661CHAP stands for Challenge Handshake Authentication Protocol. 2662Only one of CHAP and PAP (below) may be negotiated. 2663With CHAP, the authenticator sends a "challenge" message to its peer. 2664The peer uses a one-way hash function to encrypt the 2665challenge and sends the result back. 2666The authenticator does the same, and compares the results. 2667The advantage of this mechanism is that no 2668passwords are sent across the connection. 2669A challenge is made when the connection is first made. 2670Subsequent challenges may occur. 2671If you want to have your peer authenticate itself, you must 2672.Dq enable chap . 2673in 2674.Pa /etc/ppp/ppp.conf , 2675and have an entry in 2676.Pa /etc/ppp/ppp.secret 2677for the peer. 2678.Pp 2679When using CHAP as the client, you need only specify 2680.Dq AuthName 2681and 2682.Dq AuthKey 2683in 2684.Pa /etc/ppp/ppp.conf . 2685CHAP is accepted by default. 2686Some 2687.Em PPP 2688implementations use "MS-CHAP" rather than MD5 when encrypting the 2689challenge. 2690MS-CHAP is a combination of MD4 and DES. 2691If 2692.Nm 2693was built on a machine with DES libraries available, it will respond 2694to MS-CHAP authentication requests, but will never request them. 2695.It deflate 2696Default: Enabled and Accepted. 2697This option decides if deflate 2698compression will be used by the Compression Control Protocol (CCP). 2699This is the same algorithm as used by the 2700.Xr gzip 1 2701program. 2702Note: There is a problem negotiating 2703.Ar deflate 2704capabilities with 2705.Xr pppd 8 2706- a 2707.Em PPP 2708implementation available under many operating systems. 2709.Nm pppd 2710(version 2.3.1) incorrectly attempts to negotiate 2711.Ar deflate 2712compression using type 2713.Em 24 2714as the CCP configuration type rather than type 2715.Em 26 2716as specified in 2717.Pa rfc1979 . 2718Type 2719.Ar 24 2720is actually specified as 2721.Dq PPP Magna-link Variable Resource Compression 2722in 2723.Pa rfc1975 ! 2724.Nm 2725is capable of negotiating with 2726.Nm pppd , 2727but only if 2728.Dq deflate24 2729is 2730.Ar enable Ns No d 2731and 2732.Ar accept Ns No ed . 2733.It deflate24 2734Default: Disabled and Denied. 2735This is a variance of the 2736.Ar deflate 2737option, allowing negotiation with the 2738.Xr pppd 8 2739program. 2740Refer to the 2741.Ar deflate 2742section above for details. 2743It is disabled by default as it violates 2744.Pa rfc1975 . 2745.It dns 2746Default: Disabled and Denied. 2747This option allows DNS negotiation. 2748.Pp 2749If 2750.Dq enable Ns No d, 2751.Nm 2752will request that the peer confirms the entries in 2753.Pa /etc/resolv.conf . 2754If the peer NAKs our request (suggesting new IP numbers), 2755.Pa /etc/resolv.conf 2756is updated and another request is sent to confirm the new entries. 2757.Pp 2758If 2759.Dq accept Ns No ed, 2760.Nm 2761will answer any DNS queries requested by the peer rather than rejecting 2762them. 2763The answer is taken from 2764.Pa /etc/resolv.conf 2765unless the 2766.Dq set dns 2767command is used as an override. 2768.It enddisc 2769Default: Enabled and Accepted. 2770This option allows control over whether we 2771negotiate an endpoint discriminator. 2772We only send our discriminator if 2773.Dq set enddisc 2774is used and 2775.Ar enddisc 2776is enabled. 2777We reject the peers discriminator if 2778.Ar enddisc 2779is denied. 2780.It LANMan|chap80lm 2781Default: Disabled and Accepted. 2782The use of this authentication protocol 2783is discouraged as it partially violates the authentication protocol by 2784implementing two different mechanisms (LANMan & NT) under the guise of 2785a single CHAP type (0x80). 2786.Dq LANMan 2787uses a simple DES encryption mechanism and is the least secure of the 2788CHAP alternatives (although is still more secure than PAP). 2789.Pp 2790Refer to the 2791.Dq MSChap 2792description below for more details. 2793.It lqr 2794Default: Disabled and Accepted. 2795This option decides if Link Quality Requests will be sent or accepted. 2796LQR is a protocol that allows 2797.Nm 2798to determine that the link is down without relying on the modems 2799carrier detect. 2800When LQR is enabled, 2801.Nm 2802sends the 2803.Em QUALPROTO 2804option (see 2805.Dq set lqrperiod 2806below) as part of the LCP request. 2807If the peer agrees, both sides will 2808exchange LQR packets at the agreed frequency, allowing detailed link 2809quality monitoring by enabling LQM logging. 2810If the peer doesn't agree, and if the 2811.Dq echo 2812option is enabled, 2813.Nm 2814will send 2815.Em LCP ECHO 2816requests instead. 2817These packets pass no information of interest, but they 2818.Em MUST 2819be replied to by the peer. 2820.Pp 2821Whether using 2822.Em LQR 2823or 2824.Em LCP ECHO , 2825.Nm 2826will abruptly drop the connection if 5 unacknowledged packets have been 2827sent rather than sending a 6th. 2828A message is logged at the 2829.Em PHASE 2830level, and any appropriate 2831.Dq reconnect 2832values are honoured as if the peer were responsible for dropping the 2833connection. 2834.Pp 2835Refer to the 2836.Dq enable echo 2837command description for differences in behaviour prior to 2838.Nm 2839version 3.4.2. 2840.It mppe 2841Default: Enabled and Accepted. 2842This is Microsoft Point to Point Encryption scheme. 2843MPPE key size can be 284440-, 56- and 128-bits. 2845Refer to 2846.Dq set mppe 2847command. 2848.It MSChapV2|chap81 2849Default: Disabled and Accepted. 2850It is very similar to standard CHAP (type 0x05) 2851except that it issues challenges of a fixed 16 bytes in length and uses a 2852combination of MD4, SHA-1 and DES to encrypt the challenge rather than using the 2853standard MD5 mechanism. 2854.It MSChap|chap80nt 2855Default: Disabled and Accepted. 2856The use of this authentication protocol 2857is discouraged as it partially violates the authentication protocol by 2858implementing two different mechanisms (LANMan & NT) under the guise of 2859a single CHAP type (0x80). 2860It is very similar to standard CHAP (type 0x05) 2861except that it issues challenges of a fixed 8 bytes in length and uses a 2862combination of MD4 and DES to encrypt the challenge rather than using the 2863standard MD5 mechanism. 2864CHAP type 0x80 for LANMan is also supported - see 2865.Dq enable LANMan 2866for details. 2867.Pp 2868Because both 2869.Dq LANMan 2870and 2871.Dq NT 2872use CHAP type 0x80, when acting as authenticator with both 2873.Dq enable Ns No d , 2874.Nm 2875will rechallenge the peer up to three times if it responds using the wrong 2876one of the two protocols. 2877This gives the peer a chance to attempt using both protocols. 2878.Pp 2879Conversely, when 2880.Nm 2881acts as the authenticatee with both protocols 2882.Dq accept Ns No ed , 2883the protocols are used alternately in response to challenges. 2884.Pp 2885Note: If only LANMan is enabled, 2886.Xr pppd 8 2887(version 2.3.5) misbehaves when acting as authenticatee. 2888It provides both 2889the NT and the LANMan answers, but also suggests that only the NT answer 2890should be used. 2891.It pap 2892Default: Disabled and Accepted. 2893PAP stands for Password Authentication Protocol. 2894Only one of PAP and CHAP (above) may be negotiated. 2895With PAP, the ID and Password are sent repeatedly to the peer until 2896authentication is acknowledged or the connection is terminated. 2897This is a rather poor security mechanism. 2898It is only performed when the connection is first established. 2899If you want to have your peer authenticate itself, you must 2900.Dq enable pap . 2901in 2902.Pa /etc/ppp/ppp.conf , 2903and have an entry in 2904.Pa /etc/ppp/ppp.secret 2905for the peer (although see the 2906.Dq passwdauth 2907and 2908.Dq set radius 2909options below). 2910.Pp 2911When using PAP as the client, you need only specify 2912.Dq AuthName 2913and 2914.Dq AuthKey 2915in 2916.Pa /etc/ppp/ppp.conf . 2917PAP is accepted by default. 2918.It pred1 2919Default: Enabled and Accepted. 2920This option decides if Predictor 1 2921compression will be used by the Compression Control Protocol (CCP). 2922.It protocomp 2923Default: Enabled and Accepted. 2924This option is used to negotiate 2925PFC (Protocol Field Compression), a mechanism where the protocol 2926field number is reduced to one octet rather than two. 2927.It shortseq 2928Default: Enabled and Accepted. 2929This option determines if 2930.Nm 2931will request and accept requests for short 2932(12 bit) 2933sequence numbers when negotiating multi-link mode. 2934This is only applicable if our MRRU is set (thus enabling multi-link). 2935.It vjcomp 2936Default: Enabled and Accepted. 2937This option determines if Van Jacobson header compression will be used. 2938.El 2939.Pp 2940The following options are not actually negotiated with the peer. 2941Therefore, accepting or denying them makes no sense. 2942.Bl -tag -width 2n 2943.It echo 2944Default: Disabled. 2945When this option is enabled, 2946.Nm 2947will send 2948.Em LCP ECHO 2949requests to the peer at the frequency defined by 2950.Dq echoperiod . 2951Note, 2952.Em LQR 2953requests will supersede 2954.Em LCP ECHO 2955requests if enabled and negotiated. 2956See 2957.Dq set lqrperiod 2958below for details. 2959.Pp 2960Prior to 2961.Nm 2962version 3.4.2, 2963.Dq echo 2964was considered enabled if lqr was enabled and negotiated, otherwise it was 2965considered disabled. 2966For the same behaviour, it is now necessary to 2967.Dq enable lqr echo 2968rather than just 2969.Dq enable lqr . 2970.It filter-decapsulation 2971Default: Disabled. 2972When this option is enabled, 2973.Nm 2974will examine UDP frames to see if they actually contain a 2975.Em PPP 2976frame as their payload. 2977If this is the case, all filters will operate on the payload rather 2978than the actual packet. 2979.Pp 2980This is useful if you want to send PPPoUDP traffic over a 2981.Em PPP 2982link, but want that link to do smart things with the real data rather than 2983the UDP wrapper. 2984.Pp 2985The UDP frame payload must not be compressed in any way, otherwise 2986.Nm 2987will not be able to interpret it. 2988It's therefore recommended that you 2989.Ic disable vj pred1 deflate 2990and 2991.Ic deny vj pred1 deflate 2992in the configuration for the 2993.Nm 2994invocation with the udp link. 2995.It force-scripts 2996Default: Disabled. 2997Forces execution of the configured chat scripts in 2998.Dv direct 2999and 3000.Dv dedicated 3001modes. 3002.It idcheck 3003Default: Enabled. 3004When 3005.Nm 3006exchanges low-level LCP, CCP and IPCP configuration traffic, the 3007.Em Identifier 3008field of any replies is expected to be the same as that of the request. 3009By default, 3010.Nm 3011drops any reply packets that do not contain the expected identifier 3012field, reporting the fact at the respective log level. 3013If 3014.Ar idcheck 3015is disabled, 3016.Nm 3017will ignore the identifier field. 3018.It iface-alias 3019Default: Enabled if 3020.Fl nat 3021is specified. 3022This option simply tells 3023.Nm 3024to add new interface addresses to the interface rather than replacing them. 3025The option can only be enabled if network address translation is enabled 3026.Pq Dq nat enable yes . 3027.Pp 3028With this option enabled, 3029.Nm 3030will pass traffic for old interface addresses through the NAT 3031ifdef({LOCALNAT},{engine,},{engine 3032(see 3033.Xr libalias 3 ) ,}) 3034resulting in the ability (in 3035.Fl auto 3036mode) to properly connect the process that caused the PPP link to 3037come up in the first place. 3038.Pp 3039Disabling NAT with 3040.Dq nat enable no 3041will also disable 3042.Sq iface-alias . 3043.It ipcp 3044Default: Enabled. 3045This option allows 3046.Nm 3047to attempt to negotiate IP control protocol capabilities and if 3048successful to exchange IP datagrams with the peer. 3049.It ipv6cp 3050Default: Enabled. 3051This option allows 3052.Nm 3053to attempt to negotiate IPv6 control protocol capabilities and if 3054successful to exchange IPv6 datagrams with the peer. 3055.It keep-session 3056Default: Disabled. 3057When 3058.Nm 3059runs as a Multi-link server, a different 3060.Nm 3061instance initially receives each connection. 3062After determining that 3063the link belongs to an already existing bundle (controlled by another 3064.Nm 3065invocation), 3066.Nm 3067will transfer the link to that process. 3068.Pp 3069If the link is a tty device or if this option is enabled, 3070.Nm 3071will not exit, but will change its process name to 3072.Dq session owner 3073and wait for the controlling 3074.Nm 3075to finish with the link and deliver a signal back to the idle process. 3076This prevents the confusion that results from 3077.Nm Ns No 's 3078parent considering the link resource available again. 3079.Pp 3080For tty devices that have entries in 3081.Pa /etc/ttys , 3082this is necessary to prevent another 3083.Xr getty 8 3084from being started, and for program links such as 3085.Xr sshd 8 , 3086it prevents 3087.Xr sshd 8 3088from exiting due to the death of its child. 3089As 3090.Nm 3091cannot determine its parents requirements (except for the tty case), this 3092option must be enabled manually depending on the circumstances. 3093.It loopback 3094Default: Enabled. 3095When 3096.Ar loopback 3097is enabled, 3098.Nm 3099will automatically loop back packets being sent 3100out with a destination address equal to that of the 3101.Em PPP 3102interface. 3103If disabled, 3104.Nm 3105will send the packet, probably resulting in an ICMP redirect from 3106the other end. 3107It is convenient to have this option enabled when 3108the interface is also the default route as it avoids the necessity 3109of a loopback route. 3110.It NAS-IP-Address 3111Default: Enabled. 3112This option controls whether 3113.Nm 3114sends the 3115.Dq NAS-IP-Address 3116attribute to the RADIUS server when RADIUS is in use 3117.Pq see Dq set radius . 3118.Pp 3119Note, at least one of 3120.Dq NAS-IP-Address 3121and 3122.Dq NAS-Identifier 3123must be enabled. 3124.Pp 3125Versions of 3126.Nm 3127prior to version 3.4.1 did not send the 3128.Dq NAS-IP-Address 3129atribute as it was reported to break the Radiator RADIUS server. 3130As the latest rfc (2865) no longer hints that only one of 3131.Dq NAS-IP-Address 3132and 3133.Dq NAS-Identifier 3134should be sent (as rfc 2138 did), 3135.Nm 3136now sends both and leaves it up to the administrator that chooses to use 3137bad RADIUS implementations to 3138.Dq disable NAS-IP-Address . 3139.It NAS-Identifier 3140Default: Enabled. 3141This option controls whether 3142.Nm 3143sends the 3144.Dq NAS-Identifier 3145attribute to the RADIUS server when RADIUS is in use 3146.Pq see Dq set radius . 3147.Pp 3148Note, at least one of 3149.Dq NAS-IP-Address 3150and 3151.Dq NAS-Identifier 3152must be enabled. 3153.It passwdauth 3154Default: Disabled. 3155Enabling this option will tell the PAP authentication 3156code to use the password database (see 3157.Xr passwd 5 ) 3158to authenticate the caller if they cannot be found in the 3159.Pa /etc/ppp/ppp.secret 3160file. 3161.Pa /etc/ppp/ppp.secret 3162is always checked first. 3163If you wish to use passwords from 3164.Xr passwd 5 , 3165but also to specify an IP number or label for a given client, use 3166.Dq \&* 3167as the client password in 3168.Pa /etc/ppp/ppp.secret . 3169.It proxy 3170Default: Disabled. 3171Enabling this option will tell 3172.Nm 3173to proxy ARP for the peer. 3174This means that 3175.Nm 3176will make an entry in the ARP table using 3177.Dv HISADDR 3178and the 3179.Dv MAC 3180address of the local network in which 3181.Dv HISADDR 3182appears. 3183This allows other machines connecteed to the LAN to talk to 3184the peer as if the peer itself was connected to the LAN. 3185The proxy entry cannot be made unless 3186.Dv HISADDR 3187is an address from a LAN. 3188.It proxyall 3189Default: Disabled. 3190Enabling this will tell 3191.Nm 3192to add proxy arp entries for every IP address in all class C or 3193smaller subnets routed via the tun interface. 3194.Pp 3195Proxy arp entries are only made for sticky routes that are added 3196using the 3197.Dq add 3198command. 3199No proxy arp entries are made for the interface address itself 3200(as created by the 3201.Dq set ifaddr 3202command). 3203.It sroutes 3204Default: Enabled. 3205When the 3206.Dq add 3207command is used with the 3208.Dv HISADDR , 3209.Dv MYADDR , 3210.Dv HISADDR6 3211or 3212.Dv MYADDR6 3213values, entries are stored in the 3214.Sq sticky route 3215list. 3216Each time these variables change, this list is re-applied to the routing table. 3217.Pp 3218Disabling this option will prevent the re-application of sticky routes, 3219although the 3220.Sq stick route 3221list will still be maintained. 3222.It Op tcp Ns Xo 3223.No mssfixup 3224.Xc 3225Default: Enabled. 3226This option tells 3227.Nm 3228to adjust TCP SYN packets so that the maximum receive segment 3229size is not greater than the amount allowed by the interface MTU. 3230.It throughput 3231Default: Enabled. 3232This option tells 3233.Nm 3234to gather throughput statistics. 3235Input and output is sampled over 3236a rolling 5 second window, and current, best and total figures are retained. 3237This data is output when the relevant 3238.Em PPP 3239layer shuts down, and is also available using the 3240.Dq show 3241command. 3242Throughput statistics are available at the 3243.Dq IPCP 3244and 3245.Dq physical 3246levels. 3247.It utmp 3248Default: Enabled. 3249Normally, when a user is authenticated using PAP or CHAP, and when 3250.Nm 3251is running in 3252.Fl direct 3253mode, an entry is made in the utmp and wtmp files for that user. 3254Disabling this option will tell 3255.Nm 3256not to make any utmp or wtmp entries. 3257This is usually only necessary if 3258you require the user to both login and authenticate themselves. 3259.El 3260.Pp 3261.It add Ns Xo 3262.Op !\& 3263.Ar dest Ns Op / Ns Ar nn 3264.Op Ar mask 3265.Op Ar gateway 3266.Xc 3267.Ar Dest 3268is the destination IP address. 3269The netmask is specified either as a number of bits with 3270.Ar /nn 3271or as an IP number using 3272.Ar mask . 3273.Ar 0 0 3274or simply 3275.Ar 0 3276with no mask refers to the default route. 3277It is also possible to use the literal name 3278.Sq default 3279instead of 3280.Ar 0 . 3281.Ar Gateway 3282is the next hop gateway to get to the given 3283.Ar dest 3284machine/network. 3285Refer to the 3286.Xr route 8 3287command for further details. 3288.Pp 3289It is possible to use the symbolic names 3290.Sq MYADDR , 3291.Sq HISADDR , 3292.Sq MYADDR6 3293or 3294.Sq HISADDR6 3295as the destination, and 3296.Sq HISADDR 3297or 3298.Sq HISADDR6 3299as the 3300.Ar gateway . 3301.Sq MYADDR 3302is replaced with the interface IP address, 3303.Sq HISADDR 3304is replaced with the interface IP destination (peer) address, 3305.Sq MYADDR6 3306is replaced with the interface IPv6 address, and 3307.Sq HISADDR6 3308is replaced with the interface IPv6 destination address, 3309.Pp 3310If the 3311.Ar add!\& 3312command is used 3313(note the trailing 3314.Dq !\& ) , 3315then if the route already exists, it will be updated as with the 3316.Sq route change 3317command (see 3318.Xr route 8 3319for further details). 3320.Pp 3321Routes that contain the 3322.Dq HISADDR , 3323.Dq MYADDR , 3324.Dq HISADDR6 , 3325.Dq MYADDR6 , 3326.Dq DNS0 , 3327or 3328.Dq DNS1 3329constants are considered 3330.Sq sticky . 3331They are stored in a list (use 3332.Dq show ncp 3333to see the list), and each time the value of one of these variables 3334changes, the appropriate routing table entries are updated. 3335This facility may be disabled using 3336.Dq disable sroutes . 3337.It allow Ar command Op Ar args 3338This command controls access to 3339.Nm 3340and its configuration files. 3341It is possible to allow user-level access, 3342depending on the configuration file label and on the mode that 3343.Nm 3344is being run in. 3345For example, you may wish to configure 3346.Nm 3347so that only user 3348.Sq fred 3349may access label 3350.Sq fredlabel 3351in 3352.Fl background 3353mode. 3354.Pp 3355User id 0 is immune to these commands. 3356.Bl -tag -width 2n 3357.It allow user Ns Xo 3358.Op s 3359.Ar logname Ns No ... 3360.Xc 3361By default, only user id 0 is allowed access to 3362.Nm . 3363If this command is used, all of the listed users are allowed access to 3364the section in which the 3365.Dq allow users 3366command is found. 3367The 3368.Sq default 3369section is always checked first (even though it is only ever automatically 3370loaded at startup). 3371.Dq allow users 3372commands are cumulative in a given section, but users allowed in any given 3373section override users allowed in the default section, so it's possible to 3374allow users access to everything except a given label by specifying default 3375users in the 3376.Sq default 3377section, and then specifying a new user list for that label. 3378.Pp 3379If user 3380.Sq * 3381is specified, access is allowed to all users. 3382.It allow mode Ns Xo 3383.Op s 3384.Ar mode Ns No ... 3385.Xc 3386By default, access using any 3387.Nm 3388mode is possible. 3389If this command is used, it restricts the access 3390.Ar modes 3391allowed to load the label under which this command is specified. 3392Again, as with the 3393.Dq allow users 3394command, each 3395.Dq allow modes 3396command overrides any previous settings, and the 3397.Sq default 3398section is always checked first. 3399.Pp 3400Possible modes are: 3401.Sq interactive , 3402.Sq auto , 3403.Sq direct , 3404.Sq dedicated , 3405.Sq ddial , 3406.Sq background 3407and 3408.Sq * . 3409.Pp 3410When running in multi-link mode, a section can be loaded if it allows 3411.Em any 3412of the currently existing line modes. 3413.El 3414.Pp 3415.It nat Ar command Op Ar args 3416This command allows the control of the network address translation (also 3417known as masquerading or IP aliasing) facilities that are built into 3418.Nm . 3419NAT is done on the external interface only, and is unlikely to make sense 3420if used with the 3421.Fl direct 3422flag. 3423.Pp 3424If nat is enabled on your system (it may be omitted at compile time), 3425the following commands are possible: 3426.Bl -tag -width 2n 3427.It nat enable yes|no 3428This command either switches network address translation on or turns it off. 3429The 3430.Fl nat 3431command line flag is synonymous with 3432.Dq nat enable yes . 3433.It nat addr Op Ar addr_local addr_alias 3434This command allows data for 3435.Ar addr_alias 3436to be redirected to 3437.Ar addr_local . 3438It is useful if you own a small number of real IP numbers that 3439you wish to map to specific machines behind your gateway. 3440.It nat deny_incoming yes|no 3441If set to yes, this command will refuse all incoming packets where an 3442aliasing link doesn't already exist. 3443ifdef({LOCALNAT},{},{Refer to the 3444.Sx CONCEPTUAL BACKGROUND 3445section of 3446.Xr libalias 3 3447for a description of what an 3448.Dq aliasing link 3449is. 3450})dnl 3451.Pp 3452It should be noted under what circumstances an aliasing link is 3453ifdef({LOCALNAT},{created.},{created by 3454.Xr libalias 3 .}) 3455It may be necessary to further protect your network from outside 3456connections using the 3457.Dq set filter 3458or 3459.Dq nat target 3460commands. 3461.It nat help|? 3462This command gives a summary of available nat commands. 3463.It nat log yes|no 3464This option causes various NAT statistics and information to 3465be logged to the file 3466.Pa /var/log/alias.log . 3467.It nat port Ar proto Ar targetIP Ns Xo 3468.No : Ns Ar targetPort Ns 3469.Oo 3470.No - Ns Ar targetPort 3471.Oc Ar aliasPort Ns 3472.Oo 3473.No - Ns Ar aliasPort 3474.Oc Oo Ar remoteIP : Ns 3475.Ar remotePort Ns 3476.Oo 3477.No - Ns Ar remotePort 3478.Oc Ns 3479.Oc 3480.Xc 3481This command causes incoming 3482.Ar proto 3483connections to 3484.Ar aliasPort 3485to be redirected to 3486.Ar targetPort 3487on 3488.Ar targetIP . 3489.Ar proto 3490is either 3491.Dq tcp 3492or 3493.Dq udp . 3494.Pp 3495A range of port numbers may be specified as shown above. 3496The ranges must be of the same size. 3497.Pp 3498If 3499.Ar remoteIP 3500is specified, only data coming from that IP number is redirected. 3501.Ar remotePort 3502must either be 3503.Dq 0 3504(indicating any source port) 3505or a range of ports the same size as the other ranges. 3506.Pp 3507This option is useful if you wish to run things like Internet phone on 3508machines behind your gateway, but is limited in that connections to only 3509one interior machine per source machine and target port are possible. 3510.It nat proto Ar proto localIP Oo 3511.Ar publicIP Op Ar remoteIP 3512.Oc 3513This command tells 3514.Nm 3515to redirect packets of protocol type 3516.Ar proto 3517(see 3518.Xr protocols 5 ) 3519to the internal address 3520.Ar localIP . 3521.Pp 3522If 3523.Ar publicIP 3524is specified, only packets destined for that address are matched, 3525otherwise the default alias address is used. 3526.Pp 3527If 3528.Ar remoteIP 3529is specified, only packets matching that source address are matched, 3530.Pp 3531This command is useful for redirecting tunnel endpoints to an internal machine, 3532for example: 3533.Pp 3534.Dl nat proto ipencap 10.0.0.1 3535.It "nat proxy cmd" Ar arg Ns No ... 3536This command tells 3537.Nm 3538to proxy certain connections, redirecting them to a given server. 3539ifdef({LOCALNAT},{},{Refer to the description of 3540.Fn PacketAliasProxyRule 3541in 3542.Xr libalias 3 3543for details of the available commands. 3544})dnl 3545.It nat punch_fw Op Ar base count 3546This command tells 3547.Nm 3548to punch holes in the firewall for FTP or IRC DCC connections. 3549This is done dynamically by installing termporary firewall rules which 3550allow a particular connection (and only that connection) to go through 3551the firewall. 3552The rules are removed once the corresponding connection terminates. 3553.Pp 3554A maximum of 3555.Ar count 3556rules starting from rule number 3557.Ar base 3558will be used for punching firewall holes. 3559The range will be cleared when the 3560.Dq nat punch_fw 3561command is run. 3562.Pp 3563If no arguments are given, firewall punching is disabled. 3564.It nat skinny_port Op Ar port 3565This command tells 3566.Nm 3567which TCP port is used by the Skinny Station protocol. 3568Skinny is used by 3569Cisco IP phones to communicate with Cisco Call Managers to setup voice 3570over IP calls. 3571The typical port used by Skinny is 2000. 3572.Pp 3573If no argument is given, skinny aliasing is disabled. 3574.It nat same_ports yes|no 3575When enabled, this command will tell the network address translation engine to 3576attempt to avoid changing the port number on outgoing packets. 3577This is useful 3578if you want to support protocols such as RPC and LPD which require 3579connections to come from a well known port. 3580.It nat target Op Ar address 3581Set the given target address or clear it if no address is given. 3582The target address is used 3583ifdef({LOCALNAT},{},{by libalias })dnl 3584to specify how to NAT incoming packets by default. 3585If a target address is not set or if 3586.Dq default 3587is given, packets are not altered and are allowed to route to the internal 3588network. 3589.Pp 3590The target address may be set to 3591.Dq MYADDR , 3592in which case 3593ifdef({LOCALNAT},{all packets will be redirected}, 3594{libalias will redirect all packets}) 3595to the interface address. 3596.It nat use_sockets yes|no 3597When enabled, this option tells the network address translation engine to 3598create a socket so that it can guarantee a correct incoming ftp data or 3599IRC connection. 3600.It nat unregistered_only yes|no 3601Only alter outgoing packets with an unregistered source address. 3602According to RFC 1918, unregistered source addresses 3603are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16. 3604.El 3605.Pp 3606These commands are also discussed in the file 3607.Pa README.nat 3608which comes with the source distribution. 3609.Pp 3610.It Op !\& Ns Xo 3611.No bg Ar command 3612.Xc 3613The given 3614.Ar command 3615is executed in the background with the following words replaced: 3616.Bl -tag -width COMPILATIONDATE 3617.It Li AUTHNAME 3618This is replaced with the local 3619.Ar authname 3620value. 3621See the 3622.Dq set authname 3623command below. 3624.It Li COMPILATIONDATE 3625This is replaced with the date on which 3626.Nm 3627was compiled. 3628.It Li DNS0 & DNS1 3629These are replaced with the primary and secondary nameserver IP numbers. 3630If nameservers are negotiated by IPCP, the values of these macros will change. 3631.It Li ENDDISC 3632This is replaced with the local endpoint discriminator value. 3633See the 3634.Dq set enddisc 3635command below. 3636.It Li HISADDR 3637This is replaced with the peers IP number. 3638.It Li HISADDR6 3639This is replaced with the peers IPv6 number. 3640.It Li INTERFACE 3641This is replaced with the name of the interface that's in use. 3642.It Li IPOCTETSIN 3643This is replaced with the number of IP bytes received since the connection 3644was established. 3645.It Li IPOCTETSOUT 3646This is replaced with the number of IP bytes sent since the connection 3647was established. 3648.It Li IPPACKETSIN 3649This is replaced with the number of IP packets received since the connection 3650was established. 3651.It Li IPPACKETSOUT 3652This is replaced with the number of IP packets sent since the connection 3653was established. 3654.It Li IPV6OCTETSIN 3655This is replaced with the number of IPv6 bytes received since the connection 3656was established. 3657.It Li IPV6OCTETSOUT 3658This is replaced with the number of IPv6 bytes sent since the connection 3659was established. 3660.It Li IPV6PACKETSIN 3661This is replaced with the number of IPv6 packets received since the connection 3662was established. 3663.It Li IPV6PACKETSOUT 3664This is replaced with the number of IPv6 packets sent since the connection 3665was established. 3666.It Li LABEL 3667This is replaced with the last label name used. 3668A label may be specified on the 3669.Nm 3670command line, via the 3671.Dq load 3672or 3673.Dq dial 3674commands and in the 3675.Pa ppp.secret 3676file. 3677.It Li MYADDR 3678This is replaced with the IP number assigned to the local interface. 3679.It Li MYADDR6 3680This is replaced with the IPv6 number assigned to the local interface. 3681.It Li OCTETSIN 3682This is replaced with the number of bytes received since the connection 3683was established. 3684.It Li OCTETSOUT 3685This is replaced with the number of bytes sent since the connection 3686was established. 3687.It Li PACKETSIN 3688This is replaced with the number of packets received since the connection 3689was established. 3690.It Li PACKETSOUT 3691This is replaced with the number of packets sent since the connection 3692was established. 3693.It Li PEER_ENDDISC 3694This is replaced with the value of the peers endpoint discriminator. 3695.It Li PROCESSID 3696This is replaced with the current process id. 3697.It Li SOCKNAME 3698This is replaced with the name of the diagnostic socket. 3699.It Li UPTIME 3700This is replaced with the bundle uptime in HH:MM:SS format. 3701.It Li USER 3702This is replaced with the username that has been authenticated with PAP or 3703CHAP. 3704Normally, this variable is assigned only in -direct mode. 3705This value is available irrespective of whether utmp logging is enabled. 3706.It Li VERSION 3707This is replaced with the current version number of 3708.Nm . 3709.El 3710.Pp 3711These substitutions are also done by the 3712.Dq set proctitle , 3713.Dq ident 3714and 3715.Dq log 3716commands. 3717.Pp 3718If you wish to pause 3719.Nm 3720while the command executes, use the 3721.Dq shell 3722command instead. 3723.It clear physical|ipcp|ipv6 Op current|overall|peak... 3724Clear the specified throughput values at either the 3725.Dq physical , 3726.Dq ipcp 3727or 3728.Dq ipv6cp 3729level. 3730If 3731.Dq physical 3732is specified, context must be given (see the 3733.Dq link 3734command below). 3735If no second argument is given, all values are cleared. 3736.It clone Ar name Ns Xo 3737.Op \&, Ns Ar name Ns 3738.No ... 3739.Xc 3740Clone the specified link, creating one or more new links according to the 3741.Ar name 3742argument(s). 3743This command must be used from the 3744.Dq link 3745command below unless you've only got a single link (in which case that 3746link becomes the default). 3747Links may be removed using the 3748.Dq remove 3749command below. 3750.Pp 3751The default link name is 3752.Dq deflink . 3753.It close Op lcp|ccp Ns Op !\& 3754If no arguments are given, the relevant protocol layers will be brought 3755down and the link will be closed. 3756If 3757.Dq lcp 3758is specified, the LCP layer is brought down, but 3759.Nm 3760will not bring the link offline. 3761It is subsequently possible to use 3762.Dq term 3763(see below) 3764to talk to the peer machine if, for example, something like 3765.Dq slirp 3766is being used. 3767If 3768.Dq ccp 3769is specified, only the relevant compression layer is closed. 3770If the 3771.Dq !\& 3772is used, the compression layer will remain in the closed state, otherwise 3773it will re-enter the STOPPED state, waiting for the peer to initiate 3774further CCP negotiation. 3775In any event, this command does not disconnect the user from 3776.Nm 3777or exit 3778.Nm . 3779See the 3780.Dq quit 3781command below. 3782.It delete Ns Xo 3783.Op !\& 3784.Ar dest 3785.Xc 3786This command deletes the route with the given 3787.Ar dest 3788IP address. 3789If 3790.Ar dest 3791is specified as 3792.Sq ALL , 3793all non-direct entries in the routing table for the current interface, 3794and all 3795.Sq sticky route 3796entries are deleted. 3797If 3798.Ar dest 3799is specified as 3800.Sq default , 3801the default route is deleted. 3802.Pp 3803If the 3804.Ar delete!\& 3805command is used 3806(note the trailing 3807.Dq !\& ) , 3808.Nm 3809will not complain if the route does not already exist. 3810.It dial|call Op Ar label Ns Xo 3811.No ... 3812.Xc 3813This command is the equivalent of 3814.Dq load label 3815followed by 3816.Dq open , 3817and is provided for backwards compatibility. 3818.It down Op Ar lcp|ccp 3819Bring the relevant layer down ungracefully, as if the underlying layer 3820had become unavailable. 3821It's not considered polite to use this command on 3822a Finite State Machine that's in the OPEN state. 3823If no arguments are 3824supplied, the entire link is closed (or if no context is given, all links 3825are terminated). 3826If 3827.Sq lcp 3828is specified, the 3829.Em LCP 3830layer is terminated but the device is not brought offline and the link 3831is not closed. 3832If 3833.Sq ccp 3834is specified, only the relevant compression layer(s) are terminated. 3835.It help|? Op Ar command 3836Show a list of available commands. 3837If 3838.Ar command 3839is specified, show the usage string for that command. 3840.It ident Op Ar text Ns No ... 3841Identify the link to the peer using 3842.Ar text . 3843If 3844.Ar text 3845is empty, link identification is disabled. 3846It is possible to use any of the words described for the 3847.Ic bg 3848command above. 3849Refer to the 3850.Ic sendident 3851command for details of when 3852.Nm 3853identifies itself to the peer. 3854.It iface Ar command Op args 3855This command is used to control the interface used by 3856.Nm . 3857.Ar Command 3858may be one of the following: 3859.Bl -tag -width 2n 3860.It iface add Ns Xo 3861.Op !\& 3862.Ar addr Ns Op / Ns Ar bits 3863.Op Ar peer 3864.Xc 3865.It iface add Ns Xo 3866.Op !\& 3867.Ar addr 3868.Ar mask 3869.Ar peer 3870.Xc 3871Add the given 3872.Ar addr mask peer 3873combination to the interface. 3874Instead of specifying 3875.Ar mask , 3876.Ar /bits 3877can be used 3878(with no space between it and 3879.Ar addr ) . 3880If the given address already exists, the command fails unless the 3881.Dq !\& 3882is used - in which case the previous interface address entry is overwritten 3883with the new one, allowing a change of netmask or peer address. 3884.Pp 3885If only 3886.Ar addr 3887is specified, 3888.Ar bits 3889defaults to 3890.Dq 32 3891and 3892.Ar peer 3893defaults to 3894.Dq 255.255.255.255 . 3895This address (the broadcast address) is the only duplicate peer address that 3896.Nm 3897allows. 3898.It iface clear Op INET | INET6 3899If this command is used while 3900.Nm 3901is in the OPENED state or while in 3902.Fl auto 3903mode, all addresses except for the NCP negotiated address are deleted 3904from the interface. 3905If 3906.Nm 3907is not in the OPENED state and is not in 3908.Fl auto 3909mode, all interface addresses are deleted. 3910.Pp 3911If the INET or INET6 arguments are used, only addresses for that address 3912family are cleared. 3913.Pp 3914.It iface delete Ns Xo 3915.Op !\& Ns 3916.No |rm Ns Op !\& 3917.Ar addr 3918.Xc 3919This command deletes the given 3920.Ar addr 3921from the interface. 3922If the 3923.Dq !\& 3924is used, no error is given if the address isn't currently assigned to 3925the interface (and no deletion takes place). 3926.It iface show 3927Shows the current state and current addresses for the interface. 3928It is much the same as running 3929.Dq ifconfig INTERFACE . 3930.It iface help Op Ar sub-command 3931This command, when invoked without 3932.Ar sub-command , 3933will show a list of possible 3934.Dq iface 3935sub-commands and a brief synopsis for each. 3936When invoked with 3937.Ar sub-command , 3938only the synopsis for the given sub-command is shown. 3939.El 3940.It Op data Ns Xo 3941.No link 3942.Ar name Ns Op , Ns Ar name Ns 3943.No ... Ar command Op Ar args 3944.Xc 3945This command may prefix any other command if the user wishes to 3946specify which link the command should affect. 3947This is only applicable after multiple links have been created in Multi-link 3948mode using the 3949.Dq clone 3950command. 3951.Pp 3952.Ar Name 3953specifies the name of an existing link. 3954If 3955.Ar name 3956is a comma separated list, 3957.Ar command 3958is executed on each link. 3959If 3960.Ar name 3961is 3962.Dq * , 3963.Ar command 3964is executed on all links. 3965.It load Op Ar label Ns Xo 3966.No ... 3967.Xc 3968Load the given 3969.Ar label Ns No (s) 3970from the 3971.Pa ppp.conf 3972file. 3973If 3974.Ar label 3975is not given, the 3976.Ar default 3977label is used. 3978.Pp 3979Unless the 3980.Ar label 3981section uses the 3982.Dq set mode , 3983.Dq open 3984or 3985.Dq dial 3986commands, 3987.Nm 3988will not attempt to make an immediate connection. 3989.It log Ar word Ns No ... 3990Send the given word(s) to the log file with the prefix 3991.Dq LOG: . 3992Word substitutions are done as explained under the 3993.Dq !bg 3994command above. 3995.It open Op lcp|ccp|ipcp 3996This is the opposite of the 3997.Dq close 3998command. 3999All closed links are immediately brought up apart from second and subsequent 4000.Ar demand-dial 4001links - these will come up based on the 4002.Dq set autoload 4003command that has been used. 4004.Pp 4005If the 4006.Dq lcp 4007argument is used while the LCP layer is already open, LCP will be 4008renegotiated. 4009This allows various LCP options to be changed, after which 4010.Dq open lcp 4011can be used to put them into effect. 4012After renegotiating LCP, 4013any agreed authentication will also take place. 4014.Pp 4015If the 4016.Dq ccp 4017argument is used, the relevant compression layer is opened. 4018Again, if it is already open, it will be renegotiated. 4019.Pp 4020If the 4021.Dq ipcp 4022argument is used, the link will be brought up as normal, but if 4023IPCP is already open, it will be renegotiated and the network 4024interface will be reconfigured. 4025.Pp 4026It is probably not good practice to re-open the PPP state machines 4027like this as it's possible that the peer will not behave correctly. 4028It 4029.Em is 4030however useful as a way of forcing the CCP or VJ dictionaries to be reset. 4031.It passwd Ar pass 4032Specify the password required for access to the full 4033.Nm 4034command set. 4035This password is required when connecting to the diagnostic port (see the 4036.Dq set server 4037command). 4038.Ar Pass 4039is specified on the 4040.Dq set server 4041command line. 4042The value of 4043.Ar pass 4044is not logged when 4045.Ar command 4046logging is active, instead, the literal string 4047.Sq ******** 4048is logged. 4049.It quit|bye Op all 4050If 4051.Dq quit 4052is executed from the controlling connection or from a command file, 4053ppp will exit after closing all connections. 4054Otherwise, if the user 4055is connected to a diagnostic socket, the connection is simply dropped. 4056.Pp 4057If the 4058.Ar all 4059argument is given, 4060.Nm 4061will exit despite the source of the command after closing all existing 4062connections. 4063.It remove|rm 4064This command removes the given link. 4065It is only really useful in multi-link mode. 4066A link must be in the 4067.Dv CLOSED 4068state before it is removed. 4069.It rename|mv Ar name 4070This command renames the given link to 4071.Ar name . 4072It will fail if 4073.Ar name 4074is already used by another link. 4075.Pp 4076The default link name is 4077.Sq deflink . 4078Renaming it to 4079.Sq modem , 4080.Sq cuad0 4081or 4082.Sq USR 4083may make the log file more readable. 4084.It resolv Ar command 4085This command controls 4086.Nm Ns No 's 4087manipulation of the 4088.Xr resolv.conf 5 4089file. 4090When 4091.Nm 4092starts up, it loads the contents of this file into memory and retains this 4093image for future use. 4094.Ar command 4095is one of the following: 4096.Bl -tag -width readonly 4097.It Em readonly 4098Treat 4099.Pa /etc/resolv.conf 4100as read only. 4101If 4102.Dq dns 4103is enabled, 4104.Nm 4105will still attempt to negotiate nameservers with the peer, making the results 4106available via the 4107.Dv DNS0 4108and 4109.Dv DNS1 4110macros. 4111This is the opposite of the 4112.Dq resolv writable 4113command. 4114.It Em reload 4115Reload 4116.Pa /etc/resolv.conf 4117into memory. 4118This may be necessary if for example a DHCP client overwrote 4119.Pa /etc/resolv.conf . 4120.It Em restore 4121Replace 4122.Pa /etc/resolv.conf 4123with the version originally read at startup or with the last 4124.Dq resolv reload 4125command. 4126This is sometimes a useful command to put in the 4127.Pa /etc/ppp/ppp.linkdown 4128file. 4129.It Em rewrite 4130Rewrite the 4131.Pa /etc/resolv.conf 4132file. 4133This command will work even if the 4134.Dq resolv readonly 4135command has been used. 4136It may be useful as a command in the 4137.Pa /etc/ppp/ppp.linkup 4138file if you wish to defer updating 4139.Pa /etc/resolv.conf 4140until after other commands have finished. 4141.It Em writable 4142Allow 4143.Nm 4144to update 4145.Pa /etc/resolv.conf 4146if 4147.Dq dns 4148is enabled and 4149.Nm 4150successfully negotiates a DNS. 4151This is the opposite of the 4152.Dq resolv readonly 4153command. 4154.El 4155.It save 4156This option is not (yet) implemented. 4157.It sendident 4158This command tells 4159.Nm 4160to identify itself to the peer. 4161The link must be in LCP state or higher. 4162If no identity has been set (via the 4163.Ic ident 4164command), 4165.Ic sendident 4166will fail. 4167.Pp 4168When an identity has been set, 4169.Nm 4170will automatically identify itself when it sends or receives a configure 4171reject, when negotiation fails or when LCP reaches the opened state. 4172.Pp 4173Received identification packets are logged to the LCP log (see 4174.Ic set log 4175for details) and are never responded to. 4176.It set Ns Xo 4177.Op up 4178.Ar var value 4179.Xc 4180This option allows the setting of any of the following variables: 4181.Bl -tag -width 2n 4182.It set accmap Ar hex-value 4183ACCMap stands for Asynchronous Control Character Map. 4184This is always 4185negotiated with the peer, and defaults to a value of 00000000 in hex. 4186This protocol is required to defeat hardware that depends on passing 4187certain characters from end to end (such as XON/XOFF etc). 4188.Pp 4189For the XON/XOFF scenario, use 4190.Dq set accmap 000a0000 . 4191.It set Op auth Ns Xo 4192.No key Ar value 4193.Xc 4194This sets the authentication key (or password) used in client mode 4195PAP or CHAP negotiation to the given value. 4196It also specifies the 4197password to be used in the dial or login scripts in place of the 4198.Sq \eP 4199sequence, preventing the actual password from being logged. 4200If 4201.Ar command 4202or 4203.Ar chat 4204logging is in effect, 4205.Ar value 4206is logged as 4207.Sq ******** 4208for security reasons. 4209.Pp 4210If the first character of 4211.Ar value 4212is an exclamation mark 4213.Pq Dq !\& , 4214.Nm 4215treats the remainder of the string as a program that must be executed 4216to determine the 4217.Dq authname 4218and 4219.Dq authkey 4220values. 4221.Pp 4222If the 4223.Dq !\& 4224is doubled up 4225(to 4226.Dq !! ) , 4227it is treated as a single literal 4228.Dq !\& , 4229otherwise, ignoring the 4230.Dq !\& , 4231.Ar value 4232is parsed as a program to execute in the same was as the 4233.Dq !bg 4234command above, substituting special names in the same manner. 4235Once executed, 4236.Nm 4237will feed the program three lines of input, each terminated by a newline 4238character: 4239.Bl -bullet 4240.It 4241The host name as sent in the CHAP challenge. 4242.It 4243The challenge string as sent in the CHAP challenge. 4244.It 4245The locally defined 4246.Dq authname . 4247.El 4248.Pp 4249Two lines of output are expected: 4250.Bl -bullet 4251.It 4252The 4253.Dq authname 4254to be sent with the CHAP response. 4255.It 4256The 4257.Dq authkey , 4258which is encrypted with the challenge and request id, the answer being sent 4259in the CHAP response packet. 4260.El 4261.Pp 4262When configuring 4263.Nm 4264in this manner, it's expected that the host challenge is a series of ASCII 4265digits or characters. 4266An encryption device or Secure ID card is usually 4267required to calculate the secret appropriate for the given challenge. 4268.It set authname Ar id 4269This sets the authentication id used in client mode PAP or CHAP negotiation. 4270.Pp 4271If used in 4272.Fl direct 4273mode with CHAP enabled, 4274.Ar id 4275is used in the initial authentication challenge and should normally be set to 4276the local machine name. 4277.It set autoload Xo 4278.Ar min-percent max-percent period 4279.Xc 4280These settings apply only in multi-link mode and default to zero, zero and 4281five respectively. 4282When more than one 4283.Ar demand-dial 4284(also known as 4285.Fl auto ) 4286mode link is available, only the first link is made active when 4287.Nm 4288first reads data from the tun device. 4289The next 4290.Ar demand-dial 4291link will be opened only when the current bundle throughput is at least 4292.Ar max-percent 4293percent of the total bundle bandwidth for 4294.Ar period 4295seconds. 4296When the current bundle throughput decreases to 4297.Ar min-percent 4298percent or less of the total bundle bandwidth for 4299.Ar period 4300seconds, a 4301.Ar demand-dial 4302link will be brought down as long as it's not the last active link. 4303.Pp 4304Bundle throughput is measured as the maximum of inbound and outbound 4305traffic. 4306.Pp 4307The default values cause 4308.Ar demand-dial 4309links to simply come up one at a time. 4310.Pp 4311Certain devices cannot determine their physical bandwidth, so it 4312is sometimes necessary to use the 4313.Dq set bandwidth 4314command (described below) to make 4315.Dq set autoload 4316work correctly. 4317.It set bandwidth Ar value 4318This command sets the connection bandwidth in bits per second. 4319.Ar value 4320must be greater than zero. 4321It is currently only used by the 4322.Dq set autoload 4323command above. 4324.It set callback Ar option Ns No ... 4325If no arguments are given, callback is disabled, otherwise, 4326.Nm 4327will request (or in 4328.Fl direct 4329mode, will accept) one of the given 4330.Ar option Ns No s . 4331In client mode, if an 4332.Ar option 4333is NAK'd 4334.Nm 4335will request a different 4336.Ar option , 4337until no options remain at which point 4338.Nm 4339will terminate negotiations (unless 4340.Dq none 4341is one of the specified 4342.Ar option ) . 4343In server mode, 4344.Nm 4345will accept any of the given protocols - but the client 4346.Em must 4347request one of them. 4348If you wish callback to be optional, you must {include} 4349.Ar none 4350as an option. 4351.Pp 4352The 4353.Ar option Ns No s 4354are as follows (in this order of preference): 4355.Pp 4356.Bl -tag -width Ds 4357.It auth 4358The callee is expected to decide the callback number based on 4359authentication. 4360If 4361.Nm 4362is the callee, the number should be specified as the fifth field of 4363the peers entry in 4364.Pa /etc/ppp/ppp.secret . 4365.It cbcp 4366Microsoft's callback control protocol is used. 4367See 4368.Dq set cbcp 4369below. 4370.Pp 4371If you wish to negotiate 4372.Ar cbcp 4373in client mode but also wish to allow the server to request no callback at 4374CBCP negotiation time, you must specify both 4375.Ar cbcp 4376and 4377.Ar none 4378as callback options. 4379.It E.164 *| Ns Xo 4380.Ar number Ns Op , Ns Ar number Ns 4381.No ... 4382.Xc 4383The caller specifies the 4384.Ar number . 4385If 4386.Nm 4387is the callee, 4388.Ar number 4389should be either a comma separated list of allowable numbers or a 4390.Dq \&* , 4391meaning any number is permitted. 4392If 4393.Nm 4394is the caller, only a single number should be specified. 4395.Pp 4396Note, this option is very unsafe when used with a 4397.Dq \&* 4398as a malicious caller can tell 4399.Nm 4400to call any (possibly international) number without first authenticating 4401themselves. 4402.It none 4403If the peer does not wish to do callback at all, 4404.Nm 4405will accept the fact and continue without callback rather than terminating 4406the connection. 4407This is required (in addition to one or more other callback 4408options) if you wish callback to be optional. 4409.El 4410.Pp 4411.It set cbcp Oo 4412.No *| Ns Ar number Ns Oo 4413.No , Ns Ar number Ns ...\& Oc 4414.Op Ar delay Op Ar retry 4415.Oc 4416If no arguments are given, CBCP (Microsoft's CallBack Control Protocol) 4417is disabled - ie, configuring CBCP in the 4418.Dq set callback 4419command will result in 4420.Nm 4421requesting no callback in the CBCP phase. 4422Otherwise, 4423.Nm 4424attempts to use the given phone 4425.Ar number Ns No (s). 4426.Pp 4427In server mode 4428.Pq Fl direct , 4429.Nm 4430will insist that the client uses one of these numbers, unless 4431.Dq \&* 4432is used in which case the client is expected to specify the number. 4433.Pp 4434In client mode, 4435.Nm 4436will attempt to use one of the given numbers (whichever it finds to 4437be agreeable with the peer), or if 4438.Dq \&* 4439is specified, 4440.Nm 4441will expect the peer to specify the number. 4442.It set cd Oo 4443.No off| Ns Ar seconds Ns Op !\& 4444.Oc 4445Normally, 4446.Nm 4447checks for the existence of carrier depending on the type of device 4448that has been opened: 4449.Bl -tag -width XXX -offset XXX 4450.It Terminal Devices 4451Carrier is checked one second after the login script is complete. 4452If it's not set, 4453.Nm 4454assumes that this is because the device doesn't support carrier (which 4455is true for most 4456.Dq laplink 4457NULL-modem cables), logs the fact and stops checking 4458for carrier. 4459.Pp 4460As ptys don't support the TIOCMGET ioctl, the tty device will switch all 4461carrier detection off when it detects that the device is a pty. 4462.It ISDN (i4b) Devices 4463Carrier is checked once per second for 6 seconds. 4464If it's not set after 4465the sixth second, the connection attempt is considered to have failed and 4466the device is closed. 4467Carrier is always required for i4b devices. 4468.It PPPoE (netgraph) Devices 4469Carrier is checked once per second for 5 seconds. 4470If it's not set after 4471the fifth second, the connection attempt is considered to have failed and 4472the device is closed. 4473Carrier is always required for PPPoE devices. 4474.El 4475.Pp 4476All other device types don't support carrier. 4477Setting a carrier value will 4478result in a warning when the device is opened. 4479.Pp 4480Some modems take more than one second after connecting to assert the carrier 4481signal. 4482If this delay isn't increased, this will result in 4483.Nm Ns No 's 4484inability to detect when the link is dropped, as 4485.Nm 4486assumes that the device isn't asserting carrier. 4487.Pp 4488The 4489.Dq set cd 4490command overrides the default carrier behaviour. 4491.Ar seconds 4492specifies the maximum number of seconds that 4493.Nm 4494should wait after the dial script has finished before deciding if 4495carrier is available or not. 4496.Pp 4497If 4498.Dq off 4499is specified, 4500.Nm 4501will not check for carrier on the device, otherwise 4502.Nm 4503will not proceed to the login script until either carrier is detected 4504or until 4505.Ar seconds 4506has elapsed, at which point 4507.Nm 4508assumes that the device will not set carrier. 4509.Pp 4510If no arguments are given, carrier settings will go back to their default 4511values. 4512.Pp 4513If 4514.Ar seconds 4515is followed immediately by an exclamation mark 4516.Pq Dq !\& , 4517.Nm 4518will 4519.Em require 4520carrier. 4521If carrier is not detected after 4522.Ar seconds 4523seconds, the link will be disconnected. 4524.It set choked Op Ar timeout 4525This sets the number of seconds that 4526.Nm 4527will keep a choked output queue before dropping all pending output packets. 4528If 4529.Ar timeout 4530is less than or equal to zero or if 4531.Ar timeout 4532isn't specified, it is set to the default value of 4533.Em 120 seconds . 4534.Pp 4535A choked output queue occurs when 4536.Nm 4537has read a certain number of packets from the local network for transmission, 4538but cannot send the data due to link failure (the peer is busy etc.). 4539.Nm 4540will not read packets indefinitely. 4541Instead, it reads up to 4542.Em 30 4543packets (or 4544.Em 30 No + 4545.Em nlinks No * 4546.Em 2 4547packets in multi-link mode), then stops reading the network interface 4548until either 4549.Ar timeout 4550seconds have passed or at least one packet has been sent. 4551.Pp 4552If 4553.Ar timeout 4554seconds pass, all pending output packets are dropped. 4555.It set ctsrts|crtscts on|off 4556This sets hardware flow control. 4557Hardware flow control is 4558.Ar on 4559by default. 4560.It set deflate Ar out-winsize Op Ar in-winsize 4561This sets the DEFLATE algorithms default outgoing and incoming window 4562sizes. 4563Both 4564.Ar out-winsize 4565and 4566.Ar in-winsize 4567must be values between 4568.Em 8 4569and 4570.Em 15 . 4571If 4572.Ar in-winsize 4573is specified, 4574.Nm 4575will insist that this window size is used and will not accept any other 4576values from the peer. 4577.It set dns Op Ar primary Op Ar secondary 4578This command specifies DNS overrides for the 4579.Dq accept dns 4580command. 4581Refer to the 4582.Dq accept 4583command description above for details. 4584This command does not affect the IP numbers requested using 4585.Dq enable dns . 4586.It set device|line Xo 4587.Ar value Ns No ... 4588.Xc 4589This sets the device(s) to which 4590.Nm 4591will talk to the given 4592.Dq value . 4593.Pp 4594All ISDN and serial device names are expected to begin with 4595.Pa /dev/ . 4596ISDN devices are usually called 4597.Pa i4brbchX 4598and serial devices are usually called 4599.Pa cuaXX . 4600.Pp 4601If 4602.Dq value 4603does not begin with 4604.Pa /dev/ , 4605it must either begin with an exclamation mark 4606.Pq Dq !\& , 4607be of the format 4608.No PPPoE: Ns Ar iface Ns Xo 4609.Op \&: Ns Ar provider Ns 4610.Xc 4611(on 4612.Xr netgraph 4 4613enabled systems), or be of the format 4614.Sm off 4615.Ar host : port Op /tcp|udp . 4616.Sm on 4617.Pp 4618If it begins with an exclamation mark, the rest of the device name is 4619treated as a program name, and that program is executed when the device 4620is opened. 4621Standard input, output and error are fed back to 4622.Nm 4623and are read and written as if they were a regular device. 4624.Pp 4625If a 4626.No PPPoE: Ns Ar iface Ns Xo 4627.Op \&: Ns Ar provider Ns 4628.Xc 4629specification is given, 4630.Nm 4631will attempt to create a 4632.Em PPP 4633over Ethernet connection using the given 4634.Ar iface 4635interface by using 4636.Xr netgraph 4 . 4637If 4638.Xr netgraph 4 4639is not available, 4640.Nm 4641will attempt to load it using 4642.Xr kldload 2 . 4643If this fails, an external program must be used such as the 4644.Xr pppoed 8 4645program available under 4646.Ox . 4647The given 4648.Ar provider 4649is passed as the service name in the PPPoE Discovery Initiation (PADI) 4650packet. 4651If no provider is given, an empty value will be used. 4652.Pp 4653When a PPPoE connection is established, 4654.Nm 4655will place the name of the Access Concentrator in the environment variable 4656.Ev ACNAME . 4657.Pp 4658Refer to 4659.Xr netgraph 4 4660and 4661.Xr ng_pppoe 4 4662for further details. 4663.Pp 4664If a 4665.Ar host Ns No : Ns Ar port Ns Oo 4666.No /tcp|udp 4667.Oc 4668specification is given, 4669.Nm 4670will attempt to connect to the given 4671.Ar host 4672on the given 4673.Ar port . 4674If a 4675.Dq /tcp 4676or 4677.Dq /udp 4678suffix is not provided, the default is 4679.Dq /tcp . 4680Refer to the section on 4681.Em PPP OVER TCP and UDP 4682above for further details. 4683.Pp 4684If multiple 4685.Dq values 4686are specified, 4687.Nm 4688will attempt to open each one in turn until it succeeds or runs out of 4689devices. 4690.It set dial Ar chat-script 4691This specifies the chat script that will be used to dial the other 4692side. 4693See also the 4694.Dq set login 4695command below. 4696Refer to 4697.Xr chat 8 4698and to the example configuration files for details of the chat script 4699format. 4700It is possible to specify some special 4701.Sq values 4702in your chat script as follows: 4703.Bl -tag -width 2n 4704.It Li \ec 4705When used as the last character in a 4706.Sq send 4707string, this indicates that a newline should not be appended. 4708.It Li \ed 4709When the chat script encounters this sequence, it delays two seconds. 4710.It Li \ep 4711When the chat script encounters this sequence, it delays for one quarter of 4712a second. 4713.It Li \en 4714This is replaced with a newline character. 4715.It Li \er 4716This is replaced with a carriage return character. 4717.It Li \es 4718This is replaced with a space character. 4719.It Li \et 4720This is replaced with a tab character. 4721.It Li \eT 4722This is replaced by the current phone number (see 4723.Dq set phone 4724below). 4725.It Li \eP 4726This is replaced by the current 4727.Ar authkey 4728value (see 4729.Dq set authkey 4730above). 4731.It Li \eU 4732This is replaced by the current 4733.Ar authname 4734value (see 4735.Dq set authname 4736above). 4737.El 4738.Pp 4739Note that two parsers will examine these escape sequences, so in order to 4740have the 4741.Sq chat parser 4742see the escape character, it is necessary to escape it from the 4743.Sq command parser . 4744This means that in practice you should use two escapes, for example: 4745.Bd -literal -offset indent 4746set dial "... ATDT\\\\T CONNECT" 4747.Ed 4748.Pp 4749It is also possible to execute external commands from the chat script. 4750To do this, the first character of the expect or send string is an 4751exclamation mark 4752.Pq Dq !\& . 4753If a literal exclamation mark is required, double it up to 4754.Dq !!\& 4755and it will be treated as a single literal 4756.Dq !\& . 4757When the command is executed, standard input and standard output are 4758directed to the open device (see the 4759.Dq set device 4760command), and standard error is read by 4761.Nm 4762and substituted as the expect or send string. 4763If 4764.Nm 4765is running in interactive mode, file descriptor 3 is attached to 4766.Pa /dev/tty . 4767.Pp 4768For example (wrapped for readability): 4769.Bd -literal -offset indent 4770set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e 4771word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e 4772\\"!/bin/echo in\\" HELLO" 4773.Ed 4774.Pp 4775would result in the following chat sequence (output using the 4776.Sq set log local chat 4777command before dialing): 4778.Bd -literal -offset indent 4779Dial attempt 1 of 1 4780dial OK! 4781Chat: Expecting: 4782Chat: Sending: 4783Chat: Expecting: login:--login: 4784Chat: Wait for (5): login: 4785Chat: Sending: ppp 4786Chat: Expecting: word: 4787Chat: Wait for (5): word: 4788Chat: Sending: ppp 4789Chat: Expecting: !sh \\-c "echo \\-n label: >&2" 4790Chat: Exec: sh -c "echo -n label: >&2" 4791Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label: 4792Chat: Exec: /bin/echo in 4793Chat: Sending: 4794Chat: Expecting: HELLO 4795Chat: Wait for (5): HELLO 4796login OK! 4797.Ed 4798.Pp 4799Note (again) the use of the escape character, allowing many levels of 4800nesting. 4801Here, there are four parsers at work. 4802The first parses the original line, reading it as three arguments. 4803The second parses the third argument, reading it as 11 arguments. 4804At this point, it is 4805important that the 4806.Dq \&- 4807signs are escaped, otherwise this parser will see them as constituting 4808an expect-send-expect sequence. 4809When the 4810.Dq !\& 4811character is seen, the execution parser reads the first command as three 4812arguments, and then 4813.Xr sh 1 4814itself expands the argument after the 4815.Fl c . 4816As we wish to send the output back to the modem, in the first example 4817we redirect our output to file descriptor 2 (stderr) so that 4818.Nm 4819itself sends and logs it, and in the second example, we just output to stdout, 4820which is attached directly to the modem. 4821.Pp 4822This, of course means that it is possible to execute an entirely external 4823.Dq chat 4824command rather than using the internal one. 4825See 4826.Xr chat 8 4827for a good alternative. 4828.Pp 4829The external command that is executed is subjected to the same special 4830word expansions as the 4831.Dq !bg 4832command. 4833.It set enddisc Op label|IP|MAC|magic|psn value 4834This command sets our local endpoint discriminator. 4835If set prior to LCP negotiation, and if no 4836.Dq disable enddisc 4837command has been used, 4838.Nm 4839will send the information to the peer using the LCP endpoint discriminator 4840option. 4841The following discriminators may be set: 4842.Bl -tag -width indent 4843.It Li label 4844The current label is used. 4845.It Li IP 4846Our local IP number is used. 4847As LCP is negotiated prior to IPCP, it is 4848possible that the IPCP layer will subsequently change this value. 4849If 4850it does, the endpoint discriminator stays at the old value unless manually 4851reset. 4852.It Li MAC 4853This is similar to the 4854.Ar IP 4855option above, except that the MAC address associated with the local IP 4856number is used. 4857If the local IP number is not resident on any Ethernet 4858interface, the command will fail. 4859.Pp 4860As the local IP number defaults to whatever the machine host name is, 4861.Dq set enddisc mac 4862is usually done prior to any 4863.Dq set ifaddr 4864commands. 4865.It Li magic 4866A 20 digit random number is used. 4867Care should be taken when using magic numbers as restarting 4868.Nm 4869or creating a link using a different 4870.Nm 4871invocation will also use a different magic number and will therefore not 4872be recognised by the peer as belonging to the same bundle. 4873This makes it unsuitable for 4874.Fl direct 4875connections. 4876.It Li psn Ar value 4877The given 4878.Ar value 4879is used. 4880.Ar Value 4881should be set to an absolute public switched network number with the 4882country code first. 4883.El 4884.Pp 4885If no arguments are given, the endpoint discriminator is reset. 4886.It set escape Ar value... 4887This option is similar to the 4888.Dq set accmap 4889option above. 4890It allows the user to specify a set of characters that will be 4891.Sq escaped 4892as they travel across the link. 4893.It set filter dial|alive|in|out Ar rule-no Xo 4894.No permit|deny|clear| Ns Ar rule-no 4895.Op !\& 4896.Oo Op host 4897.Ar src_addr Ns Op / Ns Ar width 4898.Op Ar dst_addr Ns Op / Ns Ar width 4899.Oc [ Ns Ar proto 4900.Op src lt|eq|gt Ar port 4901.Op dst lt|eq|gt Ar port 4902.Op estab 4903.Op syn 4904.Op finrst 4905.Op timeout Ar secs ] 4906.Xc 4907.Nm 4908supports four filter sets. 4909The 4910.Em alive 4911filter specifies packets that keep the connection alive - resetting the 4912idle timer. 4913The 4914.Em dial 4915filter specifies packets that cause 4916.Nm 4917to dial when in 4918.Fl auto 4919mode. 4920The 4921.Em in 4922filter specifies packets that are allowed to travel 4923into the machine and the 4924.Em out 4925filter specifies packets that are allowed out of the machine. 4926.Pp 4927Filtering is done prior to any IP alterations that might be done by the 4928NAT engine on outgoing packets and after any IP alterations that might 4929be done by the NAT engine on incoming packets. 4930By default all empty filter sets allow all packets to pass. 4931Rules are processed in order according to 4932.Ar rule-no 4933(unless skipped by specifying a rule number as the 4934.Ar action ) . 4935Up to 40 rules may be given for each set. 4936If a packet doesn't match 4937any of the rules in a given set, it is discarded. 4938In the case of 4939.Em in 4940and 4941.Em out 4942filters, this means that the packet is dropped. 4943In the case of 4944.Em alive 4945filters it means that the packet will not reset the idle timer (even if 4946the 4947.Ar in Ns No / Ns Ar out 4948filter has a 4949.Dq timeout 4950value) and in the case of 4951.Em dial 4952filters it means that the packet will not trigger a dial. 4953A packet failing to trigger a dial will be dropped rather than queued. 4954Refer to the 4955section on 4956.Sx PACKET FILTERING 4957above for further details. 4958.It set hangup Ar chat-script 4959This specifies the chat script that will be used to reset the device 4960before it is closed. 4961It should not normally be necessary, but can 4962be used for devices that fail to reset themselves properly on close. 4963.It set help|? Op Ar command 4964This command gives a summary of available set commands, or if 4965.Ar command 4966is specified, the command usage is shown. 4967.It set ifaddr Oo Ar myaddr Ns 4968.Op / Ns Ar \&nn 4969.Oo Ar hisaddr Ns Op / Ns Ar \&nn 4970.Oo Ar netmask 4971.Op Ar triggeraddr 4972.Oc Oc 4973.Oc 4974This command specifies the IP addresses that will be used during 4975IPCP negotiation. 4976Addresses are specified using the format 4977.Pp 4978.Dl a.b.c.d/nn 4979.Pp 4980Where 4981.Dq a.b.c.d 4982is the preferred IP, but 4983.Ar nn 4984specifies how many bits of the address we will insist on. 4985If 4986.No / Ns Ar nn 4987is omitted, it defaults to 4988.Dq /32 4989unless the IP address is 0.0.0.0 in which case it defaults to 4990.Dq /0 . 4991.Pp 4992If you wish to assign a dynamic IP number to the peer, 4993.Ar hisaddr 4994may also be specified as a range of IP numbers in the format 4995.Bd -ragged -offset indent 4996.Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Xo 4997.Oc Ns Oo , Ns Ar \&IP Ns 4998.Op \&- Ns Ar \&IP Ns 4999.Oc Ns ... 5000.Xc 5001.Ed 5002.Pp 5003for example: 5004.Pp 5005.Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20 5006.Pp 5007will only negotiate 5008.Dq 10.0.0.1 5009as the local IP number, but may assign any of the given 10 IP 5010numbers to the peer. 5011If the peer requests one of these numbers, 5012and that number is not already in use, 5013.Nm 5014will grant the peers request. 5015This is useful if the peer wants 5016to re-establish a link using the same IP number as was previously 5017allocated (thus maintaining any existing tcp or udp connections). 5018.Pp 5019If the peer requests an IP number that's either outside 5020of this range or is already in use, 5021.Nm 5022will suggest a random unused IP number from the range. 5023.Pp 5024If 5025.Ar triggeraddr 5026is specified, it is used in place of 5027.Ar myaddr 5028in the initial IPCP negotiation. 5029However, only an address in the 5030.Ar myaddr 5031range will be accepted. 5032This is useful when negotiating with some 5033.Dv PPP 5034implementations that will not assign an IP number unless their peer 5035requests 5036.Dq 0.0.0.0 . 5037.Pp 5038It should be noted that in 5039.Fl auto 5040mode, 5041.Nm 5042will configure the interface immediately upon reading the 5043.Dq set ifaddr 5044line in the config file. 5045In any other mode, these values are just 5046used for IPCP negotiations, and the interface isn't configured 5047until the IPCP layer is up. 5048.Pp 5049Note that the 5050.Ar HISADDR 5051argument may be overridden by the third field in the 5052.Pa ppp.secret 5053file once the client has authenticated itself 5054(if PAP or CHAP are 5055.Dq enabled ) . 5056Refer to the 5057.Sx AUTHENTICATING INCOMING CONNECTIONS 5058section for details. 5059.Pp 5060In all cases, if the interface is already configured, 5061.Nm 5062will try to maintain the interface IP numbers so that any existing 5063bound sockets will remain valid. 5064.It set ifqueue Ar packets 5065Set the maximum number of packets that 5066.Nm 5067will read from the tunnel interface while data cannot be sent to any of 5068the available links. 5069This queue limit is necessary to flow control outgoing data as the tunnel 5070interface is likely to be far faster than the combined links available to 5071.Nm . 5072.Pp 5073If 5074.Ar packets 5075is set to a value less than the number of links, 5076.Nm 5077will read up to that value regardless. 5078This prevents any possible latency problems. 5079.Pp 5080The default value for 5081.Ar packets 5082is 5083.Dq 30 . 5084.It set ccpretry|ccpretries Oo Ar timeout 5085.Op Ar reqtries Op Ar trmtries 5086.Oc 5087.It set chapretry|chapretries Oo Ar timeout 5088.Op Ar reqtries 5089.Oc 5090.It set ipcpretry|ipcpretries Oo Ar timeout 5091.Op Ar reqtries Op Ar trmtries 5092.Oc 5093.It set ipv6cpretry|ipv6cpretries Oo Ar timeout 5094.Op Ar reqtries Op Ar trmtries 5095.Oc 5096.It set lcpretry|lcpretries Oo Ar timeout 5097.Op Ar reqtries Op Ar trmtries 5098.Oc 5099.It set papretry|papretries Oo Ar timeout 5100.Op Ar reqtries 5101.Oc 5102These commands set the number of seconds that 5103.Nm 5104will wait before resending Finite State Machine (FSM) Request packets. 5105The default 5106.Ar timeout 5107for all FSMs is 3 seconds (which should suffice in most cases). 5108.Pp 5109If 5110.Ar reqtries 5111is specified, it tells 5112.Nm 5113how many configuration request attempts it should make while receiving 5114no reply from the peer before giving up. 5115The default is 5 attempts for 5116CCP, LCP and IPCP and 3 attempts for PAP and CHAP. 5117.Pp 5118If 5119.Ar trmtries 5120is specified, it tells 5121.Nm 5122how many terminate requests should be sent before giving up waiting for the 5123peers response. 5124The default is 3 attempts. 5125Authentication protocols are 5126not terminated and it is therefore invalid to specify 5127.Ar trmtries 5128for PAP or CHAP. 5129.Pp 5130In order to avoid negotiations with the peer that will never converge, 5131.Nm 5132will only send at most 3 times the configured number of 5133.Ar reqtries 5134in any given negotiation session before giving up and closing that layer. 5135.It set log Xo 5136.Op local 5137.Op +|- Ns 5138.Ar value Ns No ... 5139.Xc 5140This command allows the adjustment of the current log level. 5141Refer to the Logging Facility section for further details. 5142.It set login Ar chat-script 5143This 5144.Ar chat-script 5145compliments the dial-script. 5146If both are specified, the login 5147script will be executed after the dial script. 5148Escape sequences available in the dial script are also available here. 5149.It set logout Ar chat-script 5150This specifies the chat script that will be used to logout 5151before the hangup script is called. 5152It should not normally be necessary. 5153.It set lqrperiod|echoperiod Ar frequency 5154This command sets the 5155.Ar frequency 5156in seconds at which 5157.Em LQR 5158or 5159.Em LCP ECHO 5160packets are sent. 5161The default is 30 seconds. 5162You must also use the 5163.Dq enable lqr 5164and/or 5165.Dq enable echo 5166commands if you wish to send 5167.Em LQR 5168or 5169.Em LCP ECHO 5170requests to the peer. 5171.It set mode Ar interactive|auto|ddial|background 5172This command allows you to change the 5173.Sq mode 5174of the specified link. 5175This is normally only useful in multi-link mode, 5176but may also be used in uni-link mode. 5177.Pp 5178It is not possible to change a link that is 5179.Sq direct 5180or 5181.Sq dedicated . 5182.Pp 5183Note: If you issue the command 5184.Dq set mode auto , 5185and have network address translation enabled, it may be useful to 5186.Dq enable iface-alias 5187afterwards. 5188This will allow 5189.Nm 5190to do the necessary address translations to enable the process that 5191triggers the connection to connect once the link is up despite the 5192peer assigning us a new (dynamic) IP address. 5193.It set mppe Op 40|56|128|* Op stateless|stateful|* 5194This option selects the encryption parameters used when negotiation 5195MPPE. 5196MPPE can be disabled entirely with the 5197.Dq disable mppe 5198command. 5199If no arguments are given, 5200.Nm 5201will attempt to negotiate a stateful link with a 128 bit key, but 5202will agree to whatever the peer requests (including no encryption 5203at all). 5204.Pp 5205If any arguments are given, 5206.Nm 5207will 5208.Em insist 5209on using MPPE and will close the link if it's rejected by the peer (Note; 5210this behaviour can be overridden by a configured RADIUS server). 5211.Pp 5212The first argument specifies the number of bits that 5213.Nm 5214should insist on during negotiations and the second specifies whether 5215.Nm 5216should insist on stateful or stateless mode. 5217In stateless mode, the 5218encryption dictionary is re-initialised with every packet according to 5219an encryption key that is changed with every packet. 5220In stateful mode, 5221the encryption dictionary is re-initialised every 256 packets or after 5222the loss of any data and the key is changed every 256 packets. 5223Stateless mode is less efficient but is better for unreliable transport 5224layers. 5225.It set mrru Op Ar value 5226Setting this option enables Multi-link PPP negotiations, also known as 5227Multi-link Protocol or MP. 5228There is no default MRRU (Maximum Reconstructed Receive Unit) value. 5229If no argument is given, multi-link mode is disabled. 5230.It set mru Xo 5231.Op max Ns Op imum 5232.Op Ar value 5233.Xc 5234The default MRU (Maximum Receive Unit) is 1500. 5235If it is increased, the other side *may* increase its MTU. 5236In theory there is no point in decreasing the MRU to below the default as the 5237.Em PPP 5238protocol says implementations *must* be able to accept packets of at 5239least 1500 octets. 5240.Pp 5241If the 5242.Dq maximum 5243keyword is used, 5244.Nm 5245will refuse to negotiate a higher value. 5246The maximum MRU can be set to 2048 at most. 5247Setting a maximum of less than 1500 violates the 5248.Em PPP 5249rfc, but may sometimes be necessary. 5250For example, 5251.Em PPPoE 5252imposes a maximum of 1492 due to hardware limitations. 5253.Pp 5254If no argument is given, 1500 is assumed. 5255A value must be given when 5256.Dq maximum 5257is specified. 5258.It set mtu Xo 5259.Op max Ns Op imum 5260.Op Ar value 5261.Xc 5262The default MTU is 1500. 5263At negotiation time, 5264.Nm 5265will accept whatever MRU the peer requests (assuming it's 5266not less than 296 bytes or greater than the assigned maximum). 5267If the MTU is set, 5268.Nm 5269will not accept MRU values less than 5270.Ar value . 5271When negotiations are complete, the MTU is used when writing to the 5272interface, even if the peer requested a higher value MRU. 5273This can be useful for 5274limiting your packet size (giving better bandwidth sharing at the expense 5275of more header data). 5276.Pp 5277If the 5278.Dq maximum 5279keyword is used, 5280.Nm 5281will refuse to negotiate a higher value. 5282The maximum MTU can be set to 2048 at most. 5283Note, it is necessary to use the 5284.Dq maximum 5285keyword to limit the MTU when using PPPoE. 5286.Pp 5287If no 5288.Ar value 5289is given, 1500, or whatever the peer asks for is used. 5290A value must be given when 5291.Dq maximum 5292is specified. 5293.It set nbns Op Ar x.x.x.x Op Ar y.y.y.y 5294This option allows the setting of the Microsoft NetBIOS name server 5295values to be returned at the peers request. 5296If no values are given, 5297.Nm 5298will reject any such requests. 5299.It set openmode active|passive Op Ar delay 5300By default, 5301.Ar openmode 5302is always 5303.Ar active 5304with a one second 5305.Ar delay . 5306That is, 5307.Nm 5308will always initiate LCP/IPCP/CCP negotiation one second after the line 5309comes up. 5310If you want to wait for the peer to initiate negotiations, you 5311can use the value 5312.Ar passive . 5313If you want to initiate negotiations immediately or after more than one 5314second, the appropriate 5315.Ar delay 5316may be specified here in seconds. 5317.It set parity odd|even|none|mark 5318This allows the line parity to be set. 5319The default value is 5320.Ar none . 5321.It set phone Ar telno Ns Xo 5322.Oo \&| Ns Ar backupnumber 5323.Oc Ns ... Ns Oo : Ns Ar nextnumber 5324.Oc Ns ... 5325.Xc 5326This allows the specification of the phone number to be used in 5327place of the \\\\T string in the dial and login chat scripts. 5328Multiple phone numbers may be given separated either by a pipe 5329.Pq Dq \&| 5330or a colon 5331.Pq Dq \&: . 5332.Pp 5333Numbers after the pipe are only dialed if the dial or login 5334script for the previous number failed. 5335.Pp 5336Numbers after the colon are tried sequentially, irrespective of 5337the reason the line was dropped. 5338.Pp 5339If multiple numbers are given, 5340.Nm 5341will dial them according to these rules until a connection is made, retrying 5342the maximum number of times specified by 5343.Dq set redial 5344below. 5345In 5346.Fl background 5347mode, each number is attempted at most once. 5348.It set pppoe Op standard|3Com 5349This option configures the underlying 5350.Xr ng_pppoe 4 5351node to either standard RFC2516 PPPoE or proprietary 3Com mode. 5352If not set the system default will be used. 5353.It set Op proc Ns Xo 5354.No title Op Ar value 5355.Xc 5356The current process title as displayed by 5357.Xr ps 1 5358is changed according to 5359.Ar value . 5360If 5361.Ar value 5362is not specified, the original process title is restored. 5363All the 5364word replacements done by the shell commands (see the 5365.Dq bg 5366command above) are done here too. 5367.Pp 5368Note, if USER is required in the process title, the 5369.Dq set proctitle 5370command must appear in 5371.Pa ppp.linkup , 5372as it is not known when the commands in 5373.Pa ppp.conf 5374are executed. 5375.It set radius Op Ar config-file 5376This command enables RADIUS support (if it's compiled in). 5377.Ar config-file 5378refers to the radius client configuration file as described in 5379.Xr radius.conf 5 . 5380If PAP, CHAP, MSCHAP or MSCHAPv2 are 5381.Dq enable Ns No d , 5382.Nm 5383behaves as a 5384.Em \&N Ns No etwork 5385.Em \&A Ns No ccess 5386.Em \&S Ns No erver 5387and uses the configured RADIUS server to authenticate rather than 5388authenticating from the 5389.Pa ppp.secret 5390file or from the passwd database. 5391.Pp 5392If none of PAP, CHAP, MSCHAP or MSCHAPv2 are enabled, 5393.Dq set radius 5394will do nothing. 5395.Pp 5396.Nm 5397uses the following attributes from the RADIUS reply: 5398.Bl -tag -width XXX -offset XXX 5399.It RAD_FRAMED_IP_ADDRESS 5400The peer IP address is set to the given value. 5401.It RAD_FRAMED_IP_NETMASK 5402The tun interface netmask is set to the given value. 5403.It RAD_FRAMED_MTU 5404If the given MTU is less than the peers MRU as agreed during LCP 5405negotiation, *and* it is less that any configured MTU (see the 5406.Dq set mru 5407command), the tun interface MTU is set to the given value. 5408.It RAD_FRAMED_COMPRESSION 5409If the received compression type is 5410.Dq 1 , 5411.Nm 5412will request VJ compression during IPCP negotiations despite any 5413.Dq disable vj 5414configuration command. 5415.It RAD_FILTER_ID 5416If this attribute is supplied, 5417.Nm 5418will attempt to use it as an additional label to load from the 5419.Pa ppp.linkup 5420and 5421.Pa ppp.linkdown 5422files. 5423The load will be attempted before (and in addition to) the normal 5424label search. 5425If the label doesn't exist, no action is taken and 5426.Nm 5427proceeds to the normal load using the current label. 5428.It RAD_FRAMED_ROUTE 5429The received string is expected to be in the format 5430.Ar dest Ns Op / Ns Ar bits 5431.Ar gw 5432.Op Ar metrics . 5433Any specified metrics are ignored. 5434.Dv MYADDR 5435and 5436.Dv HISADDR 5437are understood as valid values for 5438.Ar dest 5439and 5440.Ar gw , 5441.Dq default 5442can be used for 5443.Ar dest 5444to sepcify the default route, and 5445.Dq 0.0.0.0 5446is understood to be the same as 5447.Dq default 5448for 5449.Ar dest 5450and 5451.Dv HISADDR 5452for 5453.Ar gw . 5454.Pp 5455For example, a returned value of 5456.Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400 5457would result in a routing table entry to the 1.2.3.0/24 network via 5458.Dv HISADDR 5459and a returned value of 5460.Dq 0.0.0.0 0.0.0.0 5461or 5462.Dq default HISADDR 5463would result in a default route to 5464.Dv HISADDR . 5465.Pp 5466All RADIUS routes are applied after any sticky routes are applied, making 5467RADIUS routes override configured routes. 5468This also applies for RADIUS routes that don't {include} the 5469.Dv MYADDR 5470or 5471.Dv HISADDR 5472keywords. 5473.Pp 5474.It RAD_FRAMED_IPV6_PREFIX 5475If this attribute is supplied, the value is substituted for IPV6PREFIX 5476in a command. 5477You may pass it to such as DHCPv6 for delegating an 5478IPv6 prefix to a peer. 5479.It RAD_FRAMED_IPV6_ROUTE 5480The received string is expected to be in the format 5481.Ar dest Ns Op / Ns Ar bits 5482.Ar gw 5483.Op Ar metrics . 5484Any specified metrics are ignored. 5485.Dv MYADDR6 5486and 5487.Dv HISADDR6 5488are understood as valid values for 5489.Ar dest 5490and 5491.Ar gw , 5492.Dq default 5493can be used for 5494.Ar dest 5495to sepcify the default route, and 5496.Dq :: 5497is understood to be the same as 5498.Dq default 5499for 5500.Ar dest 5501and 5502.Dv HISADDR6 5503for 5504.Ar gw . 5505.Pp 5506For example, a returned value of 5507.Dq 3ffe:505:abcd::/48 :: 5508would result in a routing table entry to the 3ffe:505:abcd::/48 network via 5509.Dv HISADDR6 5510and a returned value of 5511.Dq :: :: 5512or 5513.Dq default HISADDR6 5514would result in a default route to 5515.Dv HISADDR6 . 5516.Pp 5517All RADIUS IPv6 routes are applied after any sticky routes are 5518applied, making RADIUS IPv6 routes override configured routes. 5519This 5520also applies for RADIUS IPv6 routes that don't {include} the 5521.Dv MYADDR6 5522or 5523.Dv HISADDR6 5524keywords. 5525.Pp 5526.It RAD_SESSION_TIMEOUT 5527If supplied, the client connection is closed after the given number of 5528seconds. 5529.It RAD_REPLY_MESSAGE 5530If supplied, this message is passed back to the peer as the authentication 5531SUCCESS text. 5532.It RAD_MICROSOFT_MS_CHAP_ERROR 5533If this 5534.Dv RAD_VENDOR_MICROSOFT 5535vendor specific attribute is supplied, it is passed back to the peer as the 5536authentication FAILURE text. 5537.It RAD_MICROSOFT_MS_CHAP2_SUCCESS 5538If this 5539.Dv RAD_VENDOR_MICROSOFT 5540vendor specific attribute is supplied and if MS-CHAPv2 authentication is 5541being used, it is passed back to the peer as the authentication SUCCESS text. 5542.It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY 5543If this 5544.Dv RAD_VENDOR_MICROSOFT 5545vendor specific attribute is supplied and has a value of 2 (Required), 5546.Nm 5547will insist that MPPE encryption is used (even if no 5548.Dq set mppe 5549configuration command has been given with arguments). 5550If it is supplied with a value of 1 (Allowed), encryption is made optional 5551(despite any 5552.Dq set mppe 5553configuration commands with arguments). 5554.It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES 5555If this 5556.Dv RAD_VENDOR_MICROSOFT 5557vendor specific attribute is supplied, bits 1 and 2 are examined. 5558If either or both are set, 40 bit and/or 128 bit (respectively) encryption 5559options are set, overriding any given first argument to the 5560.Dq set mppe 5561command. 5562Note, it is not currently possible for the RADIUS server to specify 56 bit 5563encryption. 5564.It RAD_MICROSOFT_MS_MPPE_RECV_KEY 5565If this 5566.Dv RAD_VENDOR_MICROSOFT 5567vendor specific attribute is supplied, it's value is used as the master 5568key for decryption of incoming data. 5569When clients are authenticated using 5570MSCHAPv2, the RADIUS server MUST provide this attribute if inbound MPPE is 5571to function. 5572.It RAD_MICROSOFT_MS_MPPE_SEND_KEY 5573If this 5574.Dv RAD_VENDOR_MICROSOFT 5575vendor specific attribute is supplied, it's value is used as the master 5576key for encryption of outgoing data. 5577When clients are authenticated using 5578MSCHAPv2, the RADIUS server MUST provide this attribute if outbound MPPE is 5579to function. 5580.El 5581.Pp 5582Values received from the RADIUS server may be viewed using 5583.Dq show bundle . 5584.It set rad_alive Ar timeout 5585When RADIUS is configured, setting 5586.Dq rad_alive 5587to a non-zero 5588.Ar timeout 5589value will tell 5590.Nm 5591to sent RADIUS accounting information to the RADIUS server every 5592.Ar timeout 5593seconds. 5594.It set reconnect Ar timeout ntries 5595Should the line drop unexpectedly (due to loss of CD or LQR 5596failure), a connection will be re-established after the given 5597.Ar timeout . 5598The line will be re-connected at most 5599.Ar ntries 5600times. 5601.Ar Ntries 5602defaults to zero. 5603A value of 5604.Ar random 5605for 5606.Ar timeout 5607will result in a variable pause, somewhere between 1 and 30 seconds. 5608.It set recvpipe Op Ar value 5609This sets the routing table RECVPIPE value. 5610The optimum value is just over twice the MTU value. 5611If 5612.Ar value 5613is unspecified or zero, the default kernel controlled value is used. 5614.It set redial Ar secs Ns Xo 5615.Oo + Ns Ar inc Ns 5616.Op - Ns Ar max Ns 5617.Oc Ns Op . Ns Ar next 5618.Op Ar attempts 5619.Xc 5620.Nm 5621can be instructed to attempt to redial 5622.Ar attempts 5623times. 5624If more than one phone number is specified (see 5625.Dq set phone 5626above), a pause of 5627.Ar next 5628is taken before dialing each number. 5629A pause of 5630.Ar secs 5631is taken before starting at the first number again. 5632A literal value of 5633.Dq Li random 5634may be used here in place of 5635.Ar secs 5636and 5637.Ar next , 5638causing a random delay of between 1 and 30 seconds. 5639.Pp 5640If 5641.Ar inc 5642is specified, its value is added onto 5643.Ar secs 5644each time 5645.Nm 5646tries a new number. 5647.Ar secs 5648will only be incremented at most 5649.Ar max 5650times. 5651.Ar max 5652defaults to 10. 5653.Pp 5654Note, the 5655.Ar secs 5656delay will be effective, even after 5657.Ar attempts 5658has been exceeded, so an immediate manual dial may appear to have 5659done nothing. 5660If an immediate dial is required, a 5661.Dq !\& 5662should immediately follow the 5663.Dq open 5664keyword. 5665See the 5666.Dq open 5667description above for further details. 5668.It set sendpipe Op Ar value 5669This sets the routing table SENDPIPE value. 5670The optimum value is just over twice the MTU value. 5671If 5672.Ar value 5673is unspecified or zero, the default kernel controlled value is used. 5674.It "set server|socket" Ar TcpPort Ns No \&| Ns Xo 5675.Ar LocalName Ns No |none|open|closed 5676.Op password Op Ar mask 5677.Xc 5678This command tells 5679.Nm 5680to listen on the given socket or 5681.Sq diagnostic port 5682for incoming command connections. 5683.Pp 5684The word 5685.Dq none 5686instructs 5687.Nm 5688to close any existing socket and clear the socket configuration. 5689The word 5690.Dq open 5691instructs 5692.Nm 5693to attempt to re-open the port. 5694The word 5695.Dq closed 5696instructs 5697.Nm 5698to close the open port. 5699.Pp 5700If you wish to specify a local domain socket, 5701.Ar LocalName 5702must be specified as an absolute file name, otherwise it is assumed 5703to be the name or number of a TCP port. 5704You may specify the octal umask to be used with a local domain socket. 5705Refer to 5706.Xr umask 2 5707for umask details. 5708Refer to 5709.Xr services 5 5710for details of how to translate TCP port names. 5711.Pp 5712You must also specify the password that must be entered by the client 5713(using the 5714.Dq passwd 5715variable above) when connecting to this socket. 5716If the password is 5717specified as an empty string, no password is required for connecting clients. 5718.Pp 5719When specifying a local domain socket, the first 5720.Dq %d 5721sequence found in the socket name will be replaced with the current 5722interface unit number. 5723This is useful when you wish to use the same 5724profile for more than one connection. 5725.Pp 5726In a similar manner TCP sockets may be prefixed with the 5727.Dq + 5728character, in which case the current interface unit number is added to 5729the port number. 5730.Pp 5731When using 5732.Nm 5733with a server socket, the 5734.Xr pppctl 8 5735command is the preferred mechanism of communications. 5736Currently, 5737.Xr telnet 1 5738can also be used, but link encryption may be implemented in the future, so 5739.Xr telnet 1 5740should be avoided. 5741.Pp 5742Note; 5743.Dv SIGUSR1 5744and 5745.Dv SIGUSR2 5746interact with the diagnostic socket. 5747.It set speed Ar value 5748This sets the speed of the serial device. 5749If speed is specified as 5750.Dq sync , 5751.Nm 5752treats the device as a synchronous device. 5753.Pp 5754Certain device types will know whether they should be specified as 5755synchronous or asynchronous. 5756These devices will override incorrect 5757settings and log a warning to this effect. 5758.It set stopped Op Ar LCPseconds Op Ar CCPseconds 5759If this option is set, 5760.Nm 5761will time out after the given FSM (Finite State Machine) has been in 5762the stopped state for the given number of 5763.Dq seconds . 5764This option may be useful if the peer sends a terminate request, 5765but never actually closes the connection despite our sending a terminate 5766acknowledgement. 5767This is also useful if you wish to 5768.Dq set openmode passive 5769and time out if the peer doesn't send a Configure Request within the 5770given time. 5771Use 5772.Dq set log +lcp +ccp 5773to make 5774.Nm 5775log the appropriate state transitions. 5776.Pp 5777The default value is zero, where 5778.Nm 5779doesn't time out in the stopped state. 5780.Pp 5781This value should not be set to less than the openmode delay (see 5782.Dq set openmode 5783above). 5784.It set timeout Ar idleseconds Op Ar mintimeout 5785This command allows the setting of the idle timer. 5786Refer to the section titled 5787.Sx SETTING THE IDLE TIMER 5788for further details. 5789.Pp 5790If 5791.Ar mintimeout 5792is specified, 5793.Nm 5794will never idle out before the link has been up for at least that number 5795of seconds. 5796.It set urgent Xo 5797.Op tcp|udp|none 5798.Oo Op +|- Ns 5799.Ar port 5800.Oc No ... 5801.Xc 5802This command controls the ports that 5803.Nm 5804prioritizes when transmitting data. 5805The default priority TCP ports 5806are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell), 5807543 (klogin) and 544 (kshell). 5808There are no priority UDP ports by default. 5809See 5810.Xr services 5 5811for details. 5812.Pp 5813If neither 5814.Dq tcp 5815or 5816.Dq udp 5817are specified, 5818.Dq tcp 5819is assumed. 5820.Pp 5821If no 5822.Ar port Ns No s 5823are given, the priority port lists are cleared (although if 5824.Dq tcp 5825or 5826.Dq udp 5827is specified, only that list is cleared). 5828If the first 5829.Ar port 5830argument is prefixed with a plus 5831.Pq Dq \&+ 5832or a minus 5833.Pq Dq \&- , 5834the current list is adjusted, otherwise the list is reassigned. 5835.Ar port Ns No s 5836prefixed with a plus or not prefixed at all are added to the list and 5837.Ar port Ns No s 5838prefixed with a minus are removed from the list. 5839.Pp 5840If 5841.Dq none 5842is specified, all priority port lists are disabled and even 5843.Dv IPTOS_LOWDELAY 5844packets are not prioritised. 5845.It set vj slotcomp on|off 5846This command tells 5847.Nm 5848whether it should attempt to negotiate VJ slot compression. 5849By default, slot compression is turned 5850.Ar on . 5851.It set vj slots Ar nslots 5852This command sets the initial number of slots that 5853.Nm 5854will try to negotiate with the peer when VJ compression is enabled (see the 5855.Sq enable 5856command above). 5857It defaults to a value of 16. 5858.Ar Nslots 5859must be between 5860.Ar 4 5861and 5862.Ar 16 5863inclusive. 5864.El 5865.Pp 5866.It shell|! Op Ar command 5867If 5868.Ar command 5869is not specified a shell is invoked according to the 5870.Dv SHELL 5871environment variable. 5872Otherwise, the given 5873.Ar command 5874is executed. 5875Word replacement is done in the same way as for the 5876.Dq !bg 5877command as described above. 5878.Pp 5879Use of the !\& character 5880requires a following space as with any of the other commands. 5881You should note that this command is executed in the foreground; 5882.Nm 5883will not continue running until this process has exited. 5884Use the 5885.Dv bg 5886command if you wish processing to happen in the background. 5887.It show Ar var 5888This command allows the user to examine the following: 5889.Bl -tag -width 2n 5890.It show bundle 5891Show the current bundle settings. 5892.It show ccp 5893Show the current CCP compression statistics. 5894.It show compress 5895Show the current VJ compression statistics. 5896.It show escape 5897Show the current escape characters. 5898.It show filter Op Ar name 5899List the current rules for the given filter. 5900If 5901.Ar name 5902is not specified, all filters are shown. 5903.It show hdlc 5904Show the current HDLC statistics. 5905.It show help|? 5906Give a summary of available show commands. 5907.It show iface 5908Show the current interface information 5909(the same as 5910.Dq iface show ) . 5911.It show ipcp 5912Show the current IPCP statistics. 5913.It show layers 5914Show the protocol layers currently in use. 5915.It show lcp 5916Show the current LCP statistics. 5917.It show Op data Ns Xo 5918.No link 5919.Xc 5920Show high level link information. 5921.It show links 5922Show a list of available logical links. 5923.It show log 5924Show the current log values. 5925.It show mem 5926Show current memory statistics. 5927.It show ncp 5928Show the current NCP statistics. 5929.It show physical 5930Show low level link information. 5931.It show mp 5932Show Multi-link information. 5933.It show proto 5934Show current protocol totals. 5935.It show route 5936Show the current routing tables. 5937.It show stopped 5938Show the current stopped timeouts. 5939.It show timer 5940Show the active alarm timers. 5941.It show version 5942Show the current version number of 5943.Nm . 5944.El 5945.Pp 5946.It term 5947Go into terminal mode. 5948Characters typed at the keyboard are sent to the device. 5949Characters read from the device are displayed on the screen. 5950When a remote 5951.Em PPP 5952peer is detected, 5953.Nm 5954automatically enables Packet Mode and goes back into command mode. 5955.El 5956.Sh MORE DETAILS 5957.Bl -bullet 5958.It 5959Read the example configuration files. 5960They are a good source of information. 5961.It 5962Use 5963.Dq help , 5964.Dq nat \&? , 5965.Dq enable \&? , 5966.Dq set ?\& 5967and 5968.Dq show ?\& 5969to get online information about what's available. 5970.It 5971The following URLs contain useful information: 5972.Bl -bullet -compact 5973.It 5974http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/faq/ppp.html 5975.It 5976http://www.FreeBSD.org/doc/handbook/userppp.html 5977.El 5978.Pp 5979.El 5980.Sh FILES 5981.Nm 5982refers to four files: 5983.Pa ppp.conf , 5984.Pa ppp.linkup , 5985.Pa ppp.linkdown 5986and 5987.Pa ppp.secret . 5988These files are placed in the 5989.Pa /etc/ppp 5990directory. 5991.Bl -tag -width 2n 5992.It Pa /etc/ppp/ppp.conf 5993System default configuration file. 5994.It Pa /etc/ppp/ppp.secret 5995An authorisation file for each system. 5996.It Pa /etc/ppp/ppp.linkup 5997A file to check when 5998.Nm 5999establishes a network level connection. 6000.It Pa /etc/ppp/ppp.linkdown 6001A file to check when 6002.Nm 6003closes a network level connection. 6004.It Pa /var/log/ppp.log 6005Logging and debugging information file. 6006Note, this name is specified in 6007.Pa /etc/syslog.conf . 6008See 6009.Xr syslog.conf 5 6010for further details. 6011.It Pa /var/spool/lock/LCK..* 6012tty port locking file. 6013Refer to 6014.Xr uucplock 3 6015for further details. 6016.It Pa /var/run/tunN.pid 6017The process id (pid) of the 6018.Nm 6019program connected to the tunN device, where 6020.Sq N 6021is the number of the device. 6022.It Pa /var/run/ttyXX.if 6023The tun interface used by this port. 6024Again, this file is only created in 6025.Fl background , 6026.Fl auto 6027and 6028.Fl ddial 6029modes. 6030.It Pa /etc/services 6031Get port number if port number is using service name. 6032.It Pa /var/run/ppp-authname-class-value 6033In multi-link mode, local domain sockets are created using the peer 6034authentication name 6035.Pq Sq authname , 6036the peer endpoint discriminator class 6037.Pq Sq class 6038and the peer endpoint discriminator value 6039.Pq Sq value . 6040As the endpoint discriminator value may be a binary value, it is turned 6041to HEX to determine the actual file name. 6042.Pp 6043This socket is used to pass links between different instances of 6044.Nm . 6045.El 6046.Sh SEE ALSO 6047.Xr at 1 , 6048.Xr ftp 1 , 6049.Xr gzip 1 , 6050.Xr hostname 1 , 6051.Xr login 1 , 6052.Xr tcpdump 1 , 6053.Xr telnet 1 , 6054.Xr kldload 2 , 6055ifdef({LOCALNAT},{},{.Xr libalias 3 , 6056})dnl 6057ifdef({LOCALRAD},{},{.Xr libradius 3 , 6058})dnl 6059.Xr syslog 3 , 6060.Xr uucplock 3 , 6061.Xr netgraph 4 , 6062.Xr ng_pppoe 4 , 6063.Xr crontab 5 , 6064.Xr group 5 , 6065.Xr passwd 5 , 6066.Xr protocols 5 , 6067.Xr radius.conf 5 , 6068.Xr resolv.conf 5 , 6069.Xr syslog.conf 5 , 6070.Xr adduser 8 , 6071.Xr chat 8 , 6072.Xr getty 8 , 6073.Xr inetd 8 , 6074.Xr init 8 , 6075.Xr isdn 8 , 6076.Xr named 8 , 6077.Xr ping 8 , 6078.Xr pppctl 8 , 6079.Xr pppd 8 , 6080.Xr pppoed 8 , 6081.Xr route 8 , 6082.Xr sshd 8 , 6083.Xr syslogd 8 , 6084.Xr traceroute 8 , 6085.Xr vipw 8 6086.Sh HISTORY 6087This program was originally written by 6088.An Toshiharu OHNO Aq tony-o@iij.ad.jp , 6089and was submitted to 6090.Fx 2.0.5 6091by 6092.An Atsushi Murai Aq amurai@spec.co.jp . 6093.Pp 6094It was substantially modified during 1997 by 6095.An Brian Somers Aq brian@Awfulhak.org , 6096and was ported to 6097.Ox 6098in November that year 6099(just after the 2.2 release). 6100.Pp 6101Most of the code was rewritten by 6102.An Brian Somers 6103in early 1998 when multi-link ppp support was added. 6104