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