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