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