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