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