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