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