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