1.\" $Id: ppp.8,v 1.112 1998/07/29 18:21:17 brian Exp $ 2.Dd 20 September 1995 3.Os FreeBSD 4.Dt PPP 8 5.Sh NAME 6.Nm ppp 7.Nd Point to Point Protocol (a.k.a. user-ppp) 8.Sh SYNOPSIS 9.Nm 10.Oo 11.Fl auto | 12.Fl background | 13.Fl ddial | 14.Fl direct | 15.Fl dedicated 16.Oc 17.Op Fl alias 18.Op Ar system 19.Sh DESCRIPTION 20This is a user process 21.Em PPP 22software package. Normally, 23.Em PPP 24is implemented as a part of the kernel (e.g. as managed by 25.Xr pppd 8 ) 26and it's thus somewhat hard to debug and/or modify its behaviour. 27However, in this implementation 28.Em PPP 29is done as a user process with the help of the 30tunnel device driver (tun). 31.Sh Major Features 32.Bl -diag 33.It Provides interactive user interface. 34Using its command mode, the user can 35easily enter commands to establish the connection with the remote end, check 36the status of connection and close the connection. All functions can 37also be optionally password protected for security. 38.It Supports both manual and automatic dialing. 39Interactive mode has a 40.Dq term 41command which enables you to talk to your modem directly. When your 42modem is connected to the remote peer and it starts to talk 43.Em PPP , 44.Nm 45detects it and switches to packet mode automatically. Once you have 46determined the proper sequence for connecting with the remote host, you 47can write a chat script to define the necessary dialing and login 48procedure for later convenience. 49.It Supports on-demand dialup capability. 50By using 51.Fl auto 52mode, 53.Nm 54will act as a daemon and wait for a packet to be sent over the 55.Em PPP 56link. When this happens, the daemon automatically dials and establishes the 57connection. 58In almost the same manner 59.Fl ddial 60mode (direct-dial mode) also automatically dials and establishes the 61connection. However, it differs in that it will dial the remote site 62any time it detects the link is down, even if there are no packets to be 63sent. This mode is useful for full-time connections where we worry less 64about line charges and more about being connected full time. 65A third 66.Fl dedicated 67mode is also available. This mode is targeted at a dedicated link 68between two machines. 69.Nm Ppp 70will never voluntarily quit from dedicated mode - you must send it the 71.Dq quit all 72command via its diagnostic socket. A 73.Dv SIGHUP 74will force an LCP renegotiation, and a 75.Dv SIGTERM 76will force it to exit. 77.It Supports packet aliasing. 78Packet aliasing (a.k.a. IP masquerading) allows computers on a 79private, unregistered network to access the Internet. The 80.Em PPP 81host acts as a masquerading gateway. IP addresses as well as TCP and 82UDP port numbers are aliased for outgoing packets and de-aliased for 83returning packets. 84.It Supports background PPP connections. 85In background mode, if 86.Nm 87successfully establishes the connection, it will become a daemon. 88Otherwise, it will exit with an error. This allows the setup of 89scripts that wish to execute certain commands only if the connection 90is successfully established. 91.It Supports server-side PPP connections. 92In direct mode, 93.nm 94acts as server which accepts incoming 95.Em PPP 96connections on stdin/stdout. 97.It Supports PAP and CHAP authentication. 98With PAP or CHAP, it is possible to skip the Unix style 99.Xr login 1 100procedure, and use the 101.Em PPP 102protocol for authentication instead. If the peer requests Microsoft 103CHAP authentication and 104.Nm 105is compiled with DES support, an appropriate MD4/DES response will be 106made. 107.It Supports Proxy Arp. 108When 109.Em PPP 110is set up as server, you can also configure it to do proxy arp for your 111connection. 112.It Supports packet filtering. 113User can define four kinds of filters: the 114.Em in 115filter for incoming packets, the 116.Em out 117filter for outgoing packets, the 118.Em dial 119filter to define a dialing trigger packet and the 120.Em alive 121filter for keeping a connection alive with the trigger packet. 122.It Tunnel driver supports bpf. 123The user can use 124.Xr tcpdump 1 125to check the packet flow over the 126.Em PPP 127link. 128.It Supports PPP over TCP capability. 129If a device name is specified as 130.Em host Ns No : Ns Em port , 131.Nm 132will open a TCP connection for transporting data rather than using a 133conventional serial device. 134.It Supports IETF draft Predictor-1 and DEFLATE compression. 135.Nm 136supports not only VJ-compression but also Predictor-1 and DEFLATE compression. 137Normally, a modem has built-in compression (e.g. v42.bis) and the system 138may receive higher data rates from it as a result of such compression. 139While this is generally a good thing in most other situations, this 140higher speed data imposes a penalty on the system by increasing the 141number of serial interrupts the system has to process in talking to the 142modem and also increases latency. Unlike VJ-compression, Predictor-1 and 143DEFLATE compression pre-compresses 144.Em all 145network traffic flowing through the link, thus reducing overheads to a 146minimum. 147.It Supports Microsoft's IPCP extensions. 148Name Server Addresses and NetBIOS Name Server Addresses can be negotiated 149with clients using the Microsoft 150.Em PPP 151stack (ie. Win95, WinNT) 152.It Supports Multi-link PPP 153It is possible to configure 154.Nm 155to open more than one physical connection to the peer, combining the 156bandwidth of all links for better throughput. 157.Sh PERMISSIONS 158.Nm Ppp 159is installed as user 160.Dv root 161and group 162.Dv network , 163with permissions 164.Dv 4550 . 165By default, 166.Nm 167will not run if the invoking user id is not zero. This may be overridden 168by using the 169.Dq allow users 170command in 171.Pa /etc/ppp/ppp.conf . 172When running as a normal user, 173.Nm 174switches to user id 0 in order to alter the system routing table, set up 175system lock files and read the ppp configuration files. All 176external commands (executed via the "shell" or "!bg" commands) are executed 177as the user id that invoked 178.Nm ppp . 179Refer to the 180.Sq ID0 181logging facility if you're interested in what exactly is done as user id 182zero. 183.Sh GETTING STARTED 184When you first run 185.Nm 186you may need to deal with some initial configuration details. 187.Bl -bullet 188.It 189Your kernel must include a tunnel device (the GENERIC kernel includes 190one by default). If it doesn't, or if you require more than one tun 191interface, you'll need to rebuild your kernel with the following line in 192your kernel configuration file: 193.Pp 194.Dl pseudo-device tun N 195.Pp 196where 197.Ar N 198is the maximum number of 199.Em PPP 200connections you wish to support. 201.It 202Check your 203.Pa /dev 204directory for the tunnel device entries 205.Pa /dev/tunN , 206where 207.Sq N 208represents the number of the tun device, starting at zero. 209If they don't exist, you can create them by running "sh ./MAKEDEV tunN". 210This will create tun devices 0 through 211.Ar N . 212.It 213Make sure that your system has a group named 214.Dq network 215in the 216.Pa /etc/group 217file and that that group contains the names of all users expected to use 218.Nm ppp . 219Refer to the 220.Xr group 5 221manual page for details. Each of these uses must also be given access 222using the 223.Dq allow users 224command in 225.Pa /etc/ppp/ppp.conf . 226.It 227Create a log file. 228.Nm Ppp 229uses 230.Xr syslog 3 231to log information. A common log file name is 232.Pa /var/log/ppp.log . 233To make output go to this file, put the following lines in the 234.Pa /etc/syslog.conf 235file: 236.Bd -literal -offset indent 237!ppp 238*.*<TAB>/var/log/ppp.log 239.Ed 240.Pp 241Make sure you use actual TABs here. If you use spaces, the line will be 242silently ignored by 243.Xr syslogd 8 . 244.Pp 245It is possible to have more than one 246.Em PPP 247log file by creating a link to the 248.Nm 249executable: 250.Pp 251.Dl # cd /usr/sbin 252.Dl # ln ppp ppp0 253.Pp 254and using 255.Bd -literal -offset indent 256!ppp0 257*.*<TAB>/var/log/ppp0.log 258.Ed 259.Pp 260in 261.Pa /etc/syslog.conf . 262Don't forget to send a 263.Dv HUP 264signal to 265.Xr syslogd 8 266after altering 267.Pa /etc/syslog.conf . 268.It 269Although not strictly relevant to 270.Nm ppp Ns No s 271operation, you should configure your resolver so that it works correctly. 272This can be done by configuring a local DNS 273.Pq using Xr named 8 274or by adding the correct 275.Sq name-server 276lines to the file 277.Pa /etc/resolv.conf . 278Refer to the 279.Xr resolv.conf 5 280manual page for details. 281.El 282.Sh MANUAL DIALING 283In the following examples, we assume that your machine name is 284.Dv awfulhak . 285when you invoke 286.Nm 287(see 288.Em PERMISSIONS 289above) with no arguments, you are presented with a prompt: 290.Bd -literal -offset indent 291ppp ON awfulhak> 292.Ed 293.Pp 294The 295.Sq ON 296part of your prompt should always be in upper case. If it is in lower 297case, it means that you must supply a password using the 298.Dq passwd 299command. This only ever happens if you connect to a running version of 300.Nm 301and have not authenticated yourself using the correct password. 302.Pp 303You can start by specifying the device name, speed and parity for your modem, 304and whether CTS/RTS signalling should be used (CTS/RTS is used by 305default). If your hardware does not provide CTS/RTS lines (as 306may happen when you are connected directly to certain PPP-capable 307terminal servers), 308.Nm 309will never send any output through the port; it waits for a signal 310which never comes. Thus, if you have a direct line and can't seem 311to make a connection, try turning CTS/RTS off: 312.Bd -literal -offset indent 313ppp ON awfulhak> set line /dev/cuaa0 314ppp ON awfulhak> set speed 38400 315ppp ON awfulhak> set parity even 316ppp ON awfulhak> set ctsrts on 317ppp ON awfulhak> show modem 318* Modem related information is shown here * 319ppp ON awfulhak> 320.Ed 321.Pp 322The term command can now be used to talk directly with your modem: 323.Bd -literal -offset indent 324ppp ON awfulhak> term 325at 326OK 327atdt123456 328CONNECT 329login: ppp 330Password: 331Protocol: ppp 332.Ed 333.Pp 334When the peer starts to talk in 335.Em PPP , 336.Nm 337detects this automatically and returns to command mode. 338.Bd -literal -offset indent 339ppp ON awfulhak> 340Ppp ON awfulhak> 341PPp ON awfulhak> 342PPP ON awfulhak> 343.Ed 344.Pp 345If it does not, it's possible that the peer is waiting for your end to 346start negotiating. To force 347.Nm 348to start sending PPP configuration packets to the peer, use the 349.Dq ~p 350command to enter packet mode. 351.Pp 352You are now connected! Note that 353.Sq PPP 354in the prompt has changed to capital letters to indicate that you have 355a peer connection. If only some of the three Ps go uppercase, wait 'till 356either everything is uppercase or lowercase. If they revert to lowercase, 357it means that 358.Nm 359couldn't successfully negotiate with the peer. This is probably because 360your PAP or CHAP authentication name or key is incorrect. A good first step 361for troubleshooting at this point would be to 362.Dq set log local phase . 363Refer to the 364.Dq set log 365command description below for further details. 366.Pp 367When the link is established, the show command can be used to see how 368things are going: 369.Bd -literal -offset indent 370PPP ON awfulhak> show modem 371* Modem related information is shown here * 372PPP ON awfulhak> show ccp 373* CCP (compression) related information is shown here * 374PPP ON awfulhak> show lcp 375* LCP (line control) related information is shown here * 376PPP ON awfulhak> show ipcp 377* IPCP (IP) related information is shown here * 378PPP ON awfulhak> show link 379* Link (high level) related information is shown here * 380PPP ON awfulhak> show bundle 381* Logical (high level) connection related information is shown here * 382.Ed 383.Pp 384At this point, your machine has a host route to the peer. This means 385that you can only make a connection with the host on the other side 386of the link. If you want to add a default route entry (telling your 387machine to send all packets without another routing entry to the other 388side of the 389.Em PPP 390link), enter the following command: 391.Bd -literal -offset indent 392PPP ON awfulhak> add default HISADDR 393.Ed 394.Pp 395The string 396.Sq HISADDR 397represents the IP address of the connected peer. It is possible to 398use the keyword 399.Sq INTERFACE 400in place of 401.Sq HISADDR . 402This will create a direct route on the tun interface. 403If it fails due to an existing route, you can overwrite the existing 404route using 405.Bd -literal -offset indent 406PPP ON awfulhak> add! default HISADDR 407.Ed 408.Pp 409You can now use your network applications (ping, telnet, ftp etc.) 410in other windows on your machine. 411Refer to the 412.Em PPP COMMAND LIST 413section for details on all available commands. 414.Sh AUTOMATIC DIALING 415To use automatic dialing, you must prepare some Dial and Login chat scripts. 416See the example definitions in 417.Pa /etc/ppp/ppp.conf.sample 418(the format of 419.Pa /etc/ppp/ppp.conf 420is pretty simple). 421Each line contains one comment, inclusion, label or command: 422.Bl -bullet 423.It 424A line starting with a 425.Pq Dq # 426character is treated as a comment line. Leading whitespace are ignored 427when identifying comment lines. 428.It 429An inclusion is a line beginning with the word 430.Sq !include . 431It must have one argument - the file to include. You may wish to 432.Dq !include ~/.ppp.conf 433for compatibility with older versions of 434.Nm ppp . 435.It 436A label name starts in the first column and is followed by 437a colon 438.Pq Dq \&: . 439.It 440A command line must contain a space or tab in the first column. 441.El 442.Pp 443The 444.Pa /etc/ppp/ppp.conf 445file should consist of at least a 446.Dq default 447section. This section is always executed. It should also contain 448one or more sections, named according to their purpose, for example, 449.Dq MyISP 450would represent your ISP, and 451.Dq ppp-in 452would represent an incoming 453.Nm 454configuration. 455You can now specify the destination label name when you invoke 456.Nm ppp . 457Commands associated with the 458.Dq default 459label are executed, followed by those associated with the destination 460label provided. When 461.Nm 462is started with no arguments, the 463.Dq default 464section is still executed. The load command can be used to manually 465load a section from the 466.Pa /etc/ppp/ppp.conf 467file: 468.Bd -literal -offset indent 469PPP ON awfulhak> load MyISP 470.Ed 471.Pp 472Once the connection is made, the 473.Sq ppp 474portion of the prompt will change to 475.Sq PPP : 476.Bd -literal -offset indent 477# ppp MyISP 478... 479ppp ON awfulhak> dial 480dial OK! 481login OK! 482PPP ON awfulhak> 483.Ed 484.Pp 485If the 486.Pa /etc/ppp/ppp.linkup 487file is available, its contents are executed 488when the 489.Em PPP 490connection is established. See the provided 491.Dq pmdemand 492example in 493.Pa /etc/ppp/ppp.conf.sample 494which runs a script in the background after the connection is established. 495The literal strings 496.Dv HISADDR , 497.Dv MYADDR 498and 499.Dv INTERFACE 500may be used, and will be replaced with the relevant IP addresses and interface 501name. Similarly, when a connection is closed, the 502contents of the 503.Pa /etc/ppp/ppp.linkdown 504file are executed. 505Both of these files have the same format as 506.Pa /etc/ppp/ppp.conf . 507.Pp 508In previous versions of 509.Nm ppp , 510it was necessary to re-add routes such as the default route in the 511.Pa ppp.linkup 512file. 513.Nm Ppp 514now supports 515.Sq sticky routes , 516where all routes that contain the 517.Dv HISADDR 518or 519.Dv MYADDR 520literals will automatically be updated when the values of 521.Dv HISADDR 522and/or 523.Dv MYADDR 524change. 525.Sh BACKGROUND DIALING 526If you want to establish a connection using 527.Nm 528non-interactively (such as from a 529.Xr crontab 5 530entry or an 531.Xr at 1 532job) you should use the 533.Fl background 534option. 535When 536.Fl background 537is specified, 538.Nm 539attempts to establish the connection immediately. If multiple phone 540numbers are specified, each phone number will be tried once. If the 541attempt fails, 542.Nm 543exits immediately with a non-zero exit code. 544If it succeeds, then 545.Nm 546becomes a daemon, and returns an exit status of zero to its caller. 547The daemon exits automatically if the connection is dropped by the 548remote system, or it receives a 549.Dv TERM 550signal. 551.Sh DIAL ON DEMAND 552Demand dialing is enabled with the 553.Fl auto 554or 555.Fl ddial 556options. You must also specify the destination label in 557.Pa /etc/ppp/ppp.conf 558to use. It must contain the 559.Dq set ifaddr 560command to define the remote peers IP address. (refer to 561.Pa /etc/ppp/ppp.conf.sample ) 562.Bd -literal -offset indent 563# ppp -auto pmdemand 564.Ed 565.Pp 566When 567.Fl auto 568or 569.Fl ddial 570is specified, 571.Nm 572runs as a daemon but you can still configure or examine its 573configuration by using the 574.Dq set server 575command in 576.Pa /etc/ppp/ppp.conf , 577.Pq for example, Dq set server +3000 mypasswd 578and connecting to the diagnostic port as follows: 579.Bd -literal -offset indent 580# pppctl 3000 (assuming tun0 - see the ``set server'' description) 581Password: 582PPP ON awfulhak> show who 583tcp (127.0.0.1:1028) * 584.Ed 585.Pp 586The 587.Dq show who 588command lists users that are currently connected to 589.Nm 590itself. If the diagnostic socket is closed or changed to a different 591socket, all connections are immediately dropped. 592.Pp 593In 594.Fl auto 595mode, when an outgoing packet is detected, 596.Nm 597will perform the dialing action (chat script) and try to connect 598with the peer. In 599.Fl ddial 600mode, the dialing action is performed any time the line is found 601to be down. 602If the connect fails, the default behaviour is to wait 30 seconds 603and then attempt to connect when another outgoing packet is detected. 604This behaviour can be changed with 605.Bd -literal -offset indent 606set redial seconds|random[.nseconds|random] [dial_attempts] 607.Ed 608.Pp 609.Sq Seconds 610is the number of seconds to wait before attempting 611to connect again. If the argument is 612.Sq random , 613the delay period is a random value between 0 and 30 seconds. 614.Sq Nseconds 615is the number of seconds to wait before attempting 616to dial the next number in a list of numbers (see the 617.Dq set phone 618command). The default is 3 seconds. Again, if the argument is 619.Sq random , 620the delay period is a random value between 0 and 30 seconds. 621.Sq dial_attempts 622is the number of times to try to connect for each outgoing packet 623that is received. The previous value is unchanged if this parameter 624is omitted. If a value of zero is specified for 625.Sq dial_attempts , 626.Nm 627will keep trying until a connection is made. 628.Bd -literal -offset indent 629set redial 10.3 4 630.Ed 631.Pp 632will attempt to connect 4 times for each outgoing packet that is 633detected with a 3 second delay between each number and a 10 second 634delay after all numbers have been tried. If multiple phone numbers 635are specified, the total number of attempts is still 4 (it does not 636attempt each number 4 times). 637Modifying the dial delay is very useful when running 638.Nm 639in demand 640dial mode on both ends of the link. If each end has the same timeout, 641both ends wind up calling each other at the same time if the link 642drops and both ends have packets queued. 643At some locations, the serial link may not be reliable, and carrier 644may be lost at inappropriate times. It is possible to have 645.Nm 646redial should carrier be unexpectedly lost during a session. 647.Bd -literal -offset indent 648set reconnect timeout ntries 649.Ed 650.Pp 651This command tells 652.Nm 653to re-establish the connection 654.Ar ntries 655times on loss of carrier with a pause of 656.Ar timeout 657seconds before each try. For example, 658.Bd -literal -offset indent 659set reconnect 3 5 660.Ed 661.Pp 662tells 663.Nm 664that on an unexpected loss of carrier, it should wait 665.Ar 3 666seconds before attempting to reconnect. This may happen up to 667.Ar 5 668times before 669.Nm 670gives up. The default value of ntries is zero (no reconnect). Care 671should be taken with this option. If the local timeout is slightly 672longer than the remote timeout, the reconnect feature will always be 673triggered (up to the given number of times) after the remote side 674times out and hangs up. 675NOTE: In this context, losing too many LQRs constitutes a loss of 676carrier and will trigger a reconnect. 677If the 678.Fl background 679flag is specified, all phone numbers are dialed at most once until 680a connection is made. The next number redial period specified with 681the 682.Dq set redial 683command is honoured, as is the reconnect tries value. If your redial 684value is less than the number of phone numbers specified, not all 685the specified numbers will be tried. 686To terminate the program, type 687.Bd -literal -offset indent 688PPP ON awfulhak> close 689ppp ON awfulhak> quit all 690.Ed 691.Pp 692A simple 693.Dq quit 694command will terminate the 695.Xr pppctl 8 696or 697.Xr telnet 1 698connection but not the 699.Nm 700program itself. 701You must use 702.Dq quit all 703to terminate 704.Nm 705as well. 706.Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1) 707To handle an incoming 708.Em PPP 709connection request, follow these steps: 710.Bl -enum 711.It 712Make sure the modem and (optionally) 713.Pa /etc/rc.serial 714is configured correctly. 715.Bl -bullet -compact 716.It 717Use Hardware Handshake (CTS/RTS) for flow control. 718.It 719Modem should be set to NO echo back (ATE0) and NO results string (ATQ1). 720.El 721.Pp 722.It 723Edit 724.Pa /etc/ttys 725to enable a 726.Xr getty 8 727on the port where the modem is attached. 728For example: 729.Pp 730.Dl ttyd1 "/usr/libexec/getty std.38400" dialup on secure 731.Pp 732Don't forget to send a 733.Dv HUP 734signal to the 735.Xr init 8 736process to start the 737.Xr getty 8 : 738.Pp 739.Dl # kill -HUP 1 740.It 741Create a 742.Pa /usr/local/bin/ppplogin 743file with the following contents: 744.Bd -literal -offset indent 745#! /bin/sh 746exec /usr/sbin/ppp -direct incoming 747.Ed 748.Pp 749Direct mode 750.Pq Fl direct 751lets 752.Nm 753work with stdin and stdout. You can also use 754.Xr pppctl 8 755to connect to a configured diagnostic port, in the same manner as with 756client-side 757.Nm ppp . 758.Pp 759Here, the 760.Ar incoming 761section must be set up in 762.Pa /etc/ppp/ppp.conf . 763.Pp 764Make sure that the 765.Ar incoming 766section contains the 767.Dq allow users 768command as appropriate. 769.It 770Prepare an account for the incoming user. 771.Bd -literal 772ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin 773.Ed 774.Pp 775Refer to the manual entries for 776.Xr adduser 8 777and 778.Xr vipw 8 779for details. 780.It 781Support for IPCP Domain Name Server and NetBIOS Name Server negotiation 782can be enabled using the 783.Dq accept dns 784and 785.Dq set nbns 786commands. Refer to their descriptions below. 787.El 788.Pp 789.Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2) 790This method differs in that we use 791.Nm ppp 792to authenticate the connection rather than 793.Xr login 1 : 794.Bl -enum 795.It 796Configure your default section in 797.Pa /etc/gettytab 798with automatic ppp recognition by specifying the 799.Dq pp 800capability: 801.Bd -literal 802default:\\ 803 :pp=/usr/local/bin/ppplogin:\\ 804 ..... 805.Ed 806.It 807Configure your serial device(s), enable a 808.Xr getty 8 809and create 810.Pa /usr/local/bin/ppplogin 811as in the first three steps for method 1 above. 812.It 813Add either 814.Dq enable chap 815or 816.Dq enable pap 817.Pq or both 818to 819.Pa /etc/ppp/ppp.conf 820under the 821.Sq incoming 822label (or whatever label 823.Pa ppplogin 824uses). 825.It 826Create an entry in 827.Pa /etc/ppp/ppp.secret 828for each incoming user: 829.Bd -literal 830Pfred<TAB>xxxx 831Pgeorge<TAB>yyyy 832.Ed 833.El 834.Pp 835Now, as soon as 836.Xr getty 8 837detects a ppp connection (by recognising the HDLC frame headers), it runs 838.Dq /usr/local/bin/ppplogin . 839.Pp 840It is 841.Em VITAL 842that either PAP or CHAP are enabled as above. If they are not, you are 843allowing anybody to establish ppp session with your machine 844.Em without 845a password, opening yourself up to all sorts of potential attacks. 846.Sh AUTHENTICATING INCOMING CONNECTIONS 847Normally, the receiver of a connection requires that the peer 848authenticates itself. This may be done using 849.Xr login 1 , 850but alternatively, you can use PAP or CHAP. CHAP is the more secure 851of the two, but some clients may not support it. Once you decide which 852you wish to use, add the command 853.Sq enable chap 854or 855.Sq enable pap 856to the relevant section of 857.Pa ppp.conf . 858.Pp 859You must then configure the 860.Pa /etc/ppp/ppp.secret 861file. This file contains one line per possible client, each line 862containing up to four fields: 863.Bd -literal -offset indent 864name key [hisaddr [label]] 865.Ed 866.Pp 867The 868.Ar name 869and 870.Ar key 871specify the client as expected. If 872.Ar key 873is 874.Dq \&* 875and PAP is being used, 876.Nm 877will look up the password database 878.Pq Xr passwd 5 879when authenticating. If the client does not offer a suitable 880response based on any 881.Ar name No / Ar key 882combination in 883.Pa ppp.secret , 884authentication fails. 885.Pp 886If authentication is successful, 887.Ar hisaddr 888.Pq if specified 889is used when negotiating IP numbers. See the 890.Dq set ifaddr 891command for details. 892.Pp 893If authentication is successful and 894.Ar label 895is specified, the current system label is changed to match the given 896.Ar label . 897This will change the subsequent parsing of the 898.Pa ppp.linkup 899and 900.Pa ppp.linkdown 901files. 902.Sh PPP OVER TCP (a.k.a Tunnelling) 903Instead of running 904.Nm 905over a serial link, it is possible to 906use a TCP connection instead by specifying a host and port as the 907device: 908.Dl set device ui-gate:6669 909Instead of opening a serial device, 910.Nm 911will open a TCP connection to the given machine on the given 912socket. It should be noted however that 913.Nm 914doesn't use the telnet protocol and will be unable to negotiate 915with a telnet server. You should set up a port for receiving this 916.Em PPP 917connection on the receiving machine (ui-gate). This is 918done by first updating 919.Pa /etc/services 920to name the service: 921.Dl ppp-in 6669/tcp # Incoming PPP connections over TCP 922and updating 923.Pa /etc/inetd.conf 924to tell 925.Xr inetd 8 926how to deal with incoming connections on that port: 927.Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in 928Don't forget to send a 929.Dv HUP 930signal to 931.Xr inetd 8 932after you've updated 933.Pa /etc/inetd.conf . 934Here, we use a label named 935.Dq ppp-in . 936The entry in 937.Pa /etc/ppp/ppp.conf 938on ui-gate (the receiver) should contain the following: 939.Bd -literal -offset indent 940ppp-in: 941 set timeout 0 942 set ifaddr 10.0.4.1 10.0.4.2 943 add 10.0.1.0/24 10.0.4.2 944.Ed 945.Pp 946You may also want to enable PAP or CHAP for security. To enable PAP, add 947the following line: 948.Bd -literal -offset indent 949 enable PAP 950.Ed 951.Pp 952You'll also need to create the following entry in 953.Pa /etc/ppp/ppp.secret : 954.Bd -literal -offset indent 955MyAuthName MyAuthPasswd 956.Ed 957.Pp 958If 959.Ar MyAuthPasswd 960is a 961.Pq Dq * , 962the password is looked up in the 963.Xr passwd 5 964database. 965.Pp 966The entry in 967.Pa /etc/ppp/ppp.conf 968on awfulhak (the initiator) should contain the following: 969.Bd -literal -offset indent 970ui-gate: 971 set escape 0xff 972 set device ui-gate:ppp-in 973 set dial 974 set timeout 30 975 set log Phase Chat Connect hdlc LCP IPCP CCP tun 976 set ifaddr 10.0.4.2 10.0.4.1 977 add 10.0.2.0/24 10.0.4.1 978.Ed 979.Pp 980Again, if you're enabling PAP, you'll also need: 981.Bd -literal -offset indent 982 set authname MyAuthName 983 set authkey MyAuthKey 984.Ed 985.Pp 986We're assigning the address of 10.0.4.1 to ui-gate, and the address 98710.0.4.2 to awfulhak. 988To open the connection, just type 989.Dl awfulhak # ppp -background ui-gate 990The result will be an additional "route" on awfulhak to the 99110.0.2.0/24 network via the TCP connection, and an additional 992"route" on ui-gate to the 10.0.1.0/24 network. 993The networks are effectively bridged - the underlying TCP 994connection may be across a public network (such as the 995Internet), and the 996.Em PPP 997traffic is conceptually encapsulated 998(although not packet by packet) inside the TCP stream between 999the two gateways. 1000The major disadvantage of this mechanism is that there are two 1001"guaranteed delivery" mechanisms in place - the underlying TCP 1002stream and whatever protocol is used over the 1003.Em PPP 1004link - probably TCP again. If packets are lost, both levels will 1005get in each others way trying to negotiate sending of the missing 1006packet. 1007.Sh PACKET ALIASING 1008The 1009.Fl alias 1010command line option enables packet aliasing. This allows the 1011.Nm 1012host to act as a masquerading gateway for other computers over 1013a local area network. Outgoing IP packets are aliased so that 1014they appear to come from the 1015.Nm 1016host, and incoming packets are de-aliased so that they are routed 1017to the correct machine on the local area network. 1018Packet aliasing allows computers on private, unregistered 1019subnets to have Internet access, although they are invisible 1020from the outside world. 1021In general, correct 1022.Nm 1023operation should first be verified with packet aliasing disabled. 1024Then, the 1025.Fl alias 1026option should be switched on, and network applications (web browser, 1027.Xr telnet 1 , 1028.Xr ftp 1 , 1029.Xr ping 8 , 1030.Xr traceroute 8 ) 1031should be checked on the 1032.Nm 1033host. Finally, the same or similar applications should be checked on other 1034computers in the LAN. 1035If network applications work correctly on the 1036.Nm 1037host, but not on other machines in the LAN, then the masquerading 1038software is working properly, but the host is either not forwarding 1039or possibly receiving IP packets. Check that IP forwarding is enabled in 1040.Pa /etc/rc.conf 1041and that other machines have designated the 1042.Nm 1043host as the gateway for the LAN. 1044.Sh PACKET FILTERING 1045This implementation supports packet filtering. There are four kinds of 1046filters; the 1047.Em in 1048filter, the 1049.Em out 1050filter, the 1051.Em dial 1052filter and the 1053.Em alive 1054filter. Here are the basics: 1055.Bl -bullet 1056.It 1057A filter definition has the following syntax: 1058.Pp 1059set filter 1060.Ar name 1061.Ar rule-no 1062.Ar action 1063.Op Ar src_addr Ns Op / Ns Ar width 1064.Op Ar dst_addr Ns Op / Ns Ar width 1065[ 1066.Ar proto 1067.Op src Op Ar cmp No Ar port 1068.Op dst Op Ar cmp No Ar port 1069.Op estab 1070.Op syn 1071.Op finrst 1072] 1073.Bl -enum 1074.It 1075.Ar Name 1076should be one of 1077.Sq in , 1078.Sq out , 1079.Sq dial 1080or 1081.Sq alive . 1082.It 1083.Ar Rule-no 1084is a numeric value between 1085.Sq 0 1086and 1087.Sq 19 1088specifying the rule number. Rules are specified in numeric order according to 1089.Ar rule-no , 1090but only if rule 1091.Sq 0 1092is defined. 1093.It 1094.Ar Action 1095is either 1096.Sq permit 1097or 1098.Sq deny . 1099If a given packet 1100matches the rule, the associated action is taken immediately. 1101.It 1102.Op Ar src_addr Ns Op / Ns Ar width 1103and 1104.Op Ar dst_addr Ns Op / Ns Ar width 1105are the source and destination IP number specifications. If 1106.Op / Ns Ar width 1107is specified, it gives the number of relevant netmask bits, 1108allowing the specification of an address range. 1109.It 1110.Ar Proto 1111must be one of 1112.Sq icmp , 1113.Sq udp 1114or 1115.Sq tcp . 1116.It 1117.Ar Cmp 1118is one of 1119.Sq \< , 1120.Sq \&eq 1121or 1122.Sq \> , 1123meaning less-than, equal and greater-than respectively. 1124.Ar Port 1125can be specified as a numeric port or by service name from 1126.Pa /etc/services . 1127.It 1128The 1129.Sq estab , 1130.Sq syn , 1131and 1132.Sq finrst 1133flags are only allowed when 1134.Ar proto 1135is set to 1136.Sq tcp , 1137and represent the TH_ACK, TH_SYN and TH_FIN or TH_RST TCP flags respectively. 1138.El 1139.Pp 1140.It 1141Each filter can hold up to 20 rules, starting from rule 0. 1142The entire rule set is not effective until rule 0 is defined, 1143ie. the default is to allow everything through. 1144.It 1145If no rule is matched to a packet, that packet will be discarded 1146(blocked). 1147.It 1148Use 1149.Dq set filter Ar name No -1 1150to flush all rules. 1151.El 1152.Pp 1153See 1154.Pa /etc/ppp/ppp.conf.example . 1155.Sh SETTING THE IDLE TIMER 1156To check/set the idle timer, use the 1157.Dq show bundle 1158and 1159.Dq set timeout 1160commands: 1161.Bd -literal -offset indent 1162ppp ON awfulhak> set timeout 600 1163.Ed 1164.Pp 1165The timeout period is measured in seconds, the default value for which 1166is 180 seconds 1167.Pq or 3 min . 1168To disable the idle timer function, use the command 1169.Bd -literal -offset indent 1170ppp ON awfulhak> set timeout 0 1171.Ed 1172.Pp 1173In 1174.Fl ddial 1175and 1176.Fl direct 1177modes, the idle timeout is ignored. In 1178.Fl auto 1179mode, when the idle timeout causes the 1180.Em PPP 1181session to be 1182closed, the 1183.Nm 1184program itself remains running. Another trigger packet will cause it to 1185attempt to re-establish the link. 1186.Sh PREDICTOR-1 and DEFLATE COMPRESSION 1187.Nm Ppp 1188supports both Predictor type 1 and deflate compression. 1189By default, 1190.Nm 1191will attempt to use (or be willing to accept) both compression protocols 1192when the peer agrees 1193.Pq or requests them . 1194The deflate protocol is preferred by 1195.Nm ppp . 1196Refer to the 1197.Dq disable 1198and 1199.Dq deny 1200commands if you wish to disable this functionality. 1201.Pp 1202It is possible to use a different compression algorithm in each direction 1203by using only one of 1204.Dq disable deflate 1205and 1206.Dq deny deflate 1207.Pq assuming that the peer supports both algorithms . 1208.Pp 1209By default, when negotiating DEFLATE, 1210.Nm 1211will use a window size of 15. Refer to the 1212.Dq set deflate 1213command if you wish to change this behaviour. 1214.Pp 1215A special algorithm called DEFLATE24 is also available, and is disabled 1216and denied by default. This is exactly the same as DEFLATE except that 1217it uses CCP ID 24 to negotiate. This allows 1218.Nm 1219to successfully negotiate DEFLATE with 1220.Nm pppd 1221version 2.3.*. 1222.Sh CONTROLLING IP ADDRESS 1223.Nm 1224uses IPCP to negotiate IP addresses. Each side of the connection 1225specifies the IP address that it's willing to use, and if the requested 1226IP address is acceptable then 1227.Nm 1228returns ACK to the requester. Otherwise, 1229.Nm 1230returns NAK to suggest that the peer use a different IP address. When 1231both sides of the connection agree to accept the received request (and 1232send ACK), IPCP is set to the open state and a network level connection 1233is established. 1234To control this IPCP behaviour, this implementation has the 1235.Dq set ifaddr 1236command for defining the local and remote IP address: 1237.Bd -literal -offset indent 1238set ifaddr [src_addr [dst_addr [netmask [trigger_addr]]]] 1239.Ed 1240.Pp 1241where, 1242.Sq src_addr 1243is the IP address that the local side is willing to use, 1244.Sq dst_addr 1245is the IP address which the remote side should use and 1246.Sq netmask 1247is the netmask that should be used. 1248.Sq Src_addr 1249defaults to the current 1250.Xr hostname 1 , 1251.Sq dst_addr 1252defaults to 0.0.0.0, and 1253.Sq netmask 1254defaults to whatever mask is appropriate for 1255.Sq src_addr . 1256It is only possible to make 1257.Sq netmask 1258smaller than the default. The usual value is 255.255.255.255, as 1259most kernels ignore the netmask of a POINTOPOINT interface. 1260.Pp 1261Some incorrect 1262.Em PPP 1263implementations require that the peer negotiates a specific IP 1264address instead of 1265.Sq src_addr . 1266If this is the case, 1267.Sq trigger_addr 1268may be used to specify this IP number. This will not affect the 1269routing table unless the other side agrees with this proposed number. 1270.Bd -literal -offset indent 1271set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0 1272.Ed 1273.Pp 1274The above specification means: 1275.Pp 1276.Bl -bullet -compact 1277.It 1278I will first suggest that my IP address should be 0.0.0.0, but I 1279will only accept an address of 192.244.177.38. 1280.It 1281I strongly insist that the peer uses 192.244.177.2 as his own 1282address and won't permit the use of any IP address but 192.244.177.2. 1283When the peer requests another IP address, I will always suggest that 1284it uses 192.244.177.2. 1285.It 1286The routing table entry will have a netmask of 0xffffffff. 1287.El 1288.Pp 1289This is all fine when each side has a pre-determined IP address, however 1290it is often the case that one side is acting as a server which controls 1291all IP addresses and the other side should obey the direction from it. 1292In order to allow more flexible behaviour, `ifaddr' variable allows the 1293user to specify IP address more loosely: 1294.Pp 1295.Dl set ifaddr 192.244.177.38/24 192.244.177.2/20 1296.Pp 1297A number followed by a slash (/) represent the number of bits significant in 1298the IP address. The above example signifies that: 1299.Pp 1300.Bl -bullet -compact 1301.It 1302I'd like to use 192.244.177.38 as my address if it is possible, but I'll 1303also accept any IP address between 192.244.177.0 and 192.244.177.255. 1304.It 1305I'd like to make him use 192.244.177.2 as his own address, but I'll also 1306permit him to use any IP address between 192.244.176.0 and 1307192.244.191.255. 1308.It 1309As you may have already noticed, 192.244.177.2 is equivalent to saying 1310192.244.177.2/32. 1311.It 1312As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no 1313preferred IP address and will obey the remote peers selection. When 1314using zero, no routing table entries will be made until a connection 1315is established. 1316.It 1317192.244.177.2/0 means that I'll accept/permit any IP address but I'll 1318try to insist that 192.244.177.2 be used first. 1319.El 1320.Pp 1321.Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER 1322The following steps should be taken when connecting to your ISP: 1323.Bl -enum 1324.It 1325Describe your providers phone number(s) in the dial script using the 1326.Dq set phone 1327command. This command allows you to set multiple phone numbers for 1328dialing and redialing separated by either a pipe (|) or a colon (:) 1329.Bd -literal -offset indent 1330set phone "111[|222]...[:333[|444]...]... 1331.Ed 1332.Pp 1333Numbers after the first in a pipe-separated list are only used if the 1334previous number was used in a failed dial or login script. Numbers 1335separated by a colon are used sequentially, irrespective of what happened 1336as a result of using the previous number. For example: 1337.Bd -literal -offset indent 1338set phone "1234567|2345678:3456789|4567890" 1339.Ed 1340.Pp 1341Here, the 1234567 number is attempted. If the dial or login script fails, 1342the 2345678 number is used next time, but *only* if the dial or login script 1343fails. On the dial after this, the 3456789 number is used. The 4567890 1344number is only used if the dial or login script using the 3456789 fails. If 1345the login script of the 2345678 number fails, the next number is still the 13463456789 number. As many pipes and colons can be used as are necessary 1347(although a given site would usually prefer to use either the pipe or the 1348colon, but not both). The next number redial timeout is used between all 1349numbers. When the end of the list is reached, the normal redial period is 1350used before starting at the beginning again. 1351The selected phone number is substituted for the \\\\T string in the 1352.Dq set dial 1353command (see below). 1354.It 1355Set up your redial requirements using 1356.Dq set redial . 1357For example, if you have a bad telephone line or your provider is 1358usually engaged (not so common these days), you may want to specify 1359the following: 1360.Bd -literal -offset indent 1361set redial 10 4 1362.Ed 1363.Pp 1364This says that up to 4 phone calls should be attempted with a pause of 10 1365seconds before dialing the first number again. 1366.It 1367Describe your login procedure using the 1368.Dq set dial 1369and 1370.Dq set login 1371commands. The 1372.Dq set dial 1373command is used to talk to your modem and establish a link with your 1374ISP, for example: 1375.Bd -literal -offset indent 1376set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" \e 1377 ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT" 1378.Ed 1379.Pp 1380This modem "chat" string means: 1381.Bl -bullet 1382.It 1383Abort if the string "BUSY" or "NO CARRIER" are received. 1384.It 1385Set the timeout to 4 seconds. 1386.It 1387Expect nothing. 1388.It 1389Send ATZ. 1390.It 1391Expect OK. If that's not received within the 4 second timeout, send ATZ 1392and expect OK. 1393.It 1394Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from 1395above. 1396.It 1397Set the timeout to 60. 1398.It 1399Wait for the CONNECT string. 1400.El 1401.Pp 1402Once the connection is established, the login script is executed. This 1403script is written in the same style as the dial script, but care should 1404be taken to avoid having your password logged: 1405.Bd -literal -offset indent 1406set authkey MySecret 1407set login "TIMEOUT 15 login:-\\\\r-login: awfulhak \e 1408 word: \\\\P ocol: PPP HELLO" 1409.Ed 1410.Pp 1411This login "chat" string means: 1412.Bl -bullet 1413.It 1414Set the timeout to 15 seconds. 1415.It 1416Expect "login:". If it's not received, send a carriage return and expect 1417"login:" again. 1418.It 1419Send "awfulhak" 1420.It 1421Expect "word:" (the tail end of a "Password:" prompt). 1422.It 1423Send whatever our current 1424.Ar authkey 1425value is set to. 1426.It 1427Expect "ocol:" (the tail end of a "Protocol:" prompt). 1428.It 1429Send "PPP". 1430.It 1431Expect "HELLO". 1432.El 1433.Pp 1434The 1435.Dq set authkey 1436command is logged specially (when using 1437.Ar command 1438logging) so that the actual password is not compromised 1439(it is logged as 1440.Sq ******** Ns 1441), and the '\\P' is logged when 1442.Ar chat 1443logging is active rather than the actual password. 1444.Pp 1445Login scripts vary greatly between ISPs. 1446.It 1447Use 1448.Dq set line 1449and 1450.Dq set speed 1451to specify your serial line and speed, for example: 1452.Bd -literal -offset indent 1453set line /dev/cuaa0 1454set speed 115200 1455.Ed 1456.Pp 1457Cuaa0 is the first serial port on FreeBSD. If you're running 1458.Nm 1459on OpenBSD, cua00 is the first. A speed of 115200 should be specified 1460if you have a modem capable of bit rates of 28800 or more. In general, 1461the serial speed should be about four times the modem speed. 1462.It 1463Use the 1464.Dq set ifaddr 1465command to define the IP address. 1466.Bl -bullet 1467.It 1468If you know what IP address your provider uses, then use it as the remote 1469address (dst_addr), otherwise choose something like 10.0.0.2/0 (see below). 1470.It 1471If your provider has assigned a particular IP address to you, then use 1472it as your address (src_addr). 1473.It 1474If your provider assigns your address dynamically, choose a suitably 1475unobtrusive and unspecific IP number as your address. 10.0.0.1/0 would 1476be appropriate. The bit after the / specifies how many bits of the 1477address you consider to be important, so if you wanted to insist on 1478something in the class C network 1.2.3.0, you could specify 1.2.3.1/24. 1479.It 1480If you find that your ISP accepts the first IP number that you suggest, 1481specify third and forth arguments of 1482.Dq 0.0.0.0 . 1483This will force your ISP to assign a number. (The third argument will 1484be ignored as it is less restrictive than the default mask for your 1485.Sq src_addr . 1486.El 1487.Pp 1488An example for a connection where you don't know your IP number or your 1489ISPs IP number would be: 1490.Bd -literal -offset indent 1491set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0 1492.Ed 1493.Pp 1494.It 1495In most cases, your ISP will also be your default router. If this is 1496the case, add the line 1497.Bd -literal -offset indent 1498add default HISADDR 1499.Ed 1500.Pp 1501to 1502.Pa /etc/ppp/ppp.conf . 1503.Pp 1504This tells 1505.Nm 1506to add a default route to whatever the peer address is 1507.Pq 10.0.0.2 in this example . 1508This route is 1509.Sq sticky , 1510meaning that should the value of 1511.Dv HISADDR 1512change, the route will be updated accordingly. 1513.Pp 1514Previous versions of 1515.Nm 1516required a similar entry in the 1517.Pa /etc/ppp/ppp.linkup 1518file. Since the advent of 1519.Sq sticky routes , 1520his is no longer required. 1521.It 1522If your provider requests that you use PAP/CHAP authentication methods, add 1523the next lines to your 1524.Pa /etc/ppp/ppp.conf 1525file: 1526.Bd -literal -offset indent 1527set authname MyName 1528set authkey MyPassword 1529.Ed 1530.Pp 1531Both are accepted by default, so 1532.Nm 1533will provide whatever your ISP requires. 1534.El 1535.Pp 1536Please refer to 1537.Pa /etc/ppp/ppp.conf.sample 1538and 1539.Pa /etc/ppp/ppp.linkup.sample 1540for some real examples. The pmdemand label should be appropriate for most 1541ISPs. 1542.Sh LOGGING FACILITY 1543.Nm 1544is able to generate the following log info either via 1545.Xr syslog 3 1546or directly to the screen: 1547.Bl -column SMMMMMM -offset indent 1548.It Li Async Dump async level packet in hex 1549.It Li CCP Generate a CCP packet trace 1550.It Li Chat Generate Chat script trace log 1551.It Li Command Log commands executed 1552.It Li Connect Generate complete Chat log 1553.It Li Debug Log debug information 1554.It Li HDLC Dump HDLC packet in hex 1555.It Li ID0 Log all function calls specifically made as user id 0. 1556.It Li IPCP Generate an IPCP packet trace 1557.It Li LCP Generate an LCP packet trace 1558.It Li LQM Generate LQR report 1559.It Li Phase Phase transition log output 1560.It Li TCP/IP Dump all TCP/IP packets 1561.It Li Timer Log timer manipulation 1562.It Li TUN Include the tun device on each log line 1563.It Li Warning Output to the terminal device. If there is currently no 1564terminal, output is sent to the log file using LOG_WARNING. 1565.It Li Error Output to both the terminal device and the log file using 1566LOG_ERROR. 1567.It Li Alert Output to the log file using LOG_ALERT 1568.El 1569.Pp 1570The 1571.Dq set log 1572command allows you to set the logging output level. Multiple levels 1573can be specified on a single command line. The default is equivalent to 1574.Dq set log Phase . 1575.Pp 1576It is also possible to log directly to the screen. The syntax is 1577the same except that the word 1578.Dq local 1579should immediately follow 1580.Dq set log . 1581The default is 1582.Dq set log local 1583(ie. only the un-maskable warning, error and alert output). 1584.Pp 1585If The first argument to 1586.Dq set log Op local 1587begins with a '+' or a '-' character, the current log levels are 1588not cleared, for example: 1589.Bd -literal -offset indent 1590PPP ON awfulhak> set log phase 1591PPP ON awfulhak> show log 1592Log: Phase Warning Error Alert 1593Local: Warning Error Alert 1594PPP ON awfulhak> set log +tcp/ip -warning 1595PPP ON awfulhak> set log local +command 1596PPP ON awfulhak> show log 1597Log: Phase TCP/IP Warning Error Alert 1598Local: Command Warning Error Alert 1599.Ed 1600.Pp 1601Log messages of level Warning, Error and Alert are not controllable 1602using 1603.Dq set log Op local . 1604.Pp 1605The 1606.Ar Warning 1607level is special in that it will not be logged if it can be displayed 1608locally. 1609.Sh SIGNAL HANDLING 1610.Nm Ppp 1611deals with the following signals: 1612.Bl -tag -width 20 1613.It INT 1614Receipt of this signal causes the termination of the current connection 1615(if any). This will cause 1616.Nm 1617to exit unless it is in 1618.Fl auto 1619or 1620.Fl ddial 1621mode. 1622.It HUP, TERM & QUIT 1623These signals tell 1624.Nm 1625to exit. 1626.It USR2 1627This signal, tells 1628.Nm 1629to close any existing server socket, dropping all existing diagnostic 1630connections. 1631.El 1632.Pp 1633.Sh MULTI-LINK PPP 1634If you wish to use more than one physical link to connect to a 1635.Em PPP 1636peer, that peer must also understand the 1637.Em MULTI-LINK PPP 1638protocol. Refer to RFC 1990 for specification details. 1639.Pp 1640The peer is identified using a combination of his 1641.Dq endpoint discriminator 1642and his 1643.Dq authentication id . 1644Either or both of these may be specified. It is recommended that 1645at least one is specified, otherwise there is no way of ensuring that 1646all links are actually connected to the same peer program, and some 1647confusing lock-ups may result. Locally, these identification variables 1648are specified using the 1649.Dq set enddisc 1650and 1651.Dq set authname 1652commands. The 1653.Sq authname 1654.Pq and Sq authkey 1655must be agreed in advance with the peer. 1656.Pp 1657Multi-link capabilities are enabled using the 1658.Dq set mrru 1659command (set maximum reconstructed receive unit). Once multi-link 1660is enabled, 1661.Nm 1662will attempt to negotiate a multi-link connection with the peer. 1663.Pp 1664By default, only one 1665.Sq link 1666is available 1667.Pq called Sq deflink . 1668To create more links, the 1669.Dq clone 1670command is used. This command will clone existing links, where all 1671characteristics are the same except: 1672.Bl -enum 1673.It 1674The new link has its own name as specified on the 1675.Dq clone 1676command line. 1677.It 1678The new link is an 1679.Sq interactive 1680link. It's mode may subsequently be changed using the 1681.Dq set mode 1682command. 1683.It 1684The new link is in a 1685.Sq closed 1686state. 1687.El 1688.Pp 1689A summary of all available links can be seen using the 1690.Dq show links 1691command. 1692.Pp 1693Once a new link has been created, command usage varies. All link 1694specific commands must be prefixed with the 1695.Dq link Ar name 1696command, specifying on which link the command is to be applied. When 1697only a single link is available, 1698.Nm 1699is smart enough not to require the 1700.Dq link Ar name 1701prefix. 1702.Pp 1703Some commands can still be used without specifying a link - resulting 1704in an operation at the 1705.Sq bundle 1706level. For example, once two or more links are available, the command 1707.Dq show ccp 1708will show CCP configuration and statistics at the multi-link level, and 1709.Dq link deflink show ccp 1710will show the same information at the 1711.Dq deflink 1712link level. 1713.Pp 1714Armed with this information, the following configuration might be used: 1715.Pp 1716.Bd -literal -offset indent 1717mp: 1718 set timeout 0 1719 set log phase chat 1720 set device /dev/cuaa0 /dev/cuaa1 /dev/cuaa2 1721 set phone "123456789" 1722 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \\"\\" ATZ \e 1723 OK-AT-OK \\\\dATDT\\\\T TIMEOUT 45 CONNECT" 1724 set login 1725 set ifaddr 10.0.0.1/0 10.0.0.2/0 1726 set authname ppp 1727 set authkey ppppassword 1728 1729 set mrru 1500 1730 clone 1,2,3 1731 link deflink remove 1732.Ed 1733.Pp 1734Note how all cloning is done at the end of the configuration. Usually, 1735the link will be configured first, then cloned. If you wish all links 1736to be up all the time, you can add the following line to the end of your 1737configuration. 1738.Pp 1739.Bd -literal -offset indent 1740 link 1,2,3 set mode ddial 1741.Ed 1742.Pp 1743If you want the links to dial on demand, this command could be used: 1744.Pp 1745.Bd -literal -offset indent 1746 link * set mode auto 1747.Ed 1748.Pp 1749Links may be tied to specific names by removing the 1750.Dq set device 1751line above, and specifying the following after the 1752.Dq clone 1753command: 1754.Pp 1755.Bd -literal -offset indent 1756 link 1 set device /dev/cuaa0 1757 link 2 set device /dev/cuaa1 1758 link 3 set device /dev/cuaa2 1759.Ed 1760.Pp 1761Use the 1762.Dq help 1763command to see which commands require context (using the 1764.Dq link 1765command), which have optional 1766context and which should not have any context. 1767.Pp 1768When 1769.Nm 1770has negotiated 1771.Em MULTI-LINK 1772mode with the peer, it creates a local domain socket in the 1773.Pa /var/run 1774directory. This socket is used to pass link information (including 1775the actual link file descriptor) between different 1776.Nm 1777invocations. This facilitates 1778.Nm ppp Ns No s 1779ability to be run from a 1780.Xr getty 8 1781or directly from 1782.Pa /etc/gettydefs 1783(using the 1784.Sq pp= 1785capability), without needing to have initial control of the serial 1786line. Once 1787.Nm 1788negotiates multi-link mode, it will pass its open link to any 1789already running process. If there is no already running process, 1790.Nm 1791will act as the master, creating the socket and listening for new 1792connections. 1793.Sh PPP COMMAND LIST 1794This section lists the available commands and their effect. They are 1795usable either from an interactive 1796.Nm 1797session, from a configuration file or from a 1798.Xr pppctl 8 1799or 1800.Xr telnet 1 1801session. 1802.Bl -tag -width 20 1803.It accept|deny|enable|disable Ar option.... 1804These directives tell 1805.Nm 1806how to negotiate the initial connection with the peer. Each 1807.Dq option 1808has a default of either accept or deny and enable or disable. 1809.Dq Accept 1810means that the option will be ACK'd if the peer asks for it. 1811.Dq Deny 1812means that the option will be NAK'd if the peer asks for it. 1813.Dq Enable 1814means that the option will be requested by us. 1815.Dq Disable 1816means that the option will not be requested by us. 1817.Pp 1818.Dq Option 1819may be one of the following: 1820.Bl -tag -width 20 1821.It acfcomp 1822Default: Enabled and Accepted. ACFComp stands for Address and Control 1823Field Compression. Non LCP packets usually have very similar address 1824and control fields - making them easily compressible. 1825.It chap 1826Default: Disabled and Accepted. CHAP stands for Challenge Handshake 1827Authentication Protocol. Only one of CHAP and PAP (below) may be 1828negotiated. With CHAP, the authenticator sends a "challenge" message 1829to its peer. The peer uses a one-way hash function to encrypt the 1830challenge and sends the result back. The authenticator does the same, 1831and compares the results. The advantage of this mechanism is that no 1832passwords are sent across the connection. 1833A challenge is made when the connection is first made. Subsequent 1834challenges may occur. If you want to have your peer authenticate 1835itself, you must 1836.Dq enable chap . 1837in 1838.Pa /etc/ppp/ppp.conf , 1839and have an entry in 1840.Pa /etc/ppp/ppp.secret 1841for the peer. 1842.Pp 1843When using CHAP as the client, you need only specify 1844.Dq AuthName 1845and 1846.Dq AuthKey 1847in 1848.Pa /etc/ppp/ppp.conf . 1849CHAP is accepted by default. 1850Some 1851.Em PPP 1852implementations use "MS-CHAP" rather than MD5 when encrypting the 1853challenge. MS-CHAP is a combination of MD4 and DES. If 1854.Nm 1855was built on a machine with DES libraries available, it will respond 1856to MS-CHAP authentication requests, but will never request them. 1857.It deflate 1858Default: Enabled and Accepted. This option decides if deflate 1859compression will be used by the Compression Control Protocol (CCP). 1860This is the same algorithm as used by the 1861.Xr gzip 1 1862program. 1863Note: There is a problem negotiating 1864.Ar deflate 1865capabilities with 1866.Xr pppd 8 1867- a 1868.Em PPP 1869implementation available under many operating systems. 1870.Nm Pppd 1871(version 2.3.1) incorrectly attempts to negotiate 1872.Ar deflate 1873compression using type 1874.Em 24 1875as the CCP configuration type rather than type 1876.Em 26 1877as specified in 1878.Pa rfc1979 . 1879Type 1880.Ar 24 1881is actually specified as 1882.Dq PPP Magna-link Variable Resource Compression 1883in 1884.Pa rfc1975 Ns No ! 1885.Nm Ppp 1886is capable of negotiating with 1887.Nm pppd , 1888but only if 1889.Dq deflate24 1890is 1891.Ar enable Ns No d 1892and 1893.Ar accept Ns No ed . 1894.It deflate24 1895Default: Disabled and Denied. This is a variance of the 1896.Ar deflate 1897option, allowing negotiation with the 1898.Xr pppd 8 1899program. Refer to the 1900.Ar deflate 1901section above for details. It is disabled by default as it violates 1902.Pa rfc1975 . 1903.It dns 1904Default: Enabled and Denied. This option allows DNS negotiation. 1905.Pp 1906If 1907.Dq enable Ns No d, 1908.Nm 1909will request that the peer confirms the entries in 1910.Pa /etc/resolv.conf . 1911If the peer NAKs our request (suggesting new IP numbers), 1912.Pa /etc/resolv.conf 1913is updated and another request is sent to confirm the new entries. 1914.Pp 1915If 1916.Dq accept Ns No ed, 1917.Nm 1918will answer any DNS queries requested by the peer rather than rejecting 1919them. The answer is taken from 1920.Pa /etc/resolv.conf 1921unless the 1922.Dq set dns 1923command is used as an override. 1924.It lqr 1925Default: Disabled and Accepted. This option decides if Link Quality 1926Requests will be sent or accepted. LQR is a protocol that allows 1927.Nm 1928to determine that the link is down without relying on the modems 1929carrier detect. When LQR is enabled, 1930.Nm 1931sends the 1932.Em QUALPROTO 1933option (see 1934.Dq set lqrperiod 1935below) as part of the LCP request. If the peer agrees, both sides will 1936exchange LQR packets at the agreed frequency, allowing detailed link 1937quality monitoring by enabling LQM logging. If the peer doesn't agree, 1938ppp will send ECHO LQR requests instead. These packets pass no 1939information of interest, but they 1940.Em MUST 1941be replied to by the peer. 1942.Pp 1943Whether using LQR or ECHO LQR, 1944.Nm 1945will abruptly drop the connection if 5 unacknowledged packets have been 1946sent rather than sending a 6th. A message is logged at the 1947.Em PHASE 1948level, and any appropriate 1949.Dq reconnect 1950values are honoured as if the peer were responsible for dropping the 1951connection. 1952.It pap 1953Default: Disabled and Accepted. PAP stands for Password Authentication 1954Protocol. Only one of PAP and CHAP (above) may be negotiated. With 1955PAP, the ID and Password are sent repeatedly to the peer until 1956authentication is acknowledged or the connection is terminated. This 1957is a rather poor security mechanism. It is only performed when the 1958connection is first established. 1959If you want to have your peer authenticate itself, you must 1960.Dq enable pap . 1961in 1962.Pa /etc/ppp/ppp.conf , 1963and have an entry in 1964.Pa /etc/ppp/ppp.secret 1965for the peer (although see the 1966.Dq passwdauth 1967option below). 1968.Pp 1969When using PAP as the client, you need only specify 1970.Dq AuthName 1971and 1972.Dq AuthKey 1973in 1974.Pa /etc/ppp/ppp.conf . 1975PAP is accepted by default. 1976.It pred1 1977Default: Enabled and Accepted. This option decides if Predictor 1 1978compression will be used by the Compression Control Protocol (CCP). 1979.It protocomp 1980Default: Enabled and Accepted. This option is used to negotiate 1981PFC (Protocol Field Compression), a mechanism where the protocol 1982field number is reduced to one octet rather than two. 1983.It shortseq 1984Default: Enabled and Accepted. This option determines if 1985.Nm 1986will request and accept requests for short 1987.Pq 12 bit 1988sequence numbers when negotiating multi-link mode. This is only 1989applicable if our MRRU is set (thus enabling multi-link). 1990.It vjcomp 1991Default: Enabled and Accepted. This option determines if Van Jacobson 1992header compression will be used. 1993.El 1994.Pp 1995The following options are not actually negotiated with the peer. 1996Therefore, accepting or denying them makes no sense. 1997.Bl -tag -width 20 1998.It idcheck 1999Default: Enabled. When 2000.Nm 2001exchanges low-level LCP, CCP and IPCP configuration traffic, the 2002.Em Identifier 2003field of any replies is expected to be the same as that of the request. 2004By default, 2005.Nm 2006drops any reply packets that do not contain the expected identifier 2007field, reporting the fact at the respective log level. If 2008.Ar idcheck 2009is disabled, 2010.Nm 2011will ignore the identifier field. 2012.It loopback 2013Default: Enabled. When 2014.Ar loopback 2015is enabled, 2016.Nm 2017will automatically loop back packets being sent 2018out with a destination address equal to that of the 2019.Em PPP 2020interface. If disabled, 2021.Nm 2022will send the packet, probably resulting in an ICMP redirect from 2023the other end. It is convenient to have this option enabled when 2024the interface is also the default route as it avoids the necessity 2025of a loopback route. 2026.It passwdauth 2027Default: Disabled. Enabling this option will tell the PAP authentication 2028code to use the password database (see 2029.Xr passwd 5 ) 2030to authenticate the caller if they cannot be found in the 2031.Pa /etc/ppp/ppp.secret 2032file. 2033.Pa /etc/ppp/ppp.secret 2034is always checked first. If you wish to use passwords from 2035.Xr passwd 5 , 2036but also to specify an IP number or label for a given client, use 2037.Dq \&* 2038as the client password in 2039.Pa /etc/ppp/ppp.secret . 2040.It proxy 2041Default: Disabled. Enabling this option will tell 2042.Nm 2043to proxy ARP for the peer. 2044.It sroutes 2045Default: Enabled. When the 2046.Dq add 2047command is used with the 2048.Dv HISADDR 2049or 2050.Dv MYADDR 2051values, entries are stored in the 2052.Sq stick route 2053list. Each time 2054.Dv HISADDR 2055or 2056.Dv MYADDR 2057change, this list is re-applied to the routing table. 2058.Pp 2059Disabling this option will prevent the re-application of sticky routes, 2060although the 2061.Sq stick route 2062list will still be maintained. 2063.It throughput 2064Default: Enabled. This option tells 2065.Nm 2066to gather throughput statistics. Input and output is sampled over 2067a rolling 5 second window, and current, best and total figures are 2068retained. This data is output when the relevant 2069.Em PPP 2070layer shuts down, and is also available using the 2071.Dq show 2072command. Throughput statistics are available at the 2073.Dq IPCP 2074and 2075.Dq modem 2076levels. 2077.It utmp 2078Default: Enabled. Normally, when a user is authenticated using PAP or 2079CHAP, and when 2080.Nm 2081is running in 2082.Fl direct 2083mode, an entry is made in the utmp and wtmp files for that user. Disabling 2084this option will tell 2085.Nm 2086not to make any utmp or wtmp entries. This is usually only necessary if 2087you require the user to both login and authenticate themselves. 2088.El 2089.Pp 2090.It add[!] Ar dest[/nn] [mask] gateway 2091.Ar Dest 2092is the destination IP address. The netmask is specified either as a 2093number of bits with 2094.Ar /nn 2095or as an IP number using 2096.Ar mask . 2097.Ar 0 0 2098or simply 2099.Ar 0 2100with no mask refers to the default route. It is also possible to use the 2101literal name 2102.Sq default 2103instead of 2104.Ar 0 . 2105.Ar Gateway 2106is the next hop gateway to get to the given 2107.Ar dest 2108machine/network. Refer to the 2109.Xr route 8 2110command for further details. 2111.Pp 2112It is possible to use the symbolic names 2113.Sq MYADDR 2114or 2115.Sq HISADDR 2116as the destination, and either 2117.Sq HISADDR 2118or 2119.Sq INTERFACE 2120as the 2121.Ar gateway . 2122.Sq MYADDR 2123is replaced with the interface address, 2124.Sq HISADDR 2125is replaced with the interface destination address and 2126.Sq INTERFACE 2127is replaced with the current interface name. If the interfaces destination 2128address has not yet been assigned 2129.Pq via Dq set ifaddr , 2130the current 2131.Sq INTERFACE 2132is used instead of 2133.Sq HISADDR . 2134.Pp 2135If the 2136.Ar add! 2137command is used 2138.Pq note the trailing Dq \&! , 2139then if the route already exists, it will be updated as with the 2140.Sq route change 2141command (see 2142.Xr route 8 2143for further details). 2144.Pp 2145Routes that contain the 2146.Dq HISADDR 2147or 2148.Dq MYADDR 2149constants are considered 2150.Sq sticky . 2151They are stored in a list (use 2152.Dq show ipcp 2153to see the list), and each time the value of 2154.Dv HISADDR 2155or 2156.Dv MYADDR 2157changes, the appropriate routing table entries are updated. This facility 2158may be disabled using 2159.Dq disable sroutes . 2160.It allow Ar command Op Ar args 2161This command controls access to 2162.Nm 2163and its configuration files. It is possible to allow user-level access, 2164depending on the configuration file label and on the mode that 2165.Nm 2166is being run in. For example, you may wish to configure 2167.Nm 2168so that only user 2169.Sq fred 2170may access label 2171.Sq fredlabel 2172in 2173.Fl background 2174mode. 2175.Pp 2176User id 0 is immune to these commands. 2177.Bl -tag -width 20 2178.It allow user[s] Ar logname... 2179By default, only user id 0 is allowed access to 2180.Nm ppp . 2181If this command is used, all of the listed users are allowed access to 2182the section in which the 2183.Dq allow users 2184command is found. The 2185.Sq default 2186section is always checked first (even though it is only ever automatically 2187loaded at startup). Each successive 2188.Dq allow users 2189command overrides the previous one, so it's possible to allow users access 2190to everything except a given label by specifying default users in the 2191.Sq default 2192section, and then specifying a new user list for that label. 2193.Pp 2194If user 2195.Sq * 2196is specified, access is allowed to all users. 2197.It allow mode[s] Ar modelist... 2198By default, access using any 2199.Nm 2200mode is possible. If this command is used, it restricts the access 2201mode allowed to load the label under which this command is specified. 2202Again, as with the 2203.Dq allow users 2204command, each 2205.Dq allow modes 2206command overrides the previous, and the 2207.Sq default 2208section is always checked first. 2209.Pp 2210Possible modes are: 2211.Sq interactive , 2212.Sq auto , 2213.Sq direct , 2214.Sq dedicated , 2215.Sq ddial , 2216.Sq background 2217and 2218.Sq * . 2219.Pp 2220When running in multi-link mode, a section can be loaded if it allows 2221.Em any 2222of the currently existing line modes. 2223.El 2224.Pp 2225.It alias Ar command Op Ar args 2226This command allows the control of the aliasing (or masquerading) 2227facilities that are built into 2228.Nm ppp . 2229Until this code is required, it is not loaded by 2230.Nm ppp , 2231and it is quite possible that the alias library is not installed 2232on your system (some administrators consider it a security risk). 2233If aliasing is enabled on your system, the following commands are 2234possible: 2235.Bl -tag -width 20 2236.It alias enable [yes|no] 2237This command either switches aliasing on or turns it off. 2238The 2239.Fl alias 2240command line flag is synonymous with 2241.Dq alias enable yes . 2242.It alias port Op Ar proto targetIP:targetPORT [aliasIP:]aliasPORT 2243This command allows us to redirect connections arriving at 2244.Ar aliasPORT 2245for machine 2246.Ar aliasIP 2247to 2248.Ar targetPORT 2249on 2250.Ar targetIP . 2251.Ar Proto 2252may be either 2253.Sq tcp 2254or 2255.Sq udp , 2256and only connections of the given protocol 2257are matched. This option is useful if you wish to run things like 2258Internet phone on the machines behind your gateway. 2259.It alias addr Op Ar addr_local addr_alias 2260This command allows data for 2261.Ar addr_alias 2262to be redirected to 2263.Ar addr_local . 2264It is useful if you own a small number of real IP numbers that 2265you wish to map to specific machines behind your gateway. 2266.It alias deny_incoming [yes|no] 2267If set to yes, this command will refuse all incoming connections 2268by dropping the packets in much the same way as a firewall would. 2269.It alias help|? 2270This command gives a summary of available alias commands. 2271.It alias log [yes|no] 2272This option causes various aliasing statistics and information to 2273be logged to the file 2274.Pa /var/log/alias.log . 2275.It alias same_ports [yes|no] 2276When enabled, this command will tell the alias library attempt to 2277avoid changing the port number on outgoing packets. This is useful 2278if you want to support protocols such as RPC and LPD which require 2279connections to come from a well known port. 2280.It alias use_sockets [yes|no] 2281When enabled, this option tells the alias library to create a 2282socket so that it can guarantee a correct incoming ftp data or 2283IRC connection. 2284.It alias unregistered_only [yes|no] 2285Only alter outgoing packets with an unregistered source ad- 2286dress. According to RFC 1918, unregistered source addresses 2287are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16. 2288.El 2289.Pp 2290These commands are also discussed in the file 2291.Pa README.alias 2292which comes with the source distribution. 2293.Pp 2294.It [!]bg Ar command 2295The given 2296.Ar command 2297is executed in the background. Any of the pseudo arguments 2298.Dv HISADDR , 2299.Dv INTERFACE 2300and 2301.Dv MYADDR 2302will be replaced with the appropriate values. If you wish to pause 2303.Nm 2304while the command executes, use the 2305.Dv shell 2306command instead. 2307.It clear modem|ipcp Op current|overall|peak... 2308Clear the specified throughput values at either the 2309.Dq modem 2310or 2311.Dq ipcp 2312level. If 2313.Dq modem 2314is specified, context must be given (see the 2315.Dq link 2316command below). If no second argument is given, all values are 2317cleared. 2318.It clone Ar name[,name]... 2319Clone the specified link, creating one or more new links according to the 2320.Ar name 2321argument(s). This command must be used from the 2322.Dq link 2323command below unless you've only got a single link (in which case that 2324link becomes the default). Links may be removed using the 2325.Dq remove 2326command below. 2327.Pp 2328The default link name is 2329.Dq deflink . 2330.It close Op lcp|ccp[!] 2331If no arguments are given, the relevant protocol layers will be brought 2332down and the link will be closed. If 2333.Dq lcp 2334is specified, the LCP layer is brought down, but 2335.Nm 2336will not bring the link offline. It is subsequently possible to use 2337.Dq term 2338.Pq see below 2339to talk to the peer machine if, for example, something like 2340.Dq slirp 2341is being used. If 2342.Dq ccp 2343is specified, only the relevant compression layer is closed. If the 2344.Dq \&! 2345is used, the compression layer will remain in the closed state, otherwise 2346it will re-enter the STOPPED state, waiting for the peer to initiate 2347further CCP negotiation. In any event, this command does not disconnect 2348the user from 2349.Nm 2350or exit 2351.Nm ppp . 2352See the 2353.Dq quit 2354command below. 2355.It delete[!] Ar dest 2356This command deletes the route with the given 2357.Ar dest 2358IP address. If 2359.Ar dest 2360is specified as 2361.Sq ALL , 2362all non-direct entries in the routing table for the current interface, 2363and all 2364.Sq sticky route 2365entries are deleted. If 2366.Ar dest 2367is specified as 2368.Sq default , 2369the default route is deleted. 2370.Pp 2371If the 2372.Ar delete! 2373command is used 2374.Pq note the trailing Dq \&! , 2375.Nm 2376will not complain if the route does not already exist. 2377.It dial|call Op Ar label 2378When used with no argument, this command is the same as the 2379.Dq open 2380command. When 2381.Ar label 2382is specified, a 2383.Dq load 2384will be done first. 2385.It down Op Ar lcp|ccp 2386Bring the relevant layer down ungracefully, as if the underlying layer 2387had become unavailable. It's not considered polite to use this command on 2388a Finite State Machine that's in the OPEN state. If no arguments are 2389supplied, the entire link is closed (or if no context is given, all links 2390are terminated). If 2391.Sq lcp 2392is specified, the 2393.Em LCP 2394layer is terminated but the modem is not brought offline and the link 2395is not closed. If 2396.Sq ccp 2397is specified, only the relevant compression layer(s) are terminated. 2398.It help|? Op Ar command 2399Show a list of available commands. If 2400.Ar command 2401is specified, show the usage string for that command. 2402.It [data]link Ar name[,name...] command Op Ar args 2403This command may prefix any other command if the user wishes to 2404specify which link the command should affect. This is only 2405applicable after multiple links have been created in Multi-link 2406mode using the 2407.Dq clone 2408command. 2409.Pp 2410.Ar Name 2411specifies the name of an existing link. If 2412.Ar name 2413is a comma separated list, 2414.Ar command 2415is executed on each link. If 2416.Ar name 2417is 2418.Dq * , 2419.Ar command 2420is executed on all links. 2421.It load Op Ar label 2422Load the given 2423.Ar label 2424from the 2425.Pa ppp.conf 2426file. If 2427.Ar label 2428is not given, the 2429.Ar default 2430label is used. 2431.It open Op lcp|ccp|ipcp 2432This is the opposite of the 2433.Dq close 2434command. Using 2435.Dq open 2436with no arguments is the same as using 2437.Dq dial 2438with no arguments, where all closed links are brought up (some auto 2439links may not come up based on the 2440.Dq set autoload 2441command) using the current configuration. 2442.Pp 2443If the 2444.Dq lcp 2445while the LCP layer is already open, LCP will be renegotiated. This 2446allows various LCP options to be changed, after which 2447.Dq open lcp 2448can be used to put them into effect. After renegotiating LCP, 2449any agreed authentication will also take place. 2450.Pp 2451If the 2452.Dq ccp 2453argument is used, the relevant compression layer is opened. Again, 2454if it is already open, it will be renegotiated. 2455.Pp 2456If the 2457.Dq ipcp 2458argument is used, the link will be brought up as normal, but if 2459IPCP is already open, it will be renegotiated and the network 2460interface will be reconfigured. 2461.Pp 2462It is probably not good practice to re-open the PPP state machines 2463like this as it's possible that the peer will not behave correctly. 2464It 2465.Em is 2466however useful as a way of forcing the CCP or VJ dictionaries to be reset. 2467.It passwd Ar pass 2468Specify the password required for access to the full 2469.Nm 2470command set. This password is required when connecting to the diagnostic 2471port (see the 2472.Dq set server 2473command). 2474.Ar Pass 2475is specified on the 2476.Dq set server 2477command line. The value of 2478.Ar pass 2479is not logged when 2480.Ar command 2481logging is active, instead, the literal string 2482.Sq ******** 2483is logged. 2484.It quit|bye [all] 2485If 2486.Dq quit 2487is executed from the controlling connection or from a command file, 2488ppp will exit after closing all connections. Otherwise, if the user 2489is connected to a diagnostic socket, the connection is simply dropped. 2490.Pp 2491If the 2492.Ar 2493all argument is given, 2494.Nm 2495will exit despite the source of the command after closing all existing 2496connections. 2497.It remove|rm 2498This command removes the given link. It is only really useful in 2499multi-link mode. A link must be 2500in the 2501.Dv CLOSED 2502state before it is removed. 2503.It rename|mv Ar name 2504This command renames the given link to 2505.Ar name . 2506It will fail if 2507.Ar name 2508is already used by another link. 2509.Pp 2510The default link name is 2511.Sq deflink . 2512Renaming it to 2513.Sq modem , 2514.Sq cuaa0 2515or 2516.Sq USR 2517may make the log file more readable. 2518.It save 2519This option is not (yet) implemented. 2520.It set[up] Ar var value 2521This option allows the setting of any of the following variables: 2522.Bl -tag -width 20 2523.It set accmap Ar hex-value 2524ACCMap stands for Asynchronous Control Character Map. This is always 2525negotiated with the peer, and defaults to a value of 00000000 in hex. 2526This protocol is required to defeat hardware that depends on passing 2527certain characters from end to end (such as XON/XOFF etc). 2528.Pp 2529For the XON/XOFF scenario, use 2530.Dq set accmap 000a0000 . 2531.It set authkey|key Ar value 2532This sets the authentication key (or password) used in client mode 2533PAP or CHAP negotiation to the given value. It can also be used to 2534specify the password to be used in the dial or login scripts in place 2535of the '\\P' sequence, preventing the actual password from being logged. If 2536.Ar command 2537logging is in effect, 2538.Ar value 2539is logged as 2540.Sq ******** 2541for security reasons. 2542.It set authname Ar id 2543This sets the authentication id used in client mode PAP or CHAP negotiation. 2544.It set autoload Ar max-duration max-load [min-duration min-load] 2545These settings apply only in multi-link mode and all default to zero. 2546When more than one 2547.Ar demand-dial 2548.Pq also known as Fl auto 2549mode link is available, only the first link is made active when 2550.Nm 2551first reads data from the tun device. The next 2552.Ar demand-dial 2553link will be opened only when at least 2554.Ar max-load 2555packets have been in the send queue for 2556.Ar max-duration 2557seconds. Because both values default to zero, 2558.Ar demand-dial 2559links will simply come up one at a time by default. 2560.Pp 2561If two or more links are open, at least one of which is a 2562.Ar demand-dial 2563link, a 2564.Ar demand-dial 2565link will be closed when there is less than 2566.Ar min-packets 2567in the queue for more than 2568.Ar min-duration . 2569If 2570.Ar min-duration 2571is zero, this timer is disabled. Because both values default to zero, 2572.Ar demand-dial 2573links will stay active until the bundle idle timer expires. 2574.It set ctsrts|crtscts on|off 2575This sets hardware flow control. Hardware flow control is 2576.Ar on 2577by default. 2578.It set deflate Ar out-winsize Op Ar in-winsize 2579This sets the DEFLATE algorithms default outgoing and incoming window 2580sizes. Both 2581.Ar out-winsize 2582and 2583.Ar in-winsize 2584must be values between 2585.Em 8 2586and 2587.Em 15 . 2588If 2589.Ar in-winsize 2590is specified, 2591.Nm 2592will insist that this window size is used and will not accept any other 2593values from the peer. 2594.It set dns Op Ar primary Op Ar secondary 2595This command specifies DNS overrides for the 2596.Dq accept dns 2597command. Refer to the 2598.Dq accept 2599command description above for details. This command does not affect the 2600IP numbers requested using 2601.Dq enable dns . 2602.It set device|line Ar value[,value...] 2603This sets the device(s) to which 2604.Nm 2605will talk to the given 2606.Dq value . 2607All serial device names are expected to begin with 2608.Pa /dev/ . 2609If 2610.Dq value 2611does not begin with 2612.Pa /dev/ , 2613it must either begin with an exclamation mark 2614.Pq Dq \&! 2615or be of the format 2616.Dq host:port . 2617.Pp 2618If it begins with an exclamation mark, the rest of the device name is 2619treated as a program name, and that program is executed when the device 2620is opened. Standard input, output and error are fed back to 2621.Nm 2622and are read and written as if they were a regular device. 2623.Pp 2624If a 2625.Dq host:port 2626pair is given, 2627.Nm 2628will attempt to connect to the given 2629.Dq host 2630on the given 2631.Dq port . 2632Refer to the section on 2633.Em PPP OVER TCP 2634above for further details. 2635.Pp 2636If multiple 2637.Dq values 2638are specified, 2639.Nm 2640will attempt to open each one in turn until it succeeds or runs out of 2641devices. 2642.It set dial Ar chat-script 2643This specifies the chat script that will be used to dial the other 2644side. See also the 2645.Dq set login 2646command below. Refer to 2647.Xr chat 8 2648and to the example configuration files for details of the chat script 2649format. 2650It is possible to specify some special 2651.Sq values 2652in your chat script as follows: 2653.Bd -literal -offset indent 2654.It \\\\\\\\\\\\\\\\c 2655When used as the last character in a 2656.Sq send 2657string, this indicates that a newline should not be appended. 2658.It \\\\\\\\\\\\\\\\d 2659When the chat script encounters this sequence, it delays two seconds. 2660.It \\\\\\\\\\\\\\\\p 2661When the chat script encounters this sequence, it delays for one quarter of 2662a second. 2663.It \\\\\\\\\\\\\\\\n 2664This is replaced with a newline character. 2665.It \\\\\\\\\\\\\\\\r 2666This is replaced with a carriage return character. 2667.It \\\\\\\\\\\\\\\\s 2668This is replaced with a space character. 2669.It \\\\\\\\\\\\\\\\t 2670This is replaced with a tab character. 2671.It \\\\\\\\\\\\\\\\T 2672This is replaced by the current phone number (see 2673.Dq set phone 2674below). 2675.It \\\\\\\\\\\\\\\\P 2676This is replaced by the current 2677.Ar authkey 2678value (see 2679.Dq set authkey 2680above). 2681.It \\\\\\\\\\\\\\\\U 2682This is replaced by the current 2683.Ar authname 2684value (see 2685.Dq set authname 2686above). 2687.Ed 2688.Pp 2689Note that two parsers will examine these escape sequences, so in order to 2690have the 2691.Sq chat parser 2692see the escape character, it is necessary to escape it from the 2693.Sq command parser . 2694This means that in practice you should use two escapes, for example: 2695.Bd -literal -offset indent 2696set dial "... ATDT\\\\T CONNECT" 2697.Ed 2698.Pp 2699It is also possible to execute external commands from the chat script. 2700To do this, the first character of the expect or send string is an 2701exclamation mark 2702.Pq Dq \&! . 2703When the command is executed, standard input and standard output are 2704directed to the modem device (see the 2705.Dq set device 2706command), and standard error is read by 2707.Nm 2708and substituted as the expect or send string. If 2709.Nm 2710is running in interactive mode, file descriptor 3 is attached to 2711.Pa /dev/tty . 2712.Pp 2713For example (wrapped for readability); 2714.Bd -literal -offset indent 2715set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e 2716word: ppp \\"!sh \\\\\\\\-c \\\\\\"echo \\\\\\\\-n label: >&2\\\\\\"\\" \e 2717\\"!/bin/echo in\\" HELLO" 2718.Ed 2719.Pp 2720would result in the following chat sequence (output using the 2721.Sq set log local chat 2722command before dialing): 2723.Bd -literal -offset indent 2724Dial attempt 1 of 1 2725dial OK! 2726Chat: Expecting: 2727Chat: Sending: 2728Chat: Expecting: login:--login: 2729Chat: Wait for (5): login: 2730Chat: Sending: ppp 2731Chat: Expecting: word: 2732Chat: Wait for (5): word: 2733Chat: Sending: ppp 2734Chat: Expecting: !sh \\-c "echo \\-n label: >&2" 2735Chat: Exec: sh -c "echo -n label: >&2" 2736Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label: 2737Chat: Exec: /bin/echo in 2738Chat: Sending: 2739Chat: Expecting: HELLO 2740Chat: Wait for (5): HELLO 2741login OK! 2742.Ed 2743.Pp 2744Note (again) the use of the escape character, allowing many levels of 2745nesting. Here, there are four parsers at work. The first parses the 2746original line, reading it as three arguments. The second parses the 2747third argument, reading it as 11 arguments. At this point, it is 2748important that the 2749.Dq \&- 2750signs are escaped, otherwise this parser will see them as constituting 2751an expect-send-expect sequence. When the 2752.Dq \&! 2753character is seen, the execution parser reads the first command as three 2754arguments, and then 2755.Xr sh 1 2756itself expands the argument after the 2757.Fl c . 2758As we wish to send the output back to the modem, in the first example 2759we redirect our output to file descriptor 2 (stderr) so that 2760.Nm 2761itself sends and logs it, and in the second example, we just output to stdout, 2762which is attached directly to the modem. 2763.Pp 2764This, of course means that it is possible to execute an entirely external 2765.Dq chat 2766command rather than using the internal one. See 2767.Xr chat 8 2768for a good alternative. 2769.It set enddisc Op label|IP|MAC|magic|psn value 2770This command sets our local endpoint discriminator. If set prior to 2771LCP negotiation, 2772.Nm 2773will send the information to the peer using the LCP endpoint discriminator 2774option. The following discriminators may be set: 2775.Bd -literal -offset indent 2776.It label 2777The current label is used. 2778.It IP 2779Our local IP number is used. As LCP is negotiated prior to IPCP, it is 2780possible that the IPCP layer will subsequently change this value. If 2781it does, the endpoint discriminator stays at the old value unless manually 2782reset. 2783.It MAC 2784This is similar to the 2785.Ar IP 2786option above, except that the MAC address associated with the local IP 2787number is used. If the local IP number is not resident on any Ethernet 2788interface, the command will fail. 2789.Pp 2790As the local IP number defaults to whatever the machine host name is, 2791.Dq set enddisc mac 2792is usually done prior to any 2793.Dq set ifaddr 2794commands. 2795.It magic 2796A 20 digit random number is used. 2797.It psn Ar value 2798The given 2799.Ar value 2800is used. 2801.Ar Value 2802should be set to an absolute public switched network number with the 2803country code first. 2804.Ed 2805.Pp 2806If no arguments are given, the endpoint discriminator is reset. 2807.It set escape Ar value... 2808This option is similar to the 2809.Dq set accmap 2810option above. It allows the user to specify a set of characters that 2811will be `escaped' as they travel across the link. 2812.It set filter dial|alive|in|out rule-no permit|deny Ar "[src_addr/width] [dst_addr/width] [proto [src [lt|eq|gt port]] [dst [lt|eq|gt port]] [estab] [syn] [finrst]]" 2813.Nm Ppp 2814supports four filter sets. The 2815.Em alive 2816filter specifies packets that keep the connection alive - reseting the 2817idle timer. The 2818.Em dial 2819filter specifies packets that cause 2820.Nm 2821to dial when in 2822.Fl auto 2823mode. The 2824.Em in 2825filter specifies packets that are allowed to travel 2826into the machine and the 2827.Em out 2828filter specifies packets that are allowed out of the machine. 2829.Pp 2830Filtering is done prior to any IP alterations that might be done by the 2831alias engine. By default all filter sets allow all packets to pass. 2832Rules are processed in order according to 2833.Ar rule-no . 2834Up to 20 rules may be given for each set. If a packet doesn't match 2835any of the rules in a given set, it is discarded. In the case of 2836.Em in 2837and 2838.Em out 2839filters, this means that the packet is dropped. In the case of 2840.Em alive 2841filters it means that the packet will not reset the idle timer and in 2842the case of 2843.Em dial 2844filters it means that the packet will not trigger a dial. A packet failing 2845to trigger a dial will be dropped rather than queued. Refer to the 2846section on PACKET FILTERING above for further details. 2847.It set hangup Ar chat-script 2848This specifies the chat script that will be used to reset the modem 2849before it is closed. It should not normally be necessary, but can 2850be used for devices that fail to reset themselves properly on close. 2851.It set help|? Op Ar command 2852This command gives a summary of available set commands, or if 2853.Ar command 2854is specified, the command usage is shown. 2855.It set ifaddr Ar [myaddr [hisaddr [netmask [triggeraddr]]]] 2856This command specifies the IP addresses that will be used during 2857IPCP negotiation. Addresses are specified using the format 2858.Pp 2859.Dl a.b.c.d/n 2860.Pp 2861Where 2862.Ar a.b.c.d 2863is the preferred IP, but 2864.Ar n 2865specifies how many bits of the address we will insist on. If 2866.Ar /n 2867is omitted, it defaults to 2868.Ar /32 2869unless the IP address is 0.0.0.0 in which case it defaults to 2870.Ar /0 . 2871.Pp 2872.Ar Hisaddr 2873may also be specified as a range of IP numbers in the format 2874.Pp 2875.Dl a.b.c.d[-d.e.f.g][,h.i.j.k[-l,m,n,o]]... 2876.Pp 2877for example: 2878.Pp 2879.Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20 2880.Pp 2881will only negotiate 2882.Ar 10.0.0.1 2883as the local IP number, but may assign any of the given 10 IP 2884numbers to the peer. If the peer requests one of these numbers, 2885and that number is not already in use, 2886.Nm 2887will grant the peers request. This is useful if the peer wants 2888to re-establish a link using the same IP number as was previously 2889allocated (thus maintaining any existing tcp connections). 2890.Pp 2891If the peer requests an IP number that's either outside 2892of this range or is already in use, 2893.Nm 2894will suggest a random unused IP number from the range. 2895.Pp 2896If 2897.Ar triggeraddr 2898is specified, it is used in place of 2899.Ar myaddr 2900in the initial IPCP negotiation. However, only an address in the 2901.Ar myaddr 2902range will be accepted. This is useful when negotiating with some 2903.Dv PPP 2904implementations that will not assign an IP number unless their peer 2905requests 2906.Ar 0.0.0.0 . 2907.Pp 2908It should be noted that in 2909.Fl auto 2910mode, 2911.Nm 2912will configure the interface immediately upon reading the 2913.Dq set ifaddr 2914line in the config file. In any other mode, these values are just 2915used for IPCP negotiations, and the interface isn't configured 2916until the IPCP layer is up. 2917.Pp 2918Note that the 2919.Ar HISADDR 2920argument may be overridden by the third field in the 2921.Pa ppp.secret 2922file once the client has authenticated itself 2923.Pq if PAP or CHAP are Dq enabled . 2924Refer to the 2925.Em AUTHENTICATING INCOMING CONNECTIONS 2926section for details. 2927.Pp 2928In all cases, if the interface is already configured, 2929.Nm 2930will try to maintain the interface IP numbers so that any existing 2931bound sockets will remain valid. 2932.It set ccpretry Ar period 2933.It set chapretry Ar period 2934.It set ipcpretry Ar period 2935.It set lcpretry Ar period 2936.It set papretry Ar period 2937These commands set the number of seconds that 2938.Nm 2939will wait before resending Finite State Machine (FSM) Request packets. 2940The default 2941.Ar period 2942for all FSMs is 3 seconds (which should suffice in most cases). 2943.It set log [local] [+|-] Ns Ar value... 2944This command allows the adjustment of the current log level. Refer 2945to the Logging Facility section for further details. 2946.It set login Ar chat-script 2947This 2948.Ar chat-script 2949compliments the dial-script. If both are specified, the login 2950script will be executed after the dial script. Escape sequences 2951available in the dial script are also available here. 2952.It set lqrperiod Ar frequency 2953This command sets the 2954.Ar frequency 2955in seconds at which 2956.Em LQR 2957or 2958.Em ECHO LQR 2959packets are sent. The default is 30 seconds. You must also use the 2960.Dq enable lqr 2961command if you wish to send LQR requests to the peer. 2962.It set mode Ar interactive|auto|ddial|background 2963This command allows you to change the 2964.Sq mode 2965of the specified link. This is normally only useful in multi-link mode, 2966but may also be used in uni-link mode. 2967.Pp 2968It is not possible to change a link that is 2969.Sq direct 2970or 2971.Sq dedicated . 2972.It set mrru Op Ar value 2973Setting this option enables Multi-link PPP negotiations, also known as 2974Multi-link Protocol or MP. There is no default MRRU (Maximum 2975Reconstructed Receive Unit) value. If no argument is given, multi-link 2976mode is disabled. 2977.It set mru Op Ar value 2978The default MRU (Maximum Receive Unit) is 1500. If it is increased, the 2979other side *may* increase its mtu. There is no point in decreasing the 2980MRU to below the default as the 2981.Em PPP 2982protocol *must* be able to accept packets of at least 1500 octets. If 2983no argument is given, 1500 is assumed. 2984.It set mtu Op Ar value 2985The default MTU is 1500. At negotiation time, 2986.Nm 2987will accept whatever MRU or MRRU that the peer wants (assuming it's 2988not less than 296 bytes). If the MTU is set, 2989.Nm 2990will not accept MRU/MRRU values less than 2991.Ar value . 2992When negotiations are complete, the MTU is assigned to the interface, even 2993if the peer requested a higher value MRU/MRRU. This can be useful for 2994limiting your packet size (giving better bandwidth sharing at the expense 2995of more header data). 2996.Pp 2997If no 2998.Ar value 2999is given, 1500, or whatever the peer asks for is used. 3000.It set nbns Op Ar x.x.x.x Op Ar y.y.y.y 3001This option allows the setting of the Microsoft NetBIOS name server 3002values to be returned at the peers request. If no values are given, 3003.Nm 3004will reject any such requests. 3005.It set openmode active|passive Op Ar delay 3006By default, 3007.Ar openmode 3008is always 3009.Ar active 3010with a one second 3011.Ar delay . 3012That is, 3013.Nm 3014will always initiate LCP/IPCP/CCP negotiation one second after the line 3015comes up. If you want to wait for the peer to initiate negotiations, you 3016can use the value 3017.Ar passive . 3018If you want to initiate negotiations immediately or after more than one 3019second, the appropriate 3020.Ar delay 3021may be specified here in seconds. 3022.It set parity odd|even|none|mark 3023This allows the line parity to be set. The default value is 3024.Ar none . 3025.It set phone Ar telno[|telno]...[:telno[|telno]...]... 3026This allows the specification of the phone number to be used in 3027place of the \\\\T string in the dial and login chat scripts. 3028Multiple phone numbers may be given separated by a pipe (|) or 3029a colon (:). Numbers after the pipe are only dialed if the dial or login 3030script for the previous number failed. Numbers separated by a colon are 3031tried sequentially, irrespective of the reason the line was dropped. 3032If multiple numbers are given, 3033.Nm 3034will dial them according to these rules until a connection is made, retrying 3035the maximum number of times specified by 3036.Dq set redial 3037below. In 3038.Fl background 3039mode, each number is attempted at most once. 3040.It set reconnect Ar timeout ntries 3041Should the line drop unexpectedly (due to loss of CD or LQR 3042failure), a connection will be re-established after the given 3043.Ar timeout . 3044The line will be re-connected at most 3045.Ar ntries 3046times. 3047.Ar Ntries 3048defaults to zero. A value of 3049.Ar random 3050for 3051.Ar timeout 3052will result in a variable pause, somewhere between 0 and 30 seconds. 3053.It set redial Ar seconds[.nseconds] [attempts] 3054.Nm Ppp 3055can be instructed to attempt to redial 3056.Ar attempts 3057times. If more than one phone number is specified (see 3058.Dq set phone 3059above), a pause of 3060.Ar nseconds 3061is taken before dialing each number. A pause of 3062.Ar seconds 3063is taken before starting at the first number again. A value of 3064.Ar random 3065may be used here in place of 3066.Ar seconds 3067and 3068.Ar nseconds , 3069causing a random delay of between 0 and 30 seconds. 3070.Pp 3071Note, this delay will be effective, even after 3072.Ar attempts 3073has been exceeded, so an immediate manual dial may appear to have 3074done nothing. If an immediate dial is required, a 3075.Dq \&! 3076should immediately follow the 3077.Dq open 3078keyword. See the 3079.Dq open 3080description above for further details. 3081.It set server|socket Ar TcpPort|LocalName|none password Op Ar mask 3082This command tells 3083.Nm 3084to listen on the given socket or 3085.Sq diagnostic port 3086for incoming command connections. 3087.Pp 3088The word 3089.Ar none 3090instructs 3091.Nm 3092to close any existing socket. 3093.Pp 3094If you wish to specify a local domain socket, 3095.Ar LocalName 3096must be specified as an absolute file name, otherwise it is assumed 3097to be the name or number of a TCP port. You may specify the octal umask that 3098should be used with local domain sockets as a four character octal number 3099beginning with 3100.Sq 0 . 3101Refer to 3102.Xr umask 2 3103for umask details. Refer to 3104.Xr services 5 3105for details of how to translate TCP port names. 3106.Pp 3107You must also specify the password that must be entered by the client 3108(using the 3109.Dq passwd 3110command above) when connecting to this socket. If the password is 3111specified as an empty string, no password is required for connecting clients. 3112.Pp 3113When specifying a local domain socket, the first 3114.Dq %d 3115sequence found in the socket name will be replaced with the current 3116interface unit number. This is useful when you wish to use the same 3117profile for more than one connection. 3118.Pp 3119In a similar manner TCP sockets may be prefixed with the 3120.Dq + 3121character, in which case the current interface unit number is added to 3122the port number. 3123.Pp 3124When using 3125.Nm 3126with a server socket, the 3127.Xr pppctl 8 3128command is the preferred mechanism of communications. Currently, 3129.Xr telnet 1 3130can also be used, but link encryption may be implemented in the future, so 3131.Xr telnet 1 3132should not be relied upon. 3133.It set speed Ar value 3134This sets the speed of the serial device. 3135.It set stopped Ar [LCPseconds [CCPseconds]] 3136If this option is set, 3137.Nm 3138will time out after the given FSM (Finite State Machine) has been in 3139the stopped state for the given number of 3140.Dq seconds . 3141This option may be useful if the peer sends a terminate request, 3142but never actually closes the connection despite our sending a terminate 3143acknowledgement. This is also useful if you wish to 3144.Dq set openmode passive 3145and time out if the peer doesn't send a Configure Request within the 3146given time. Use 3147.Dq set log +lcp +ccp 3148to make 3149.Nm 3150log the appropriate state transitions. 3151.Pp 3152The default value is zero, where 3153.Nm 3154doesn't time out in the stopped state. 3155.Pp 3156This value should not be set to less than the openmode delay (see 3157.Dq set openmode 3158above). 3159.It set timeout Ar idleseconds 3160This command allows the setting of the idle timer. Refer to the 3161section titled 3162.Dq SETTING THE IDLE TIMER 3163for further details. 3164.It set vj slotcomp on|off 3165This command tells 3166.Nm 3167whether it should attempt to negotiate VJ slot compression. By default, 3168slot compression is turned 3169.Ar on . 3170.It set vj slots Ar nslots 3171This command sets the initial number of slots that 3172.Nm 3173will try to negotiate with the peer when VJ compression is enabled (see the 3174.Sq enable 3175command above). It defaults to a value of 16. 3176.Ar Nslots 3177must be between 3178.Ar 4 3179and 3180.Ar 16 3181inclusive. 3182.El 3183.Pp 3184.It shell|! Op Ar command 3185If 3186.Ar command 3187is not specified a shell is invoked according to the 3188.Dv SHELL 3189environment variable. Otherwise, the given 3190.Ar command 3191is executed. Any of the pseudo arguments 3192.Dv HISADDR , 3193.Dv INTERFACE 3194and 3195.Dv MYADDR 3196will be replaced with the appropriate values. Use of the ! character 3197requires a following space as with any other commands. You should note 3198that this command is executed in the foreground - 3199.Nm 3200will not continue running until this process has exited. Use the 3201.Dv bg 3202command if you wish processing to happen in the background. 3203.It show Ar var 3204This command allows the user to examine the following: 3205.Bl -tag -width 20 3206.It show bundle 3207Show the current bundle settings. 3208.It show ccp 3209Show the current CCP compression statistics. 3210.It show compress 3211Show the current VJ compression statistics. 3212.It show escape 3213Show the current escape characters. 3214.It show filter Op Ar name 3215List the current rules for the given filter. If 3216.Ar name 3217is not specified, all filters are shown. 3218.It show hdlc 3219Show the current HDLC statistics. 3220.It show help|? 3221Give a summary of available show commands. 3222.It show ipcp 3223Show the current IPCP statistics. 3224.It show lcp 3225Show the current LCP statistics. 3226.It show [data]link 3227Show high level link information. 3228.It show links 3229Show a list of available logical links. 3230.It show log 3231Show the current log values. 3232.It show mem 3233Show current memory statistics. 3234.It show modem 3235Show low level link information. 3236.It show proto 3237Show current protocol totals. 3238.It show route 3239Show the current routing tables. 3240.It show stopped 3241Show the current stopped timeouts. 3242.It show timer 3243Show the active alarm timers. 3244.It show version 3245Show the current version number of 3246.Nm ppp . 3247.El 3248.Pp 3249.It term 3250Go into terminal mode. Characters typed at the keyboard are sent to 3251the modem. Characters read from the modem are displayed on the 3252screen. When a 3253.Nm 3254peer is detected on the other side of the modem, 3255.Nm 3256automatically enables Packet Mode and goes back into command mode. 3257.El 3258.Pp 3259.Sh MORE DETAILS 3260.Bl -bullet 3261.It 3262Read the example configuration files. They are a good source of information. 3263.It 3264Use 3265.Dq help , 3266.Dq show ? , 3267.Dq alias ? , 3268.Dq set ? 3269and 3270.Dq set ? <var> 3271to get online information about what's available. 3272.It 3273The following urls contain useful information: 3274.Bl -bullet -compact 3275.It 3276http://www.FreeBSD.org/FAQ/userppp.html 3277.It 3278http://www.FreeBSD.org/handbook/userppp.html 3279.El 3280.Pp 3281.El 3282.Pp 3283.Sh FILES 3284.Nm Ppp 3285refers to four files: 3286.Pa ppp.conf , 3287.Pa ppp.linkup , 3288.Pa ppp.linkdown 3289and 3290.Pa ppp.secret . 3291These files are placed in the 3292.Pa /etc/ppp 3293directory. 3294.Bl -tag -width flag 3295.It Pa /etc/ppp/ppp.conf 3296System default configuration file. 3297.It Pa /etc/ppp/ppp.secret 3298An authorisation file for each system. 3299.It Pa /etc/ppp/ppp.linkup 3300A file to check when 3301.Nm 3302establishes a network level connection. 3303.It Pa /etc/ppp/ppp.linkdown 3304A file to check when 3305.Nm 3306closes a network level connection. 3307.It Pa /var/log/ppp.log 3308Logging and debugging information file. Note, this name is specified in 3309.Pa /etc/syslogd.conf . 3310See 3311.Xr syslog.conf 5 3312for further details. 3313.It Pa /var/spool/lock/LCK..* 3314tty port locking file. Refer to 3315.Xr uucplock 3 3316for further details. 3317.It Pa /var/run/tunN.pid 3318The process id (pid) of the 3319.Nm 3320program connected to the tunN device, where 3321.Sq N 3322is the number of the device. This file is only created in 3323.Fl background , 3324.Fl auto 3325and 3326.Fl ddial 3327modes. 3328.It Pa /var/run/ttyXX.if 3329The tun interface used by this port. Again, this file is only created in 3330.Fl background , 3331.Fl auto 3332and 3333.Fl ddial 3334modes. 3335.It Pa /etc/services 3336Get port number if port number is using service name. 3337.It Pa /var/run/ppp-authname-class-value 3338In multi-link mode, local domain sockets are created using the peer 3339authentication name 3340.Pq Sq authname , 3341the peer endpoint discriminator class 3342.Pq Sq class 3343and the peer endpoint discriminator value 3344.Pq Sq value . 3345As the endpoint discriminator value may be a binary value, it is turned 3346to HEX to determine the actual file name. 3347.Pp 3348This socket is used to pass links between different instances of 3349.Nm ppp . 3350.El 3351.Pp 3352.Sh SEE ALSO 3353.Xr adduser 8 , 3354.Xr at 1 , 3355.Xr chat 8 , 3356.Xr crontab 5 , 3357.Xr ftp 1 , 3358.Xr getty 8 , 3359.Xr group 5 , 3360.Xr gzip 1 , 3361.Xr hostname 1 , 3362.Xr inetd 8 , 3363.Xr init 8 , 3364.Xr login 1 , 3365.Xr named 8 , 3366.Xr passwd 5 , 3367.Xr ping 8 , 3368.Xr pppctl 8 , 3369.Xr pppd 8 , 3370.Xr route 8 , 3371.Xr resolv.conf 5 , 3372.Xr syslog 3 , 3373.Xr syslog.conf 5 , 3374.Xr syslogd 8 , 3375.Xr tcpdump 1 , 3376.Xr telnet 1 , 3377.Xr traceroute 8 , 3378.Xr uucplock 3 , 3379.Xr vipw 8 3380.Sh HISTORY 3381This program was originally written by Toshiharu OHNO (tony-o@iij.ad.jp), 3382and was submitted to FreeBSD-2.0.5 by Atsushi Murai (amurai@spec.co.jp). 3383.Pp 3384It was substantially modified during 1997 by Brian Somers 3385(brian@Awfulhak.org), and was ported to OpenBSD in November that year 3386(just after the 2.2 release). 3387.Pp 3388Most of the code was rewritten by Brian Somers in early 1998 when 3389multi-link ppp support was added. 3390