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