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