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