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