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