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