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