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 November 18, 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 use_sockets yes|no 3583When enabled, this option tells the network address translation engine to 3584create a socket so that it can guarantee a correct incoming ftp data or 3585IRC connection. 3586.It nat unregistered_only yes|no 3587Only alter outgoing packets with an unregistered source address. 3588According to RFC 1918, unregistered source addresses 3589are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16. 3590.El 3591.Pp 3592These commands are also discussed in the file 3593.Pa README.nat 3594which comes with the source distribution. 3595.It Oo !\& Oc Ns Xo 3596.No bg Ar command 3597.Xc 3598The given 3599.Ar command 3600is executed in the background with the following words replaced: 3601.Bl -tag -width COMPILATIONDATE 3602.It Li AUTHNAME 3603This is replaced with the local 3604.Ar authname 3605value. 3606See the 3607.Dq set authname 3608command below. 3609.It Li COMPILATIONDATE 3610In previous software revisions, this was replaced with the date on which 3611.Nm 3612was compiled. 3613This is no longer supported as it breaks the ability to recompile the same 3614code to produce an exact duplicate of a previous compilation. 3615.It Li DNS0 & DNS1 3616These are replaced with the primary and secondary nameserver IP numbers. 3617If nameservers are negotiated by IPCP, the values of these macros will change. 3618.It Li ENDDISC 3619This is replaced with the local endpoint discriminator value. 3620See the 3621.Dq set enddisc 3622command below. 3623.It Li HISADDR 3624This is replaced with the peers IP number. 3625.It Li HISADDR6 3626This is replaced with the peers IPv6 number. 3627.It Li INTERFACE 3628This is replaced with the name of the interface that is in use. 3629.It Li IPOCTETSIN 3630This is replaced with the number of IP bytes received since the connection 3631was established. 3632.It Li IPOCTETSOUT 3633This is replaced with the number of IP bytes sent since the connection 3634was established. 3635.It Li IPPACKETSIN 3636This is replaced with the number of IP packets received since the connection 3637was established. 3638.It Li IPPACKETSOUT 3639This is replaced with the number of IP packets sent since the connection 3640was established. 3641.It Li IPV6OCTETSIN 3642This is replaced with the number of IPv6 bytes received since the connection 3643was established. 3644.It Li IPV6OCTETSOUT 3645This is replaced with the number of IPv6 bytes sent since the connection 3646was established. 3647.It Li IPV6PACKETSIN 3648This is replaced with the number of IPv6 packets received since the connection 3649was established. 3650.It Li IPV6PACKETSOUT 3651This is replaced with the number of IPv6 packets sent since the connection 3652was established. 3653.It Li LABEL 3654This is replaced with the last label name used. 3655A label may be specified on the 3656.Nm 3657command line, via the 3658.Dq load 3659or 3660.Dq dial 3661commands and in the 3662.Pa ppp.secret 3663file. 3664.It Li MYADDR 3665This is replaced with the IP number assigned to the local interface. 3666.It Li MYADDR6 3667This is replaced with the IPv6 number assigned to the local interface. 3668.It Li OCTETSIN 3669This is replaced with the number of bytes received since the connection 3670was established. 3671.It Li OCTETSOUT 3672This is replaced with the number of bytes sent since the connection 3673was established. 3674.It Li PACKETSIN 3675This is replaced with the number of packets received since the connection 3676was established. 3677.It Li PACKETSOUT 3678This is replaced with the number of packets sent since the connection 3679was established. 3680.It Li PEER_ENDDISC 3681This is replaced with the value of the peers endpoint discriminator. 3682.It Li PROCESSID 3683This is replaced with the current process id. 3684.It Li SOCKNAME 3685This is replaced with the name of the diagnostic socket. 3686.It Li UPTIME 3687This is replaced with the bundle uptime in HH:MM:SS format. 3688.It Li USER 3689This is replaced with the username that has been authenticated with PAP or 3690CHAP. 3691Normally, this variable is assigned only in -direct mode. 3692This value is available irrespective of whether utmp logging is enabled. 3693.It Li VERSION 3694This is replaced with the current version number of 3695.Nm . 3696.El 3697.Pp 3698These substitutions are also done by the 3699.Dq set proctitle , 3700.Dq ident 3701and 3702.Dq log 3703commands. 3704.Pp 3705If you wish to pause 3706.Nm 3707while the command executes, use the 3708.Dq shell 3709command instead. 3710.It clear physical|ipcp|ipv6 Op current|overall|peak... 3711Clear the specified throughput values at either the 3712.Dq physical , 3713.Dq ipcp 3714or 3715.Dq ipv6cp 3716level. 3717If 3718.Dq physical 3719is specified, context must be given (see the 3720.Dq link 3721command below). 3722If no second argument is given, all values are cleared. 3723.It clone Ar name Ns Xo 3724.Op \&, Ns Ar name Ns 3725.No ... 3726.Xc 3727Clone the specified link, creating one or more new links according to the 3728.Ar name 3729argument(s). 3730This command must be used from the 3731.Dq link 3732command below unless you have only got a single link (in which case that 3733link becomes the default). 3734Links may be removed using the 3735.Dq remove 3736command below. 3737.Pp 3738The default link name is 3739.Dq deflink . 3740.It close Op lcp|ccp Ns Op !\& 3741If no arguments are given, the relevant protocol layers will be brought 3742down and the link will be closed. 3743If 3744.Dq lcp 3745is specified, the LCP layer is brought down, but 3746.Nm 3747will not bring the link offline. 3748It is subsequently possible to use 3749.Dq term 3750(see below) 3751to talk to the peer machine if, for example, something like 3752.Dq slirp 3753is being used. 3754If 3755.Dq ccp 3756is specified, only the relevant compression layer is closed. 3757If the 3758.Dq !\& 3759is used, the compression layer will remain in the closed state, otherwise 3760it will re-enter the STOPPED state, waiting for the peer to initiate 3761further CCP negotiation. 3762In any event, this command does not disconnect the user from 3763.Nm 3764or exit 3765.Nm . 3766See the 3767.Dq quit 3768command below. 3769.It delete Ns Xo 3770.Op !\& 3771.Ar dest 3772.Xc 3773This command deletes the route with the given 3774.Ar dest 3775IP address. 3776If 3777.Ar dest 3778is specified as 3779.Sq ALL , 3780all non-direct entries in the routing table for the current interface, 3781and all 3782.Sq sticky route 3783entries are deleted. 3784If 3785.Ar dest 3786is specified as 3787.Sq default , 3788the default route is deleted. 3789.Pp 3790If the 3791.Ar delete!\& 3792command is used 3793(note the trailing 3794.Dq !\& ) , 3795.Nm 3796will not complain if the route does not already exist. 3797.It dial|call Oo Ar label Oc Ns Xo 3798.No ... 3799.Xc 3800This command is the equivalent of 3801.Dq load label 3802followed by 3803.Dq open , 3804and is provided for backwards compatibility. 3805.It down Op Ar lcp|ccp 3806Bring the relevant layer down ungracefully, as if the underlying layer 3807had become unavailable. 3808It is not considered polite to use this command on 3809a Finite State Machine that is in the OPEN state. 3810If no arguments are 3811supplied, the entire link is closed (or if no context is given, all links 3812are terminated). 3813If 3814.Sq lcp 3815is specified, the 3816.Em LCP 3817layer is terminated but the device is not brought offline and the link 3818is not closed. 3819If 3820.Sq ccp 3821is specified, only the relevant compression layer(s) are terminated. 3822.It help|? Op Ar command 3823Show a list of available commands. 3824If 3825.Ar command 3826is specified, show the usage string for that command. 3827.It ident Op Ar text Ns No ... 3828Identify the link to the peer using 3829.Ar text . 3830If 3831.Ar text 3832is empty, link identification is disabled. 3833It is possible to use any of the words described for the 3834.Ic bg 3835command above. 3836Refer to the 3837.Ic sendident 3838command for details of when 3839.Nm 3840identifies itself to the peer. 3841.It iface Ar command Op args 3842This command is used to control the interface used by 3843.Nm . 3844.Ar Command 3845may be one of the following: 3846.Bl -tag -width 2n 3847.It iface add Ns Xo 3848.Op !\& 3849.Ar addr Ns Op / Ns Ar bits 3850.Op Ar peer 3851.Xc 3852.It iface add Ns Xo 3853.Op !\& 3854.Ar addr 3855.Ar mask 3856.Ar peer 3857.Xc 3858Add the given 3859.Ar addr mask peer 3860combination to the interface. 3861Instead of specifying 3862.Ar mask , 3863.Ar /bits 3864can be used 3865(with no space between it and 3866.Ar addr ) . 3867If the given address already exists, the command fails unless the 3868.Dq !\& 3869is used - in which case the previous interface address entry is overwritten 3870with the new one, allowing a change of netmask or peer address. 3871.Pp 3872If only 3873.Ar addr 3874is specified, 3875.Ar bits 3876defaults to 3877.Dq 32 3878and 3879.Ar peer 3880defaults to 3881.Dq 255.255.255.255 . 3882This address (the broadcast address) is the only duplicate peer address that 3883.Nm 3884allows. 3885.It iface clear Op INET | INET6 3886If this command is used while 3887.Nm 3888is in the OPENED state or while in 3889.Fl auto 3890mode, all addresses except for the NCP negotiated address are deleted 3891from the interface. 3892If 3893.Nm 3894is not in the OPENED state and is not in 3895.Fl auto 3896mode, all interface addresses are deleted. 3897.Pp 3898If the INET or INET6 arguments are used, only addresses for that address 3899family are cleared. 3900.It iface delete Ns Xo 3901.Op !\& Ns 3902.No |rm Ns Op !\& 3903.Ar addr 3904.Xc 3905This command deletes the given 3906.Ar addr 3907from the interface. 3908If the 3909.Dq !\& 3910is used, no error is given if the address is not currently assigned to 3911the interface (and no deletion takes place). 3912.It iface name Ar name 3913Renames the interface to 3914.Ar name . 3915.It iface description Ar description 3916Sets the interface description to 3917.Ar description . 3918Useful if you have many interfaces on your system. 3919.It iface show 3920Shows the current state and current addresses for the interface. 3921It is much the same as running 3922.Dq ifconfig INTERFACE . 3923.It iface help Op Ar sub-command 3924This command, when invoked without 3925.Ar sub-command , 3926will show a list of possible 3927.Dq iface 3928sub-commands and a brief synopsis for each. 3929When invoked with 3930.Ar sub-command , 3931only the synopsis for the given sub-command is shown. 3932.El 3933.It Oo data Oc Ns Xo 3934.No link 3935.Ar name Ns Oo , Ns Ar name Oc Ns ... Ar command Op Ar args 3936.Xc 3937This command may prefix any other command if the user wishes to 3938specify which link the command should affect. 3939This is only applicable after multiple links have been created in Multi-link 3940mode using the 3941.Dq clone 3942command. 3943.Pp 3944.Ar Name 3945specifies the name of an existing link. 3946If 3947.Ar name 3948is a comma separated list, 3949.Ar command 3950is executed on each link. 3951If 3952.Ar name 3953is 3954.Dq * , 3955.Ar command 3956is executed on all links. 3957.It load Oo Ar label Oc Ns Xo 3958.No ... 3959.Xc 3960Load the given 3961.Ar label Ns No (s) 3962from the 3963.Pa ppp.conf 3964file. 3965If 3966.Ar label 3967is not given, the 3968.Ar default 3969label is used. 3970.Pp 3971Unless the 3972.Ar label 3973section uses the 3974.Dq set mode , 3975.Dq open 3976or 3977.Dq dial 3978commands, 3979.Nm 3980will not attempt to make an immediate connection. 3981.It log Ar word Ns No ... 3982Send the given word(s) to the log file with the prefix 3983.Dq LOG: . 3984Word substitutions are done as explained under the 3985.Dq !bg 3986command above. 3987.It open Op lcp|ccp|ipcp 3988This is the opposite of the 3989.Dq close 3990command. 3991All closed links are immediately brought up apart from second and subsequent 3992.Ar demand-dial 3993links - these will come up based on the 3994.Dq set autoload 3995command that has been used. 3996.Pp 3997If the 3998.Dq lcp 3999argument is used while the LCP layer is already open, LCP will be 4000renegotiated. 4001This allows various LCP options to be changed, after which 4002.Dq open lcp 4003can be used to put them into effect. 4004After renegotiating LCP, 4005any agreed authentication will also take place. 4006.Pp 4007If the 4008.Dq ccp 4009argument is used, the relevant compression layer is opened. 4010Again, if it is already open, it will be renegotiated. 4011.Pp 4012If the 4013.Dq ipcp 4014argument is used, the link will be brought up as normal, but if 4015IPCP is already open, it will be renegotiated and the network 4016interface will be reconfigured. 4017.Pp 4018It is probably not good practice to re-open the PPP state machines 4019like this as it is possible that the peer will not behave correctly. 4020It 4021.Em is 4022however useful as a way of forcing the CCP or VJ dictionaries to be reset. 4023.It passwd Ar pass 4024Specify the password required for access to the full 4025.Nm 4026command set. 4027This password is required when connecting to the diagnostic port (see the 4028.Dq set server 4029command). 4030.Ar Pass 4031is specified on the 4032.Dq set server 4033command line. 4034The value of 4035.Ar pass 4036is not logged when 4037.Ar command 4038logging is active, instead, the literal string 4039.Sq ******** 4040is logged. 4041.It quit|bye Op all 4042If 4043.Dq quit 4044is executed from the controlling connection or from a command file, 4045ppp will exit after closing all connections. 4046Otherwise, if the user 4047is connected to a diagnostic socket, the connection is simply dropped. 4048.Pp 4049If the 4050.Ar all 4051argument is given, 4052.Nm 4053will exit despite the source of the command after closing all existing 4054connections. 4055.It remove|rm 4056This command removes the given link. 4057It is only really useful in multi-link mode. 4058A link must be in the 4059.Dv CLOSED 4060state before it is removed. 4061.It rename|mv Ar name 4062This command renames the given link to 4063.Ar name . 4064It will fail if 4065.Ar name 4066is already used by another link. 4067.Pp 4068The default link name is 4069.Sq deflink . 4070Renaming it to 4071.Sq modem , 4072.Sq cuau0 4073or 4074.Sq USR 4075may make the log file more readable. 4076.It resolv Ar command 4077This command controls 4078.Nm Ns No 's 4079manipulation of the 4080.Xr resolv.conf 5 4081file. 4082When 4083.Nm 4084starts up, it loads the contents of this file into memory and retains this 4085image for future use. 4086.Ar command 4087is one of the following: 4088.Bl -tag -width readonly 4089.It Em readonly 4090Treat 4091.Pa /etc/resolv.conf 4092as read only. 4093If 4094.Dq dns 4095is enabled, 4096.Nm 4097will still attempt to negotiate nameservers with the peer, making the results 4098available via the 4099.Dv DNS0 4100and 4101.Dv DNS1 4102macros. 4103This is the opposite of the 4104.Dq resolv writable 4105command. 4106.It Em reload 4107Reload 4108.Pa /etc/resolv.conf 4109into memory. 4110This may be necessary if for example a DHCP client overwrote 4111.Pa /etc/resolv.conf . 4112.It Em restore 4113Replace 4114.Pa /etc/resolv.conf 4115with the version originally read at startup or with the last 4116.Dq resolv reload 4117command. 4118This is sometimes a useful command to put in the 4119.Pa /etc/ppp/ppp.linkdown 4120file. 4121.It Em rewrite 4122Rewrite the 4123.Pa /etc/resolv.conf 4124file. 4125This command will work even if the 4126.Dq resolv readonly 4127command has been used. 4128It may be useful as a command in the 4129.Pa /etc/ppp/ppp.linkup 4130file if you wish to defer updating 4131.Pa /etc/resolv.conf 4132until after other commands have finished. 4133.It Em writable 4134Allow 4135.Nm 4136to update 4137.Pa /etc/resolv.conf 4138if 4139.Dq dns 4140is enabled and 4141.Nm 4142successfully negotiates a DNS. 4143This is the opposite of the 4144.Dq resolv readonly 4145command. 4146.El 4147.It save 4148This option is not (yet) implemented. 4149.It sendident 4150This command tells 4151.Nm 4152to identify itself to the peer. 4153The link must be in LCP state or higher. 4154If no identity has been set (via the 4155.Ic ident 4156command), 4157.Ic sendident 4158will fail. 4159.Pp 4160When an identity has been set, 4161.Nm 4162will automatically identify itself when it sends or receives a configure 4163reject, when negotiation fails or when LCP reaches the opened state. 4164.Pp 4165Received identification packets are logged to the LCP log (see 4166.Ic set log 4167for details) and are never responded to. 4168.It set Ns Xo 4169.Op up 4170.Ar var value 4171.Xc 4172This option allows the setting of any of the following variables: 4173.Bl -tag -width 2n 4174.It set accmap Ar hex-value 4175ACCMap stands for Asynchronous Control Character Map. 4176This is always 4177negotiated with the peer, and defaults to a value of 00000000 in hex. 4178This protocol is required to defeat hardware that depends on passing 4179certain characters from end to end (such as XON/XOFF etc). 4180.Pp 4181For the XON/XOFF scenario, use 4182.Dq set accmap 000a0000 . 4183.It set Oo auth Oc Ns Xo 4184.No key Ar value 4185.Xc 4186This sets the authentication key (or password) used in client mode 4187PAP or CHAP negotiation to the given value. 4188It also specifies the 4189password to be used in the dial or login scripts in place of the 4190.Sq \eP 4191sequence, preventing the actual password from being logged. 4192If 4193.Ar command 4194or 4195.Ar chat 4196logging is in effect, 4197.Ar value 4198is logged as 4199.Sq ******** 4200for security reasons. 4201.Pp 4202If the first character of 4203.Ar value 4204is an exclamation mark 4205.Pq Dq !\& , 4206.Nm 4207treats the remainder of the string as a program that must be executed 4208to determine the 4209.Dq authname 4210and 4211.Dq authkey 4212values. 4213.Pp 4214If the 4215.Dq !\& 4216is doubled up 4217(to 4218.Dq !! ) , 4219it is treated as a single literal 4220.Dq !\& , 4221otherwise, ignoring the 4222.Dq !\& , 4223.Ar value 4224is parsed as a program to execute in the same was as the 4225.Dq !bg 4226command above, substituting special names in the same manner. 4227Once executed, 4228.Nm 4229will feed the program three lines of input, each terminated by a newline 4230character: 4231.Bl -bullet 4232.It 4233The host name as sent in the CHAP challenge. 4234.It 4235The challenge string as sent in the CHAP challenge. 4236.It 4237The locally defined 4238.Dq authname . 4239.El 4240.Pp 4241Two lines of output are expected: 4242.Bl -bullet 4243.It 4244The 4245.Dq authname 4246to be sent with the CHAP response. 4247.It 4248The 4249.Dq authkey , 4250which is encrypted with the challenge and request id, the answer being sent 4251in the CHAP response packet. 4252.El 4253.Pp 4254When configuring 4255.Nm 4256in this manner, it is expected that the host challenge is a series of ASCII 4257digits or characters. 4258An encryption device or Secure ID card is usually 4259required to calculate the secret appropriate for the given challenge. 4260.It set authname Ar id 4261This sets the authentication id used in client mode PAP or CHAP negotiation. 4262.Pp 4263If used in 4264.Fl direct 4265mode with CHAP enabled, 4266.Ar id 4267is used in the initial authentication challenge and should normally be set to 4268the local machine name. 4269.It set autoload Xo 4270.Ar min-percent max-percent period 4271.Xc 4272These settings apply only in multi-link mode and default to zero, zero and 4273five respectively. 4274When more than one 4275.Ar demand-dial 4276(also known as 4277.Fl auto ) 4278mode link is available, only the first link is made active when 4279.Nm 4280first reads data from the tun device. 4281The next 4282.Ar demand-dial 4283link will be opened only when the current bundle throughput is at least 4284.Ar max-percent 4285percent of the total bundle bandwidth for 4286.Ar period 4287seconds. 4288When the current bundle throughput decreases to 4289.Ar min-percent 4290percent or less of the total bundle bandwidth for 4291.Ar period 4292seconds, a 4293.Ar demand-dial 4294link will be brought down as long as it is not the last active link. 4295.Pp 4296Bundle throughput is measured as the maximum of inbound and outbound 4297traffic. 4298.Pp 4299The default values cause 4300.Ar demand-dial 4301links to simply come up one at a time. 4302.Pp 4303Certain devices cannot determine their physical bandwidth, so it 4304is sometimes necessary to use the 4305.Dq set bandwidth 4306command (described below) to make 4307.Dq set autoload 4308work correctly. 4309.It set bandwidth Ar value 4310This command sets the connection bandwidth in bits per second. 4311.Ar value 4312must be greater than zero. 4313It is currently only used by the 4314.Dq set autoload 4315command above. 4316.It set callback Ar option Ns No ... 4317If no arguments are given, callback is disabled, otherwise, 4318.Nm 4319will request (or in 4320.Fl direct 4321mode, will accept) one of the given 4322.Ar option Ns No s . 4323In client mode, if an 4324.Ar option 4325is NAK'd 4326.Nm 4327will request a different 4328.Ar option , 4329until no options remain at which point 4330.Nm 4331will terminate negotiations (unless 4332.Dq none 4333is one of the specified 4334.Ar option ) . 4335In server mode, 4336.Nm 4337will accept any of the given protocols - but the client 4338.Em must 4339request one of them. 4340If you wish callback to be optional, you must {include} 4341.Ar none 4342as an option. 4343.Pp 4344The 4345.Ar option Ns No s 4346are as follows (in this order of preference): 4347.Bl -tag -width Ds 4348.It auth 4349The callee is expected to decide the callback number based on 4350authentication. 4351If 4352.Nm 4353is the callee, the number should be specified as the fifth field of 4354the peers entry in 4355.Pa /etc/ppp/ppp.secret . 4356.It cbcp 4357Microsoft's callback control protocol is used. 4358See 4359.Dq set cbcp 4360below. 4361.Pp 4362If you wish to negotiate 4363.Ar cbcp 4364in client mode but also wish to allow the server to request no callback at 4365CBCP negotiation time, you must specify both 4366.Ar cbcp 4367and 4368.Ar none 4369as callback options. 4370.It E.164 *| Ns Xo 4371.Ar number Ns Op , Ns Ar number Ns 4372.No ... 4373.Xc 4374The caller specifies the 4375.Ar number . 4376If 4377.Nm 4378is the callee, 4379.Ar number 4380should be either a comma separated list of allowable numbers or a 4381.Dq \&* , 4382meaning any number is permitted. 4383If 4384.Nm 4385is the caller, only a single number should be specified. 4386.Pp 4387Note, this option is very unsafe when used with a 4388.Dq \&* 4389as a malicious caller can tell 4390.Nm 4391to call any (possibly international) number without first authenticating 4392themselves. 4393.It none 4394If the peer does not wish to do callback at all, 4395.Nm 4396will accept the fact and continue without callback rather than terminating 4397the connection. 4398This is required (in addition to one or more other callback 4399options) if you wish callback to be optional. 4400.El 4401.It set cbcp Oo 4402.No *| Ns Ar number Ns 4403.Oo , Ns Ar number Ns ...\& Oc 4404.Op Ar delay Op Ar retry 4405.Oc 4406If no arguments are given, CBCP (Microsoft's CallBack Control Protocol) 4407is disabled - ie, configuring CBCP in the 4408.Dq set callback 4409command will result in 4410.Nm 4411requesting no callback in the CBCP phase. 4412Otherwise, 4413.Nm 4414attempts to use the given phone 4415.Ar number Ns No (s) . 4416.Pp 4417In server mode 4418.Pq Fl direct , 4419.Nm 4420will insist that the client uses one of these numbers, unless 4421.Dq \&* 4422is used in which case the client is expected to specify the number. 4423.Pp 4424In client mode, 4425.Nm 4426will attempt to use one of the given numbers (whichever it finds to 4427be agreeable with the peer), or if 4428.Dq \&* 4429is specified, 4430.Nm 4431will expect the peer to specify the number. 4432.It set cd Oo 4433.No off\&| Ns Ar seconds Ns Op !\& 4434.Oc 4435Normally, 4436.Nm 4437checks for the existence of carrier depending on the type of device 4438that has been opened: 4439.Bl -tag -width XXX -offset XXX 4440.It Terminal Devices 4441Carrier is checked one second after the login script is complete. 4442If it is not set, 4443.Nm 4444assumes that this is because the device does not support carrier (which 4445is true for most 4446.Dq laplink 4447NULL-modem cables), logs the fact and stops checking 4448for carrier. 4449.Pp 4450As ptys do not support the TIOCMGET ioctl, the tty device will switch all 4451carrier detection off when it detects that the device is a pty. 4452.It PPPoE (netgraph) Devices 4453Carrier is checked once per second for 5 seconds. 4454If it is not set after 4455the fifth second, the connection attempt is considered to have failed and 4456the device is closed. 4457Carrier is always required for PPPoE devices. 4458.El 4459.Pp 4460All other device types do not support carrier. 4461Setting a carrier value will 4462result in a warning when the device is opened. 4463.Pp 4464Some modems take more than one second after connecting to assert the carrier 4465signal. 4466If this delay is not increased, this will result in 4467.Nm Ns No 's 4468inability to detect when the link is dropped, as 4469.Nm 4470assumes that the device is not asserting carrier. 4471.Pp 4472The 4473.Dq set cd 4474command overrides the default carrier behaviour. 4475.Ar seconds 4476specifies the maximum number of seconds that 4477.Nm 4478should wait after the dial script has finished before deciding if 4479carrier is available or not. 4480.Pp 4481If 4482.Dq off 4483is specified, 4484.Nm 4485will not check for carrier on the device, otherwise 4486.Nm 4487will not proceed to the login script until either carrier is detected 4488or until 4489.Ar seconds 4490has elapsed, at which point 4491.Nm 4492assumes that the device will not set carrier. 4493.Pp 4494If no arguments are given, carrier settings will go back to their default 4495values. 4496.Pp 4497If 4498.Ar seconds 4499is followed immediately by an exclamation mark 4500.Pq Dq !\& , 4501.Nm 4502will 4503.Em require 4504carrier. 4505If carrier is not detected after 4506.Ar seconds 4507seconds, the link will be disconnected. 4508.It set choked Op Ar timeout 4509This sets the number of seconds that 4510.Nm 4511will keep a choked output queue before dropping all pending output packets. 4512If 4513.Ar timeout 4514is less than or equal to zero or if 4515.Ar timeout 4516is not specified, it is set to the default value of 4517.Em 120 seconds . 4518.Pp 4519A choked output queue occurs when 4520.Nm 4521has read a certain number of packets from the local network for transmission, 4522but cannot send the data due to link failure (the peer is busy etc.). 4523.Nm 4524will not read packets indefinitely. 4525Instead, it reads up to 4526.Em 30 4527packets (or 4528.Em 30 No + 4529.Em nlinks No * 4530.Em 2 4531packets in multi-link mode), then stops reading the network interface 4532until either 4533.Ar timeout 4534seconds have passed or at least one packet has been sent. 4535.Pp 4536If 4537.Ar timeout 4538seconds pass, all pending output packets are dropped. 4539.It set ctsrts|crtscts on|off 4540This sets hardware flow control. 4541Hardware flow control is 4542.Ar on 4543by default. 4544.It set deflate Ar out-winsize Op Ar in-winsize 4545This sets the DEFLATE algorithms default outgoing and incoming window 4546sizes. 4547Both 4548.Ar out-winsize 4549and 4550.Ar in-winsize 4551must be values between 4552.Em 8 4553and 4554.Em 15 . 4555If 4556.Ar in-winsize 4557is specified, 4558.Nm 4559will insist that this window size is used and will not accept any other 4560values from the peer. 4561.It set dns Op Ar primary Op Ar secondary 4562This command specifies DNS overrides for the 4563.Dq accept dns 4564command. 4565Refer to the 4566.Dq accept 4567command description above for details. 4568This command does not affect the IP numbers requested using 4569.Dq enable dns . 4570.It set device|line Xo 4571.Ar value Ns No ... 4572.Xc 4573This sets the device(s) to which 4574.Nm 4575will talk to the given 4576.Dq value . 4577.Pp 4578All serial device names are expected to begin with 4579.Pa /dev/ . 4580Serial devices are usually called 4581.Pa cuaXX . 4582.Pp 4583If 4584.Dq value 4585does not begin with 4586.Pa /dev/ , 4587it must either begin with an exclamation mark 4588.Pq Dq !\& , 4589be of the format 4590.No PPPoE\&: Ns Ar iface Ns Xo 4591.Op \&: Ns Ar provider Ns 4592.Xc 4593(on 4594.Xr netgraph 4 4595enabled systems), or be of the format 4596.Sm off 4597.Ar host : port Op /tcp|udp . 4598.Sm on 4599.Pp 4600If it begins with an exclamation mark, the rest of the device name is 4601treated as a program name, and that program is executed when the device 4602is opened. 4603Standard input, output and error are fed back to 4604.Nm 4605and are read and written as if they were a regular device. 4606.Pp 4607If a 4608.No PPPoE\&: Ns Ar iface Ns Xo 4609.Op \&: Ns Ar provider Ns 4610.Xc 4611specification is given, 4612.Nm 4613will attempt to create a 4614.Em PPP 4615over Ethernet connection using the given 4616.Ar iface 4617interface by using 4618.Xr netgraph 4 . 4619If 4620.Xr netgraph 4 4621is not available, 4622.Nm 4623will attempt to load it using 4624.Xr kldload 2 . 4625If this fails, an external program must be used such as the 4626.Xr pppoed 8 4627program available under 4628.Ox . 4629The given 4630.Ar provider 4631is passed as the service name in the PPPoE Discovery Initiation (PADI) 4632packet. 4633If no provider is given, an empty value will be used. 4634.Pp 4635When a PPPoE connection is established, 4636.Nm 4637will place the name of the Access Concentrator in the environment variable 4638.Ev ACNAME . 4639.Pp 4640Refer to 4641.Xr netgraph 4 4642and 4643.Xr ng_pppoe 4 4644for further details. 4645.Pp 4646If a 4647.Ar host : Ns Ar port Ns Oo 4648.No /tcp|udp 4649.Oc 4650specification is given, 4651.Nm 4652will attempt to connect to the given 4653.Ar host 4654on the given 4655.Ar port . 4656If a 4657.Dq /tcp 4658or 4659.Dq /udp 4660suffix is not provided, the default is 4661.Dq /tcp . 4662Refer to the section on 4663.Em PPP OVER TCP and UDP 4664above for further details. 4665.Pp 4666If multiple 4667.Dq values 4668are specified, 4669.Nm 4670will attempt to open each one in turn until it succeeds or runs out of 4671devices. 4672.It set dial Ar chat-script 4673This specifies the chat script that will be used to dial the other 4674side. 4675See also the 4676.Dq set login 4677command below. 4678Refer to 4679.Xr chat 8 4680and to the example configuration files for details of the chat script 4681format. 4682It is possible to specify some special 4683.Sq values 4684in your chat script as follows: 4685.Bl -tag -width 2n 4686.It Li \ec 4687When used as the last character in a 4688.Sq send 4689string, this indicates that a newline should not be appended. 4690.It Li \ed 4691When the chat script encounters this sequence, it delays two seconds. 4692.It Li \ep 4693When the chat script encounters this sequence, it delays for one quarter of 4694a second. 4695.It Li \en 4696This is replaced with a newline character. 4697.It Li \er 4698This is replaced with a carriage return character. 4699.It Li \es 4700This is replaced with a space character. 4701.It Li \et 4702This is replaced with a tab character. 4703.It Li \eT 4704This is replaced by the current phone number (see 4705.Dq set phone 4706below). 4707.It Li \eP 4708This is replaced by the current 4709.Ar authkey 4710value (see 4711.Dq set authkey 4712above). 4713.It Li \eU 4714This is replaced by the current 4715.Ar authname 4716value (see 4717.Dq set authname 4718above). 4719.El 4720.Pp 4721Note that two parsers will examine these escape sequences, so in order to 4722have the 4723.Sq chat parser 4724see the escape character, it is necessary to escape it from the 4725.Sq command parser . 4726This means that in practice you should use two escapes, for example: 4727.Bd -literal -offset indent 4728set dial "... ATDT\\\\T CONNECT" 4729.Ed 4730.Pp 4731It is also possible to execute external commands from the chat script. 4732To do this, the first character of the expect or send string is an 4733exclamation mark 4734.Pq Dq !\& . 4735If a literal exclamation mark is required, double it up to 4736.Dq !!\& 4737and it will be treated as a single literal 4738.Dq !\& . 4739When the command is executed, standard input and standard output are 4740directed to the open device (see the 4741.Dq set device 4742command), and standard error is read by 4743.Nm 4744and substituted as the expect or send string. 4745If 4746.Nm 4747is running in interactive mode, file descriptor 3 is attached to 4748.Pa /dev/tty . 4749.Pp 4750For example (wrapped for readability): 4751.Bd -literal -offset indent 4752set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e 4753word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e 4754\\"!/bin/echo in\\" HELLO" 4755.Ed 4756.Pp 4757would result in the following chat sequence (output using the 4758.Sq set log local chat 4759command before dialing): 4760.Bd -literal -offset indent 4761Dial attempt 1 of 1 4762dial OK! 4763Chat: Expecting: 4764Chat: Sending: 4765Chat: Expecting: login:--login: 4766Chat: Wait for (5): login: 4767Chat: Sending: ppp 4768Chat: Expecting: word: 4769Chat: Wait for (5): word: 4770Chat: Sending: ppp 4771Chat: Expecting: !sh \\-c "echo \\-n label: >&2" 4772Chat: Exec: sh -c "echo -n label: >&2" 4773Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label: 4774Chat: Exec: /bin/echo in 4775Chat: Sending: 4776Chat: Expecting: HELLO 4777Chat: Wait for (5): HELLO 4778login OK! 4779.Ed 4780.Pp 4781Note (again) the use of the escape character, allowing many levels of 4782nesting. 4783Here, there are four parsers at work. 4784The first parses the original line, reading it as three arguments. 4785The second parses the third argument, reading it as 11 arguments. 4786At this point, it is 4787important that the 4788.Dq \&- 4789signs are escaped, otherwise this parser will see them as constituting 4790an expect-send-expect sequence. 4791When the 4792.Dq !\& 4793character is seen, the execution parser reads the first command as three 4794arguments, and then 4795.Xr sh 1 4796itself expands the argument after the 4797.Fl c . 4798As we wish to send the output back to the modem, in the first example 4799we redirect our output to file descriptor 2 (stderr) so that 4800.Nm 4801itself sends and logs it, and in the second example, we just output to stdout, 4802which is attached directly to the modem. 4803.Pp 4804This, of course means that it is possible to execute an entirely external 4805.Dq chat 4806command rather than using the internal one. 4807See 4808.Xr chat 8 4809for a good alternative. 4810.Pp 4811The external command that is executed is subjected to the same special 4812word expansions as the 4813.Dq !bg 4814command. 4815.It set enddisc Op label|IP|MAC|magic|psn value 4816This command sets our local endpoint discriminator. 4817If set prior to LCP negotiation, and if no 4818.Dq disable enddisc 4819command has been used, 4820.Nm 4821will send the information to the peer using the LCP endpoint discriminator 4822option. 4823The following discriminators may be set: 4824.Bl -tag -width indent 4825.It Li label 4826The current label is used. 4827.It Li IP 4828Our local IP number is used. 4829As LCP is negotiated prior to IPCP, it is 4830possible that the IPCP layer will subsequently change this value. 4831If 4832it does, the endpoint discriminator stays at the old value unless manually 4833reset. 4834.It Li MAC 4835This is similar to the 4836.Ar IP 4837option above, except that the MAC address associated with the local IP 4838number is used. 4839If the local IP number is not resident on any Ethernet 4840interface, the command will fail. 4841.Pp 4842As the local IP number defaults to whatever the machine host name is, 4843.Dq set enddisc mac 4844is usually done prior to any 4845.Dq set ifaddr 4846commands. 4847.It Li magic 4848A 20 digit random number is used. 4849Care should be taken when using magic numbers as restarting 4850.Nm 4851or creating a link using a different 4852.Nm 4853invocation will also use a different magic number and will therefore not 4854be recognised by the peer as belonging to the same bundle. 4855This makes it unsuitable for 4856.Fl direct 4857connections. 4858.It Li psn Ar value 4859The given 4860.Ar value 4861is used. 4862.Ar Value 4863should be set to an absolute public switched network number with the 4864country code first. 4865.El 4866.Pp 4867If no arguments are given, the endpoint discriminator is reset. 4868.It set escape Ar value... 4869This option is similar to the 4870.Dq set accmap 4871option above. 4872It allows the user to specify a set of characters that will be 4873.Sq escaped 4874as they travel across the link. 4875.It set filter dial|alive|in|out Ar rule-no Xo 4876.No permit|deny|clear\&| Ns Ar rule-no 4877.Op !\& 4878.Oo Op host 4879.Ar src_addr Ns Op / Ns Ar width 4880.Op Ar dst_addr Ns Op / Ns Ar width 4881.Oc [ Ns Ar proto 4882.Op src lt|eq|gt Ar port 4883.Op dst lt|eq|gt Ar port 4884.Op estab 4885.Op syn 4886.Op finrst 4887.Op timeout Ar secs ] 4888.Xc 4889.Nm 4890supports four filter sets. 4891The 4892.Em alive 4893filter specifies packets that keep the connection alive - resetting the 4894idle timer. 4895The 4896.Em dial 4897filter specifies packets that cause 4898.Nm 4899to dial when in 4900.Fl auto 4901mode. 4902The 4903.Em in 4904filter specifies packets that are allowed to travel 4905into the machine and the 4906.Em out 4907filter specifies packets that are allowed out of the machine. 4908.Pp 4909Filtering is done prior to any IP alterations that might be done by the 4910NAT engine on outgoing packets and after any IP alterations that might 4911be done by the NAT engine on incoming packets. 4912By default all empty filter sets allow all packets to pass. 4913Rules are processed in order according to 4914.Ar rule-no 4915(unless skipped by specifying a rule number as the 4916.Ar action ) . 4917Up to 40 rules may be given for each set. 4918If a packet does not match 4919any of the rules in a given set, it is discarded. 4920In the case of 4921.Em in 4922and 4923.Em out 4924filters, this means that the packet is dropped. 4925In the case of 4926.Em alive 4927filters it means that the packet will not reset the idle timer (even if 4928the 4929.Ar in Ns No / Ns Ar out 4930filter has a 4931.Dq timeout 4932value) and in the case of 4933.Em dial 4934filters it means that the packet will not trigger a dial. 4935A packet failing to trigger a dial will be dropped rather than queued. 4936Refer to the 4937section on 4938.Sx PACKET FILTERING 4939above for further details. 4940.It set hangup Ar chat-script 4941This specifies the chat script that will be used to reset the device 4942before it is closed. 4943It should not normally be necessary, but can 4944be used for devices that fail to reset themselves properly on close. 4945.It set help|? Op Ar command 4946This command gives a summary of available set commands, or if 4947.Ar command 4948is specified, the command usage is shown. 4949.It set ifaddr Oo Ar myaddr Ns 4950.Op / Ns Ar \&nn 4951.Oo Ar hisaddr Ns Op / Ns Ar \&nn 4952.Oo Ar netmask 4953.Op Ar triggeraddr 4954.Oc Oc 4955.Oc 4956This command specifies the IP addresses that will be used during 4957IPCP negotiation. 4958Addresses are specified using the format 4959.Pp 4960.Dl a.b.c.d/nn 4961.Pp 4962Where 4963.Dq a.b.c.d 4964is the preferred IP, but 4965.Ar nn 4966specifies how many bits of the address we will insist on. 4967If 4968.No / Ns Ar nn 4969is omitted, it defaults to 4970.Dq /32 4971unless the IP address is 0.0.0.0 in which case it defaults to 4972.Dq /0 . 4973.Pp 4974If you wish to assign a dynamic IP number to the peer, 4975.Ar hisaddr 4976may also be specified as a range of IP numbers in the format 4977.Bd -ragged -offset indent 4978.Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Oc Ns Oo , Ns Ar \&IP Ns 4979.Oo \&- Ns Ar \&IP Ns Oc Oc Ns ... 4980.Ed 4981.Pp 4982for example: 4983.Pp 4984.Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20 4985.Pp 4986will only negotiate 4987.Dq 10.0.0.1 4988as the local IP number, but may assign any of the given 10 IP 4989numbers to the peer. 4990If the peer requests one of these numbers, 4991and that number is not already in use, 4992.Nm 4993will grant the peers request. 4994This is useful if the peer wants 4995to re-establish a link using the same IP number as was previously 4996allocated (thus maintaining any existing tcp or udp connections). 4997.Pp 4998If the peer requests an IP number that is either outside 4999of this range or is already in use, 5000.Nm 5001will suggest a random unused IP number from the range. 5002.Pp 5003If 5004.Ar triggeraddr 5005is specified, it is used in place of 5006.Ar myaddr 5007in the initial IPCP negotiation. 5008However, only an address in the 5009.Ar myaddr 5010range will be accepted. 5011This is useful when negotiating with some 5012.Dv PPP 5013implementations that will not assign an IP number unless their peer 5014requests 5015.Dq 0.0.0.0 . 5016.Pp 5017It should be noted that in 5018.Fl auto 5019mode, 5020.Nm 5021will configure the interface immediately upon reading the 5022.Dq set ifaddr 5023line in the config file. 5024In any other mode, these values are just 5025used for IPCP negotiations, and the interface is not configured 5026until the IPCP layer is up. 5027.Pp 5028Note that the 5029.Ar HISADDR 5030argument may be overridden by the third field in the 5031.Pa ppp.secret 5032file once the client has authenticated itself 5033(if PAP or CHAP are 5034.Dq enabled ) . 5035Refer to the 5036.Sx AUTHENTICATING INCOMING CONNECTIONS 5037section for details. 5038.Pp 5039In all cases, if the interface is already configured, 5040.Nm 5041will try to maintain the interface IP numbers so that any existing 5042bound sockets will remain valid. 5043.It set ifqueue Ar packets 5044Set the maximum number of packets that 5045.Nm 5046will read from the tunnel interface while data cannot be sent to any of 5047the available links. 5048This queue limit is necessary to flow control outgoing data as the tunnel 5049interface is likely to be far faster than the combined links available to 5050.Nm . 5051.Pp 5052If 5053.Ar packets 5054is set to a value less than the number of links, 5055.Nm 5056will read up to that value regardless. 5057This prevents any possible latency problems. 5058.Pp 5059The default value for 5060.Ar packets 5061is 5062.Dq 30 . 5063.It set ccpretry|ccpretries Oo Ar timeout 5064.Op Ar reqtries Op Ar trmtries 5065.Oc 5066.It set chapretry|chapretries Oo Ar timeout 5067.Op Ar reqtries 5068.Oc 5069.It set ipcpretry|ipcpretries Oo Ar timeout 5070.Op Ar reqtries Op Ar trmtries 5071.Oc 5072.It set ipv6cpretry|ipv6cpretries Oo Ar timeout 5073.Op Ar reqtries Op Ar trmtries 5074.Oc 5075.It set lcpretry|lcpretries Oo Ar timeout 5076.Op Ar reqtries Op Ar trmtries 5077.Oc 5078.It set papretry|papretries Oo Ar timeout 5079.Op Ar reqtries 5080.Oc 5081These commands set the number of seconds that 5082.Nm 5083will wait before resending Finite State Machine (FSM) Request packets. 5084The default 5085.Ar timeout 5086for all FSMs is 3 seconds (which should suffice in most cases). 5087.Pp 5088If 5089.Ar reqtries 5090is specified, it tells 5091.Nm 5092how many configuration request attempts it should make while receiving 5093no reply from the peer before giving up. 5094The default is 5 attempts for 5095CCP, LCP and IPCP and 3 attempts for PAP and CHAP. 5096.Pp 5097If 5098.Ar trmtries 5099is specified, it tells 5100.Nm 5101how many terminate requests should be sent before giving up waiting for the 5102peers response. 5103The default is 3 attempts. 5104Authentication protocols are 5105not terminated and it is therefore invalid to specify 5106.Ar trmtries 5107for PAP or CHAP. 5108.Pp 5109In order to avoid negotiations with the peer that will never converge, 5110.Nm 5111will only send at most 3 times the configured number of 5112.Ar reqtries 5113in any given negotiation session before giving up and closing that layer. 5114.It set log Xo 5115.Op local 5116.Op +|- Ns 5117.Ar value Ns No ... 5118.Xc 5119This command allows the adjustment of the current log level. 5120Refer to the Logging Facility section for further details. 5121.It set login Ar chat-script 5122This 5123.Ar chat-script 5124compliments the dial-script. 5125If both are specified, the login 5126script will be executed after the dial script. 5127Escape sequences available in the dial script are also available here. 5128.It set logout Ar chat-script 5129This specifies the chat script that will be used to logout 5130before the hangup script is called. 5131It should not normally be necessary. 5132.It set lqrperiod|echoperiod Ar frequency 5133This command sets the 5134.Ar frequency 5135in seconds at which 5136.Em LQR 5137or 5138.Em LCP ECHO 5139packets are sent. 5140The default is 30 seconds. 5141You must also use the 5142.Dq enable lqr 5143and/or 5144.Dq enable echo 5145commands if you wish to send 5146.Em LQR 5147or 5148.Em LCP ECHO 5149requests to the peer. 5150.It set mode Ar interactive|auto|ddial|background 5151This command allows you to change the 5152.Sq mode 5153of the specified link. 5154This is normally only useful in multi-link mode, 5155but may also be used in uni-link mode. 5156.Pp 5157It is not possible to change a link that is 5158.Sq direct 5159or 5160.Sq dedicated . 5161.Pp 5162Note: If you issue the command 5163.Dq set mode auto , 5164and have network address translation enabled, it may be useful to 5165.Dq enable iface-alias 5166afterwards. 5167This will allow 5168.Nm 5169to do the necessary address translations to enable the process that 5170triggers the connection to connect once the link is up despite the 5171peer assigning us a new (dynamic) IP address. 5172.It set mppe Op 40|56|128|* Op stateless|stateful|* 5173This option selects the encryption parameters used when negotiation 5174MPPE. 5175MPPE can be disabled entirely with the 5176.Dq disable mppe 5177command. 5178If no arguments are given, 5179.Nm 5180will attempt to negotiate a stateful link with a 128 bit key, but 5181will agree to whatever the peer requests (including no encryption 5182at all). 5183.Pp 5184If any arguments are given, 5185.Nm 5186will 5187.Em insist 5188on using MPPE and will close the link if it is rejected by the peer (Note; 5189this behaviour can be overridden by a configured RADIUS server). 5190.Pp 5191The first argument specifies the number of bits that 5192.Nm 5193should insist on during negotiations and the second specifies whether 5194.Nm 5195should insist on stateful or stateless mode. 5196In stateless mode, the 5197encryption dictionary is re-initialised with every packet according to 5198an encryption key that is changed with every packet. 5199In stateful mode, 5200the encryption dictionary is re-initialised every 256 packets or after 5201the loss of any data and the key is changed every 256 packets. 5202Stateless mode is less efficient but is better for unreliable transport 5203layers. 5204.It set mrru Op Ar value 5205Setting this option enables Multi-link PPP negotiations, also known as 5206Multi-link Protocol or MP. 5207There is no default MRRU (Maximum Reconstructed Receive Unit) value. 5208If no argument is given, multi-link mode is disabled. 5209.It set mru Xo 5210.Op max Ns Op imum 5211.Op Ar value 5212.Xc 5213The default MRU (Maximum Receive Unit) is 1500. 5214If it is increased, the other side *may* increase its MTU. 5215In theory there is no point in decreasing the MRU to below the default as the 5216.Em PPP 5217protocol says implementations *must* be able to accept packets of at 5218least 1500 octets. 5219.Pp 5220If the 5221.Dq maximum 5222keyword is used, 5223.Nm 5224will refuse to negotiate a higher value. 5225The maximum MRU can be set to 2048 at most. 5226Setting a maximum of less than 1500 violates the 5227.Em PPP 5228rfc, but may sometimes be necessary. 5229For example, 5230.Em PPPoE 5231imposes a maximum of 1492 due to hardware limitations. 5232.Pp 5233If no argument is given, 1500 is assumed. 5234A value must be given when 5235.Dq maximum 5236is specified. 5237.It set mtu Xo 5238.Op max Ns Op imum 5239.Op Ar value 5240.Xc 5241The default MTU is 1500. 5242At negotiation time, 5243.Nm 5244will accept whatever MRU the peer requests (assuming it is 5245not less than 296 bytes or greater than the assigned maximum). 5246If the MTU is set, 5247.Nm 5248will not accept MRU values less than 5249.Ar value . 5250When negotiations are complete, the MTU is used when writing to the 5251interface, even if the peer requested a higher value MRU. 5252This can be useful for 5253limiting your packet size (giving better bandwidth sharing at the expense 5254of more header data). 5255.Pp 5256If the 5257.Dq maximum 5258keyword is used, 5259.Nm 5260will refuse to negotiate a higher value. 5261The maximum MTU can be set to 2048 at most. 5262Note, it is necessary to use the 5263.Dq maximum 5264keyword to limit the MTU when using PPPoE. 5265.Pp 5266If no 5267.Ar value 5268is given, 1500, or whatever the peer asks for is used. 5269A value must be given when 5270.Dq maximum 5271is specified. 5272.It set nbns Op Ar x.x.x.x Op Ar y.y.y.y 5273This option allows the setting of the Microsoft NetBIOS name server 5274values to be returned at the peers request. 5275If no values are given, 5276.Nm 5277will reject any such requests. 5278.It set openmode active|passive Op Ar delay 5279By default, 5280.Ar openmode 5281is always 5282.Ar active 5283with a one second 5284.Ar delay . 5285That is, 5286.Nm 5287will always initiate LCP/IPCP/CCP negotiation one second after the line 5288comes up. 5289If you want to wait for the peer to initiate negotiations, you 5290can use the value 5291.Ar passive . 5292If you want to initiate negotiations immediately or after more than one 5293second, the appropriate 5294.Ar delay 5295may be specified here in seconds. 5296.It set parity odd|even|none|mark 5297This allows the line parity to be set. 5298The default value is 5299.Ar none . 5300.It set phone Ar telno Ns Xo 5301.Oo \&| Ns Ar backupnumber Oc Ns ... Ns Oo : Ns Ar nextnumber Oc Ns ... Xc 5302This allows the specification of the phone number to be used in 5303place of the \\\\T string in the dial and login chat scripts. 5304Multiple phone numbers may be given separated either by a pipe 5305.Pq Dq \&| 5306or a colon 5307.Pq Dq \&: . 5308.Pp 5309Numbers after the pipe are only dialed if the dial or login 5310script for the previous number failed. 5311.Pp 5312Numbers after the colon are tried sequentially, irrespective of 5313the reason the line was dropped. 5314.Pp 5315If multiple numbers are given, 5316.Nm 5317will dial them according to these rules until a connection is made, retrying 5318the maximum number of times specified by 5319.Dq set redial 5320below. 5321In 5322.Fl background 5323mode, each number is attempted at most once. 5324.It set pppoe Op standard|3Com 5325This option configures the underlying 5326.Xr ng_pppoe 4 5327node to either standard RFC2516 PPPoE or proprietary 3Com mode. 5328If not set the system default will be used. 5329.It set Oo proc Oc Ns Xo 5330.No title Op Ar value 5331.Xc 5332The current process title as displayed by 5333.Xr ps 1 5334is changed according to 5335.Ar value . 5336If 5337.Ar value 5338is not specified, the original process title is restored. 5339All the 5340word replacements done by the shell commands (see the 5341.Dq bg 5342command above) are done here too. 5343.Pp 5344Note, if USER is required in the process title, the 5345.Dq set proctitle 5346command must appear in 5347.Pa ppp.linkup , 5348as it is not known when the commands in 5349.Pa ppp.conf 5350are executed. 5351.It set radius Op Ar config-file 5352This command enables RADIUS support (if it is compiled in). 5353.Ar config-file 5354refers to the radius client configuration file as described in 5355.Xr radius.conf 5 . 5356If PAP, CHAP, MSCHAP or MSCHAPv2 are 5357.Dq enable Ns No d , 5358.Nm 5359behaves as a 5360.Em \&N Ns No etwork 5361.Em \&A Ns No ccess 5362.Em \&S Ns No erver 5363and uses the configured RADIUS server to authenticate rather than 5364authenticating from the 5365.Pa ppp.secret 5366file or from the passwd database. 5367.Pp 5368If none of PAP, CHAP, MSCHAP or MSCHAPv2 are enabled, 5369.Dq set radius 5370will do nothing. 5371.Pp 5372.Nm 5373uses the following attributes from the RADIUS reply: 5374.Bl -tag -width XXX -offset XXX 5375.It RAD_FRAMED_IP_ADDRESS 5376The peer IP address is set to the given value. 5377.It RAD_FRAMED_IP_NETMASK 5378The tun interface netmask is set to the given value. 5379.It RAD_FRAMED_MTU 5380If the given MTU is less than the peers MRU as agreed during LCP 5381negotiation, *and* it is less that any configured MTU (see the 5382.Dq set mru 5383command), the tun interface MTU is set to the given value. 5384.It RAD_FRAMED_COMPRESSION 5385If the received compression type is 5386.Dq 1 , 5387.Nm 5388will request VJ compression during IPCP negotiations despite any 5389.Dq disable vj 5390configuration command. 5391.It RAD_FILTER_ID 5392If this attribute is supplied, 5393.Nm 5394will attempt to use it as an additional label to load from the 5395.Pa ppp.linkup 5396and 5397.Pa ppp.linkdown 5398files. 5399The load will be attempted before (and in addition to) the normal 5400label search. 5401If the label does not exist, no action is taken and 5402.Nm 5403proceeds to the normal load using the current label. 5404.It RAD_FRAMED_ROUTE 5405The received string is expected to be in the format 5406.Ar dest Ns Op / Ns Ar bits 5407.Ar gw 5408.Op Ar metrics . 5409Any specified metrics are ignored. 5410.Dv MYADDR 5411and 5412.Dv HISADDR 5413are understood as valid values for 5414.Ar dest 5415and 5416.Ar gw , 5417.Dq default 5418can be used for 5419.Ar dest 5420to specify the default route, and 5421.Dq 0.0.0.0 5422is understood to be the same as 5423.Dq default 5424for 5425.Ar dest 5426and 5427.Dv HISADDR 5428for 5429.Ar gw . 5430.Pp 5431For example, a returned value of 5432.Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400 5433would result in a routing table entry to the 1.2.3.0/24 network via 5434.Dv HISADDR 5435and a returned value of 5436.Dq 0.0.0.0 0.0.0.0 5437or 5438.Dq default HISADDR 5439would result in a default route to 5440.Dv HISADDR . 5441.Pp 5442All RADIUS routes are applied after any sticky routes are applied, making 5443RADIUS routes override configured routes. 5444This also applies for RADIUS routes that do not {include} the 5445.Dv MYADDR 5446or 5447.Dv HISADDR 5448keywords. 5449.It RAD_FRAMED_IPV6_PREFIX 5450If this attribute is supplied, the value is substituted for IPV6PREFIX 5451in a command. 5452You may pass it to an upper layer protocol such as DHCPv6 for delegating an 5453IPv6 prefix to a peer. 5454.It RAD_FRAMED_IPV6_ROUTE 5455The received string is expected to be in the format 5456.Ar dest Ns Op / Ns Ar bits 5457.Ar gw 5458.Op Ar metrics . 5459Any specified metrics are ignored. 5460.Dv MYADDR6 5461and 5462.Dv HISADDR6 5463are understood as valid values for 5464.Ar dest 5465and 5466.Ar gw , 5467.Dq default 5468can be used for 5469.Ar dest 5470to specify the default route, and 5471.Dq :: 5472is understood to be the same as 5473.Dq default 5474for 5475.Ar dest 5476and 5477.Dv HISADDR6 5478for 5479.Ar gw . 5480.Pp 5481For example, a returned value of 5482.Dq 3ffe:505:abcd::/48 :: 5483would result in a routing table entry to the 3ffe:505:abcd::/48 network via 5484.Dv HISADDR6 5485and a returned value of 5486.Dq :: :: 5487or 5488.Dq default HISADDR6 5489would result in a default route to 5490.Dv HISADDR6 . 5491.Pp 5492All RADIUS IPv6 routes are applied after any sticky routes are 5493applied, making RADIUS IPv6 routes override configured routes. 5494This 5495also applies for RADIUS IPv6 routes that do not {include} the 5496.Dv MYADDR6 5497or 5498.Dv HISADDR6 5499keywords. 5500.It RAD_SESSION_TIMEOUT 5501If supplied, the client connection is closed after the given number of 5502seconds. 5503.It RAD_REPLY_MESSAGE 5504If supplied, this message is passed back to the peer as the authentication 5505SUCCESS text. 5506.It RAD_MICROSOFT_MS_CHAP_ERROR 5507If this 5508.Dv RAD_VENDOR_MICROSOFT 5509vendor specific attribute is supplied, it is passed back to the peer as the 5510authentication FAILURE text. 5511.It RAD_MICROSOFT_MS_CHAP2_SUCCESS 5512If this 5513.Dv RAD_VENDOR_MICROSOFT 5514vendor specific attribute is supplied and if MS-CHAPv2 authentication is 5515being used, it is passed back to the peer as the authentication SUCCESS text. 5516.It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY 5517If this 5518.Dv RAD_VENDOR_MICROSOFT 5519vendor specific attribute is supplied and has a value of 2 (Required), 5520.Nm 5521will insist that MPPE encryption is used (even if no 5522.Dq set mppe 5523configuration command has been given with arguments). 5524If it is supplied with a value of 1 (Allowed), encryption is made optional 5525(despite any 5526.Dq set mppe 5527configuration commands with arguments). 5528.It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES 5529If this 5530.Dv RAD_VENDOR_MICROSOFT 5531vendor specific attribute is supplied, bits 1 and 2 are examined. 5532If either or both are set, 40 bit and/or 128 bit (respectively) encryption 5533options are set, overriding any given first argument to the 5534.Dq set mppe 5535command. 5536Note, it is not currently possible for the RADIUS server to specify 56 bit 5537encryption. 5538.It RAD_MICROSOFT_MS_MPPE_RECV_KEY 5539If this 5540.Dv RAD_VENDOR_MICROSOFT 5541vendor specific attribute is supplied, it is value is used as the master 5542key for decryption of incoming data. 5543When clients are authenticated using 5544MSCHAPv2, the RADIUS server MUST provide this attribute if inbound MPPE is 5545to function. 5546.It RAD_MICROSOFT_MS_MPPE_SEND_KEY 5547If this 5548.Dv RAD_VENDOR_MICROSOFT 5549vendor specific attribute is supplied, it is value is used as the master 5550key for encryption of outgoing data. 5551When clients are authenticated using 5552MSCHAPv2, the RADIUS server MUST provide this attribute if outbound MPPE is 5553to function. 5554.El 5555.Pp 5556Values received from the RADIUS server may be viewed using 5557.Dq show bundle . 5558.It set rad_alive Ar timeout 5559When RADIUS is configured, setting 5560.Dq rad_alive 5561to a non-zero 5562.Ar timeout 5563value will tell 5564.Nm 5565to sent RADIUS accounting information to the RADIUS server every 5566.Ar timeout 5567seconds. 5568.It set rad_port_id Ar option 5569When RADIUS is configured, setting the 5570.Dq rad_port_id 5571value specifies what should be sent to the RADIUS server as 5572NAS-Port-Id. 5573The 5574.Ar option Ns No s 5575are as follows: 5576.Bl -tag -width Ds 5577.It pid 5578PID of the corresponding tunnel. 5579.It tunnum 5580.Xr tun 4 5581interface number. 5582.It ifnum 5583index of the interface as returned by 5584.Xr if_nametoindex 3 . 5585.It default 5586keeps the default behavior. 5587.El 5588.It set reconnect Ar timeout ntries 5589Should the line drop unexpectedly (due to loss of CD or LQR 5590failure), a connection will be re-established after the given 5591.Ar timeout . 5592The line will be re-connected at most 5593.Ar ntries 5594times. 5595.Ar Ntries 5596defaults to zero. 5597A value of 5598.Ar random 5599for 5600.Ar timeout 5601will result in a variable pause, somewhere between 1 and 30 seconds. 5602.It set recvpipe Op Ar value 5603This sets the routing table RECVPIPE value. 5604The optimum value is just over twice the MTU value. 5605If 5606.Ar value 5607is unspecified or zero, the default kernel controlled value is used. 5608.It set redial Ar secs Ns Xo 5609.Oo + Ns Ar inc Ns 5610.Oo - Ns Ar max Ns Oc Oc Ns 5611.Op . Ns Ar next 5612.Op Ar attempts 5613.Xc 5614.Nm 5615can be instructed to attempt to redial 5616.Ar attempts 5617times. 5618If more than one phone number is specified (see 5619.Dq set phone 5620above), a pause of 5621.Ar next 5622is taken before dialing each number. 5623A pause of 5624.Ar secs 5625is taken before starting at the first number again. 5626A literal value of 5627.Dq Li random 5628may be used here in place of 5629.Ar secs 5630and 5631.Ar next , 5632causing a random delay of between 1 and 30 seconds. 5633.Pp 5634If 5635.Ar inc 5636is specified, its value is added onto 5637.Ar secs 5638each time 5639.Nm 5640tries a new number. 5641.Ar secs 5642will only be incremented at most 5643.Ar max 5644times. 5645.Ar max 5646defaults to 10. 5647.Pp 5648Note, the 5649.Ar secs 5650delay will be effective, even after 5651.Ar attempts 5652has been exceeded, so an immediate manual dial may appear to have 5653done nothing. 5654If an immediate dial is required, a 5655.Dq !\& 5656should immediately follow the 5657.Dq open 5658keyword. 5659See the 5660.Dq open 5661description above for further details. 5662.It set sendpipe Op Ar value 5663This sets the routing table SENDPIPE value. 5664The optimum value is just over twice the MTU value. 5665If 5666.Ar value 5667is unspecified or zero, the default kernel controlled value is used. 5668.It "set server|socket" Ar TcpPort Ns No \&| Ns Xo 5669.Ar LocalName Ns No |none|open|closed 5670.Op password Op Ar mask 5671.Xc 5672This command tells 5673.Nm 5674to listen on the given socket or 5675.Sq diagnostic port 5676for incoming command connections. 5677.Pp 5678The word 5679.Dq none 5680instructs 5681.Nm 5682to close any existing socket and clear the socket configuration. 5683The word 5684.Dq open 5685instructs 5686.Nm 5687to attempt to re-open the port. 5688The word 5689.Dq closed 5690instructs 5691.Nm 5692to close the open port. 5693.Pp 5694If you wish to specify a local domain socket, 5695.Ar LocalName 5696must be specified as an absolute file name, otherwise it is assumed 5697to be the name or number of a TCP port. 5698You may specify the octal umask to be used with a local domain socket. 5699Refer to 5700.Xr umask 2 5701for umask details. 5702Refer to 5703.Xr services 5 5704for details of how to translate TCP port names. 5705.Pp 5706You must also specify the password that must be entered by the client 5707(using the 5708.Dq passwd 5709variable above) when connecting to this socket. 5710If the password is 5711specified as an empty string, no password is required for connecting clients. 5712.Pp 5713When specifying a local domain socket, the first 5714.Dq %d 5715sequence found in the socket name will be replaced with the current 5716interface unit number. 5717This is useful when you wish to use the same 5718profile for more than one connection. 5719.Pp 5720In a similar manner TCP sockets may be prefixed with the 5721.Dq + 5722character, in which case the current interface unit number is added to 5723the port number. 5724.Pp 5725When using 5726.Nm 5727with a server socket, the 5728.Xr pppctl 8 5729command is the preferred mechanism of communications. 5730Currently, 5731.Xr telnet 1 5732can also be used, but link encryption may be implemented in the future, so 5733.Xr telnet 1 5734should be avoided. 5735.Pp 5736Note; 5737.Dv SIGUSR1 5738and 5739.Dv SIGUSR2 5740interact with the diagnostic socket. 5741.It set speed Ar value 5742This sets the speed of the serial device. 5743If speed is specified as 5744.Dq sync , 5745.Nm 5746treats the device as a synchronous device. 5747.Pp 5748Certain device types will know whether they should be specified as 5749synchronous or asynchronous. 5750These devices will override incorrect 5751settings and log a warning to this effect. 5752.It set stopped Op Ar LCPseconds Op Ar CCPseconds 5753If this option is set, 5754.Nm 5755will time out after the given FSM (Finite State Machine) has been in 5756the stopped state for the given number of 5757.Dq seconds . 5758This option may be useful if the peer sends a terminate request, 5759but never actually closes the connection despite our sending a terminate 5760acknowledgement. 5761This is also useful if you wish to 5762.Dq set openmode passive 5763and time out if the peer does not send a Configure Request within the 5764given time. 5765Use 5766.Dq set log +lcp +ccp 5767to make 5768.Nm 5769log the appropriate state transitions. 5770.Pp 5771The default value is zero, where 5772.Nm 5773does not time out in the stopped state. 5774.Pp 5775This value should not be set to less than the openmode delay (see 5776.Dq set openmode 5777above). 5778.It set timeout Ar idleseconds Op Ar mintimeout 5779This command allows the setting of the idle timer. 5780Refer to the section titled 5781.Sx SETTING THE IDLE TIMER 5782for further details. 5783.Pp 5784If 5785.Ar mintimeout 5786is specified, 5787.Nm 5788will never idle out before the link has been up for at least that number 5789of seconds. 5790.It set urgent Xo 5791.Op tcp|udp|none 5792.Oo Op +|- Ns 5793.Ar port 5794.Oc No ... 5795.Xc 5796This command controls the ports that 5797.Nm 5798prioritizes when transmitting data. 5799The default priority TCP ports 5800are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell), 5801543 (klogin) and 544 (kshell). 5802There are no priority UDP ports by default. 5803See 5804.Xr services 5 5805for details. 5806.Pp 5807If neither 5808.Dq tcp 5809or 5810.Dq udp 5811are specified, 5812.Dq tcp 5813is assumed. 5814.Pp 5815If no 5816.Ar port Ns No s 5817are given, the priority port lists are cleared (although if 5818.Dq tcp 5819or 5820.Dq udp 5821is specified, only that list is cleared). 5822If the first 5823.Ar port 5824argument is prefixed with a plus 5825.Pq Dq \&+ 5826or a minus 5827.Pq Dq \&- , 5828the current list is adjusted, otherwise the list is reassigned. 5829.Ar port Ns No s 5830prefixed with a plus or not prefixed at all are added to the list and 5831.Ar port Ns No s 5832prefixed with a minus are removed from the list. 5833.Pp 5834If 5835.Dq none 5836is specified, all priority port lists are disabled and even 5837.Dv IPTOS_LOWDELAY 5838packets are not prioritised. 5839.It set urgent length Ar length 5840This command tells ppp to prioritize small packets up to 5841.Ar length 5842bytes. 5843If 5844.Ar length 5845is not specified, or 0, this feature is disabled. 5846.It set vj slotcomp on|off 5847This command tells 5848.Nm 5849whether it should attempt to negotiate VJ slot compression. 5850By default, slot compression is turned 5851.Ar on . 5852.It set vj slots Ar nslots 5853This command sets the initial number of slots that 5854.Nm 5855will try to negotiate with the peer when VJ compression is enabled (see the 5856.Sq enable 5857command above). 5858It defaults to a value of 16. 5859.Ar Nslots 5860must be between 5861.Ar 4 5862and 5863.Ar 16 5864inclusive. 5865.El 5866.It shell|! Op Ar command 5867If 5868.Ar command 5869is not specified a shell is invoked according to the 5870.Dv SHELL 5871environment variable. 5872Otherwise, the given 5873.Ar command 5874is executed. 5875Word replacement is done in the same way as for the 5876.Dq !bg 5877command as described above. 5878.Pp 5879Use of the !\& character 5880requires a following space as with any of the other commands. 5881You should note that this command is executed in the foreground; 5882.Nm 5883will not continue running until this process has exited. 5884Use the 5885.Dv bg 5886command if you wish processing to happen in the background. 5887.It show Ar var 5888This command allows the user to examine the following: 5889.Bl -tag -width 2n 5890.It show bundle 5891Show the current bundle settings. 5892.It show ccp 5893Show the current CCP compression statistics. 5894.It show compress 5895Show the current VJ compression statistics. 5896.It show escape 5897Show the current escape characters. 5898.It show filter Op Ar name 5899List the current rules for the given filter. 5900If 5901.Ar name 5902is not specified, all filters are shown. 5903.It show hdlc 5904Show the current HDLC statistics. 5905.It show help|? 5906Give a summary of available show commands. 5907.It show iface 5908Show the current interface information 5909(the same as 5910.Dq iface show ) . 5911.It show ipcp 5912Show the current IPCP statistics. 5913.It show layers 5914Show the protocol layers currently in use. 5915.It show lcp 5916Show the current LCP statistics. 5917.It show Oo data Oc Ns Xo 5918.No link 5919.Xc 5920Show high level link information. 5921.It show links 5922Show a list of available logical links. 5923.It show log 5924Show the current log values. 5925.It show mem 5926Show current memory statistics. 5927.It show ncp 5928Show the current NCP statistics. 5929.It show physical 5930Show low level link information. 5931.It show mp 5932Show Multi-link information. 5933.It show proto 5934Show current protocol totals. 5935.It show route 5936Show the current routing tables. 5937.It show stopped 5938Show the current stopped timeouts. 5939.It show timer 5940Show the active alarm timers. 5941.It show version 5942Show the current version number of 5943.Nm . 5944.El 5945.It term 5946Go into terminal mode. 5947Characters typed at the keyboard are sent to the device. 5948Characters read from the device are displayed on the screen. 5949When a remote 5950.Em PPP 5951peer is detected, 5952.Nm 5953automatically enables Packet Mode and goes back into command mode. 5954.El 5955.Sh MORE DETAILS 5956.Bl -bullet 5957.It 5958Read the example configuration files. 5959They are a good source of information. 5960.It 5961Use 5962.Dq help , 5963.Dq nat \&? , 5964.Dq enable \&? , 5965.Dq set ?\& 5966and 5967.Dq show ?\& 5968to get online information about what is available. 5969.It 5970The following URL contains useful information: 5971.Bl -bullet -compact 5972.It 5973https://docs.freebsd.org/en/books/handbook/ppp-and-slip/ 5974.El 5975.El 5976.Sh FILES 5977.Nm 5978refers to four files: 5979.Pa ppp.conf , 5980.Pa ppp.linkup , 5981.Pa ppp.linkdown 5982and 5983.Pa ppp.secret . 5984These files are placed in the 5985.Pa /etc/ppp 5986directory. 5987.Bl -tag -width 2n 5988.It Pa /etc/ppp/ppp.conf 5989System default configuration file. 5990.It Pa /etc/ppp/ppp.secret 5991An authorisation file for each system. 5992.It Pa /etc/ppp/ppp.linkup 5993A file to check when 5994.Nm 5995establishes a network level connection. 5996.It Pa /etc/ppp/ppp.linkdown 5997A file to check when 5998.Nm 5999closes a network level connection. 6000.It Pa /var/log/ppp.log 6001Logging and debugging information file. 6002Note, this name is specified in 6003.Pa /etc/syslog.conf . 6004See 6005.Xr syslog.conf 5 6006for further details. 6007.It Pa /var/spool/lock/LCK..* 6008tty port locking file. 6009Refer to 6010.Xr uucplock 3 6011for further details. 6012.It Pa /var/run/tunN.pid 6013The process id (pid) of the 6014.Nm 6015program connected to the tunN device, where 6016.Sq N 6017is the number of the device. 6018.It Pa /var/run/ttyXX.if 6019The tun interface used by this port. 6020Again, this file is only created in 6021.Fl background , 6022.Fl auto 6023and 6024.Fl ddial 6025modes. 6026.It Pa /etc/services 6027Get port number if port number is using service name. 6028.It Pa /var/run/ppp-authname-class-value 6029In multi-link mode, local domain sockets are created using the peer 6030authentication name 6031.Pq Sq authname , 6032the peer endpoint discriminator class 6033.Pq Sq class 6034and the peer endpoint discriminator value 6035.Pq Sq value . 6036As the endpoint discriminator value may be a binary value, it is turned 6037to HEX to determine the actual file name. 6038.Pp 6039This socket is used to pass links between different instances of 6040.Nm . 6041.El 6042.Sh SEE ALSO 6043.Xr at 1 , 6044.Xr ftp 1 , 6045.Xr gzip 1 , 6046.Xr hostname 1 , 6047.Xr login 1 , 6048.Xr tcpdump 1 , 6049.Xr telnet 1 , 6050.Xr kldload 2 , 6051.Xr pipe 2 , 6052.Xr socketpair 2 , 6053.Xr libalias 3 , 6054.Xr libradius 3 , 6055.Xr syslog 3 , 6056.Xr uucplock 3 , 6057.Xr netgraph 4 , 6058.Xr ng_pppoe 4 , 6059.Xr crontab 5 , 6060.Xr group 5 , 6061.Xr passwd 5 , 6062.Xr protocols 5 , 6063.Xr radius.conf 5 , 6064.Xr resolv.conf 5 , 6065.Xr syslog.conf 5 , 6066.Xr adduser 8 , 6067.Xr chat 8 , 6068.Xr getty 8 , 6069.Xr inetd 8 , 6070.Xr init 8 , 6071.Xr ping 8 , 6072.Xr pppctl 8 , 6073.Xr pppoed 8 , 6074.Xr route 8 , 6075.Xr sshd 8 , 6076.Xr syslogd 8 , 6077.Xr traceroute 8 , 6078.Xr vipw 8 6079.Sh HISTORY 6080This program was originally written by 6081.An Toshiharu OHNO Aq Mt tony-o@iij.ad.jp , 6082and was submitted to 6083.Fx 2.0.5 6084by 6085.An Atsushi Murai Aq Mt amurai@spec.co.jp . 6086.Pp 6087It was substantially modified during 1997 by 6088.An Brian Somers Aq Mt brian@Awfulhak.org , 6089and was ported to 6090.Ox 6091in November that year 6092(just after the 2.2 release). 6093.Pp 6094Most of the code was rewritten by 6095.An Brian Somers 6096in early 1998 when multi-link ppp support was added. 6097