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