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