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