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