diff --git a/sbin/ipf/ipnat/ipnat.5 b/sbin/ipf/ipnat/ipnat.5 index 2b391f119450..c6c8c2e54fc2 100644 --- a/sbin/ipf/ipnat/ipnat.5 +++ b/sbin/ipf/ipnat/ipnat.5 @@ -1,718 +1,718 @@ .\" .TH IPNAT 5 .SH NAME ipnat, ipnat.conf \- IPFilter NAT file format .SH DESCRIPTION The .B ipnat.conf file is used to specify rules for the Network Address Translation (NAT) component of IPFilter. To load rules specified in the .B ipnat.conf file, the .B ipnat(8) program is used. .PP For standard NAT functionality, a rule should start with \fBmap\fP and then proceeds to specify the interface for which outgoing packets will have their source address rewritten. Following this it is expected that the old source address, and optionally port number, will be specified. .PP In general, all NAT rules conform to the following layout: the first word indicates what type of NAT rule is present, this is followed by some stanzas to match a packet, followed by a "->" and this is then followed by several more stanzas describing the new data to be put in the packet. .PP In this text and in others, use of the term "left hand side" (LHS) when talking about a NAT rule refers to text that appears before the "->" and the "right hand side" (RHS) for text that appears after it. In essence, the LHS is the packet matching and the RHS is the new data to be used. .SH VARIABLES This configuration file, like all others used with IPFilter, supports the use of variable substitution throughout the text. .nf nif="ppp0"; map $nif 0/0 -> 0/32 .fi .PP would become .nf map ppp0 0/0 -> 0/32 .fi .PP Variables can be used recursively, such as 'foo="$bar baz";', so long as $bar exists when the parser reaches the assignment for foo. .PP See .B ipnat(8) for instructions on how to define variables to be used from a shell environment. .SH OUTBOUND SOURCE TRANSLATION (map'ing) Changing the source address of a packet is traditionally performed using .B map rules. Both the source address and optionally port number can be changed according to various controls. .PP To start out with, a common rule used is of the form: .nf map le0 0/0 -> 0/32 .fi .PP Here we're saying change the source address of all packets going out of le0 (the address/mask pair of 0/0 matching all packets) to that of the interface le0 (0/32 is a synonym for the interface's own address at the current point in time.) If we wanted to pass the packet through with no change in address, we would write it as: .nf map le0 0/0 -> 0/0 .fi .PP If we only want to change a portion of our internal network and to a different address that is routed back through this host, we might do: .nf map le0 10.1.1.0/24 -> 192.168.55.3/32 .fi .PP In some instances, we may have an entire subnet to map internal addresses out onto, in which case we can express the translation as this: .nf map le0 10.0.0.0/8 -> 192.168.55.0/24 .fi .PP IPFilter will cycle through each of the 256 addresses in the 192.168.55.0/24 address space to ensure that they all get used. .PP Of course this poses a problem for TCP and UDP, with many connections made, each with its own port number pair. If we're unlucky, translations can be dropped because the new address/port pair mapping already exists. To mitigate this problem, we add in port translation or port mapping: .nf map le0 10.0.0.0/8 -> 192.168.55.0/24 portmap tcp/udp auto .fi .PP In this instance, the word "auto" tells IPFilter to calculate a private range of port numbers for each address on the LHS to use without fear of them being trampled by others. This can lead to problems if there are connections being generated more quickly than IPFilter can expire them. In this instance, and if we want to get away from a private range of port numbers, we can say: .nf map le0 10.0.0.0/8 -> 192.168.55.0/24 portmap tcp/udp 5000:65000 .fi .PP And now each connection through le0 will add to the enumeration of the port number space 5000-65000 as well as the IP address subnet of 192.168.55.0/24. .PP If the new addresses to be used are in a consecutive range, rather than a complete subnet, we can express this as: .nf map le0 10.0.0.0/8 -> range 192.168.55.10-192.168.55.249 portmap tcp/udp 5000:65000 .fi .PP This tells IPFilter that it has a range of 240 IP address to use, from 192.168.55.10 to 192.168.55.249, inclusive. .PP If there were several ranges of addresses for use, we can use each one in a round-robin fashion as followed: .nf map le0 10.0.0.0/8 -> range 192.168.55.10-192.168.55.29 portmap tcp/udp 5000:65000 round-robin map le0 10.0.0.0/8 -> range 192.168.55.40-192.168.55.49 portmap tcp/udp 5000:65000 round-robin .fi .PP To specify translation rules that impact a specific IP protocol, the protocol name or number is appended to the rule like this: .nf map le0 10.0.0.0/8 -> 192.168.55.0/24 tcp/udp map le0 10.0.0.0/8 -> 192.168.55.1/32 icmp map le0 10.0.0.0/8 -> 192.168.55.2/32 gre .fi .PP For TCP connections exiting a connection such as PPPoE where the MTU is slightly smaller than normal ethernet, it can be useful to reduce the Maximum Segment Size (MSS) offered by the internal machines to match, reducing the liklihood that the either end will attempt to send packets that are too big and result in fragmentation. This is achieved using the .B mssclamp option with TCP .B map rules like this: .nf map pppoe0 0/0 -> 0/32 mssclamp 1400 tcp .fi .PP For ICMP packets, we can map the ICMP id space in query packets: .nf map le0 10.0.0.0/8 -> 192.168.55.1/32 icmpidmap icmp 1000:20000 .fi .PP If we wish to be more specific about our initial matching criteria on the LHS, we can expand to using a syntax more similar to that in .B ipf.conf(5) : .nf map le0 from 10.0.0.0/8 to 26.0.0.0/8 -> 192.168.55.1 map le0 from 10.0.0.0/8 port > 1024 to 26.0.0.0/8 -> 192.168.55.2 portmap 5000:9999 tcp/udp map le0 from 10.0.0.0/8 ! to 26.0.0.0/8 -> 192.168.55.3 portmap 5000:9999 tcp/udp .fi .TP .B NOTE: negation matching with source addresses is .B NOT possible with .B map / .B map-block rules. .PP The NAT code has builtin default timeouts for TCP, UDP, ICMP and another for all other protocols. In general, the timeout for an entry to be deleted shrinks once a reply packet has been seen (excluding TCP.) If you wish to specify your own timeouts, this can be achieved either by setting one timeout for both directions: .nf map le0 0/0 -> 0/32 gre age 30 .fi .PP or setting a different timeout for the reply: .nf map le0 from any to any port = 53 -> 0/32 age 60/10 udp .fi .PP A pressing problem that many people encounter when using NAT is that the address protocol can be embedded inside an application's communication. To address this problem, IPFilter provides a number of built-in proxies for the more common trouble makers, such as FTP. These proxies can be used as follows: .nf map le0 0/0 -> 0/32 proxy port 21 ftp/tcp .fi .PP In this rule, the word "proxy" tells us that we want to connect up this translation with an internal proxy. The "port 21" is an extra restriction that requires the destination port number to be 21 if this rule is to be activated. The word "ftp" is the proxy identifier that the kernel will try and resolve internally, "tcp" the protocol that packets must match. .PP See below for a list of proxies and their relative status. .PP To associate NAT rules with filtering rules, it is possible to set and match tags during either inbound or outbound processing. At present the tags for forwarded packets are not preserved by forwarding, so once the packet leaves IPFilter, the tag is forgotten. For .B map rules, we can match tags set by filter rules like this: .nf map le0 0/0 -> 0/32 proxy portmap 5000:5999 tag lan1 tcp .fi .PP This would be used with "pass out" rules that includes a stanza such as "set-tag (nat = lan1)". .PP If the interface in which packets are received is different from the interface on which packets are sent out, then the translation rule needs to be written to take this into account: .nf map hme0,le0 0/0 -> 0/32 .fi .PP Although this might seem counterintuitive, the interfaces when listed in rules for .B ipnat.conf are always in the .I inbound , .I outbound order. In this case, hme0 would be the return interface and le0 would be the outgoing interface. If you wish to allow return packets on any interface, the correct syntax to use would be: .nf map *,le0 0/0 -> 0/32 .fi .LP A special variant of .B map rules exists, called .B map-block. This command is intended for use when there is a large network to be mapped onto a smaller network, where the difference in netmasks is upto 14 bits difference in size. This is achieved by dividing the address space and port space up to ensure that each source address has its own private range of ports to use. For example, this rule: .nf map-block ppp0 172.192.0.0/16 -> 209.1.2.0/24 ports auto .fi .PP would result in 172.192.0.0/24 being mapped to 209.1.2.0/32 with each address, from 172.192.0.0 to 172.192.0.255 having 252 ports of its own. As opposed to the above use of \fBmap\fP, if for some reason the user of (say) 172.192.0.2 wanted 260 simultaneous connections going out, they would be limited to 252 with \fBmap-block\fP but would just \fImove on\fP to the next IP address with the \fBmap\fP command. .SS Extended matching If it is desirable to match on both the source and destination of a packet before applying an address translation to it, this can be achieved by using the same from-to syntax as is used in \fBipf.conf\fP(5). What follows applies equally to the .B map rules discussed above and .B rdr rules discussed below. A simple example is as follows: .nf map bge0 from 10.1.0.0/16 to 192.168.1.0/24 -> 172.12.1.4 .fi .PP This would only match packets that are coming from hosts that have a source address matching 10.1.0.0/16 and a destination matching 192.168.1.0/24. This can be expanded upon with ports for TCP like this: .nf rdr bge0 from 10.1.0.0/16 to any port = 25 -> 127.0.0.1 port 2501 tcp .fi .PP Where only TCP packets from 10.1.0.0/16 to port 25 will be redirected to port 2501. .PP As with \fBipf.conf\fR(5), if we have a large set of networks or addresses that we would like to match up with then we can define a pool using \fBippool\fR(8) in \fBippool.conf\fR(5) and then refer to it in an \fBipnat\fR rule like this: .nf map bge0 from pool/100 to any port = 25 -> 127.0.0.1 port 2501 tcp .fi .TP .B NOTE: In this situation, the rule is considered to have a netmask of "0" and thus is looked at last, after any rules with /16's or /24's in them, .I even if the defined pool only has /24's or /32's. Pools may also be used .I wherever the from-to syntax in \fBipnat.conf\fR(5) is allowed. .SH INBOUND DESTINATION TRANSLATION (redirection) Redirection of packets is used to change the destination fields in a packet and is supported for packets that are moving \fIin\fP on a network interface. While the same general syntax for .B map rules is supported, there are differences and limitations. .PP Firstly, by default all redirection rules target a single IP address, not a network or range of network addresses, so a rule written like this: .nf rdr le0 0/0 -> 192.168.1.0 .fi .PP -Will not spread packets across all 256 IP addresses in that class C network. +Will not spread packets across all 256 IP addresses in that /24 subnet. If you were to try a rule like this: .nf rdr le0 0/0 -> 192.168.1.0/24 .fi .PP then you will receive a parsing error. .PP The from-to source-destination matching used with .B map rules can be used with rdr rules, along with negation, however the restriction moves - only a source address match can be negated: .nf rdr le0 from 1.1.0.0/16 to any -> 192.168.1.3 rdr le0 ! from 1.1.0.0/16 to any -> 192.168.1.4 .fi .PP If there is a consecutive set of addresses you wish to spread the packets over, then this can be done in one of two ways, the word "range" optional to preserve: .nf rdr le0 0/0 -> 192.168.1.1 - 192.168.1.5 rdr le0 0/0 -> range 192.168.1.1 - 192.168.1.5 .fi .PP If there are only two addresses to split the packets across, the recommended method is to use a comma (",") like this: .nf rdr le0 0/0 -> 192.168.1.1,192.168.1.2 .fi .PP If there is a large group of destination addresses that are somewhat disjoint in nature, we can cycle through them using a .B round-robin technique like this: .nf rdr le0 0/0 -> 192.168.1.1,192.168.1.2 round-robin rdr le0 0/0 -> 192.168.1.5,192.168.1.7 round-robin rdr le0 0/0 -> 192.168.1.9 round-robin .fi .PP If there are a large number of redirect rules and hosts being targeted then it may be desirable to have all those from a single source address be targeted at the same destination address. To achieve this, the word .B sticky is appended to the rule like this: .nf rdr le0 0/0 -> 192.168.1.1,192.168.1.2 sticky rdr le0 0/0 -> 192.168.1.5,192.168.1.7 round-robin sticky rdr le0 0/0 -> 192.168.1.9 round-robin sticky .fi .PP The .B sticky feature can only be combined with .B round-robin and the use of a comma. .PP For TCP and UDP packets, it is possible to both match on the destination port number and to modify it. For example, to change the destination port from 80 to 3128, we would use a rule like this: .nf rdr de0 0/0 port 80 -> 127.0.0.1 port 3128 tcp .fi .PP If a range of ports is given on the LHS and a single port is given on the RHS, the entire range of ports is moved. For example, if we had this: .nf rdr le0 0/0 port 80-88 -> 127.0.0.1 port 3128 tcp .fi .PP then port 80 would become 3128, port 81 would become 3129, etc. If we want to redirect a number of different pots to just a single port, an equals sign ("=") is placed before the port number on the RHS like this: .nf rdr le0 0/0 port 80-88 -> 127.0.0.1 port = 3128 tcp .fi .PP In this case, port 80 goes to 3128, port 81 to 3128, etc. .PP As with .B map rules, it is possible to manually set a timeout using the .B age option, like this: .nf rdr le0 0/0 port 53 -> 127.0.0.1 port 10053 udp age 5/5 .fi .PP The use of proxies is not restricted to .B map rules and outbound sessions. Proxies can also be used with redirect rules, although the syntax is slightly different: .nf rdr ge0 0/0 port 21 -> 127.0.0.1 port 21 tcp proxy ftp .fi .PP For .B rdr rules, the interfaces supplied are in the same order as .B map rules - input first, then output. In situations where the outgoing interface is not certain, it is also possible to use a wildcard ("*") to effect a match on any interface. .nf rdr le0,* 0/0 -> 192.168.1.0 .fi .PP A single rule, with as many options set as possible would look something like this: .nf rdr le0,ppp0 9.8.7.6/32 port 80 -> 1.1.1.1,1.1.1.2 port 80 tcp round-robin frag age 40/40 sticky mssclamp 1000 tag tagged .fi .SH REWRITING SOURCE AND DESTINATION Whilst the above two commands provide a lot of flexibility in changing addressing fields in packets, often it can be of benefit to translate \fIboth\fP source \fBand\fR destination at the same time or to change the source address on input or the destination address on output. Doing all of these things can be accomplished using .B rewrite NAT rules. .PP A .B rewrite rule requires the same level of packet matching as before, protocol and source/destination information but in addition allows either .B in or .B out to be specified like this: .nf rewrite in on ppp0 proto tcp from any to any port = 80 -> src 0/0 dst 127.0.0.1,3128; rewrite out on ppp0 from any to any -> src 0/32 dst 10.1.1.0/24; .fi .PP On the RHS we can specify both new source and destination information to place into the packet being sent out. As with other rules used in \fBipnat.conf\fR, there are shortcuts syntaxes available to use the original address information (\fB0/0\fR) and the address associated with the network interface (\fB0/32\fR.) For TCP and UDP, both address and port information can be changed. At present it is only possible to specify either a range of port numbers to be used (\fBX-Y\fR) or a single port number (\fB= X\fR) as follows: .nf rewrite in on le0 proto tcp from any to any port = 80 -> src 0/0,2000-20000 dst 127.0.0.1,port = 3128; .fi .PP There are four fields that are stepped through in enumerating the number space available for creating a new destination: .LP source address .LP source port .LP destination address .LP destination port .PP If one of these happens to be a static then it will be skipped and the next one incremented. As an example: .nf rewrite out on le0 proto tcp from any to any port = 80 -> src 1.0.0.0/8,5000-5999 dst 2.0.0.0/24,6000-6999; .fi .PP The translated packets would be: .LP 1st src=1.0.0.1,5000 dst=2.0.0.1,6000 .LP 2nd src=1.0.0.2,5000 dst=2.0.0.1,6000 .LP 3rd src=1.0.0.2,5001 dst=2.0.0.1,6000 .LP 4th src=1.0.0.2,5001 dst=2.0.0.2,6000 .LP 5th src=1.0.0.2,5001 dst=2.0.0.2,6001 .LP 6th src=1.0.0.3,5001 dst=2.0.0.2,6001 .PP and so on. .PP As with .B map rules, it is possible to specify a range of addresses by including the word \fIrange\fR before the addresses: .nf rewrite from any to any port = 80 -> src 1.1.2.3 - 1.1.2.6 dst 2.2.3.4 - 2.2.3.6; .fi .SH DIVERTING PACKETS If you'd like to send packets to a UDP socket rather than just another computer to be decapsulated, this can be achieved using a .B divert rule. .PP Divert rules can be used with both inbound and outbound packet matching however the rule .B must specify host addresses for the outer packet, not ranges of addresses or netmasks, just single addresses. Additionally the syntax must supply required information for UDP. An example of what a divert rule looks ike is as follows: .nf divert in on le0 proto udp from any to any port = 53 -> src 192.1.1.1,54 dst 192.168.1.22.1,5300; .fi .PP On the LHS is a normal set of matching capabilities but on the RHS it is a requirement to specify both the source and destination addresses and ports. .PP As this feature is intended to be used with targeting packets at sockets and not IPFilter running on other systems, there is no rule provided to \fIundivert\fR packets. .TP .B NOTE: Diverted packets \fImay\fP be fragmented if the addition of the encapsulating IP header plus UDP header causes the packet to exceed the size allowed by the outbound network interface. At present it is not possible to cause Path MTU discovery to happen as this feature is intended to be transparent to both endpoints. .B Path MTU Discovery If Path MTU discovery is being used and the "do not fragment" flag is set in packets to be encapsulated, an ICMP error message will be sent back to the sender if the new packet would need to be fragmented. .SH COMMON OPTIONS This section deals with options that are available with all rules. .TP .B purge When the purge keyword is added to the end of a NAT rule, it will cause all of the active NAT sessions to be removed when the rule is removed as an individual operation. If all of the NAT rules are flushed out, it is expected that the operator will similarly flush the NAT table and thus NAT sessions are not removed when the NAT rules are flushed out. .SH RULE ORDERING .B NOTE: Rules in .B ipnat.conf are read in sequentially as listed and loaded into the kernel in this fashion .B BUT packet matching is done on \fBnetmask\fR, going from 32 down to 0. If a rule uses .B pool or .B hash to reference a set of addresses or networks, the netmask value for these fields is considered to be "0". So if your .B ipnat.conf has the following rules: .nf rdr le0 192.0.0.0/8 port 80 -> 127.0.0.1 3132 tcp rdr le0 192.2.0.0/16 port 80 -> 127.0.0.1 3131 tcp rdr le0 from any to pool/100 port 80 -> 127.0.0.1 port 3130 tcp rdr le0 192.2.2.0/24 port 80 -> 127.0.0.1 3129 tcp rdr le0 192.2.2.1 port 80 -> 127.0.0.1 3128 tcp .fi .PP then the rule with 192.2.2.1 will match \fBfirst\fR, regardless of where it appears in the ordering of the above rules. In fact, the order in which they would be used to match a packet is: .nf rdr le0 192.2.2.1 port 80 -> 127.0.0.1 3128 tcp rdr le0 192.2.2.0/24 port 80 -> 127.0.0.1 3129 tcp rdr le0 192.2.0.0/16 port 80 -> 127.0.0.1 3131 tcp rdr le0 192.0.0.0/8 port 80 -> 127.0.0.1 3132 tcp rdr le0 from any to pool/100 port 80 -> 127.0.0.1 port 3130 tcp .fi .PP where the first line is actually a /32. .PP If your .B ipnat.conf file has entries with matching target fields (source address for .B map rules and destination address for .B rdr rules), then the ordering in the .B ipnat.conf file does matter. So if you had the following: .nf rdr le0 from 1.1.0.0/16 to 192.2.2.1 port 80 -> 127.0.0.1 3129 tcp rdr le0 from 1.1.1.0/24 to 192.2.2.1 port 80 -> 127.0.0.1 3128 tcp .fi .PP Then no packets will match the 2nd rule, they'll all match the first. .SH IPv6 In all of the examples above, where an IPv4 address is present, an IPv6 address can also be used. All rules must use either IPv4 addresses with both halves of the NAT rule or IPv6 addresses for both halves. Mixing IPv6 addresses with IPv4 addresses, in a single rule, will result in an error. .PP For shorthand notations such as "0/32", the equivalent for IPv6 is "0/128". IPFilter will treat any netmask greater than 32 as an implicit direction that the address should be IPv6, not IPv4. To be unambiguous with 0/0, for IPv6 use ::0/0. .SH KERNEL PROXIES IP Filter comes with a few, simple, proxies built into the code that is loaded into the kernel to allow secondary channels to be opened without forcing the packets through a user program. The current state of the proxies is listed below, as one of three states: .HP Aging - protocol is roughly understood from the time at which the proxy was written but it is not well tested or maintained; .HP Developmental - basic functionality exists, works most of the time but may be problematic in extended real use; .HP Experimental - rough support for the protocol at best, may or may not work as testing has been at best sporadic, possible large scale changes to the code in order to properly support the protocol. .HP Mature - well tested, protocol is properly understood by the proxy; .PP The currently compiled in proxy list is as follows: .TP FTP - Mature (map ... proxy port ftp ftp/tcp) .TP IRC - Experimental (proxy port 6667 irc/tcp) .TP rpcbind - Experimental .TP PPTP - Experimental .TP H.323 - Experimental (map ... proxy port 1720 h323/tcp) .TP Real Audio (PNA) - Aging .TP DNS - Developmental (map ... proxy port 53 dns/udp { block .cnn.com; }) .TP IPsec - Developmental (map ... proxy port 500 ipsec/tcp) .TP netbios - Experimental .TP R-command - Mature (map ... proxy port shell rcmd/tcp) .SH KERNEL PROXIES .SH FILES /dev/ipnat .br /etc/protocols .br /etc/services .br /etc/hosts .SH SEE ALSO ipnat(4), hosts(5), ipf(5), services(5), ipf(8), ipnat(8) diff --git a/sys/netinet/libalias/libalias.3 b/sys/netinet/libalias/libalias.3 index c19acffe03ae..1b8ecc14059d 100644 --- a/sys/netinet/libalias/libalias.3 +++ b/sys/netinet/libalias/libalias.3 @@ -1,1499 +1,1499 @@ .\"- .\" Copyright (c) 2001 Charles Mott .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd November 29, 2024 .Dt LIBALIAS 3 .Os .Sh NAME .Nm libalias .Nd packet aliasing library for masquerading and network address translation .Sh SYNOPSIS .In sys/types.h .In netinet/in.h .In alias.h .Pp Function prototypes are given in the main body of the text. .Sh DESCRIPTION The .Nm library is a collection of functions for aliasing and de-aliasing of IP packets, intended for masquerading and network address translation (NAT). .Sh INTRODUCTION This library is a moderately portable set of functions designed to assist in the process of IP masquerading and network address translation. Outgoing packets from a local network with unregistered IP addresses can be aliased to appear as if they came from an accessible IP address. Incoming packets are then de-aliased so that they are sent to the correct machine on the local network. .Pp A certain amount of flexibility is built into the packet aliasing engine. In the simplest mode of operation, a many-to-one address mapping takes place between the local network and the packet aliasing host. This is known as IP masquerading. In addition, one-to-one mappings between local and public addresses can also be implemented, which is known as static NAT. In between these extremes, different groups of private addresses can be linked to different public addresses, comprising several distinct many-to-one mappings. Also, a given public address and port can be statically redirected to a private address/port. .Sh INITIALIZATION AND CONTROL One special function, .Fn LibAliasInit , must always be called before any packet handling may be performed, and the returned instance pointer must be passed to all the other functions. Normally, the .Fn LibAliasSetAddress function is called afterwards, to set the default aliasing address. In addition, the operating mode of the packet aliasing engine can be customized by calling .Fn LibAliasSetMode . .Pp .Ft "struct libalias *" .Fn LibAliasInit "struct libalias *" .Bd -ragged -offset indent This function is used to initialize internal data structures. When called the first time, a .Dv NULL pointer should be passed as an argument. The following mode bits are always set after calling .Fn LibAliasInit . See the description of .Fn LibAliasSetMode below for the meaning of these mode bits. .Pp .Bl -item -offset indent -compact .It .Dv PKT_ALIAS_SAME_PORTS .It .Dv PKT_ALIAS_USE_SOCKETS .It .Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE .El .Pp This function will always return the packet aliasing engine to the same initial state. The .Fn LibAliasSetAddress function is normally called afterwards, and any desired changes from the default mode bits listed above require a call to .Fn LibAliasSetMode . .Pp It is mandatory that this function be called at the beginning of a program prior to any packet handling. .Ed .Pp .Ft void .Fn LibAliasUninit "struct libalias *" .Bd -ragged -offset indent This function has no return value and is used to clear any resources attached to internal data structures. .Pp This function should be called when a program stops using the aliasing engine; amongst other things, it clears out any firewall holes. To provide backwards compatibility and extra security, it is added to the .Xr atexit 3 chain by .Fn LibAliasInit . .Ed .Pp .Ft void .Fn LibAliasSetAddress "struct libalias *" "struct in_addr addr" .Bd -ragged -offset indent This function sets the source address to which outgoing packets from the local area network are aliased. All outgoing packets are re-mapped to this address unless overridden by a static address mapping established by .Fn LibAliasRedirectAddr . If this function has not been called, and no static rules match, an outgoing packet retains its source address. .Pp If the .Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE mode bit is set (the default mode of operation), then the internal aliasing link tables will be reset any time the aliasing address changes. This is useful for interfaces such as .Xr ppp 8 , where the IP address may or may not change on successive dial-up attempts. .Pp If the .Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE mode bit is set to zero, this function can also be used to dynamically change the aliasing address on a packet-to-packet basis (it is a low overhead call). .Pp It is mandatory that this function be called prior to any packet handling. .Ed .Pp .Ft unsigned int .Fn LibAliasSetMode "struct libalias *" "unsigned int flags" "unsigned int mask" .Bd -ragged -offset indent This function sets or clears mode bits according to the value of .Fa flags . Only bits marked in .Fa mask are affected. The following mode bits are defined in .In alias.h : .Bl -tag -width indent .It Dv PKT_ALIAS_LOG Enables logging into .Pa /var/log/alias.log . Each time an aliasing link is created or deleted, the log file is appended to with the current number of ICMP, TCP and UDP links. Mainly useful for debugging when the log file is viewed continuously with .Xr tail 1 . .It Dv PKT_ALIAS_DENY_INCOMING If this mode bit is set, all incoming packets associated with new TCP connections or new UDP transactions will be marked for being ignored .Po .Fn LibAliasIn returns .Dv PKT_ALIAS_IGNORED code .Pc by the calling program. Response packets to connections or transactions initiated from the packet aliasing host or local network will be unaffected. This mode bit is useful for implementing a one-way firewall. .It Dv PKT_ALIAS_SAME_PORTS If this mode bit is set, the packet-aliasing engine will attempt to leave the alias port numbers unchanged from the actual local port numbers. This can be done as long as the quintuple (proto, alias addr, alias port, remote addr, remote port) is unique. If a conflict exists, a new aliasing port number is chosen even if this mode bit is set. .It Dv PKT_ALIAS_USE_SOCKETS This bit should be set when the packet aliasing host originates network traffic as well as forwards it. When the packet aliasing host is waiting for a connection from an unknown host address or unknown port number (e.g.\& an FTP data connection), this mode bit specifies that a socket be allocated as a place holder to prevent port conflicts. Once a connection is established, usually within a minute or so, the socket is closed. .It Dv PKT_ALIAS_UNREGISTERED_ONLY If this mode bit is set, traffic on the local network which does not originate from unregistered address spaces will be ignored. -Standard Class A, B and C unregistered addresses are: +The standard private IP address ranges are: .Pp -10.0.0.0 -> 10.255.255.255 (Class A subnet) -172.16.0.0 -> 172.31.255.255 (Class B subnets) -192.168.0.0 -> 192.168.255.255 (Class C subnets) +10.0.0.0 -> 10.255.255.255 (/8) +172.16.0.0 -> 172.31.255.255 (/16) +192.168.0.0 -> 192.168.255.255 (/24) .Pp This option is useful in the case that the packet aliasing host has both registered and unregistered subnets on different interfaces. The registered subnet is fully accessible to the outside world, so traffic from it does not need to be passed through the packet aliasing engine. .It Dv PKT_ALIAS_UNREGISTERED_CGN Like PKT_ALIAS_UNREGISTERED_ONLY, but includes the RFC 6598 (Carrier Grade NAT) subnet as follows: .Pp 100.64.0.0 -> 100.127.255.255 (RFC 6598 subnet) .It Dv PKT_ALIAS_RESET_ON_ADDR_CHANGE When this mode bit is set and .Fn LibAliasSetAddress is called to change the aliasing address, the internal link table of the packet aliasing engine will be cleared. This operating mode is useful for .Xr ppp 8 links where the interface address can sometimes change or remain the same between dial-up attempts. If this mode bit is not set, the link table will never be reset in the event of an address change. .It Dv PKT_ALIAS_PUNCH_FW This option makes .Nm .Dq punch holes in an .Xr ipfirewall 4 - based firewall for FTP/IRC DCC connections. The holes punched are bound by from/to IP address and port; it will not be possible to use a hole for another connection. A hole is removed when the connection that uses it dies. To cater to unexpected death of a program using .Nm (e.g.\& kill -9), changing the state of the flag will clear the entire firewall range allocated for holes. This clearing will also happen on the initial call to .Fn LibAliasSetFWBase , which must happen prior to setting this flag. .It Dv PKT_ALIAS_REVERSE This option makes .Nm reverse the way it handles incoming and outgoing packets, allowing it to be fed with data that passes through the internal interface rather than the external one. .It Dv PKT_ALIAS_PROXY_ONLY This option tells .Nm to obey transparent proxy rules only. Normal packet aliasing is not performed. See .Fn LibAliasProxyRule below for details. .It Dv PKT_ALIAS_SKIP_GLOBAL This option is used by .Pa ipfw_nat only. Specifying it as a flag to .Fn LibAliasSetMode has no effect. See section .Sx NETWORK ADDRESS TRANSLATION in .Xr ipfw 8 for more details. .It Dv PKT_ALIAS_UDP_EIM When this bit is set, UDP uses endpoint-independent mapping (EIM), as per RFC 4787 ("full cone" NAT of RFC 3489). All packets from the same internal address:port are mapped to the same NAT address:port, regardless of their destination address:port. If filtering rules allow, and if .Em PKT_ALIAS_DENY_INCOMING is unset, any other external address:port can also send to the internal address:port through its mapped NAT address:port. This is more compatible with applications, and can reduce the need for port forwarding, but less scalable as each NAT address:port can only be concurrently used by at most one internal address:port. .Pp When this bit is unset, UDP packets use endpoint-dependent mapping (EDM) ("symmetric" NAT). Each connection from a particular internal address:port to different external addresses:ports is mapped to a random and unpredictable NAT address:port. Two appplications behind EDM NATs can only connect to each other by port forwarding on the NAT, or tunnelling through an in-between server. .El .Ed .Pp .Ft void .Fn LibAliasSetFWBase "struct libalias *" "unsigned int base" "unsigned int num" .Bd -ragged -offset indent Set the firewall range allocated for punching firewall holes (with the .Dv PKT_ALIAS_PUNCH_FW flag). The range is cleared for all rules on initialization. .Ed .Pp .Ft void .Fn LibAliasSkinnyPort "struct libalias *" "unsigned int port" .Bd -ragged -offset indent Set the TCP port used by the Skinny Station protocol. Skinny is used by Cisco IP phones to communicate with Cisco Call Managers to set up voice over IP calls. If this is not set, Skinny aliasing will not be done. The typical port used by Skinny is 2000. .Ed .Sh PACKET HANDLING The packet handling functions are used to modify incoming (remote to local) and outgoing (local to remote) packets. The calling program is responsible for receiving and sending packets via network interfaces. .Pp Along with .Fn LibAliasInit and .Fn LibAliasSetAddress , the two packet handling functions, .Fn LibAliasIn and .Fn LibAliasOut , comprise the minimal set of functions needed for a basic IP masquerading implementation. .Pp .Ft int .Fn LibAliasIn "struct libalias *" "void *buffer" "int maxpacketsize" .Bd -ragged -offset indent An incoming packet coming from a remote machine to the local network is de-aliased by this function. The IP packet is pointed to by .Fa buffer , and .Fa maxpacketsize indicates the size of the data structure containing the packet and should be at least as large as the actual packet size. .Pp Return codes: .Bl -tag -width indent .It Dv PKT_ALIAS_OK The packet aliasing process was successful. .It Dv PKT_ALIAS_IGNORED The packet was ignored and not de-aliased. This can happen if the protocol is unrecognized, as for an ICMP message type that is not handled, or if incoming packets for new connections are being ignored (if the .Dv PKT_ALIAS_DENY_INCOMING mode bit was set using .Fn LibAliasSetMode ) . .It Dv PKT_ALIAS_UNRESOLVED_FRAGMENT This is returned when a fragment cannot be resolved because the header fragment has not been sent yet. In this situation, fragments must be saved with .Fn LibAliasSaveFragment until a header fragment is found. .It Dv PKT_ALIAS_FOUND_HEADER_FRAGMENT The packet aliasing process was successful, and a header fragment was found. This is a signal to retrieve any unresolved fragments with .Fn LibAliasGetFragment and de-alias them with .Fn LibAliasFragmentIn . .It Dv PKT_ALIAS_ERROR An internal error within the packet aliasing engine occurred. .El .Ed .Pp .Ft int .Fn LibAliasOut "struct libalias *" "void *buffer" "int maxpacketsize" .Bd -ragged -offset indent An outgoing packet coming from the local network to a remote machine is aliased by this function. The IP packet is pointed to by .Fa buffer , and .Fa maxpacketsize indicates the maximum packet size permissible should the packet length be changed. IP encoding protocols place address and port information in the encapsulated data stream which has to be modified and can account for changes in packet length. Well known examples of such protocols are FTP and IRC DCC. .Pp Return codes: .Bl -tag -width indent .It Dv PKT_ALIAS_OK The packet aliasing process was successful. .It Dv PKT_ALIAS_IGNORED The packet was ignored and not aliased. This can happen if the protocol is unrecognized, or possibly an ICMP message type is not handled. .It Dv PKT_ALIAS_ERROR An internal error within the packet aliasing engine occurred. .El .Ed .Sh PORT AND ADDRESS REDIRECTION The functions described in this section allow machines on the local network to be accessible in some degree to new incoming connections from the external network. Individual ports can be re-mapped or static network address translations can be designated. .Pp .Ft struct alias_link * .Fo LibAliasRedirectPort .Fa "struct libalias *" .Fa "struct in_addr local_addr" .Fa "u_short local_port" .Fa "struct in_addr remote_addr" .Fa "u_short remote_port" .Fa "struct in_addr alias_addr" .Fa "u_short alias_port" .Fa "u_char proto" .Fc .Bd -ragged -offset indent This function specifies that traffic from a given remote address/port to an alias address/port be redirected to a specified local address/port. The parameter .Fa proto can be either .Dv IPPROTO_TCP or .Dv IPPROTO_UDP , as defined in .In netinet/in.h . .Pp If .Fa local_addr or .Fa alias_addr is zero, this indicates that the packet aliasing address as established by .Fn LibAliasSetAddress is to be used. Even if .Fn LibAliasSetAddress is called to change the address after .Fn LibAliasRedirectPort is called, a zero reference will track this change. .Pp If the link is further set up to operate with load sharing, then .Fa local_addr and .Fa local_port are ignored, and are selected dynamically from the server pool, as described in .Fn LibAliasAddServer below. .Pp If .Fa remote_addr is zero, this indicates to redirect packets from any remote address. Likewise, if .Fa remote_port is zero, this indicates to redirect packets originating from any remote port number. The remote port specification will almost always be zero, but non-zero remote addresses can sometimes be useful for firewalling. If two calls to .Fn LibAliasRedirectPort overlap in their address/port specifications, then the most recent call will have precedence. .Pp This function returns a pointer which can subsequently be used by .Fn LibAliasRedirectDelete . If .Dv NULL is returned, then the function call did not complete successfully. .Pp All port numbers should be in network address byte order, so it is necessary to use .Xr htons 3 to convert these parameters from internally readable numbers to network byte order. Addresses are also in network byte order, which is implicit in the use of the .Fa struct in_addr data type. .Ed .Pp .Ft struct alias_link * .Fo LibAliasRedirectAddr .Fa "struct libalias *" .Fa "struct in_addr local_addr" .Fa "struct in_addr alias_addr" .Fc .Bd -ragged -offset indent This function designates that all incoming traffic to .Fa alias_addr be redirected to .Fa local_addr . Similarly, all outgoing traffic from .Fa local_addr is aliased to .Fa alias_addr . .Pp If .Fa local_addr or .Fa alias_addr is zero, this indicates that the packet aliasing address as established by .Fn LibAliasSetAddress is to be used. Even if .Fn LibAliasSetAddress is called to change the address after .Fn LibAliasRedirectAddr is called, a zero reference will track this change. .Pp If the link is further set up to operate with load sharing, then the .Fa local_addr argument is ignored, and is selected dynamically from the server pool, as described in .Fn LibAliasAddServer below. .Pp If subsequent calls to .Fn LibAliasRedirectAddr use the same aliasing address, all new incoming traffic to this aliasing address will be redirected to the local address made in the last function call. New traffic generated by any of the local machines, designated in the several function calls, will be aliased to the same address. Consider the following example: .Pp LibAliasRedirectAddr(la, inet_aton("192.168.0.2"), inet_aton("141.221.254.101")); LibAliasRedirectAddr(la, inet_aton("192.168.0.3"), inet_aton("141.221.254.101")); LibAliasRedirectAddr(la, inet_aton("192.168.0.4"), inet_aton("141.221.254.101")); .Pp Any outgoing connections such as .Xr telnet 1 or .Xr ftp 1 from 192.168.0.2, 192.168.0.3 and 192.168.0.4 will appear to come from 141.221.254.101. Any incoming connections to 141.221.254.101 will be directed to 192.168.0.4. .Pp Any calls to .Fn LibAliasRedirectPort will have precedence over address mappings designated by .Fn LibAliasRedirectAddr . .Pp This function returns a pointer which can subsequently be used by .Fn LibAliasRedirectDelete . If .Dv NULL is returned, then the function call did not complete successfully. .Ed .Pp .Ft int .Fo LibAliasAddServer .Fa "struct libalias *" .Fa "struct alias_link *link" .Fa "struct in_addr addr" .Fa "u_short port" .Fc .Bd -ragged -offset indent This function sets the .Fa link up for Load Sharing using IP Network Address Translation (RFC 2391, LSNAT). LSNAT operates as follows. A client attempts to access a server by using the server virtual address. The LSNAT router transparently redirects the request to one of the hosts in the server pool, using a real-time load sharing algorithm. Multiple sessions may be initiated from the same client, and each session could be directed to a different host based on the load balance across server pool hosts when the sessions are initiated. If load sharing is desired for just a few specific services, the configuration on LSNAT could be defined to restrict load sharing to just the services desired. .Pp Currently, only the simplest selection algorithm is implemented, where a host is selected on a round-robin basis only, without regard to load on the host. .Pp First, the .Fa link is created by either .Fn LibAliasRedirectPort or .Fn LibAliasRedirectAddr . Then, .Fn LibAliasAddServer is called multiple times to add entries to the .Fa link Ns 's server pool. .Pp For links created with .Fn LibAliasRedirectAddr , the .Fa port argument is ignored and could have any value, e.g.\& htons(~0). .Pp This function returns 0 on success, \-1 otherwise. .Ed .Pp .Ft int .Fn LibAliasRedirectDynamic "struct libalias *" "struct alias_link *link" .Bd -ragged -offset indent This function marks the specified static redirect rule entered by .Fn LibAliasRedirectPort as dynamic. This can be used to e.g.\& dynamically redirect a single TCP connection, after which the rule is removed. Only fully specified links can be made dynamic. (See the .Sx STATIC AND DYNAMIC LINKS and .Sx PARTIALLY SPECIFIED ALIASING LINKS sections below for a definition of static vs.\& dynamic, and partially vs.\& fully specified links.) .Pp This function returns 0 on success, \-1 otherwise. .Ed .Pp .Ft void .Fn LibAliasRedirectDelete "struct libalias *" "struct alias_link *link" .Bd -ragged -offset indent This function will delete a specific static redirect rule entered by .Fn LibAliasRedirectPort or .Fn LibAliasRedirectAddr . The parameter .Fa link is the pointer returned by either of the redirection functions. If an invalid pointer is passed to .Fn LibAliasRedirectDelete , then a program crash or unpredictable operation could result, so care is needed when using this function. .Ed .Pp .Ft int .Fn LibAliasProxyRule "struct libalias *" "const char *cmd" .Bd -ragged -offset indent The passed .Fa cmd string consists of one or more pairs of words. The first word in each pair is a token and the second is the value that should be applied for that token. Tokens and their argument types are as follows: .Bl -tag -width indent .It Cm type encode_ip_hdr | encode_tcp_stream | no_encode In order to support transparent proxying, it is necessary to somehow pass the original address and port information into the new destination server. If .Cm encode_ip_hdr is specified, the original destination address and port are passed as an extra IP option. If .Cm encode_tcp_stream is specified, the original destination address and port are passed as the first piece of data in the TCP stream in the format .Dq Li DEST Ar IP port . .It Cm port Ar portnum Only packets with the destination port .Ar portnum are proxied. .It Cm server Ar host Ns Op : Ns Ar portnum This specifies the .Ar host and .Ar portnum that the data is to be redirected to. .Ar host must be an IP address rather than a DNS host name. If .Ar portnum is not specified, the destination port number is not changed. .Pp The .Ar server specification is mandatory unless the .Cm delete command is being used. .It Cm rule Ar index Normally, each call to .Fn LibAliasProxyRule inserts the next rule at the start of a linear list of rules. If an .Ar index is specified, the new rule will be checked after all rules with lower indices. Calls to .Fn LibAliasProxyRule that do not specify a rule are assigned rule 0. .It Cm delete Ar index This token and its argument MUST NOT be used with any other tokens. When used, all existing rules with the given .Ar index are deleted. .It Cm proto tcp | udp If specified, only packets of the given protocol type are matched. .It Cm src Ar IP Ns Op / Ns Ar bits If specified, only packets with a source address matching the given .Ar IP are matched. If .Ar bits is also specified, then the first .Ar bits bits of .Ar IP are taken as a network specification, and all IP addresses from that network will be matched. .It Cm dst Ar IP Ns Op / Ns Ar bits If specified, only packets with a destination address matching the given .Ar IP are matched. If .Ar bits is also specified, then the first .Ar bits bits of .Ar IP are taken as a network specification, and all IP addresses from that network will be matched. .El .Pp This function is usually used to redirect outgoing connections for internal machines that are not permitted certain types of internet access, or to restrict access to certain external machines. .Ed .Pp .Ft struct alias_link * .Fo LibAliasRedirectProto .Fa "struct libalias *" .Fa "struct in_addr local_addr" .Fa "struct in_addr remote_addr" .Fa "struct in_addr alias_addr" .Fa "u_char proto" .Fc .Bd -ragged -offset indent This function specifies that any IP packet with protocol number of .Fa proto from a given remote address to an alias address will be redirected to a specified local address. .Pp If .Fa local_addr or .Fa alias_addr is zero, this indicates that the packet aliasing address as established by .Fn LibAliasSetAddress is to be used. Even if .Fn LibAliasSetAddress is called to change the address after .Fn LibAliasRedirectProto is called, a zero reference will track this change. .Pp If .Fa remote_addr is zero, this indicates to redirect packets from any remote address. Non-zero remote addresses can sometimes be useful for firewalling. .Pp If two calls to .Fn LibAliasRedirectProto overlap in their address specifications, then the most recent call will have precedence. .Pp This function returns a pointer which can subsequently be used by .Fn LibAliasRedirectDelete . If .Dv NULL is returned, then the function call did not complete successfully. .Ed .Sh FRAGMENT HANDLING The functions in this section are used to deal with incoming fragments. .Pp Outgoing fragments are handled within .Fn LibAliasOut by changing the address according to any applicable mapping set by .Fn LibAliasRedirectAddr , or the default aliasing address set by .Fn LibAliasSetAddress . .Pp Incoming fragments are handled in one of two ways. If the header of a fragmented IP packet has already been seen, then all subsequent fragments will be re-mapped in the same manner the header fragment was. Fragments which arrive before the header are saved and then retrieved once the header fragment has been resolved. .Pp .Ft int .Fn LibAliasSaveFragment "struct libalias *" "void *ptr" .Bd -ragged -offset indent When .Fn LibAliasIn returns .Dv PKT_ALIAS_UNRESOLVED_FRAGMENT , this function can be used to save the pointer to the unresolved fragment. .Pp It is implicitly assumed that .Fa ptr points to a block of memory allocated by .Xr malloc 3 . If the fragment is never resolved, the packet aliasing engine will automatically free the memory after a timeout period. [Eventually this function should be modified so that a callback function for freeing memory is passed as an argument.] .Pp This function returns .Dv PKT_ALIAS_OK if it was successful and .Dv PKT_ALIAS_ERROR if there was an error. .Ed .Pp .Ft void * .Fn LibAliasGetFragment "struct libalias *" "void *buffer" .Bd -ragged -offset indent This function can be used to retrieve fragment pointers saved by .Fn LibAliasSaveFragment . The IP header fragment pointed to by .Fa buffer is the header fragment indicated when .Fn LibAliasIn returns .Dv PKT_ALIAS_FOUND_HEADER_FRAGMENT . Once a fragment pointer is retrieved, it becomes the calling program's responsibility to free the dynamically allocated memory for the fragment. .Pp The .Fn LibAliasGetFragment function can be called sequentially until there are no more fragments available, at which time it returns .Dv NULL . .Ed .Pp .Ft void .Fn LibAliasFragmentIn "struct libalias *" "void *header" "void *fragment" .Bd -ragged -offset indent When a fragment is retrieved with .Fn LibAliasGetFragment , it can then be de-aliased with a call to .Fn LibAliasFragmentIn . The .Fa header argument is the pointer to a header fragment used as a template, and .Fa fragment is the pointer to the packet to be de-aliased. .Ed .Sh MISCELLANEOUS FUNCTIONS .Ft struct alias_link * .Fn AddLink "struct libalias *" "struct in_addr src_addr" "struct in_addr dst_addr" \ "struct in_addr alias_addr" "u_short src_port" "u_short dst_port" \ "int alias_param" "int link_type" .Bd -ragged -offset indent This function adds new state to the instance hash table. The dst_address and/or dst_port may be given as zero, which introduces some dynamic character into the link, since LibAliasSetAddress can change the address that is used. However, in the current implementation, such links can only be used for inbound (ext -> int) traffic. .Ed .Pp .Ft void .Fn LibAliasSetTarget "struct libalias *" "struct in_addr addr" .Bd -ragged -offset indent When an incoming packet not associated with any pre-existing aliasing link arrives at the host machine, it will be sent to the address indicated by a call to .Fn LibAliasSetTarget . .Pp If this function is called with an .Dv INADDR_NONE address argument, then all new incoming packets go to the address set by .Fn LibAliasSetAddress . .Pp If this function is not called, or is called with an .Dv INADDR_ANY address argument, then all new incoming packets go to the address specified in the packet. This allows external machines to talk directly to internal machines if they can route packets to the machine in question. .Ed .Pp .Ft u_short .Fn LibAliasInternetChecksum "struct libalias *" "u_short *buffer" "int nbytes" .Bd -ragged -offset indent This is a utility function that does not seem to be available elsewhere and is included as a convenience. It computes the internet checksum, which is used in both IP and protocol-specific headers (TCP, UDP, ICMP). .Pp The .Fa buffer argument points to the data block to be checksummed, and .Fa nbytes is the number of bytes. The 16-bit checksum field should be zeroed before computing the checksum. .Pp Checksums can also be verified by operating on a block of data including its checksum. If the checksum is valid, .Fn LibAliasInternetChecksum will return zero. .Ed .Pp .Ft int .Fn LibAliasUnaliasOut "struct libalias *" "void *buffer" "int maxpacketsize" .Bd -ragged -offset indent An outgoing packet, which has already been aliased, has its private address/port information restored by this function. The IP packet is pointed to by .Fa buffer , and .Fa maxpacketsize is provided for error checking purposes. This function can be used if an already-aliased packet needs to have its original IP header restored for further processing (e.g.\& logging). .Ed .Sh CONCEPTUAL BACKGROUND This section is intended for those who are planning to modify the source code or want to create somewhat esoteric applications using the packet aliasing functions. .Pp The conceptual framework under which the packet aliasing engine operates is described here. Central to the discussion is the idea of an .Em aliasing link which describes the relationship for a given packet transaction between the local machine, aliased identity and remote machine. It is discussed how such links come into existence and are destroyed. .Ss ALIASING LINKS There is a notion of an .Em aliasing link , which is a 7-tuple describing a specific translation: .Bd -literal -offset indent (local addr, local port, alias addr, alias port, remote addr, remote port, protocol) .Ed .Pp Outgoing packets have the local address and port number replaced with the alias address and port number. Incoming packets undergo the reverse process. The packet aliasing engine attempts to match packets against an internal table of aliasing links to determine how to modify a given IP packet. Both the IP header and protocol dependent headers are modified as necessary. Aliasing links are created and deleted as necessary according to network traffic. .Pp Protocols can be TCP, UDP or even ICMP in certain circumstances. (Some types of ICMP packets can be aliased according to sequence or ID number which acts as an equivalent port number for identifying how individual packets should be handled.) .Pp Each aliasing link must have a unique combination of the following five quantities: alias address/port, remote address/port and protocol. This ensures that several machines on a local network can share the same aliasing IP address. In cases where conflicts might arise, the aliasing port is chosen so that uniqueness is maintained. .Ss STATIC AND DYNAMIC LINKS Aliasing links can either be static or dynamic. Static links persist indefinitely and represent fixed rules for translating IP packets. Dynamic links come into existence for a specific TCP connection or UDP transaction or ICMP ECHO sequence. For the case of TCP, the connection can be monitored to see when the associated aliasing link should be deleted. Aliasing links for UDP transactions (and ICMP ECHO and TIMESTAMP requests) work on a simple timeout rule. When no activity is observed on a dynamic link for a certain amount of time it is automatically deleted. Timeout rules also apply to TCP connections which do not open or close properly. .Ss PARTIALLY SPECIFIED ALIASING LINKS Aliasing links can be partially specified, meaning that the remote address and/or remote port are unknown. In this case, when a packet matching the incomplete specification is found, a fully specified dynamic link is created. If the original partially specified link is dynamic, it will be deleted after the fully specified link is created, otherwise it will persist. .Pp For instance, a partially specified link might be .Bd -literal -offset indent (192.168.0.4, 23, 204.228.203.215, 8066, 0, 0, tcp) .Ed .Pp The zeros denote unspecified components for the remote address and port. If this link were static it would have the effect of redirecting all incoming traffic from port 8066 of 204.228.203.215 to port 23 (telnet) of machine 192.168.0.4 on the local network. Each individual telnet connection would initiate the creation of a distinct dynamic link. .Ss DYNAMIC LINK CREATION In addition to aliasing links, there are also address mappings that can be stored within the internal data table of the packet aliasing mechanism. .Bd -literal -offset indent (local addr, alias addr) .Ed .Pp Address mappings are searched when creating new dynamic links. .Pp All outgoing packets from the local network automatically create a dynamic link if they do not match an already existing fully specified link. If an address mapping exists for the outgoing packet, this determines the alias address to be used. If no mapping exists, then a default address, usually the address of the packet aliasing host, is used. If necessary, this default address can be changed as often as each individual packet arrives. .Pp The aliasing port number is determined such that the new dynamic link does not conflict with any existing links. In the default operating mode, the packet aliasing engine attempts to set the aliasing port equal to the local port number. If this results in a conflict, then port numbers are randomly chosen until a unique aliasing link can be established. In an alternate operating mode, the first choice of an aliasing port is also random and unrelated to the local port number. .Sh MODULAR ARCHITECTURE Po AND Xr ipfw 4 SUPPORT Pc One of the latest improvements to .Nm was to make its support for new protocols independent from the rest of the library, giving it the ability to load/unload support for new protocols at run-time. To achieve this feature, all the code for protocol handling was moved to a series of modules outside of the main library. These modules are compiled from the same sources but work in different ways, depending on whether they are compiled to work inside a kernel or as part of the userland library. .Ss LIBALIAS MODULES IN KERNEL LAND When compiled for the kernel, .Nm modules are plain KLDs recognizable with the .Pa alias_ prefix. .Pp To add support for a new protocol, load the corresponding module. For example: .Pp .Dl "kldload alias_ftp" .Pp When support for a protocol is no longer needed, its module can be unloaded: .Pp .Dl "kldunload alias_ftp" .Ss LIBALIAS MODULES IN USERLAND Due to the differences between kernel and userland (no KLD mechanism, many different address spaces, etc.), we had to change a bit how to handle module loading/tracking/unloading in userland. .Pp While compiled for a userland .Nm , all the modules are plain libraries, residing in .Pa /usr/lib , and recognizable with the .Pa libalias_ prefix. .Pp There is a configuration file, .Pa /etc/libalias.conf , with the following contents (by default): .Bd -literal -offset indent /usr/lib/libalias_ftp.so /usr/lib/libalias_irc.so /usr/lib/libalias_nbt.so /usr/lib/libalias_pptp.so /usr/lib/libalias_skinny.so /usr/lib/libalias_smedia.so .Ed .Pp This file contains the paths to the modules that .Nm will load. To load/unload a new module, just add its path to .Pa libalias.conf and call .Fn LibAliasRefreshModules from the program. In case the application provides a .Dv SIGHUP signal handler, add a call to .Fn LibAliasRefreshModules inside the handler, and every time you want to refresh the loaded modules, send it the .Dv SIGHUP signal: .Pp .Dl "kill -HUP " .Ss MODULAR ARCHITECURE: HOW IT WORKS The modular architecture of .Nm works similar whether it is running inside the kernel or in userland. From .Pa alias_mod.c : .Bd -literal /* Protocol and userland module handlers chains. */ LIST_HEAD(handler_chain, proto_handler) handler_chain ... \&... SLIST_HEAD(dll_chain, dll) dll_chain ... .Ed .Pp .Va handler_chain keeps track of all the protocol handlers loaded, while .Va ddl_chain tracks which userland modules are loaded. .Pp .Va handler_chain is composed of .Vt "struct proto_handler" entries: .Bd -literal struct proto_handler { u_int pri; int16_t dir; uint8_t proto; int (*fingerprint)(struct libalias *la, struct ip *pip, struct alias_data *ah); int (*protohandler)(struct libalias *la, struct ip *pip, struct alias_data *ah); TAILQ_ENTRY(proto_handler) link; }; .Ed .Pp where: .Bl -inset .It Va pri is the priority assigned to a protocol handler; lower priority is better. .It Va dir is the direction of packets: ingoing or outgoing. .It Va proto indicates to which protocol this packet belongs: IP, TCP or UDP. .It Va fingerprint points to the fingerprint function while protohandler points to the protocol handler function. .El .Pp The .Va fingerprint function has the dual role of checking if the incoming packet is found, and if it belongs to any categories that this module can handle. .Pp The .Va protohandler function actually manipulates the packet to make .Nm correctly NAT it. .Pp When a packet enters .Nm , if it meets a module hook, .Va handler_chain is searched to see if there is an handler that matches this type of a packet (it checks protocol and direction of packet). Then, if more than one handler is found, it starts with the module with the lowest priority number: it calls the .Va fingerprint function and interprets the result. .Pp If the result value is equal to 0 then it calls the protocol handler of this handler and returns. Otherwise, it proceeds to the next eligible module until the .Va handler_chain is exhausted. .Pp Inside .Nm , the module hook looks like this: .Bd -literal -offset indent struct alias_data ad = { lnk, &original_address, &alias_address, &alias_port, &ud->uh_sport, /* original source port */ &ud->uh_dport, /* original dest port */ 256 /* maxpacketsize */ }; \&... /* walk out chain */ err = find_handler(IN, UDP, la, pip, &ad); .Ed .Pp All data useful to a module are gathered together in an .Vt alias_data structure, then .Fn find_handler is called. The .Fn find_handler function is responsible for walking the handler chain; it receives as input parameters: .Bl -tag -width indent .It Fa IN direction .It Fa UDP working protocol .It Fa la pointer to this instance of libalias .It Fa pip pointer to a .Vt "struct ip" .It Fa ad pointer to .Vt "struct alias_data" (see above) .El .Pp In this case, .Fn find_handler will search only for modules registered for supporting INcoming UDP packets. .Pp As was mentioned earlier, .Nm in userland is a bit different, as care must be taken in module handling as well (avoiding duplicate load of modules, avoiding modules with same name, etc.) so .Va dll_chain was introduced. .Pp .Va dll_chain contains a list of all userland .Nm modules loaded. .Pp When an application calls .Fn LibAliasRefreshModules , .Nm first unloads all the loaded modules, then reloads all the modules listed in .Pa /etc/libalias.conf : for every module loaded, a new entry is added to .Va dll_chain . .Pp .Va dll_chain is composed of .Vt "struct dll" entries: .Bd -literal struct dll { /* name of module */ char name[DLL_LEN]; /* * ptr to shared obj obtained through * dlopen() - use this ptr to get access * to any symbols from a loaded module * via dlsym() */ void *handle; struct dll *next; }; .Ed .Bl -inset .It Va name is the name of the module. .It Va handle is a pointer to the module obtained through .Xr dlopen 3 . .El Whenever a module is loaded in userland, an entry is added to .Va dll_chain , then every protocol handler present in that module is resolved and registered in .Va handler_chain . .Ss HOW TO WRITE A MODULE FOR LIBALIAS There is a module (called .Pa alias_dummy.[ch] ) in .Nm that can be used as a skeleton for future work. Here we analyse some parts of that module. From .Pa alias_dummy.c : .Bd -literal struct proto_handler handlers[] = { { .pri = 666, .dir = IN|OUT, .proto = UDP|TCP, .fingerprint = fingerprint, .protohandler= protohandler, }, { EOH } }; .Ed .Pp The variable .Va handlers is the .Dq "most important thing" in a module since it describes the handlers present and lets the outside world use it in an opaque way. .Pp It must ALWAYS be present in every module, and it MUST retain the name .Va handlers , otherwise attempting to load a module in userland will fail and complain about missing symbols: for more information about module load/unload, please refer to .Fn LibAliasRefreshModules , .Fn LibAliasLoadModule and .Fn LibAliasUnloadModule in .Pa alias.c . .Pp .Va handlers contains all the .Vt proto_handler structures present in a module. .Bd -literal static int mod_handler(module_t mod, int type, void *data) { int error; switch (type) { case MOD_LOAD: error = LibAliasAttachHandlers(handlers); break; case MOD_UNLOAD: error = LibAliasDetachHandlers(handlers); break; default: error = EINVAL; } return (error); } .Ed When running as KLD, .Fn mod_handler registers/deregisters the module using .Fn LibAliasAttachHandlers and .Fn LibAliasDetachHandlers , respectively. .Pp Every module must contain at least 2 functions: one fingerprint function and a protocol handler function. .Bd -literal #ifdef _KERNEL static #endif int fingerprint(struct libalias *la, struct ip *pip, struct alias_data *ah) { \&... } #ifdef _KERNEL static #endif int protohandler(struct libalias *la, struct ip *pip, struct alias_data *ah) { \&... } .Ed and they must accept exactly these input parameters. .Ss PATCHING AN APPLICATION FOR USERLAND LIBALIAS MODULES To add module support into an application that uses .Nm , the following simple steps can be followed. .Bl -enum .It Find the main file of an application (let us call it .Pa main.c ) . .It Add this to the header section of .Pa main.c , if not already present: .Pp .Dl "#include " .Pp and this just after the header section: .Pp .Dl "static void signal_handler(int);" .It Add the following line to the init function of an application or, if it does not have any init function, put it in .Fn main : .Pp .Dl "signal(SIGHUP, signal_handler);" .Pp and place the .Fn signal_handler function somewhere in .Pa main.c : .Bd -literal -offset indent static void signal_handler(int sig) { LibAliasRefreshModules(); } .Ed .Pp Otherwise, if an application already traps the .Dv SIGHUP signal, just add a call to .Fn LibAliasRefreshModules in the signal handler function. .El For example, to patch .Xr natd 8 to use .Nm modules, just add the following line to .Fn RefreshAddr "int sig __unused" : .Pp .Dl "LibAliasRefreshModules()" .Pp recompile and you are done. .Ss LOGGING SUPPORT IN KERNEL LAND When working as KLD, .Nm now has log support that happens on a buffer allocated inside .Vt "struct libalias" (from .Pa alias_local.h ) : .Bd -literal struct libalias { ... /* log descriptor */ #ifdef KERNEL_LOG char *logDesc; /* * ptr to an auto-malloced * memory buffer when libalias * works as kld */ #else FILE *logDesc; /* * ptr to /var/log/alias.log * when libalias runs as a * userland lib */ #endif ... } .Ed so all applications using .Nm will be able to handle their own logs, if they want, accessing .Va logDesc . Moreover, every change to a log buffer is automatically added to .Xr syslog 3 with the .Dv LOG_SECURITY facility and the .Dv LOG_INFO level. .Sh AUTHORS .An Charles Mott Aq cm@linktel.net , versions 1.0 - 1.8, 2.0 - 2.4. .An Eivind Eklund Aq eivind@FreeBSD.org , versions 1.8b, 1.9 and 2.5. Added IRC DCC support as well as contributing a number of architectural improvements; added the firewall bypass for FTP/IRC DCC. .An Erik Salander Aq erik@whistle.com added support for PPTP and RTSP. .An Junichi Satoh Aq junichi@junichi.org added support for RTSP/PNA. .An Ruslan Ermilov Aq ru@FreeBSD.org added support for PPTP and LSNAT as well as general hacking. .An Gleb Smirnoff Aq glebius@FreeBSD.org ported the library to kernel space. .An Paolo Pisati Aq piso@FreeBSD.org made the library modular, moving support for all protocols (except for IP, TCP and UDP) to external modules. .Sh ACKNOWLEDGEMENTS Listed below, in approximate chronological order, are individuals who have provided valuable comments and/or debugging assistance. .Bd -ragged -offset indent .An -split .An Gary Roberts .An Tom Torrance .An Reto Burkhalter .An Martin Renters .An Brian Somers .An Paul Traina .An Ari Suutari .An Dave Remien .An J. Fortes .An Andrzej Bialecki .An Gordon Burditt .Ed diff --git a/usr.sbin/ppp/ppp.8 b/usr.sbin/ppp/ppp.8 index 33bdc69f45a3..c351bd50c8c7 100644 --- a/usr.sbin/ppp/ppp.8 +++ b/usr.sbin/ppp/ppp.8 @@ -1,6116 +1,6116 @@ .\" .\" Copyright (c) 2001 Brian Somers .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd December 6, 2024 .Dt PPP 8 .Os .Sh NAME .Nm ppp .Nd Point to Point Protocol (a.k.a. user-ppp) .Sh SYNOPSIS .Nm .Op Fl Va mode .Op Fl nat .Op Fl quiet .Op Fl unit Ns Ar N .Op Ar system ... .Sh DESCRIPTION This is a user process .Em PPP software package. Sometimes, .Em PPP is implemented as a part of the kernel (e.g., as managed by .Nm pppd ) and it is thus somewhat hard to debug and/or modify its behaviour. However, in this implementation .Em PPP is done as a user process with the help of the tunnel device driver (tun). .Pp The .Fl nat flag does the equivalent of a .Dq nat enable yes , enabling .Nm Ns No 's network address translation features. This allows .Nm to act as a NAT or masquerading engine for all machines on an internal LAN. Refer to .Xr libalias 3 for details on the technical side of the NAT engine. Refer to the .Sx NETWORK ADDRESS TRANSLATION (PACKET ALIASING) section of this manual page for details on how to configure NAT in .Nm . .Pp The .Fl quiet flag tells .Nm to be silent at startup rather than displaying the mode and interface to standard output. .Pp The .Fl unit flag tells .Nm to only attempt to open .Pa /dev/tun Ns Ar N . Normally, .Nm will start with a value of 0 for .Ar N , and keep trying to open a tunnel device by incrementing the value of .Ar N by one each time until it succeeds. If it fails three times in a row because the device file is missing, it gives up. .Pp The following .Va mode Ns No s are understood by .Nm : .Bl -tag -width XXX -offset XXX .It Fl auto .Nm opens the tun interface, configures it then goes into the background. The link is not brought up until outgoing data is detected on the tun interface at which point .Nm attempts to bring up the link. Packets received (including the first one) while .Nm is trying to bring the link up will remain queued for a default of 2 minutes. See the .Dq set choked command below. .Pp In .Fl auto mode, at least one .Dq system must be given on the command line (see below) and a .Dq set ifaddr must be done in the system profile that specifies a peer IP address to use when configuring the interface. Something like .Dq 10.0.0.1/0 is usually appropriate. See the .Dq pmdemand system in .Pa /usr/share/examples/ppp/ppp.conf.sample for an example. .It Fl background Here, .Nm attempts to establish a connection with the peer immediately. If it succeeds, .Nm goes into the background and the parent process returns an exit code of 0. If it fails, .Nm exits with a non-zero result. .It Fl foreground In foreground mode, .Nm attempts to establish a connection with the peer immediately, but never becomes a daemon. The link is created in background mode. This is useful if you wish to control .Nm Ns No 's invocation from another process. .It Fl direct This is used for communicating over an already established connection, usually when receiving incoming connections accepted by .Xr getty 8 . .Nm ignores the .Dq set device line and uses descriptor 0 as the link. .Nm will also ignore any configured chat scripts unless the .Dq force-scripts option has been enabled. .Pp If callback is configured, .Nm will use the .Dq set device information when dialing back. .Pp When run in .Fl direct mode, .Nm will behave slightly differently if descriptor 0 was created by .Xr pipe 2 . As pipes are not bi-directional, ppp will redirect all writes to descriptor 1 (standard output), leaving only reads acting on descriptor 0. No special action is taken if descriptor 0 was created by .Xr socketpair 2 . .It Fl dedicated This option is designed for machines connected with a dedicated wire. .Nm will always keep the device open and will ignore any configured chat scripts unless the .Dq force-scripts option has been enabled. .It Fl ddial This mode is equivalent to .Fl auto mode except that .Nm will bring the link back up any time it is dropped for any reason. .It Fl interactive This is a no-op, and gives the same behaviour as if none of the above modes have been specified. .Nm loads any sections specified on the command line then provides an interactive prompt. .El .Pp One or more configuration entries or systems (as specified in .Pa /etc/ppp/ppp.conf ) may also be specified on the command line. .Nm will read the .Dq default system from .Pa /etc/ppp/ppp.conf at startup, followed by each of the systems specified on the command line. .Sh Major Features .Bl -diag .It Provides an interactive user interface. Using its command mode, the user can easily enter commands to establish the connection with the remote end, check the status of connection and close the connection. All functions can also be optionally password protected for security. .It Supports both manual and automatic dialing. Interactive mode has a .Dq term command which enables you to talk to the device directly. When you are connected to the remote peer and it starts to talk .Em PPP , .Nm detects it and switches to packet mode automatically. Once you have determined the proper sequence for connecting with the remote host, you can write a chat script to {define} the necessary dialing and login procedure for later convenience. .It Supports on-demand dialup capability. By using .Fl auto mode, .Nm will act as a daemon and wait for a packet to be sent over the .Em PPP link. When this happens, the daemon automatically dials and establishes the connection. In almost the same manner .Fl ddial mode (direct-dial mode) also automatically dials and establishes the connection. However, it differs in that it will dial the remote site any time it detects the link is down, even if there are no packets to be sent. This mode is useful for full-time connections where we worry less about line charges and more about being connected full time. A third .Fl dedicated mode is also available. This mode is targeted at a dedicated link between two machines. .Nm will never voluntarily quit from dedicated mode - you must send it the .Dq quit all command via its diagnostic socket. A .Dv SIGHUP will force an LCP renegotiation, and a .Dv SIGTERM will force it to exit. .It Supports client callback. .Nm can use either the standard LCP callback protocol or the Microsoft CallBack Control Protocol .Pq Lk https://winprotocoldocs-bhdugrdyduf5h2e4.b02.azurefd.net/MS-CBCP/%5bMS-CBCP%5d.pdf . .It Supports NAT or packet aliasing. Packet aliasing (a.k.a.\& IP masquerading) allows computers on a private, unregistered network to access the Internet. The .Em PPP host acts as a masquerading gateway. IP addresses as well as TCP and UDP port numbers are NAT'd for outgoing packets and de-NAT'd for returning packets. .It Supports background PPP connections. In background mode, if .Nm successfully establishes the connection, it will become a daemon. Otherwise, it will exit with an error. This allows the setup of scripts that wish to execute certain commands only if the connection is successfully established. .It Supports server-side PPP connections. In direct mode, .Nm acts as server which accepts incoming .Em PPP connections on stdin/stdout. .It Supports PAP and CHAP (rfc 1994, 2433 and 2759) authentication. With PAP or CHAP, it is possible to skip the Unix style .Xr login 1 procedure, and use the .Em PPP protocol for authentication instead. If the peer requests Microsoft CHAP authentication and .Nm is compiled with DES support, an appropriate MD4/DES response will be made. .It Supports RADIUS (rfc 2138 & 2548) authentication. An extension to PAP and CHAP, .Em \&R Ns No emote .Em \&A Ns No ccess .Em \&D Ns No ial .Em \&I Ns No n .Em \&U Ns No ser .Em \&S Ns No ervice allows authentication information to be stored in a central or distributed database along with various per-user framed connection characteristics. If .Xr libradius 3 is available at compile time, .Nm will use it to make .Em RADIUS requests when configured to do so. .It Supports Proxy Arp. .Nm can be configured to make one or more proxy arp entries on behalf of the peer. This allows routing from the peer to the LAN without configuring each machine on that LAN. .It Supports packet filtering. User can {define} four kinds of filters: the .Em in filter for incoming packets, the .Em out filter for outgoing packets, the .Em dial filter to {define} a dialing trigger packet and the .Em alive filter for keeping a connection alive with the trigger packet. .It Tunnel driver supports bpf. The user can use .Xr tcpdump 1 to check the packet flow over the .Em PPP link. .It Supports PPP over TCP and PPP over UDP. If a device name is specified as .Em host : Ns Em port Ns .Xo .Op / Ns tcp|udp , .Xc .Nm will open a TCP or UDP connection for transporting data rather than using a conventional serial device. UDP connections force .Nm into synchronous mode. .It Supports PPP over Ethernet (rfc 2516). If .Nm is given a device specification of the format .No PPPoE\&: Ns Ar iface Ns Xo .Op \&: Ns Ar provider Ns .Xc and if .Xr netgraph 4 is available, .Nm will attempt talk .Em PPP over Ethernet to .Ar provider using the .Ar iface network interface. .Pp On systems that do not support .Xr netgraph 4 , an external program such as .Xr pppoed 8 may be used. .It "Supports IETF draft Predictor-1 (rfc 1978) and DEFLATE (rfc 1979) compression." .Nm supports not only VJ-compression but also Predictor-1 and DEFLATE compression. Normally, a modem has built-in compression (e.g., v42.bis) and the system may receive higher data rates from it as a result of such compression. While this is generally a good thing in most other situations, this higher speed data imposes a penalty on the system by increasing the number of serial interrupts the system has to process in talking to the modem and also increases latency. Unlike VJ-compression, Predictor-1 and DEFLATE compression pre-compresses .Em all network traffic flowing through the link, thus reducing overheads to a minimum. .It Supports Microsoft's IPCP extensions (rfc 1877). Name Server Addresses and NetBIOS Name Server Addresses can be negotiated with clients using the Microsoft .Em PPP stack (i.e., Win95, WinNT) .It Supports Multi-link PPP (rfc 1990) It is possible to configure .Nm to open more than one physical connection to the peer, combining the bandwidth of all links for better throughput. .It Supports MPPE (draft-ietf-pppext-mppe) MPPE is Microsoft Point to Point Encryption scheme. It is possible to configure .Nm to participate in Microsoft's Windows VPN. For now, .Nm can only get encryption keys from CHAP 81 authentication. .Nm must be compiled with DES for MPPE to operate. .It Supports IPV6CP (rfc 2023). An IPv6 connection can be made in addition to or instead of the normal IPv4 connection. .El .Sh PERMISSIONS .Nm is installed as user .Dv root and group .Dv network , with permissions .Dv 04554 . By default, .Nm will not run if the invoking user id is not zero. This may be overridden by using the .Dq allow users command in .Pa /etc/ppp/ppp.conf . When running as a normal user, .Nm switches to user id 0 in order to alter the system routing table, set up system lock files and read the ppp configuration files. All external commands (executed via the "shell" or "!bg" commands) are executed as the user id that invoked .Nm . Refer to the .Sq ID0 logging facility if you are interested in what exactly is done as user id zero. .Sh GETTING STARTED When you first run .Nm you may need to deal with some initial configuration details. .Bl -bullet .It Make sure that your system has a group named .Dq network in the .Pa /etc/group file and that the group contains the names of all users expected to use .Nm . Refer to the .Xr group 5 manual page for details. Each of these users must also be given access using the .Dq allow users command in .Pa /etc/ppp/ppp.conf . .It Create a log file. .Nm uses .Xr syslog 3 to log information. A common log file name is .Pa /var/log/ppp.log . To make output go to this file, put the following lines in the .Pa /etc/syslog.conf file: .Bd -literal -offset indent !ppp *.*/var/log/ppp.log .Ed .Pp It is possible to have more than one .Em PPP log file by creating a link to the .Nm executable: .Pp .Dl # cd /usr/sbin .Dl # ln ppp ppp0 .Pp and using .Bd -literal -offset indent !ppp0 *.*/var/log/ppp0.log .Ed .Pp in .Pa /etc/syslog.conf . Do not forget to send a .Dv HUP signal to .Xr syslogd 8 after altering .Pa /etc/syslog.conf . .It Although not strictly relevant to .Nm Ns No 's operation, you should configure your resolver so that it works correctly. This can be done by configuring a local DNS resolver or by adding the correct .Sq nameserver lines to the file .Pa /etc/resolv.conf . Refer to the .Xr resolv.conf 5 manual page for details. .Pp Alternatively, if the peer supports it, .Nm can be configured to ask the peer for the nameserver address(es) and to update .Pa /etc/resolv.conf automatically. Refer to the .Dq enable dns and .Dq resolv commands below for details. .El .Sh MANUAL DIALING In the following examples, we assume that your machine name is .Dv awfulhak . when you invoke .Nm (see .Sx PERMISSIONS above) with no arguments, you are presented with a prompt: .Bd -literal -offset indent ppp ON awfulhak> .Ed .Pp The .Sq ON part of your prompt should always be in upper case. If it is in lower case, it means that you must supply a password using the .Dq passwd command. This only ever happens if you connect to a running version of .Nm and have not authenticated yourself using the correct password. .Pp You can start by specifying the device name and speed: .Bd -literal -offset indent ppp ON awfulhak> set device /dev/cuau0 ppp ON awfulhak> set speed 38400 .Ed .Pp Normally, hardware flow control (CTS/RTS) is used. However, under certain circumstances (as may happen when you are connected directly to certain PPP-capable terminal servers), this may result in .Nm hanging as soon as it tries to write data to your communications link as it is waiting for the CTS (clear to send) signal - which will never come. Thus, if you have a direct line and cannot seem to make a connection, try turning CTS/RTS off with .Dq set ctsrts off . If you need to do this, check the .Dq set accmap description below too - you will probably need to .Dq set accmap 000a0000 . .Pp Usually, parity is set to .Dq none , and this is .Nm Ns No 's default. Parity is a rather archaic error checking mechanism that is no longer used because modern modems do their own error checking, and most link-layer protocols (that is what .Nm is) use much more reliable checking mechanisms. Parity has a relatively huge overhead (a 12.5% increase in traffic) and as a result, it is always disabled (set to .Dq none ) when .Dv PPP is opened. However, some ISPs (Internet Service Providers) may use specific parity settings at connection time (before .Dv PPP is opened). Notably, Compuserve insist on even parity when logging in: .Bd -literal -offset indent ppp ON awfulhak> set parity even .Ed .Pp You can now see what your current device settings look like: .Bd -literal -offset indent ppp ON awfulhak> show physical Name: deflink State: closed Device: N/A Link Type: interactive Connect Count: 0 Queued Packets: 0 Phone Number: N/A Defaults: Device List: /dev/cuau0 Characteristics: 38400bps, cs8, even parity, CTS/RTS on Connect time: 0 secs 0 octets in, 0 octets out Overall 0 bytes/sec ppp ON awfulhak> .Ed .Pp The term command can now be used to talk directly to the device: .Bd -literal -offset indent ppp ON awfulhak> term at OK atdt123456 CONNECT login: myispusername Password: myisppassword Protocol: ppp .Ed .Pp When the peer starts to talk in .Em PPP , .Nm detects this automatically and returns to command mode. .Bd -literal -offset indent ppp ON awfulhak> # No link has been established Ppp ON awfulhak> # We've connected & finished LCP PPp ON awfulhak> # We've authenticated PPP ON awfulhak> # We've agreed IP numbers .Ed .Pp If it does not, it is probable that the peer is waiting for your end to start negotiating. To force .Nm to start sending .Em PPP configuration packets to the peer, use the .Dq ~p command to drop out of terminal mode and enter packet mode. .Pp If you never even receive a login prompt, it is quite likely that the peer wants to use PAP or CHAP authentication instead of using Unix-style login/password authentication. To set things up properly, drop back to the prompt and set your authentication name and key, then reconnect: .Bd -literal -offset indent ~. ppp ON awfulhak> set authname myispusername ppp ON awfulhak> set authkey myisppassword ppp ON awfulhak> term at OK atdt123456 CONNECT .Ed .Pp You may need to tell ppp to initiate negotiations with the peer here too: .Bd -literal -offset indent ~p ppp ON awfulhak> # No link has been established Ppp ON awfulhak> # We've connected & finished LCP PPp ON awfulhak> # We've authenticated PPP ON awfulhak> # We've agreed IP numbers .Ed .Pp You are now connected! Note that .Sq PPP in the prompt has changed to capital letters to indicate that you have a peer connection. If only some of the three Ps go uppercase, wait until either everything is uppercase or lowercase. If they revert to lowercase, it means that .Nm could not successfully negotiate with the peer. A good first step for troubleshooting at this point would be to .Bd -literal -offset indent ppp ON awfulhak> set log local phase lcp ipcp .Ed .Pp and try again. Refer to the .Dq set log command description below for further details. If things fail at this point, it is quite important that you turn logging on and try again. It is also important that you note any prompt changes and report them to anyone trying to help you. .Pp When the link is established, the show command can be used to see how things are going: .Bd -literal -offset indent PPP ON awfulhak> show physical * Modem related information is shown here * PPP ON awfulhak> show ccp * CCP (compression) related information is shown here * PPP ON awfulhak> show lcp * LCP (line control) related information is shown here * PPP ON awfulhak> show ipcp * IPCP (IP) related information is shown here * PPP ON awfulhak> show ipv6cp * IPV6CP (IPv6) related information is shown here * PPP ON awfulhak> show link * Link (high level) related information is shown here * PPP ON awfulhak> show bundle * Logical (high level) connection related information is shown here * .Ed .Pp At this point, your machine has a host route to the peer. This means that you can only make a connection with the host on the other side of the link. If you want to add a default route entry (telling your machine to send all packets without another routing entry to the other side of the .Em PPP link), enter the following command: .Bd -literal -offset indent PPP ON awfulhak> add default HISADDR .Ed .Pp The string .Sq HISADDR represents the IP address of the connected peer. If the .Dq add command fails due to an existing route, you can overwrite the existing route using: .Bd -literal -offset indent PPP ON awfulhak> add! default HISADDR .Ed .Pp This command can also be executed before actually making the connection. If a new IP address is negotiated at connection time, .Nm will update your default route accordingly. .Pp You can now use your network applications (ping, telnet, ftp, etc.) in other windows or terminals on your machine. If you wish to reuse the current terminal, you can put .Nm into the background using your standard shell suspend and background commands (usually .Dq ^Z followed by .Dq bg ) . .Pp Refer to the .Sx PPP COMMAND LIST section for details on all available commands. .Sh AUTOMATIC DIALING To use automatic dialing, you must prepare some Dial and Login chat scripts. See the example definitions in .Pa /usr/share/examples/ppp/ppp.conf.sample (the format of .Pa /etc/ppp/ppp.conf is pretty simple). Each line contains one comment, inclusion, label or command: .Bl -bullet .It A line starting with a .Pq Dq # character is treated as a comment line. Leading whitespace are ignored when identifying comment lines. .It An inclusion is a line beginning with the word .Sq {!include} . It must have one argument - the file to {include}. You may wish to .Dq {!include} ~/.ppp.conf for compatibility with older versions of .Nm . .It A label name starts in the first column and is followed by a colon .Pq Dq \&: . .It A command line must contain a space or tab in the first column. .It A string starting with the .Dq $ character is substituted with the value of the environment variable by the same name. Likewise, a string starting with the .Dq ~ character is substituted with the full path to the home directory of the user account by the same name, and the .Dq ~ character by itself is substituted with the full path to the home directory of the current user. If you want to include a literal .Dq $ or .Dq ~ character in a command or argument, enclose them in double quotes, e.g., .Bd -literal -offset indent set password "pa$ss~word" .Ed .El .Pp The .Pa /etc/ppp/ppp.conf file should consist of at least a .Dq default section. This section is always executed. It should also contain one or more sections, named according to their purpose, for example, .Dq MyISP would represent your ISP, and .Dq ppp-in would represent an incoming .Nm configuration. You can now specify the destination label name when you invoke .Nm . Commands associated with the .Dq default label are executed, followed by those associated with the destination label provided. When .Nm is started with no arguments, the .Dq default section is still executed. The load command can be used to manually load a section from the .Pa /etc/ppp/ppp.conf file: .Bd -literal -offset indent ppp ON awfulhak> load MyISP .Ed .Pp Note, no action is taken by .Nm after a section is loaded, whether it is the result of passing a label on the command line or using the .Dq load command. Only the commands specified for that label in the configuration file are executed. However, when invoking .Nm with the .Fl background , .Fl ddial , or .Fl dedicated switches, the link mode tells .Nm to establish a connection. Refer to the .Dq set mode command below for further details. .Pp Once the connection is made, the .Sq ppp portion of the prompt will change to .Sq PPP : .Bd -literal -offset indent # ppp MyISP \&... ppp ON awfulhak> dial Ppp ON awfulhak> PPp ON awfulhak> PPP ON awfulhak> .Ed .Pp The Ppp prompt indicates that .Nm has entered the authentication phase. The PPp prompt indicates that .Nm has entered the network phase. The PPP prompt indicates that .Nm has successfully negotiated a network layer protocol and is in a usable state. .Pp If the .Pa /etc/ppp/ppp.linkup file is available, its contents are executed when the .Em PPP connection is established. See the provided .Dq pmdemand example in .Pa /usr/share/examples/ppp/ppp.conf.sample which runs a script in the background after the connection is established (refer to the .Dq shell and .Dq bg commands below for a description of possible substitution strings). Similarly, when a connection is closed, the contents of the .Pa /etc/ppp/ppp.linkdown file are executed. Both of these files have the same format as .Pa /etc/ppp/ppp.conf . .Pp In previous versions of .Nm , it was necessary to re-add routes such as the default route in the .Pa ppp.linkup file. .Nm supports .Sq sticky routes , where all routes that contain the .Dv HISADDR , .Dv MYADDR , .Dv HISADDR6 or .Dv MYADDR6 literals will automatically be updated when the values of these variables change. .Sh BACKGROUND DIALING If you want to establish a connection using .Nm non-interactively (such as from a .Xr crontab 5 entry or an .Xr at 1 job) you should use the .Fl background option. When .Fl background is specified, .Nm attempts to establish the connection immediately. If multiple phone numbers are specified, each phone number will be tried once. If the attempt fails, .Nm exits immediately with a non-zero exit code. If it succeeds, then .Nm becomes a daemon, and returns an exit status of zero to its caller. The daemon exits automatically if the connection is dropped by the remote system, or it receives a .Dv TERM signal. .Sh DIAL ON DEMAND Demand dialing is enabled with the .Fl auto or .Fl ddial options. You must also specify the destination label in .Pa /etc/ppp/ppp.conf to use. It must contain the .Dq set ifaddr command to {define} the remote peers IP address. (refer to .Pa /usr/share/examples/ppp/ppp.conf.sample ) .Bd -literal -offset indent # ppp -auto pmdemand .Ed .Pp When .Fl auto or .Fl ddial is specified, .Nm runs as a daemon but you can still configure or examine its configuration by using the .Dq set server command in .Pa /etc/ppp/ppp.conf , (for example, .Dq Li "set server +3000 mypasswd" ) and connecting to the diagnostic port as follows: .Bd -literal -offset indent # pppctl 3000 (assuming tun0) Password: PPP ON awfulhak> show who tcp (127.0.0.1:1028) * .Ed .Pp The .Dq show who command lists users that are currently connected to .Nm itself. If the diagnostic socket is closed or changed to a different socket, all connections are immediately dropped. .Pp In .Fl auto mode, when an outgoing packet is detected, .Nm will perform the dialing action (chat script) and try to connect with the peer. In .Fl ddial mode, the dialing action is performed any time the line is found to be down. If the connect fails, the default behaviour is to wait 30 seconds and then attempt to connect when another outgoing packet is detected. This behaviour can be changed using the .Dq set redial command: .Pp .No set redial Ar secs Ns .Oo + Ns Ar inc Ns .Oo - Ns Ar max Ns Oc Oc Ns .Op . Ns Ar next .Op Ar attempts .Pp .Bl -tag -width attempts -compact .It Ar secs is the number of seconds to wait before attempting to connect again. If the argument is the literal string .Sq Li random , the delay period is a random value between 1 and 30 seconds inclusive. .It Ar inc is the number of seconds that .Ar secs should be incremented each time a new dial attempt is made. The timeout reverts to .Ar secs only after a successful connection is established. The default value for .Ar inc is zero. .It Ar max is the maximum number of times .Nm should increment .Ar secs . The default value for .Ar max is 10. .It Ar next is the number of seconds to wait before attempting to dial the next number in a list of numbers (see the .Dq set phone command). The default is 3 seconds. Again, if the argument is the literal string .Sq Li random , the delay period is a random value between 1 and 30 seconds. .It Ar attempts is the maximum number of times to try to connect for each outgoing packet that triggers a dial. The previous value is unchanged if this parameter is omitted. If a value of zero is specified for .Ar attempts , .Nm will keep trying until a connection is made. .El .Pp So, for example: .Bd -literal -offset indent set redial 10.3 4 .Ed .Pp will attempt to connect 4 times for each outgoing packet that causes a dial attempt with a 3 second delay between each number and a 10 second delay after all numbers have been tried. If multiple phone numbers are specified, the total number of attempts is still 4 (it does not attempt each number 4 times). .Pp Alternatively, .Bd -literal -offset indent set redial 10+10-5.3 20 .Ed .Pp tells .Nm to attempt to connect 20 times. After the first attempt, .Nm pauses for 10 seconds. After the next attempt it pauses for 20 seconds and so on until after the sixth attempt it pauses for 1 minute. The next 14 pauses will also have a duration of one minute. If .Nm connects, disconnects and fails to connect again, the timeout starts again at 10 seconds. .Pp Modifying the dial delay is very useful when running .Nm in .Fl auto mode on both ends of the link. If each end has the same timeout, both ends wind up calling each other at the same time if the link drops and both ends have packets queued. At some locations, the serial link may not be reliable, and carrier may be lost at inappropriate times. It is possible to have .Nm redial should carrier be unexpectedly lost during a session. .Bd -literal -offset indent set reconnect timeout ntries .Ed .Pp This command tells .Nm to re-establish the connection .Ar ntries times on loss of carrier with a pause of .Ar timeout seconds before each try. For example, .Bd -literal -offset indent set reconnect 3 5 .Ed .Pp tells .Nm that on an unexpected loss of carrier, it should wait .Ar 3 seconds before attempting to reconnect. This may happen up to .Ar 5 times before .Nm gives up. The default value of ntries is zero (no reconnect). Care should be taken with this option. If the local timeout is slightly longer than the remote timeout, the reconnect feature will always be triggered (up to the given number of times) after the remote side times out and hangs up. NOTE: In this context, losing too many LQRs constitutes a loss of carrier and will trigger a reconnect. If the .Fl background flag is specified, all phone numbers are dialed at most once until a connection is made. The next number redial period specified with the .Dq set redial command is honoured, as is the reconnect tries value. If your redial value is less than the number of phone numbers specified, not all the specified numbers will be tried. To terminate the program, type .Bd -literal -offset indent PPP ON awfulhak> close ppp ON awfulhak> quit all .Ed .Pp A simple .Dq quit command will terminate the .Xr pppctl 8 or .Xr telnet 1 connection but not the .Nm program itself. You must use .Dq quit all to terminate .Nm as well. .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1) To handle an incoming .Em PPP connection request, follow these steps: .Bl -enum .It Make sure the modem and (optionally) .Pa /etc/rc.serial is configured correctly. .Bl -bullet -compact .It Use Hardware Handshake (CTS/RTS) for flow control. .It Modem should be set to NO echo back (ATE0) and NO results string (ATQ1). .El .It Edit .Pa /etc/ttys to enable a .Xr getty 8 on the port where the modem is attached. For example: .Pp .Dl ttyd1 Qo /usr/libexec/getty std.38400 Qc dialup on secure .Pp Do not forget to send a .Dv HUP signal to the .Xr init 8 process to start the .Xr getty 8 : .Pp .Dl # kill -HUP 1 .Pp It is usually also necessary to train your modem to the same DTR speed as the getty: .Bd -literal -offset indent # ppp ppp ON awfulhak> set device /dev/cuau1 ppp ON awfulhak> set speed 38400 ppp ON awfulhak> term deflink: Entering terminal mode on /dev/cuau1 Type `~?' for help at OK at OK atz OK at OK ~. ppp ON awfulhak> quit .Ed .It Create a .Pa /usr/local/bin/ppplogin file with the following contents: .Bd -literal -offset indent #! /bin/sh exec /usr/sbin/ppp -direct incoming .Ed .Pp Direct mode .Pq Fl direct lets .Nm work with stdin and stdout. You can also use .Xr pppctl 8 to connect to a configured diagnostic port, in the same manner as with client-side .Nm . .Pp Here, the .Ar incoming section must be set up in .Pa /etc/ppp/ppp.conf . .Pp Make sure that the .Ar incoming section contains the .Dq allow users command as appropriate. .It Prepare an account for the incoming user. .Bd -literal ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin .Ed .Pp Refer to the manual entries for .Xr adduser 8 and .Xr vipw 8 for details. .It Support for IPCP Domain Name Server and NetBIOS Name Server negotiation can be enabled using the .Dq accept dns and .Dq set nbns commands. Refer to their descriptions below. .El .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2) This method differs in that we use .Nm to authenticate the connection rather than .Xr login 1 : .Bl -enum .It Configure your default section in .Pa /etc/gettytab with automatic ppp recognition by specifying the .Dq pp capability: .Bd -literal default:\\ :pp=/usr/local/bin/ppplogin:\\ ..... .Ed .It Configure your serial device(s), enable a .Xr getty 8 and create .Pa /usr/local/bin/ppplogin as in the first three steps for method 1 above. .It Add either .Dq enable chap or .Dq enable pap (or both) to .Pa /etc/ppp/ppp.conf under the .Sq incoming label (or whatever label .Pa ppplogin uses). .It Create an entry in .Pa /etc/ppp/ppp.secret for each incoming user: .Bd -literal Pfredxxxx Pgeorgeyyyy .Ed .El .Pp Now, as soon as .Xr getty 8 detects a ppp connection (by recognising the HDLC frame headers), it runs .Dq /usr/local/bin/ppplogin . .Pp It is .Em VITAL that either PAP or CHAP are enabled as above. If they are not, you are allowing anybody to establish a ppp session with your machine .Em without a password, opening yourself up to all sorts of potential attacks. .Sh AUTHENTICATING INCOMING CONNECTIONS Normally, the receiver of a connection requires that the peer authenticates itself. This may be done using .Xr login 1 , but alternatively, you can use PAP or CHAP. CHAP is the more secure of the two, but some clients may not support it. Once you decide which you wish to use, add the command .Sq enable chap or .Sq enable pap to the relevant section of .Pa ppp.conf . .Pp You must then configure the .Pa /etc/ppp/ppp.secret file. This file contains one line per possible client, each line containing up to five fields: .Pp .Ar name Ar key Oo .Ar hisaddr Op Ar label Op Ar callback-number .Oc .Pp The .Ar name and .Ar key specify the client username and password. If .Ar key is .Dq \&* and PAP is being used, .Nm will look up the password database .Pq Xr passwd 5 when authenticating. If the client does not offer a suitable response based on any .Ar name Ns No / Ns Ar key combination in .Pa ppp.secret , authentication fails. .Pp If authentication is successful, .Ar hisaddr (if specified) is used when negotiating IP numbers. See the .Dq set ifaddr command for details. .Pp If authentication is successful and .Ar label is specified, the current system label is changed to match the given .Ar label . This will change the subsequent parsing of the .Pa ppp.linkup and .Pa ppp.linkdown files. .Pp If authentication is successful and .Ar callback-number is specified and .Dq set callback has been used in .Pa ppp.conf , the client will be called back on the given number. If CBCP is being used, .Ar callback-number may also contain a list of numbers or a .Dq \&* , as if passed to the .Dq set cbcp command. The value will be used in .Nm Ns No 's subsequent CBCP phase. .Sh PPP OVER TCP and UDP (a.k.a Tunnelling) Instead of running .Nm over a serial link, it is possible to use a TCP connection instead by specifying the host, port and protocol as the device: .Pp .Dl set device ui-gate:6669/tcp .Pp Instead of opening a serial device, .Nm will open a TCP connection to the given machine on the given socket. It should be noted however that .Nm does not use the telnet protocol and will be unable to negotiate with a telnet server. You should set up a port for receiving this .Em PPP connection on the receiving machine (ui-gate). This is done by first updating .Pa /etc/services to name the service: .Pp .Dl ppp-in 6669/tcp # Incoming PPP connections over TCP .Pp and updating .Pa /etc/inetd.conf to tell .Xr inetd 8 how to deal with incoming connections on that port: .Pp .Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in .Pp Do not forget to send a .Dv HUP signal to .Xr inetd 8 after you have updated .Pa /etc/inetd.conf . Here, we use a label named .Dq ppp-in . The entry in .Pa /etc/ppp/ppp.conf on ui-gate (the receiver) should contain the following: .Bd -literal -offset indent ppp-in: set timeout 0 set ifaddr 10.0.4.1 10.0.4.2 .Ed .Pp and the entry in .Pa /etc/ppp/ppp.linkup should contain: .Bd -literal -offset indent ppp-in: add 10.0.1.0/24 HISADDR .Ed .Pp It is necessary to put the .Dq add command in .Pa ppp.linkup to ensure that the route is only added after .Nm has negotiated and assigned addresses to its interface. .Pp You may also want to enable PAP or CHAP for security. To enable PAP, add the following line: .Bd -literal -offset indent enable PAP .Ed .Pp You will also need to create the following entry in .Pa /etc/ppp/ppp.secret : .Bd -literal -offset indent MyAuthName MyAuthPasswd .Ed .Pp If .Ar MyAuthPasswd is a .Dq * , the password is looked up in the .Xr passwd 5 database. .Pp The entry in .Pa /etc/ppp/ppp.conf on awfulhak (the initiator) should contain the following: .Bd -literal -offset indent ui-gate: set escape 0xff set device ui-gate:ppp-in/tcp set dial set timeout 30 set log Phase Chat Connect hdlc LCP IPCP IPV6CP CCP tun set ifaddr 10.0.4.2 10.0.4.1 .Ed .Pp with the route setup in .Pa /etc/ppp/ppp.linkup : .Bd -literal -offset indent ui-gate: add 10.0.2.0/24 HISADDR .Ed .Pp Again, if you are enabling PAP, you will also need this in the .Pa /etc/ppp/ppp.conf profile: .Bd -literal -offset indent set authname MyAuthName set authkey MyAuthKey .Ed .Pp We are assigning the address of 10.0.4.1 to ui-gate, and the address 10.0.4.2 to awfulhak. To open the connection, just type .Pp .Dl awfulhak # ppp -background ui-gate .Pp The result will be an additional "route" on awfulhak to the 10.0.2.0/24 network via the TCP connection, and an additional "route" on ui-gate to the 10.0.1.0/24 network. The networks are effectively bridged - the underlying TCP connection may be across a public network (such as the Internet), and the .Em PPP traffic is conceptually encapsulated (although not packet by packet) inside the TCP stream between the two gateways. .Pp The major disadvantage of this mechanism is that there are two "guaranteed delivery" mechanisms in place - the underlying TCP stream and whatever protocol is used over the .Em PPP link - probably TCP again. If packets are lost, both levels will get in each others way trying to negotiate sending of the missing packet. .Pp To avoid this overhead, it is also possible to do all this using UDP instead of TCP as the transport by simply changing the protocol from "tcp" to "udp". When using UDP as a transport, .Nm will operate in synchronous mode. This is another gain as the incoming data does not have to be rearranged into packets. .Pp Care should be taken when adding a default route through a tunneled setup like this. It is quite common for the default route (added in .Pa /etc/ppp/ppp.linkup ) to end up routing the link's TCP connection through the tunnel, effectively garrotting the connection. To avoid this, make sure you add a static route for the benefit of the link: .Bd -literal -offset indent ui-gate: set escape 0xff set device ui-gate:ppp-in/tcp add ui-gate x.x.x.x ..... .Ed .Pp where .Dq x.x.x.x is the IP number that your route to .Dq ui-gate would normally use. .Pp When routing your connection across a public network such as the Internet, it is preferable to encrypt the data. This can be done with the help of the MPPE protocol, although currently this means that you will not be able to also compress the traffic as MPPE is implemented as a compression layer (thank Microsoft for this). To enable MPPE encryption, add the following lines to .Pa /etc/ppp/ppp.conf on the server: .Bd -literal -offset indent enable MSCHAPv2 disable deflate pred1 deny deflate pred1 .Ed .Pp ensuring that you have put the requisite entry in .Pa /etc/ppp/ppp.secret (MSCHAPv2 is challenge based, so .Xr passwd 5 cannot be used) .Pp MSCHAPv2 and MPPE are accepted by default, so the client end should work without any additional changes (although ensure you have .Dq set authname and .Dq set authkey in your profile). .Sh NETWORK ADDRESS TRANSLATION (PACKET ALIASING) The .Fl nat command line option enables network address translation (a.k.a.\& packet aliasing). This allows the .Nm host to act as a masquerading gateway for other computers over a local area network. Outgoing IP packets are NAT'd so that they appear to come from the .Nm host, and incoming packets are de-NAT'd so that they are routed to the correct machine on the local area network. NAT allows computers on private, unregistered subnets to have Internet access, although they are invisible from the outside world. In general, correct .Nm operation should first be verified with network address translation disabled. Then, the .Fl nat option should be switched on, and network applications (web browser, .Xr telnet 1 , .Xr ftp 1 , .Xr ping 8 , .Xr traceroute 8 ) should be checked on the .Nm host. Finally, the same or similar applications should be checked on other computers in the LAN. If network applications work correctly on the .Nm host, but not on other machines in the LAN, then the masquerading software is working properly, but the host is either not forwarding or possibly receiving IP packets. Check that IP forwarding is enabled in .Pa /etc/rc.conf and that other machines have designated the .Nm host as the gateway for the LAN. When starting .Nm with the provided rc script, the default is to enable NAT; see .Va ppp_nat in .Xr rc.conf 5 and .Pa /etc/defaults/rc.conf . .Sh PACKET FILTERING This implementation supports packet filtering. There are four kinds of filters: the .Em in filter, the .Em out filter, the .Em dial filter and the .Em alive filter. Here are the basics: .Bl -bullet .It A filter definition has the following syntax: .Pp set filter .Ar name .Ar rule-no .Ar action .Op !\& .Oo .Op host .Ar src_addr Ns Op / Ns Ar width .Op Ar dst_addr Ns Op / Ns Ar width .Oc .Ar [ proto Op src Ar cmp port .Op dst Ar cmp port .Op estab .Op syn .Op finrst .Op timeout Ar secs ] .Bl -enum .It .Ar Name should be one of .Sq in , .Sq out , .Sq dial or .Sq alive . .It .Ar Rule-no is a numeric value between .Sq 0 and .Sq 39 specifying the rule number. Rules are specified in numeric order according to .Ar rule-no , but only if rule .Sq 0 is defined. .It .Ar Action may be specified as .Sq permit or .Sq deny , in which case, if a given packet matches the rule, the associated action is taken immediately. .Ar Action can also be specified as .Sq clear to clear the action associated with that particular rule, or as a new rule number greater than the current rule. In this case, if a given packet matches the current rule, the packet will next be matched against the new rule number (rather than the next rule number). .Pp The .Ar action may optionally be followed with an exclamation mark .Pq Dq !\& , telling .Nm to reverse the sense of the following match. .It .Op Ar src_addr Ns Op / Ns Ar width and .Op Ar dst_addr Ns Op / Ns Ar width are the source and destination IP number specifications. If .Op / Ns Ar width is specified, it gives the number of relevant netmask bits, allowing the specification of an address range. .Pp Either .Ar src_addr or .Ar dst_addr may be given the values .Dv MYADDR , .Dv HISADDR , .Dv MYADDR6 or .Dv HISADDR6 (refer to the description of the .Dq bg command for a description of these values). When these values are used, the filters will be updated any time the values change. This is similar to the behaviour of the .Dq add command below. .It .Ar Proto may be any protocol from .Xr protocols 5 . .It .Ar Cmp is one of .Sq \< , .Sq \&eq or .Sq \> , meaning less-than, equal and greater-than respectively. .Ar Port can be specified as a numeric port or by service name from .Pa /etc/services . .It The .Sq estab , .Sq syn , and .Sq finrst flags are only allowed when .Ar proto is set to .Sq tcp , and represent the TH_ACK, TH_SYN and TH_FIN or TH_RST TCP flags respectively. .It The timeout value adjusts the current idle timeout to at least .Ar secs seconds. If a timeout is given in the alive filter as well as in the in/out filter, the in/out value is used. If no timeout is given, the default timeout (set using .Ic set timeout and defaulting to 180 seconds) is used. .El .It Each filter can hold up to 40 rules, starting from rule 0. The entire rule set is not effective until rule 0 is defined, i.e., the default is to allow everything through. .It If no rule in a defined set of rules matches a packet, that packet will be discarded (blocked). If there are no rules in a given filter, the packet will be permitted. .It It is possible to filter based on the payload of UDP frames where those frames contain a .Em PROTO_IP .Em PPP frame header. See the .Ar filter-decapsulation option below for further details. .It Use .Dq set filter Ar name No -1 to flush all rules. .El .Pp See .Pa /usr/share/examples/ppp/ppp.conf.sample . .Sh SETTING THE IDLE TIMER To check/set the idle timer, use the .Dq show bundle and .Dq set timeout commands: .Bd -literal -offset indent ppp ON awfulhak> set timeout 600 .Ed .Pp The timeout period is measured in seconds, the default value for which is 180 seconds (or 3 min). To disable the idle timer function, use the command .Bd -literal -offset indent ppp ON awfulhak> set timeout 0 .Ed .Pp In .Fl ddial and .Fl dedicated modes, the idle timeout is ignored. In .Fl auto mode, when the idle timeout causes the .Em PPP session to be closed, the .Nm program itself remains running. Another trigger packet will cause it to attempt to re-establish the link. .Sh PREDICTOR-1 and DEFLATE COMPRESSION .Nm supports both Predictor type 1 and deflate compression. By default, .Nm will attempt to use (or be willing to accept) both compression protocols when the peer agrees (or requests them). The deflate protocol is preferred by .Nm . Refer to the .Dq disable and .Dq deny commands if you wish to disable this functionality. .Pp It is possible to use a different compression algorithm in each direction by using only one of .Dq disable deflate and .Dq deny deflate (assuming that the peer supports both algorithms). .Pp By default, when negotiating DEFLATE, .Nm will use a window size of 15. Refer to the .Dq set deflate command if you wish to change this behaviour. .Pp A special algorithm called DEFLATE24 is also available, and is disabled and denied by default. This is exactly the same as DEFLATE except that it uses CCP ID 24 to negotiate. This allows .Nm to successfully negotiate DEFLATE with .Nm pppd version 2.3.*. .Sh CONTROLLING IP ADDRESS For IPv4, .Nm uses IPCP to negotiate IP addresses. Each side of the connection specifies the IP address that it is willing to use, and if the requested IP address is acceptable then .Nm returns an ACK to the requester. Otherwise, .Nm returns NAK to suggest that the peer use a different IP address. When both sides of the connection agree to accept the received request (and send an ACK), IPCP is set to the open state and a network level connection is established. To control this IPCP behaviour, this implementation has the .Dq set ifaddr command for defining the local and remote IP address: .Bd -ragged -offset indent .No set ifaddr Oo Ar src_addr Ns .Op / Ns Ar \&nn .Oo Ar dst_addr Ns Op / Ns Ar \&nn .Oo Ar netmask .Op Ar trigger_addr .Oc .Oc .Oc .Ed .Pp where, .Sq src_addr is the IP address that the local side is willing to use, .Sq dst_addr is the IP address which the remote side should use and .Sq netmask is the netmask that should be used. .Sq Src_addr defaults to the current .Xr hostname 1 , .Sq dst_addr defaults to 0.0.0.0, and .Sq netmask defaults to whatever mask is appropriate for .Sq src_addr . It is only possible to make .Sq netmask smaller than the default. The usual value is 255.255.255.255, as most kernels ignore the netmask of a POINTOPOINT interface. .Pp Some incorrect .Em PPP implementations require that the peer negotiates a specific IP address instead of .Sq src_addr . If this is the case, .Sq trigger_addr may be used to specify this IP number. This will not affect the routing table unless the other side agrees with this proposed number. .Bd -literal -offset indent set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0 .Ed .Pp The above specification means: .Pp .Bl -bullet -compact .It I will first suggest that my IP address should be 0.0.0.0, but I will only accept an address of 192.244.177.38. .It I strongly insist that the peer uses 192.244.177.2 as his own address and will not permit the use of any IP address but 192.244.177.2. When the peer requests another IP address, I will always suggest that it uses 192.244.177.2. .It The routing table entry will have a netmask of 0xffffffff. .El .Pp This is all fine when each side has a pre-determined IP address, however it is often the case that one side is acting as a server which controls all IP addresses and the other side should go along with it. In order to allow more flexible behaviour, the .Dq set ifaddr command allows the user to specify IP addresses more loosely: .Pp .Dl set ifaddr 192.244.177.38/24 192.244.177.2/20 .Pp A number followed by a slash .Pq Dq / represents the number of bits significant in the IP address. The above example means: .Pp .Bl -bullet -compact .It I would like to use 192.244.177.38 as my address if it is possible, but I will also accept any IP address between 192.244.177.0 and 192.244.177.255. .It I would like to make him use 192.244.177.2 as his own address, but I will also permit him to use any IP address between 192.244.176.0 and 192.244.191.255. .It As you may have already noticed, 192.244.177.2 is equivalent to saying 192.244.177.2/32. .It As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no preferred IP address and will obey the remote peers selection. When using zero, no routing table entries will be made until a connection is established. .It 192.244.177.2/0 means that I will accept/permit any IP address but I will suggest that 192.244.177.2 be used first. .El .Pp When negotiating IPv6 addresses, no control is given to the user. IPV6CP negotiation is fully automatic. .Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER The following steps should be taken when connecting to your ISP: .Bl -enum .It Describe your providers phone number(s) in the dial script using the .Dq set phone command. This command allows you to set multiple phone numbers for dialing and redialing separated by either a pipe .Pq Dq \&| or a colon .Pq Dq \&: : .Bd -ragged -offset indent .No set phone Ar telno Ns .Oo \&| Ns Ar backupnumber Oc Ns ... Ns Oo : Ns Ar nextnumber Oc Ns ... .Ed .Pp Numbers after the first in a pipe-separated list are only used if the previous number was used in a failed dial or login script. Numbers separated by a colon are used sequentially, irrespective of what happened as a result of using the previous number. For example: .Bd -literal -offset indent set phone "1234567|2345678:3456789|4567890" .Ed .Pp Here, the 1234567 number is attempted. If the dial or login script fails, the 2345678 number is used next time, but *only* if the dial or login script fails. On the dial after this, the 3456789 number is used. The 4567890 number is only used if the dial or login script using the 3456789 fails. If the login script of the 2345678 number fails, the next number is still the 3456789 number. As many pipes and colons can be used as are necessary (although a given site would usually prefer to use either the pipe or the colon, but not both). The next number redial timeout is used between all numbers. When the end of the list is reached, the normal redial period is used before starting at the beginning again. The selected phone number is substituted for the \\\\T string in the .Dq set dial command (see below). .It Set up your redial requirements using .Dq set redial . For example, if you have a bad telephone line or your provider is usually engaged (not so common these days), you may want to specify the following: .Bd -literal -offset indent set redial 10 4 .Ed .Pp This says that up to 4 phone calls should be attempted with a pause of 10 seconds before dialing the first number again. .It Describe your login procedure using the .Dq set dial and .Dq set login commands. The .Dq set dial command is used to talk to your modem and establish a link with your ISP, for example: .Bd -literal -offset indent set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" \e ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT" .Ed .Pp This modem "chat" string means: .Bl -bullet .It Abort if the string "BUSY" or "NO CARRIER" are received. .It Set the timeout to 4 seconds. .It Expect nothing. .It Send ATZ. .It Expect OK. If that is not received within the 4 second timeout, send ATZ and expect OK. .It Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from above. .It Set the timeout to 60. .It Wait for the CONNECT string. .El .Pp Once the connection is established, the login script is executed. This script is written in the same style as the dial script, but care should be taken to avoid having your password logged: .Bd -literal -offset indent set authkey MySecret set login "TIMEOUT 15 login:-\\\\r-login: awfulhak \e word: \\\\P ocol: PPP HELLO" .Ed .Pp This login "chat" string means: .Bl -bullet .It Set the timeout to 15 seconds. .It Expect "login:". If it is not received, send a carriage return and expect "login:" again. .It Send "awfulhak" .It Expect "word:" (the tail end of a "Password:" prompt). .It Send whatever our current .Ar authkey value is set to. .It Expect "ocol:" (the tail end of a "Protocol:" prompt). .It Send "PPP". .It Expect "HELLO". .El .Pp The .Dq set authkey command is logged specially. When .Ar command or .Ar chat logging is enabled, the actual password is not logged; .Sq ******** is logged instead. .Pp Login scripts vary greatly between ISPs. If you are setting one up for the first time, .Em ENABLE CHAT LOGGING so that you can see if your script is behaving as you expect. .It Use .Dq set device and .Dq set speed to specify your serial line and speed, for example: .Bd -literal -offset indent set device /dev/cuau0 set speed 115200 .Ed .Pp .Pa cuaU0 and .Pa cuau0 are the first .Xr usb 4 and .Xr uart 4 serial ports found by .Fx , respectively. If you are running .Nm on .Ox , .Pa cua00 is the first. A speed of 115200 should be specified if you have a modem capable of bit rates of 28800 or more. In general, the serial speed should be about four times the modem speed. .It Use the .Dq set ifaddr command to {define} the IP address. .Bl -bullet .It If you know what IP address your provider uses, then use it as the remote address (dst_addr), otherwise choose something like 10.0.0.2/0 (see below). .It If your provider has assigned a particular IP address to you, then use it as your address (src_addr). .It If your provider assigns your address dynamically, choose a suitably unobtrusive and unspecific IP number as your address. 10.0.0.1/0 would be appropriate. The bit after the / specifies how many bits of the -address you consider to be important, so if you wanted to insist on -something in the class C network 1.2.3.0, you could specify 1.2.3.1/24. +address you consider to be important, so if you wanted to specify an +address within the 1.2.3.0/24 subnet, you could specify 1.2.3.1/24. .It If you find that your ISP accepts the first IP number that you suggest, specify third and forth arguments of .Dq 0.0.0.0 . This will force your ISP to assign a number. (The third argument will be ignored as it is less restrictive than the default mask for your .Sq src_addr ) . .El .Pp An example for a connection where you do not know your IP number or your ISPs IP number would be: .Bd -literal -offset indent set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0 .Ed .It In most cases, your ISP will also be your default router. If this is the case, add the line .Bd -literal -offset indent add default HISADDR .Ed .Pp to .Pa /etc/ppp/ppp.conf (or to .Pa /etc/ppp/ppp.linkup for setups that do not use .Fl auto mode). .Pp This tells .Nm to add a default route to whatever the peer address is (10.0.0.2 in this example). This route is .Sq sticky , meaning that should the value of .Dv HISADDR change, the route will be updated accordingly. .It If your provider requests that you use PAP/CHAP authentication methods, add the next lines to your .Pa /etc/ppp/ppp.conf file: .Bd -literal -offset indent set authname MyName set authkey MyPassword .Ed .Pp Both are accepted by default, so .Nm will provide whatever your ISP requires. .Pp It should be noted that a login script is rarely (if ever) required when PAP or CHAP are in use. .It Ask your ISP to authenticate your nameserver address(es) with the line .Bd -literal -offset indent enable dns .Ed .Pp Do .Em NOT do this if you are running a local DNS unless you also either use .Dq resolv readonly or have .Dq resolv restore in .Pa /etc/ppp/ppp.linkdown , as .Nm will simply circumvent its use by entering some nameserver lines in .Pa /etc/resolv.conf . .El .Pp Please refer to .Pa /usr/share/examples/ppp/ppp.conf.sample and .Pa /usr/share/examples/ppp/ppp.linkup.sample for some real examples. The pmdemand label should be appropriate for most ISPs. .Sh LOGGING FACILITY .Nm is able to generate the following log info either via .Xr syslog 3 or directly to the screen: .Pp .Bl -tag -width XXXXXXXXX -offset XXX -compact .It Li All Enable all logging facilities. This generates a lot of log. The most common use of 'all' is as a basis, where you remove some facilities after enabling 'all' ('debug' and 'timer' are usually best disabled.) .It Li Async Dump async level packet in hex. .It Li CBCP Generate CBCP (CallBack Control Protocol) logs. .It Li CCP Generate a CCP packet trace. .It Li Chat Generate .Sq dial , .Sq login , .Sq logout and .Sq hangup chat script trace logs. .It Li Command Log commands executed either from the command line or any of the configuration files. .It Li Connect Log Chat lines containing the string "CONNECT". .It Li Debug Log debug information. .It Li DNS Log DNS QUERY packets. .It Li Filter Log packets permitted by the dial filter and denied by any filter. .It Li HDLC Dump HDLC packet in hex. .It Li ID0 Log all function calls specifically made as user id 0. .It Li IPCP Generate an IPCP packet trace. .It Li LCP Generate an LCP packet trace. .It Li LQM Generate LQR reports. .It Li Phase Phase transition log output. .It Li Physical Dump physical level packet in hex. .It Li Radius Dump RADIUS information. RADIUS information resulting from the link coming up or down is logged at .Dq Phase level unless .Dq Radius logging is enabled. This log level is most useful for monitoring RADIUS alive information. .It Li Sync Dump sync level packet in hex. .It Li TCP/IP Dump all TCP/IP packets. .It Li Timer Log timer manipulation. .It Li TUN Include the tun device on each log line. .It Li Warning Output to the terminal device. If there is currently no terminal, output is sent to the log file using syslogs .Dv LOG_WARNING . .It Li Error Output to both the terminal device and the log file using syslogs .Dv LOG_ERROR . .It Li Alert Output to the log file using .Dv LOG_ALERT . .El .Pp The .Dq set log command allows you to set the logging output level. Multiple levels can be specified on a single command line. The default is equivalent to .Dq set log Phase . .Pp It is also possible to log directly to the screen. The syntax is the same except that the word .Dq local should immediately follow .Dq set log . The default is .Dq set log local (i.e., only the un-maskable warning, error and alert output). .Pp If The first argument to .Dq set log Op local begins with a .Sq + or a .Sq - character, the current log levels are not cleared, for example: .Bd -literal -offset indent PPP ON awfulhak> set log phase PPP ON awfulhak> show log Log: Phase Warning Error Alert Local: Warning Error Alert PPP ON awfulhak> set log +tcp/ip -warning PPP ON awfulhak> set log local +command PPP ON awfulhak> show log Log: Phase TCP/IP Warning Error Alert Local: Command Warning Error Alert .Ed .Pp Log messages of level Warning, Error and Alert are not controllable using .Dq set log Op local . .Pp The .Ar Warning level is special in that it will not be logged if it can be displayed locally. .Sh SIGNAL HANDLING .Nm deals with the following signals: .Bl -tag -width "USR2" .It INT Receipt of this signal causes the termination of the current connection (if any). This will cause .Nm to exit unless it is in .Fl auto or .Fl ddial mode. .It HUP, TERM & QUIT These signals tell .Nm to exit. .It USR1 This signal, tells .Nm to re-open any existing server socket, dropping all existing diagnostic connections. Sockets that could not previously be opened will be retried. .It USR2 This signal, tells .Nm to close any existing server socket, dropping all existing diagnostic connections. .Dv SIGUSR1 can still be used to re-open the socket. .El .Sh MULTI-LINK PPP If you wish to use more than one physical link to connect to a .Em PPP peer, that peer must also understand the .Em MULTI-LINK PPP protocol. Refer to RFC 1990 for specification details. .Pp The peer is identified using a combination of his .Dq endpoint discriminator and his .Dq authentication id . Either or both of these may be specified. It is recommended that at least one is specified, otherwise there is no way of ensuring that all links are actually connected to the same peer program, and some confusing lock-ups may result. Locally, these identification variables are specified using the .Dq set enddisc and .Dq set authname commands. The .Sq authname (and .Sq authkey ) must be agreed in advance with the peer. .Pp Multi-link capabilities are enabled using the .Dq set mrru command (set maximum reconstructed receive unit). Once multi-link is enabled, .Nm will attempt to negotiate a multi-link connection with the peer. .Pp By default, only one .Sq link is available (called .Sq deflink ) . To create more links, the .Dq clone command is used. This command will clone existing links, where all characteristics are the same except: .Bl -enum .It The new link has its own name as specified on the .Dq clone command line. .It The new link is an .Sq interactive link. Its mode may subsequently be changed using the .Dq set mode command. .It The new link is in a .Sq closed state. .El .Pp A summary of all available links can be seen using the .Dq show links command. .Pp Once a new link has been created, command usage varies. All link specific commands must be prefixed with the .Dq link Ar name command, specifying on which link the command is to be applied. When only a single link is available, .Nm is smart enough not to require the .Dq link Ar name prefix. .Pp Some commands can still be used without specifying a link - resulting in an operation at the .Sq bundle level. For example, once two or more links are available, the command .Dq show ccp will show CCP configuration and statistics at the multi-link level, and .Dq link deflink show ccp will show the same information at the .Dq deflink link level. .Pp Armed with this information, the following configuration might be used: .Bd -literal -offset indent mp: set timeout 0 set log phase chat set device /dev/cuau0 /dev/cuau1 /dev/cuau2 set phone "123456789" set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \\"\\" ATZ \e OK-AT-OK \\\\dATDT\\\\T TIMEOUT 45 CONNECT" set login set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0 set authname ppp set authkey ppppassword set mrru 1500 clone 1,2,3 # Create 3 new links - duplicates of the default link deflink remove # Delete the default link (called ``deflink'') .Ed .Pp Note how all cloning is done at the end of the configuration. Usually, the link will be configured first, then cloned. If you wish all links to be up all the time, you can add the following line to the end of your configuration. .Bd -literal -offset indent link 1,2,3 set mode ddial .Ed .Pp If you want the links to dial on demand, this command could be used: .Bd -literal -offset indent link * set mode auto .Ed .Pp Links may be tied to specific names by removing the .Dq set device line above, and specifying the following after the .Dq clone command: .Bd -literal -offset indent link 1 set device /dev/cuau0 link 2 set device /dev/cuau1 link 3 set device /dev/cuau2 .Ed .Pp Use the .Dq help command to see which commands require context (using the .Dq link command), which have optional context and which should not have any context. .Pp When .Nm has negotiated .Em MULTI-LINK mode with the peer, it creates a local domain socket in the .Pa /var/run directory. This socket is used to pass link information (including the actual link file descriptor) between different .Nm invocations. This facilitates .Nm Ns No 's ability to be run from a .Xr getty 8 or directly from .Pa /etc/gettydefs (using the .Sq pp= capability), without needing to have initial control of the serial line. Once .Nm negotiates multi-link mode, it will pass its open link to any already running process. If there is no already running process, .Nm will act as the master, creating the socket and listening for new connections. .Sh PPP COMMAND LIST This section lists the available commands and their effect. They are usable either from an interactive .Nm session, from a configuration file or from a .Xr pppctl 8 or .Xr telnet 1 session. .Bl -tag -width 2n .It accept|deny|enable|disable Ar option.... These directives tell .Nm how to negotiate the initial connection with the peer. Each .Dq option has a default of either accept or deny and enable or disable. .Dq Accept means that the option will be ACK'd if the peer asks for it. .Dq Deny means that the option will be NAK'd if the peer asks for it. .Dq Enable means that the option will be requested by us. .Dq Disable means that the option will not be requested by us. .Pp .Dq Option may be one of the following: .Bl -tag -width 2n .It acfcomp Default: Enabled and Accepted. ACFComp stands for Address and Control Field Compression. Non LCP packets will usually have an address field of 0xff (the All-Stations address) and a control field of 0x03 (the Unnumbered Information command). If this option is negotiated, these two bytes are simply not sent, thus minimising traffic. .Pp See .Pa rfc1662 for details. .It chap Ns Op \&05 Default: Disabled and Accepted. CHAP stands for Challenge Handshake Authentication Protocol. Only one of CHAP and PAP (below) may be negotiated. With CHAP, the authenticator sends a "challenge" message to its peer. The peer uses a one-way hash function to encrypt the challenge and sends the result back. The authenticator does the same, and compares the results. The advantage of this mechanism is that no passwords are sent across the connection. A challenge is made when the connection is first made. Subsequent challenges may occur. If you want to have your peer authenticate itself, you must .Dq enable chap . in .Pa /etc/ppp/ppp.conf , and have an entry in .Pa /etc/ppp/ppp.secret for the peer. .Pp When using CHAP as the client, you need only specify .Dq AuthName and .Dq AuthKey in .Pa /etc/ppp/ppp.conf . CHAP is accepted by default. Some .Em PPP implementations use "MS-CHAP" rather than MD5 when encrypting the challenge. MS-CHAP is a combination of MD4 and DES. If .Nm was built on a machine with DES libraries available, it will respond to MS-CHAP authentication requests, but will never request them. .It deflate Default: Enabled and Accepted. This option decides if deflate compression will be used by the Compression Control Protocol (CCP). This is the same algorithm as used by the .Xr gzip 1 program. Note: There is a problem negotiating .Ar deflate capabilities with .Nm pppd - a .Em PPP implementation available under many operating systems. .Nm pppd (version 2.3.1) incorrectly attempts to negotiate .Ar deflate compression using type .Em 24 as the CCP configuration type rather than type .Em 26 as specified in .Pa rfc1979 . Type .Ar 24 is actually specified as .Dq PPP Magna-link Variable Resource Compression in .Pa rfc1975 ! .Nm is capable of negotiating with .Nm pppd , but only if .Dq deflate24 is .Ar enable Ns No d and .Ar accept Ns No ed . .It deflate24 Default: Disabled and Denied. This is a variance of the .Ar deflate option, allowing negotiation with the .Nm pppd program. Refer to the .Ar deflate section above for details. It is disabled by default as it violates .Pa rfc1975 . .It dns Default: Disabled and Denied. This option allows DNS negotiation. .Pp If .Dq enable Ns No d , .Nm will request that the peer confirms the entries in .Pa /etc/resolv.conf . If the peer NAKs our request (suggesting new IP numbers), .Pa /etc/resolv.conf is updated and another request is sent to confirm the new entries. .Pp If .Dq accept Ns No ed , .Nm will answer any DNS queries requested by the peer rather than rejecting them. The answer is taken from .Pa /etc/resolv.conf unless the .Dq set dns command is used as an override. .It enddisc Default: Enabled and Accepted. This option allows control over whether we negotiate an endpoint discriminator. We only send our discriminator if .Dq set enddisc is used and .Ar enddisc is enabled. We reject the peers discriminator if .Ar enddisc is denied. .It LANMan|chap80lm Default: Disabled and Accepted. The use of this authentication protocol is discouraged as it partially violates the authentication protocol by implementing two different mechanisms (LANMan & NT) under the guise of a single CHAP type (0x80). .Dq LANMan uses a simple DES encryption mechanism and is the least secure of the CHAP alternatives (although is still more secure than PAP). .Pp Refer to the .Dq MSChap description below for more details. .It lqr Default: Disabled and Accepted. This option decides if Link Quality Requests will be sent or accepted. LQR is a protocol that allows .Nm to determine that the link is down without relying on the modems carrier detect. When LQR is enabled, .Nm sends the .Em QUALPROTO option (see .Dq set lqrperiod below) as part of the LCP request. If the peer agrees, both sides will exchange LQR packets at the agreed frequency, allowing detailed link quality monitoring by enabling LQM logging. If the peer does not agree, and if the .Dq echo option is enabled, .Nm will send .Em LCP ECHO requests instead. These packets pass no information of interest, but they .Em MUST be replied to by the peer. .Pp Whether using .Em LQR or .Em LCP ECHO , .Nm will abruptly drop the connection if 5 unacknowledged packets have been sent rather than sending a 6th. A message is logged at the .Em PHASE level, and any appropriate .Dq reconnect values are honoured as if the peer were responsible for dropping the connection. .Pp Refer to the .Dq enable echo command description for differences in behaviour prior to .Nm version 3.4.2. .It mppe Default: Enabled and Accepted. This is Microsoft Point to Point Encryption scheme. MPPE key size can be 40-, 56- and 128-bits. Refer to .Dq set mppe command. .It MSChapV2|chap81 Default: Disabled and Accepted. It is very similar to standard CHAP (type 0x05) except that it issues challenges of a fixed 16 bytes in length and uses a combination of MD4, SHA-1 and DES to encrypt the challenge rather than using the standard MD5 mechanism. .It MSChap|chap80nt Default: Disabled and Accepted. The use of this authentication protocol is discouraged as it partially violates the authentication protocol by implementing two different mechanisms (LANMan & NT) under the guise of a single CHAP type (0x80). It is very similar to standard CHAP (type 0x05) except that it issues challenges of a fixed 8 bytes in length and uses a combination of MD4 and DES to encrypt the challenge rather than using the standard MD5 mechanism. CHAP type 0x80 for LANMan is also supported - see .Dq enable LANMan for details. .Pp Because both .Dq LANMan and .Dq NT use CHAP type 0x80, when acting as authenticator with both .Dq enable Ns No d , .Nm will rechallenge the peer up to three times if it responds using the wrong one of the two protocols. This gives the peer a chance to attempt using both protocols. .Pp Conversely, when .Nm acts as the authenticatee with both protocols .Dq accept Ns No ed , the protocols are used alternately in response to challenges. .Pp Note: If only LANMan is enabled, .Nm pppd (version 2.3.5) misbehaves when acting as authenticatee. It provides both the NT and the LANMan answers, but also suggests that only the NT answer should be used. .It pap Default: Disabled and Accepted. PAP stands for Password Authentication Protocol. Only one of PAP and CHAP (above) may be negotiated. With PAP, the ID and Password are sent repeatedly to the peer until authentication is acknowledged or the connection is terminated. This is a rather poor security mechanism. It is only performed when the connection is first established. If you want to have your peer authenticate itself, you must .Dq enable pap . in .Pa /etc/ppp/ppp.conf , and have an entry in .Pa /etc/ppp/ppp.secret for the peer (although see the .Dq passwdauth and .Dq set radius options below). .Pp When using PAP as the client, you need only specify .Dq AuthName and .Dq AuthKey in .Pa /etc/ppp/ppp.conf . PAP is accepted by default. .It pred1 Default: Enabled and Accepted. This option decides if Predictor 1 compression will be used by the Compression Control Protocol (CCP). .It protocomp Default: Enabled and Accepted. This option is used to negotiate PFC (Protocol Field Compression), a mechanism where the protocol field number is reduced to one octet rather than two. .It shortseq Default: Enabled and Accepted. This option determines if .Nm will request and accept requests for short (12 bit) sequence numbers when negotiating multi-link mode. This is only applicable if our MRRU is set (thus enabling multi-link). .It vjcomp Default: Enabled and Accepted. This option determines if Van Jacobson header compression will be used. .El .Pp The following options are not actually negotiated with the peer. Therefore, accepting or denying them makes no sense. .Bl -tag -width 2n .It echo Default: Disabled. When this option is enabled, .Nm will send .Em LCP ECHO requests to the peer at the frequency defined by .Dq echoperiod . Note, .Em LQR requests will supersede .Em LCP ECHO requests if enabled and negotiated. See .Dq set lqrperiod below for details. .Pp Prior to .Nm version 3.4.2, .Dq echo was considered enabled if lqr was enabled and negotiated, otherwise it was considered disabled. For the same behaviour, it is now necessary to .Dq enable lqr echo rather than just .Dq enable lqr . .It filter-decapsulation Default: Disabled. When this option is enabled, .Nm will examine UDP frames to see if they actually contain a .Em PPP frame as their payload. If this is the case, all filters will operate on the payload rather than the actual packet. .Pp This is useful if you want to send PPPoUDP traffic over a .Em PPP link, but want that link to do smart things with the real data rather than the UDP wrapper. .Pp The UDP frame payload must not be compressed in any way, otherwise .Nm will not be able to interpret it. It is therefore recommended that you .Ic disable vj pred1 deflate and .Ic deny vj pred1 deflate in the configuration for the .Nm invocation with the udp link. .It force-scripts Default: Disabled. Forces execution of the configured chat scripts in .Dv direct and .Dv dedicated modes. .It idcheck Default: Enabled. When .Nm exchanges low-level LCP, CCP and IPCP configuration traffic, the .Em Identifier field of any replies is expected to be the same as that of the request. By default, .Nm drops any reply packets that do not contain the expected identifier field, reporting the fact at the respective log level. If .Ar idcheck is disabled, .Nm will ignore the identifier field. .It iface-alias Default: Enabled if .Fl nat is specified. This option simply tells .Nm to add new interface addresses to the interface rather than replacing them. The option can only be enabled if network address translation is enabled .Pq Dq nat enable yes . .Pp With this option enabled, .Nm will pass traffic for old interface addresses through the NAT engine (see .Xr libalias 3 ) , resulting in the ability (in .Fl auto mode) to properly connect the process that caused the PPP link to come up in the first place. .Pp Disabling NAT with .Dq nat enable no will also disable .Sq iface-alias . .It ipcp Default: Enabled. This option allows .Nm to attempt to negotiate IP control protocol capabilities and if successful to exchange IP datagrams with the peer. .It ipv6cp Default: Enabled. This option allows .Nm to attempt to negotiate IPv6 control protocol capabilities and if successful to exchange IPv6 datagrams with the peer. .It keep-session Default: Disabled. When .Nm runs as a Multi-link server, a different .Nm instance initially receives each connection. After determining that the link belongs to an already existing bundle (controlled by another .Nm invocation), .Nm will transfer the link to that process. .Pp If the link is a tty device or if this option is enabled, .Nm will not exit, but will change its process name to .Dq session owner and wait for the controlling .Nm to finish with the link and deliver a signal back to the idle process. This prevents the confusion that results from .Nm Ns No 's parent considering the link resource available again. .Pp For tty devices that have entries in .Pa /etc/ttys , this is necessary to prevent another .Xr getty 8 from being started, and for program links such as .Xr sshd 8 , it prevents .Xr sshd 8 from exiting due to the death of its child. As .Nm cannot determine its parents requirements (except for the tty case), this option must be enabled manually depending on the circumstances. .It loopback Default: Enabled. When .Ar loopback is enabled, .Nm will automatically loop back packets being sent out with a destination address equal to that of the .Em PPP interface. If disabled, .Nm will send the packet, probably resulting in an ICMP redirect from the other end. It is convenient to have this option enabled when the interface is also the default route as it avoids the necessity of a loopback route. .It NAS-IP-Address Default: Enabled. This option controls whether .Nm sends the .Dq NAS-IP-Address attribute to the RADIUS server when RADIUS is in use .Pq see Dq set radius . .Pp Note, at least one of .Dq NAS-IP-Address and .Dq NAS-Identifier must be enabled. .Pp Versions of .Nm prior to version 3.4.1 did not send the .Dq NAS-IP-Address attribute as it was reported to break the Radiator RADIUS server. As the latest rfc (2865) no longer hints that only one of .Dq NAS-IP-Address and .Dq NAS-Identifier should be sent (as rfc 2138 did), .Nm now sends both and leaves it up to the administrator that chooses to use bad RADIUS implementations to .Dq disable NAS-IP-Address . .It NAS-Identifier Default: Enabled. This option controls whether .Nm sends the .Dq NAS-Identifier attribute to the RADIUS server when RADIUS is in use .Pq see Dq set radius . .Pp Note, at least one of .Dq NAS-IP-Address and .Dq NAS-Identifier must be enabled. .It passwdauth Default: Disabled. Enabling this option will tell the PAP authentication code to use the password database (see .Xr passwd 5 ) to authenticate the caller if they cannot be found in the .Pa /etc/ppp/ppp.secret file. .Pa /etc/ppp/ppp.secret is always checked first. If you wish to use passwords from .Xr passwd 5 , but also to specify an IP number or label for a given client, use .Dq \&* as the client password in .Pa /etc/ppp/ppp.secret . .It proxy Default: Disabled. Enabling this option will tell .Nm to proxy ARP for the peer. This means that .Nm will make an entry in the ARP table using .Dv HISADDR and the .Dv MAC address of the local network in which .Dv HISADDR appears. This allows other machines connecteed to the LAN to talk to the peer as if the peer itself was connected to the LAN. The proxy entry cannot be made unless .Dv HISADDR is an address from a LAN. .It proxyall Default: Disabled. Enabling this will tell .Nm -to add proxy arp entries for every IP address in all class C or +to add proxy arp entries for every IP address in all /24 subnets or smaller subnets routed via the tun interface. .Pp Proxy arp entries are only made for sticky routes that are added using the .Dq add command. No proxy arp entries are made for the interface address itself (as created by the .Dq set ifaddr command). .It sroutes Default: Enabled. When the .Dq add command is used with the .Dv HISADDR , .Dv MYADDR , .Dv HISADDR6 or .Dv MYADDR6 values, entries are stored in the .Sq sticky route list. Each time these variables change, this list is re-applied to the routing table. .Pp Disabling this option will prevent the re-application of sticky routes, although the .Sq stick route list will still be maintained. .It Oo tcp Oc Ns No mssfixup Default: Enabled. This option tells .Nm to adjust TCP SYN packets so that the maximum receive segment size is not greater than the amount allowed by the interface MTU. .It throughput Default: Enabled. This option tells .Nm to gather throughput statistics. Input and output is sampled over a rolling 5 second window, and current, best and total figures are retained. This data is output when the relevant .Em PPP layer shuts down, and is also available using the .Dq show command. Throughput statistics are available at the .Dq IPCP and .Dq physical levels. .It utmp Default: Enabled. Normally, when a user is authenticated using PAP or CHAP, and when .Nm is running in .Fl direct mode, an entry is made in the utmp and wtmp files for that user. Disabling this option will tell .Nm not to make any utmp or wtmp entries. This is usually only necessary if you require the user to both login and authenticate themselves. .El .It add Ns Xo .Op !\& .Ar dest Ns Op / Ns Ar nn .Op Ar mask .Op Ar gateway .Xc .Ar Dest is the destination IP address. The netmask is specified either as a number of bits with .Ar /nn or as an IP number using .Ar mask . .Ar 0 0 or simply .Ar 0 with no mask refers to the default route. It is also possible to use the literal name .Sq default instead of .Ar 0 . .Ar Gateway is the next hop gateway to get to the given .Ar dest machine/network. Refer to the .Xr route 8 command for further details. .Pp It is possible to use the symbolic names .Sq MYADDR , .Sq HISADDR , .Sq MYADDR6 or .Sq HISADDR6 as the destination, and .Sq HISADDR or .Sq HISADDR6 as the .Ar gateway . .Sq MYADDR is replaced with the interface IP address, .Sq HISADDR is replaced with the interface IP destination (peer) address, .Sq MYADDR6 is replaced with the interface IPv6 address, and .Sq HISADDR6 is replaced with the interface IPv6 destination address, .Pp If the .Ar add!\& command is used (note the trailing .Dq !\& ) , then if the route already exists, it will be updated as with the .Sq route change command (see .Xr route 8 for further details). .Pp Routes that contain the .Dq HISADDR , .Dq MYADDR , .Dq HISADDR6 , .Dq MYADDR6 , .Dq DNS0 , or .Dq DNS1 constants are considered .Sq sticky . They are stored in a list (use .Dq show ncp to see the list), and each time the value of one of these variables changes, the appropriate routing table entries are updated. This facility may be disabled using .Dq disable sroutes . .It allow Ar command Op Ar args This command controls access to .Nm and its configuration files. It is possible to allow user-level access, depending on the configuration file label and on the mode that .Nm is being run in. For example, you may wish to configure .Nm so that only user .Sq fred may access label .Sq fredlabel in .Fl background mode. .Pp User id 0 is immune to these commands. .Bl -tag -width 2n .It allow user Ns Xo .Op s .Ar logname Ns No ... .Xc By default, only user id 0 is allowed access to .Nm . If this command is used, all of the listed users are allowed access to the section in which the .Dq allow users command is found. The .Sq default section is always checked first (even though it is only ever automatically loaded at startup). .Dq allow users commands are cumulative in a given section, but users allowed in any given section override users allowed in the default section, so it is possible to allow users access to everything except a given label by specifying default users in the .Sq default section, and then specifying a new user list for that label. .Pp If user .Sq * is specified, access is allowed to all users. .It allow mode Ns Xo .Op s .Ar mode Ns No ... .Xc By default, access using any .Nm mode is possible. If this command is used, it restricts the access .Ar modes allowed to load the label under which this command is specified. Again, as with the .Dq allow users command, each .Dq allow modes command overrides any previous settings, and the .Sq default section is always checked first. .Pp Possible modes are: .Sq interactive , .Sq auto , .Sq direct , .Sq dedicated , .Sq ddial , .Sq background and .Sq * . .Pp When running in multi-link mode, a section can be loaded if it allows .Em any of the currently existing line modes. .El .It nat Ar command Op Ar args This command allows the control of the network address translation (also known as masquerading or IP aliasing) facilities that are built into .Nm . NAT is done on the external interface only, and is unlikely to make sense if used with the .Fl direct flag. .Pp If nat is enabled on your system (it may be omitted at compile time), the following commands are possible: .Bl -tag -width 2n .It nat enable yes|no This command either switches network address translation on or turns it off. The .Fl nat command line flag is synonymous with .Dq nat enable yes . .It nat addr Op Ar addr_local addr_alias This command allows data for .Ar addr_alias to be redirected to .Ar addr_local . It is useful if you own a small number of real IP numbers that you wish to map to specific machines behind your gateway. .It nat deny_incoming yes|no If set to yes, this command will refuse all incoming packets where an aliasing link does not already exist. Refer to the .Sx CONCEPTUAL BACKGROUND section of .Xr libalias 3 for a description of what an .Dq aliasing link is. .Pp It should be noted under what circumstances an aliasing link is created by .Xr libalias 3 . It may be necessary to further protect your network from outside connections using the .Dq set filter or .Dq nat target commands. .It nat help|? This command gives a summary of available nat commands. .It nat log yes|no This option causes various NAT statistics and information to be logged to the file .Pa /var/log/alias.log . .It nat port Ar proto Ar targetIP Ns Xo : Ns Ar targetPort Ns .Oo .No - Ns Ar targetPort .Oc Ar aliasPort Ns .Oo .No - Ns Ar aliasPort .Oc Oo Ar remoteIP : Ns .Ar remotePort Ns .Oo .No - Ns Ar remotePort .Oc .Oc .Xc This command causes incoming .Ar proto connections to .Ar aliasPort to be redirected to .Ar targetPort on .Ar targetIP . .Ar proto is either .Dq tcp or .Dq udp . .Pp A range of port numbers may be specified as shown above. The ranges must be of the same size. .Pp If .Ar remoteIP is specified, only data coming from that IP number is redirected. .Ar remotePort must either be .Dq 0 (indicating any source port) or a range of ports the same size as the other ranges. .Pp This option is useful if you wish to run things like Internet phone on machines behind your gateway, but is limited in that connections to only one interior machine per source machine and target port are possible. .It nat proto Ar proto localIP Oo .Ar publicIP Op Ar remoteIP .Oc This command tells .Nm to redirect packets of protocol type .Ar proto (see .Xr protocols 5 ) to the internal address .Ar localIP . .Pp If .Ar publicIP is specified, only packets destined for that address are matched, otherwise the default alias address is used. .Pp If .Ar remoteIP is specified, only packets matching that source address are matched, .Pp This command is useful for redirecting tunnel endpoints to an internal machine, for example: .Pp .Dl nat proto ipencap 10.0.0.1 .It "nat proxy cmd" Ar arg Ns No ... This command tells .Nm to proxy certain connections, redirecting them to a given server. Refer to the description of .Fn PacketAliasProxyRule in .Xr libalias 3 for details of the available commands. .It nat punch_fw Op Ar base count This command tells .Nm to punch holes in the firewall for FTP or IRC DCC connections. This is done dynamically by installing temporary firewall rules which allow a particular connection (and only that connection) to go through the firewall. The rules are removed once the corresponding connection terminates. .Pp A maximum of .Ar count rules starting from rule number .Ar base will be used for punching firewall holes. The range will be cleared when the .Dq nat punch_fw command is run. .Pp If no arguments are given, firewall punching is disabled. .It nat skinny_port Op Ar port This command tells .Nm which TCP port is used by the Skinny Station protocol. Skinny is used by Cisco IP phones to communicate with Cisco Call Managers to setup voice over IP calls. The typical port used by Skinny is 2000. .Pp If no argument is given, skinny aliasing is disabled. .It nat same_ports yes|no When enabled, this command will tell the network address translation engine to attempt to avoid changing the port number on outgoing packets. This is useful if you want to support protocols such as RPC and LPD which require connections to come from a well known port. .It nat target Op Ar address Set the given target address or clear it if no address is given. The target address is used by libalias to specify how to NAT incoming packets by default. If a target address is not set or if .Dq default is given, packets are not altered and are allowed to route to the internal network. .Pp The target address may be set to .Dq MYADDR , in which case libalias will redirect all packets to the interface address. .It nat udp_eim yes|no When enabled, UDP packets use endpoint-independent mapping (EIM) from RFC 4787 ("full cone" NAT of RFC 3489). All packets from the same internal address:port are mapped to the same NAT address:port, regardless of their destination address:port. If filtering rules allow, and if .Em deny_incoming is disabled, any other external address:port can also send to the internal address:port through its mapped NAT address:port. This is more compatible with applications, and can reduce the need for port forwarding, but less scalable as each NAT address:port can only be concurrently used by at most one internal address:port. .Pp When disabled, UDP packets use endpoint-dependent mapping (EDM) ("symmetric" NAT). Each connection from a particular internal address:port to different external addresses:ports is mapped to a random and unpredictable NAT address:port. Two appplications behind EDM NATs can only connect to each other by port forwarding on the NAT, or tunnelling through an in-between server. .It nat use_sockets yes|no When enabled, this option tells the network address translation engine to create a socket so that it can guarantee a correct incoming ftp data or IRC connection. .It nat unregistered_only yes|no Only alter outgoing packets with an unregistered source address. According to RFC 1918, unregistered source addresses are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16. .El .Pp These commands are also discussed in the file .Pa README.nat which comes with the source distribution. .It Oo !\& Oc Ns Xo .No bg Ar command .Xc The given .Ar command is executed in the background with the following words replaced: .Bl -tag -width COMPILATIONDATE .It Li AUTHNAME This is replaced with the local .Ar authname value. See the .Dq set authname command below. .It Li COMPILATIONDATE In previous software revisions, this was replaced with the date on which .Nm was compiled. This is no longer supported as it breaks the ability to recompile the same code to produce an exact duplicate of a previous compilation. .It Li DNS0 & DNS1 These are replaced with the primary and secondary nameserver IP numbers. If nameservers are negotiated by IPCP, the values of these macros will change. .It Li ENDDISC This is replaced with the local endpoint discriminator value. See the .Dq set enddisc command below. .It Li HISADDR This is replaced with the peers IP number. .It Li HISADDR6 This is replaced with the peers IPv6 number. .It Li INTERFACE This is replaced with the name of the interface that is in use. .It Li IPOCTETSIN This is replaced with the number of IP bytes received since the connection was established. .It Li IPOCTETSOUT This is replaced with the number of IP bytes sent since the connection was established. .It Li IPPACKETSIN This is replaced with the number of IP packets received since the connection was established. .It Li IPPACKETSOUT This is replaced with the number of IP packets sent since the connection was established. .It Li IPV6OCTETSIN This is replaced with the number of IPv6 bytes received since the connection was established. .It Li IPV6OCTETSOUT This is replaced with the number of IPv6 bytes sent since the connection was established. .It Li IPV6PACKETSIN This is replaced with the number of IPv6 packets received since the connection was established. .It Li IPV6PACKETSOUT This is replaced with the number of IPv6 packets sent since the connection was established. .It Li LABEL This is replaced with the last label name used. A label may be specified on the .Nm command line, via the .Dq load or .Dq dial commands and in the .Pa ppp.secret file. .It Li MYADDR This is replaced with the IP number assigned to the local interface. .It Li MYADDR6 This is replaced with the IPv6 number assigned to the local interface. .It Li OCTETSIN This is replaced with the number of bytes received since the connection was established. .It Li OCTETSOUT This is replaced with the number of bytes sent since the connection was established. .It Li PACKETSIN This is replaced with the number of packets received since the connection was established. .It Li PACKETSOUT This is replaced with the number of packets sent since the connection was established. .It Li PEER_ENDDISC This is replaced with the value of the peers endpoint discriminator. .It Li PROCESSID This is replaced with the current process id. .It Li SOCKNAME This is replaced with the name of the diagnostic socket. .It Li UPTIME This is replaced with the bundle uptime in HH:MM:SS format. .It Li USER This is replaced with the username that has been authenticated with PAP or CHAP. Normally, this variable is assigned only in -direct mode. This value is available irrespective of whether utmp logging is enabled. .It Li VERSION This is replaced with the current version number of .Nm . .El .Pp These substitutions are also done by the .Dq set proctitle , .Dq ident and .Dq log commands. .Pp If you wish to pause .Nm while the command executes, use the .Dq shell command instead. .It clear physical|ipcp|ipv6 Op current|overall|peak... Clear the specified throughput values at either the .Dq physical , .Dq ipcp or .Dq ipv6cp level. If .Dq physical is specified, context must be given (see the .Dq link command below). If no second argument is given, all values are cleared. .It clone Ar name Ns Xo .Op \&, Ns Ar name Ns .No ... .Xc Clone the specified link, creating one or more new links according to the .Ar name argument(s). This command must be used from the .Dq link command below unless you have only got a single link (in which case that link becomes the default). Links may be removed using the .Dq remove command below. .Pp The default link name is .Dq deflink . .It close Op lcp|ccp Ns Op !\& If no arguments are given, the relevant protocol layers will be brought down and the link will be closed. If .Dq lcp is specified, the LCP layer is brought down, but .Nm will not bring the link offline. It is subsequently possible to use .Dq term (see below) to talk to the peer machine if, for example, something like .Dq slirp is being used. If .Dq ccp is specified, only the relevant compression layer is closed. If the .Dq !\& is used, the compression layer will remain in the closed state, otherwise it will re-enter the STOPPED state, waiting for the peer to initiate further CCP negotiation. In any event, this command does not disconnect the user from .Nm or exit .Nm . See the .Dq quit command below. .It delete Ns Xo .Op !\& .Ar dest .Xc This command deletes the route with the given .Ar dest IP address. If .Ar dest is specified as .Sq ALL , all non-direct entries in the routing table for the current interface, and all .Sq sticky route entries are deleted. If .Ar dest is specified as .Sq default , the default route is deleted. .Pp If the .Ar delete!\& command is used (note the trailing .Dq !\& ) , .Nm will not complain if the route does not already exist. .It dial|call Oo Ar label Oc Ns Xo .No ... .Xc This command is the equivalent of .Dq load label followed by .Dq open , and is provided for backwards compatibility. .It down Op Ar lcp|ccp Bring the relevant layer down ungracefully, as if the underlying layer had become unavailable. It is not considered polite to use this command on a Finite State Machine that is in the OPEN state. If no arguments are supplied, the entire link is closed (or if no context is given, all links are terminated). If .Sq lcp is specified, the .Em LCP layer is terminated but the device is not brought offline and the link is not closed. If .Sq ccp is specified, only the relevant compression layer(s) are terminated. .It help|? Op Ar command Show a list of available commands. If .Ar command is specified, show the usage string for that command. .It ident Op Ar text Ns No ... Identify the link to the peer using .Ar text . If .Ar text is empty, link identification is disabled. It is possible to use any of the words described for the .Ic bg command above. Refer to the .Ic sendident command for details of when .Nm identifies itself to the peer. .It iface Ar command Op args This command is used to control the interface used by .Nm . .Ar Command may be one of the following: .Bl -tag -width 2n .It iface add Ns Xo .Op !\& .Ar addr Ns Op / Ns Ar bits .Op Ar peer .Xc .It iface add Ns Xo .Op !\& .Ar addr .Ar mask .Ar peer .Xc Add the given .Ar addr mask peer combination to the interface. Instead of specifying .Ar mask , .Ar /bits can be used (with no space between it and .Ar addr ) . If the given address already exists, the command fails unless the .Dq !\& is used - in which case the previous interface address entry is overwritten with the new one, allowing a change of netmask or peer address. .Pp If only .Ar addr is specified, .Ar bits defaults to .Dq 32 and .Ar peer defaults to .Dq 255.255.255.255 . This address (the broadcast address) is the only duplicate peer address that .Nm allows. .It iface clear Op INET | INET6 If this command is used while .Nm is in the OPENED state or while in .Fl auto mode, all addresses except for the NCP negotiated address are deleted from the interface. If .Nm is not in the OPENED state and is not in .Fl auto mode, all interface addresses are deleted. .Pp If the INET or INET6 arguments are used, only addresses for that address family are cleared. .It iface delete Ns Xo .Op !\& Ns .No |rm Ns Op !\& .Ar addr .Xc This command deletes the given .Ar addr from the interface. If the .Dq !\& is used, no error is given if the address is not currently assigned to the interface (and no deletion takes place). .It iface name Ar name Renames the interface to .Ar name . .It iface description Ar description Sets the interface description to .Ar description . Useful if you have many interfaces on your system. .It iface show Shows the current state and current addresses for the interface. It is much the same as running .Dq ifconfig INTERFACE . .It iface help Op Ar sub-command This command, when invoked without .Ar sub-command , will show a list of possible .Dq iface sub-commands and a brief synopsis for each. When invoked with .Ar sub-command , only the synopsis for the given sub-command is shown. .El .It Oo data Oc Ns Xo .No link .Ar name Ns Oo , Ns Ar name Oc Ns ... Ar command Op Ar args .Xc This command may prefix any other command if the user wishes to specify which link the command should affect. This is only applicable after multiple links have been created in Multi-link mode using the .Dq clone command. .Pp .Ar Name specifies the name of an existing link. If .Ar name is a comma separated list, .Ar command is executed on each link. If .Ar name is .Dq * , .Ar command is executed on all links. .It load Oo Ar label Oc Ns Xo .No ... .Xc Load the given .Ar label Ns No (s) from the .Pa ppp.conf file. If .Ar label is not given, the .Ar default label is used. .Pp Unless the .Ar label section uses the .Dq set mode , .Dq open or .Dq dial commands, .Nm will not attempt to make an immediate connection. .It log Ar word Ns No ... Send the given word(s) to the log file with the prefix .Dq LOG: . Word substitutions are done as explained under the .Dq !bg command above. .It open Op lcp|ccp|ipcp This is the opposite of the .Dq close command. All closed links are immediately brought up apart from second and subsequent .Ar demand-dial links - these will come up based on the .Dq set autoload command that has been used. .Pp If the .Dq lcp argument is used while the LCP layer is already open, LCP will be renegotiated. This allows various LCP options to be changed, after which .Dq open lcp can be used to put them into effect. After renegotiating LCP, any agreed authentication will also take place. .Pp If the .Dq ccp argument is used, the relevant compression layer is opened. Again, if it is already open, it will be renegotiated. .Pp If the .Dq ipcp argument is used, the link will be brought up as normal, but if IPCP is already open, it will be renegotiated and the network interface will be reconfigured. .Pp It is probably not good practice to re-open the PPP state machines like this as it is possible that the peer will not behave correctly. It .Em is however useful as a way of forcing the CCP or VJ dictionaries to be reset. .It passwd Ar pass Specify the password required for access to the full .Nm command set. This password is required when connecting to the diagnostic port (see the .Dq set server command). .Ar Pass is specified on the .Dq set server command line. The value of .Ar pass is not logged when .Ar command logging is active, instead, the literal string .Sq ******** is logged. .It quit|bye Op all If .Dq quit is executed from the controlling connection or from a command file, ppp will exit after closing all connections. Otherwise, if the user is connected to a diagnostic socket, the connection is simply dropped. .Pp If the .Ar all argument is given, .Nm will exit despite the source of the command after closing all existing connections. .It remove|rm This command removes the given link. It is only really useful in multi-link mode. A link must be in the .Dv CLOSED state before it is removed. .It rename|mv Ar name This command renames the given link to .Ar name . It will fail if .Ar name is already used by another link. .Pp The default link name is .Sq deflink . Renaming it to .Sq modem , .Sq cuau0 or .Sq USR may make the log file more readable. .It resolv Ar command This command controls .Nm Ns No 's manipulation of the .Xr resolv.conf 5 file. When .Nm starts up, it loads the contents of this file into memory and retains this image for future use. .Ar command is one of the following: .Bl -tag -width readonly .It Em readonly Treat .Pa /etc/resolv.conf as read only. If .Dq dns is enabled, .Nm will still attempt to negotiate nameservers with the peer, making the results available via the .Dv DNS0 and .Dv DNS1 macros. This is the opposite of the .Dq resolv writable command. .It Em reload Reload .Pa /etc/resolv.conf into memory. This may be necessary if for example a DHCP client overwrote .Pa /etc/resolv.conf . .It Em restore Replace .Pa /etc/resolv.conf with the version originally read at startup or with the last .Dq resolv reload command. This is sometimes a useful command to put in the .Pa /etc/ppp/ppp.linkdown file. .It Em rewrite Rewrite the .Pa /etc/resolv.conf file. This command will work even if the .Dq resolv readonly command has been used. It may be useful as a command in the .Pa /etc/ppp/ppp.linkup file if you wish to defer updating .Pa /etc/resolv.conf until after other commands have finished. .It Em writable Allow .Nm to update .Pa /etc/resolv.conf if .Dq dns is enabled and .Nm successfully negotiates a DNS. This is the opposite of the .Dq resolv readonly command. .El .It save This option is not (yet) implemented. .It sendident This command tells .Nm to identify itself to the peer. The link must be in LCP state or higher. If no identity has been set (via the .Ic ident command), .Ic sendident will fail. .Pp When an identity has been set, .Nm will automatically identify itself when it sends or receives a configure reject, when negotiation fails or when LCP reaches the opened state. .Pp Received identification packets are logged to the LCP log (see .Ic set log for details) and are never responded to. .It set Ns Xo .Op up .Ar var value .Xc This option allows the setting of any of the following variables: .Bl -tag -width 2n .It set accmap Ar hex-value ACCMap stands for Asynchronous Control Character Map. This is always negotiated with the peer, and defaults to a value of 00000000 in hex. This protocol is required to defeat hardware that depends on passing certain characters from end to end (such as XON/XOFF etc). .Pp For the XON/XOFF scenario, use .Dq set accmap 000a0000 . .It set Oo auth Oc Ns Xo .No key Ar value .Xc This sets the authentication key (or password) used in client mode PAP or CHAP negotiation to the given value. It also specifies the password to be used in the dial or login scripts in place of the .Sq \eP sequence, preventing the actual password from being logged. If .Ar command or .Ar chat logging is in effect, .Ar value is logged as .Sq ******** for security reasons. .Pp If the first character of .Ar value is an exclamation mark .Pq Dq !\& , .Nm treats the remainder of the string as a program that must be executed to determine the .Dq authname and .Dq authkey values. .Pp If the .Dq !\& is doubled up (to .Dq !! ) , it is treated as a single literal .Dq !\& , otherwise, ignoring the .Dq !\& , .Ar value is parsed as a program to execute in the same was as the .Dq !bg command above, substituting special names in the same manner. Once executed, .Nm will feed the program three lines of input, each terminated by a newline character: .Bl -bullet .It The host name as sent in the CHAP challenge. .It The challenge string as sent in the CHAP challenge. .It The locally defined .Dq authname . .El .Pp Two lines of output are expected: .Bl -bullet .It The .Dq authname to be sent with the CHAP response. .It The .Dq authkey , which is encrypted with the challenge and request id, the answer being sent in the CHAP response packet. .El .Pp When configuring .Nm in this manner, it is expected that the host challenge is a series of ASCII digits or characters. An encryption device or Secure ID card is usually required to calculate the secret appropriate for the given challenge. .It set authname Ar id This sets the authentication id used in client mode PAP or CHAP negotiation. .Pp If used in .Fl direct mode with CHAP enabled, .Ar id is used in the initial authentication challenge and should normally be set to the local machine name. .It set autoload Xo .Ar min-percent max-percent period .Xc These settings apply only in multi-link mode and default to zero, zero and five respectively. When more than one .Ar demand-dial (also known as .Fl auto ) mode link is available, only the first link is made active when .Nm first reads data from the tun device. The next .Ar demand-dial link will be opened only when the current bundle throughput is at least .Ar max-percent percent of the total bundle bandwidth for .Ar period seconds. When the current bundle throughput decreases to .Ar min-percent percent or less of the total bundle bandwidth for .Ar period seconds, a .Ar demand-dial link will be brought down as long as it is not the last active link. .Pp Bundle throughput is measured as the maximum of inbound and outbound traffic. .Pp The default values cause .Ar demand-dial links to simply come up one at a time. .Pp Certain devices cannot determine their physical bandwidth, so it is sometimes necessary to use the .Dq set bandwidth command (described below) to make .Dq set autoload work correctly. .It set bandwidth Ar value This command sets the connection bandwidth in bits per second. .Ar value must be greater than zero. It is currently only used by the .Dq set autoload command above. .It set callback Ar option Ns No ... If no arguments are given, callback is disabled, otherwise, .Nm will request (or in .Fl direct mode, will accept) one of the given .Ar option Ns No s . In client mode, if an .Ar option is NAK'd .Nm will request a different .Ar option , until no options remain at which point .Nm will terminate negotiations (unless .Dq none is one of the specified .Ar option ) . In server mode, .Nm will accept any of the given protocols - but the client .Em must request one of them. If you wish callback to be optional, you must {include} .Ar none as an option. .Pp The .Ar option Ns No s are as follows (in this order of preference): .Bl -tag -width Ds .It auth The callee is expected to decide the callback number based on authentication. If .Nm is the callee, the number should be specified as the fifth field of the peers entry in .Pa /etc/ppp/ppp.secret . .It cbcp Microsoft's callback control protocol is used. See .Dq set cbcp below. .Pp If you wish to negotiate .Ar cbcp in client mode but also wish to allow the server to request no callback at CBCP negotiation time, you must specify both .Ar cbcp and .Ar none as callback options. .It E.164 *| Ns Xo .Ar number Ns Op , Ns Ar number Ns .No ... .Xc The caller specifies the .Ar number . If .Nm is the callee, .Ar number should be either a comma separated list of allowable numbers or a .Dq \&* , meaning any number is permitted. If .Nm is the caller, only a single number should be specified. .Pp Note, this option is very unsafe when used with a .Dq \&* as a malicious caller can tell .Nm to call any (possibly international) number without first authenticating themselves. .It none If the peer does not wish to do callback at all, .Nm will accept the fact and continue without callback rather than terminating the connection. This is required (in addition to one or more other callback options) if you wish callback to be optional. .El .It set cbcp Oo .No *| Ns Ar number Ns .Oo , Ns Ar number Ns ...\& Oc .Op Ar delay Op Ar retry .Oc If no arguments are given, CBCP (Microsoft's CallBack Control Protocol) is disabled - ie, configuring CBCP in the .Dq set callback command will result in .Nm requesting no callback in the CBCP phase. Otherwise, .Nm attempts to use the given phone .Ar number Ns No (s) . .Pp In server mode .Pq Fl direct , .Nm will insist that the client uses one of these numbers, unless .Dq \&* is used in which case the client is expected to specify the number. .Pp In client mode, .Nm will attempt to use one of the given numbers (whichever it finds to be agreeable with the peer), or if .Dq \&* is specified, .Nm will expect the peer to specify the number. .It set cd Oo .No off\&| Ns Ar seconds Ns Op !\& .Oc Normally, .Nm checks for the existence of carrier depending on the type of device that has been opened: .Bl -tag -width XXX -offset XXX .It Terminal Devices Carrier is checked one second after the login script is complete. If it is not set, .Nm assumes that this is because the device does not support carrier (which is true for most .Dq laplink NULL-modem cables), logs the fact and stops checking for carrier. .Pp As ptys do not support the TIOCMGET ioctl, the tty device will switch all carrier detection off when it detects that the device is a pty. .It PPPoE (netgraph) Devices Carrier is checked once per second for 5 seconds. If it is not set after the fifth second, the connection attempt is considered to have failed and the device is closed. Carrier is always required for PPPoE devices. .El .Pp All other device types do not support carrier. Setting a carrier value will result in a warning when the device is opened. .Pp Some modems take more than one second after connecting to assert the carrier signal. If this delay is not increased, this will result in .Nm Ns No 's inability to detect when the link is dropped, as .Nm assumes that the device is not asserting carrier. .Pp The .Dq set cd command overrides the default carrier behaviour. .Ar seconds specifies the maximum number of seconds that .Nm should wait after the dial script has finished before deciding if carrier is available or not. .Pp If .Dq off is specified, .Nm will not check for carrier on the device, otherwise .Nm will not proceed to the login script until either carrier is detected or until .Ar seconds has elapsed, at which point .Nm assumes that the device will not set carrier. .Pp If no arguments are given, carrier settings will go back to their default values. .Pp If .Ar seconds is followed immediately by an exclamation mark .Pq Dq !\& , .Nm will .Em require carrier. If carrier is not detected after .Ar seconds seconds, the link will be disconnected. .It set choked Op Ar timeout This sets the number of seconds that .Nm will keep a choked output queue before dropping all pending output packets. If .Ar timeout is less than or equal to zero or if .Ar timeout is not specified, it is set to the default value of .Em 120 seconds . .Pp A choked output queue occurs when .Nm has read a certain number of packets from the local network for transmission, but cannot send the data due to link failure (the peer is busy etc.). .Nm will not read packets indefinitely. Instead, it reads up to .Em 30 packets (or .Em 30 No + .Em nlinks No * .Em 2 packets in multi-link mode), then stops reading the network interface until either .Ar timeout seconds have passed or at least one packet has been sent. .Pp If .Ar timeout seconds pass, all pending output packets are dropped. .It set ctsrts|crtscts on|off This sets hardware flow control. Hardware flow control is .Ar on by default. .It set deflate Ar out-winsize Op Ar in-winsize This sets the DEFLATE algorithms default outgoing and incoming window sizes. Both .Ar out-winsize and .Ar in-winsize must be values between .Em 8 and .Em 15 . If .Ar in-winsize is specified, .Nm will insist that this window size is used and will not accept any other values from the peer. .It set dns Op Ar primary Op Ar secondary This command specifies DNS overrides for the .Dq accept dns command. Refer to the .Dq accept command description above for details. This command does not affect the IP numbers requested using .Dq enable dns . .It set device|line Xo .Ar value Ns No ... .Xc This sets the device(s) to which .Nm will talk to the given .Dq value . .Pp All serial device names are expected to begin with .Pa /dev/ . Serial devices are usually called .Pa cuaXX . .Pp If .Dq value does not begin with .Pa /dev/ , it must either begin with an exclamation mark .Pq Dq !\& , be of the format .No PPPoE\&: Ns Ar iface Ns Xo .Op \&: Ns Ar provider Ns .Xc (on .Xr netgraph 4 enabled systems), or be of the format .Sm off .Ar host : port Op /tcp|udp . .Sm on .Pp If it begins with an exclamation mark, the rest of the device name is treated as a program name, and that program is executed when the device is opened. Standard input, output and error are fed back to .Nm and are read and written as if they were a regular device. .Pp If a .No PPPoE\&: Ns Ar iface Ns Xo .Op \&: Ns Ar provider Ns .Xc specification is given, .Nm will attempt to create a .Em PPP over Ethernet connection using the given .Ar iface interface by using .Xr netgraph 4 . If .Xr netgraph 4 is not available, .Nm will attempt to load it using .Xr kldload 2 . If this fails, an external program must be used such as the .Xr pppoed 8 program available under .Ox . The given .Ar provider is passed as the service name in the PPPoE Discovery Initiation (PADI) packet. If no provider is given, an empty value will be used. .Pp When a PPPoE connection is established, .Nm will place the name of the Access Concentrator in the environment variable .Ev ACNAME . .Pp Refer to .Xr netgraph 4 and .Xr ng_pppoe 4 for further details. .Pp If a .Ar host : Ns Ar port Ns Oo .No /tcp|udp .Oc specification is given, .Nm will attempt to connect to the given .Ar host on the given .Ar port . If a .Dq /tcp or .Dq /udp suffix is not provided, the default is .Dq /tcp . Refer to the section on .Em PPP OVER TCP and UDP above for further details. .Pp If multiple .Dq values are specified, .Nm will attempt to open each one in turn until it succeeds or runs out of devices. .It set dial Ar chat-script This specifies the chat script that will be used to dial the other side. See also the .Dq set login command below. Refer to .Xr chat 8 and to the example configuration files for details of the chat script format. It is possible to specify some special .Sq values in your chat script as follows: .Bl -tag -width 2n .It Li \ec When used as the last character in a .Sq send string, this indicates that a newline should not be appended. .It Li \ed When the chat script encounters this sequence, it delays two seconds. .It Li \ep When the chat script encounters this sequence, it delays for one quarter of a second. .It Li \en This is replaced with a newline character. .It Li \er This is replaced with a carriage return character. .It Li \es This is replaced with a space character. .It Li \et This is replaced with a tab character. .It Li \eT This is replaced by the current phone number (see .Dq set phone below). .It Li \eP This is replaced by the current .Ar authkey value (see .Dq set authkey above). .It Li \eU This is replaced by the current .Ar authname value (see .Dq set authname above). .El .Pp Note that two parsers will examine these escape sequences, so in order to have the .Sq chat parser see the escape character, it is necessary to escape it from the .Sq command parser . This means that in practice you should use two escapes, for example: .Bd -literal -offset indent set dial "... ATDT\\\\T CONNECT" .Ed .Pp It is also possible to execute external commands from the chat script. To do this, the first character of the expect or send string is an exclamation mark .Pq Dq !\& . If a literal exclamation mark is required, double it up to .Dq !!\& and it will be treated as a single literal .Dq !\& . When the command is executed, standard input and standard output are directed to the open device (see the .Dq set device command), and standard error is read by .Nm and substituted as the expect or send string. If .Nm is running in interactive mode, file descriptor 3 is attached to .Pa /dev/tty . .Pp For example (wrapped for readability): .Bd -literal -offset indent set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e \\"!/bin/echo in\\" HELLO" .Ed .Pp would result in the following chat sequence (output using the .Sq set log local chat command before dialing): .Bd -literal -offset indent Dial attempt 1 of 1 dial OK! Chat: Expecting: Chat: Sending: Chat: Expecting: login:--login: Chat: Wait for (5): login: Chat: Sending: ppp Chat: Expecting: word: Chat: Wait for (5): word: Chat: Sending: ppp Chat: Expecting: !sh \\-c "echo \\-n label: >&2" Chat: Exec: sh -c "echo -n label: >&2" Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label: Chat: Exec: /bin/echo in Chat: Sending: Chat: Expecting: HELLO Chat: Wait for (5): HELLO login OK! .Ed .Pp Note (again) the use of the escape character, allowing many levels of nesting. Here, there are four parsers at work. The first parses the original line, reading it as three arguments. The second parses the third argument, reading it as 11 arguments. At this point, it is important that the .Dq \&- signs are escaped, otherwise this parser will see them as constituting an expect-send-expect sequence. When the .Dq !\& character is seen, the execution parser reads the first command as three arguments, and then .Xr sh 1 itself expands the argument after the .Fl c . As we wish to send the output back to the modem, in the first example we redirect our output to file descriptor 2 (stderr) so that .Nm itself sends and logs it, and in the second example, we just output to stdout, which is attached directly to the modem. .Pp This, of course means that it is possible to execute an entirely external .Dq chat command rather than using the internal one. See .Xr chat 8 for a good alternative. .Pp The external command that is executed is subjected to the same special word expansions as the .Dq !bg command. .It set enddisc Op label|IP|MAC|magic|psn value This command sets our local endpoint discriminator. If set prior to LCP negotiation, and if no .Dq disable enddisc command has been used, .Nm will send the information to the peer using the LCP endpoint discriminator option. The following discriminators may be set: .Bl -tag -width indent .It Li label The current label is used. .It Li IP Our local IP number is used. As LCP is negotiated prior to IPCP, it is possible that the IPCP layer will subsequently change this value. If it does, the endpoint discriminator stays at the old value unless manually reset. .It Li MAC This is similar to the .Ar IP option above, except that the MAC address associated with the local IP number is used. If the local IP number is not resident on any Ethernet interface, the command will fail. .Pp As the local IP number defaults to whatever the machine host name is, .Dq set enddisc mac is usually done prior to any .Dq set ifaddr commands. .It Li magic A 20 digit random number is used. Care should be taken when using magic numbers as restarting .Nm or creating a link using a different .Nm invocation will also use a different magic number and will therefore not be recognised by the peer as belonging to the same bundle. This makes it unsuitable for .Fl direct connections. .It Li psn Ar value The given .Ar value is used. .Ar Value should be set to an absolute public switched network number with the country code first. .El .Pp If no arguments are given, the endpoint discriminator is reset. .It set escape Ar value... This option is similar to the .Dq set accmap option above. It allows the user to specify a set of characters that will be .Sq escaped as they travel across the link. .It set filter dial|alive|in|out Ar rule-no Xo .No permit|deny|clear\&| Ns Ar rule-no .Op !\& .Oo Op host .Ar src_addr Ns Op / Ns Ar width .Op Ar dst_addr Ns Op / Ns Ar width .Oc [ Ns Ar proto .Op src lt|eq|gt Ar port .Op dst lt|eq|gt Ar port .Op estab .Op syn .Op finrst .Op timeout Ar secs ] .Xc .Nm supports four filter sets. The .Em alive filter specifies packets that keep the connection alive - resetting the idle timer. The .Em dial filter specifies packets that cause .Nm to dial when in .Fl auto mode. The .Em in filter specifies packets that are allowed to travel into the machine and the .Em out filter specifies packets that are allowed out of the machine. .Pp Filtering is done prior to any IP alterations that might be done by the NAT engine on outgoing packets and after any IP alterations that might be done by the NAT engine on incoming packets. By default all empty filter sets allow all packets to pass. Rules are processed in order according to .Ar rule-no (unless skipped by specifying a rule number as the .Ar action ) . Up to 40 rules may be given for each set. If a packet does not match any of the rules in a given set, it is discarded. In the case of .Em in and .Em out filters, this means that the packet is dropped. In the case of .Em alive filters it means that the packet will not reset the idle timer (even if the .Ar in Ns No / Ns Ar out filter has a .Dq timeout value) and in the case of .Em dial filters it means that the packet will not trigger a dial. A packet failing to trigger a dial will be dropped rather than queued. Refer to the section on .Sx PACKET FILTERING above for further details. .It set hangup Ar chat-script This specifies the chat script that will be used to reset the device before it is closed. It should not normally be necessary, but can be used for devices that fail to reset themselves properly on close. .It set help|? Op Ar command This command gives a summary of available set commands, or if .Ar command is specified, the command usage is shown. .It set ifaddr Oo Ar myaddr Ns .Op / Ns Ar \&nn .Oo Ar hisaddr Ns Op / Ns Ar \&nn .Oo Ar netmask .Op Ar triggeraddr .Oc Oc .Oc This command specifies the IP addresses that will be used during IPCP negotiation. Addresses are specified using the format .Pp .Dl a.b.c.d/nn .Pp Where .Dq a.b.c.d is the preferred IP, but .Ar nn specifies how many bits of the address we will insist on. If .No / Ns Ar nn is omitted, it defaults to .Dq /32 unless the IP address is 0.0.0.0 in which case it defaults to .Dq /0 . .Pp If you wish to assign a dynamic IP number to the peer, .Ar hisaddr may also be specified as a range of IP numbers in the format .Bd -ragged -offset indent .Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Oc Ns Oo , Ns Ar \&IP Ns .Oo \&- Ns Ar \&IP Ns Oc Oc Ns ... .Ed .Pp for example: .Pp .Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20 .Pp will only negotiate .Dq 10.0.0.1 as the local IP number, but may assign any of the given 10 IP numbers to the peer. If the peer requests one of these numbers, and that number is not already in use, .Nm will grant the peers request. This is useful if the peer wants to re-establish a link using the same IP number as was previously allocated (thus maintaining any existing tcp or udp connections). .Pp If the peer requests an IP number that is either outside of this range or is already in use, .Nm will suggest a random unused IP number from the range. .Pp If .Ar triggeraddr is specified, it is used in place of .Ar myaddr in the initial IPCP negotiation. However, only an address in the .Ar myaddr range will be accepted. This is useful when negotiating with some .Dv PPP implementations that will not assign an IP number unless their peer requests .Dq 0.0.0.0 . .Pp It should be noted that in .Fl auto mode, .Nm will configure the interface immediately upon reading the .Dq set ifaddr line in the config file. In any other mode, these values are just used for IPCP negotiations, and the interface is not configured until the IPCP layer is up. .Pp Note that the .Ar HISADDR argument may be overridden by the third field in the .Pa ppp.secret file once the client has authenticated itself (if PAP or CHAP are .Dq enabled ) . Refer to the .Sx AUTHENTICATING INCOMING CONNECTIONS section for details. .Pp In all cases, if the interface is already configured, .Nm will try to maintain the interface IP numbers so that any existing bound sockets will remain valid. .It set ifqueue Ar packets Set the maximum number of packets that .Nm will read from the tunnel interface while data cannot be sent to any of the available links. This queue limit is necessary to flow control outgoing data as the tunnel interface is likely to be far faster than the combined links available to .Nm . .Pp If .Ar packets is set to a value less than the number of links, .Nm will read up to that value regardless. This prevents any possible latency problems. .Pp The default value for .Ar packets is .Dq 30 . .It set ccpretry|ccpretries Oo Ar timeout .Op Ar reqtries Op Ar trmtries .Oc .It set chapretry|chapretries Oo Ar timeout .Op Ar reqtries .Oc .It set ipcpretry|ipcpretries Oo Ar timeout .Op Ar reqtries Op Ar trmtries .Oc .It set ipv6cpretry|ipv6cpretries Oo Ar timeout .Op Ar reqtries Op Ar trmtries .Oc .It set lcpretry|lcpretries Oo Ar timeout .Op Ar reqtries Op Ar trmtries .Oc .It set papretry|papretries Oo Ar timeout .Op Ar reqtries .Oc These commands set the number of seconds that .Nm will wait before resending Finite State Machine (FSM) Request packets. The default .Ar timeout for all FSMs is 3 seconds (which should suffice in most cases). .Pp If .Ar reqtries is specified, it tells .Nm how many configuration request attempts it should make while receiving no reply from the peer before giving up. The default is 5 attempts for CCP, LCP and IPCP and 3 attempts for PAP and CHAP. .Pp If .Ar trmtries is specified, it tells .Nm how many terminate requests should be sent before giving up waiting for the peers response. The default is 3 attempts. Authentication protocols are not terminated and it is therefore invalid to specify .Ar trmtries for PAP or CHAP. .Pp In order to avoid negotiations with the peer that will never converge, .Nm will only send at most 3 times the configured number of .Ar reqtries in any given negotiation session before giving up and closing that layer. .It set log Xo .Op local .Op +|- Ns .Ar value Ns No ... .Xc This command allows the adjustment of the current log level. Refer to the Logging Facility section for further details. .It set login Ar chat-script This .Ar chat-script compliments the dial-script. If both are specified, the login script will be executed after the dial script. Escape sequences available in the dial script are also available here. .It set logout Ar chat-script This specifies the chat script that will be used to logout before the hangup script is called. It should not normally be necessary. .It set lqrperiod|echoperiod Ar frequency This command sets the .Ar frequency in seconds at which .Em LQR or .Em LCP ECHO packets are sent. The default is 30 seconds. You must also use the .Dq enable lqr and/or .Dq enable echo commands if you wish to send .Em LQR or .Em LCP ECHO requests to the peer. .It set mode Ar interactive|auto|ddial|background This command allows you to change the .Sq mode of the specified link. This is normally only useful in multi-link mode, but may also be used in uni-link mode. .Pp It is not possible to change a link that is .Sq direct or .Sq dedicated . .Pp Note: If you issue the command .Dq set mode auto , and have network address translation enabled, it may be useful to .Dq enable iface-alias afterwards. This will allow .Nm to do the necessary address translations to enable the process that triggers the connection to connect once the link is up despite the peer assigning us a new (dynamic) IP address. .It set mppe Op 40|56|128|* Op stateless|stateful|* This option selects the encryption parameters used when negotiation MPPE. MPPE can be disabled entirely with the .Dq disable mppe command. If no arguments are given, .Nm will attempt to negotiate a stateful link with a 128 bit key, but will agree to whatever the peer requests (including no encryption at all). .Pp If any arguments are given, .Nm will .Em insist on using MPPE and will close the link if it is rejected by the peer (Note; this behaviour can be overridden by a configured RADIUS server). .Pp The first argument specifies the number of bits that .Nm should insist on during negotiations and the second specifies whether .Nm should insist on stateful or stateless mode. In stateless mode, the encryption dictionary is re-initialised with every packet according to an encryption key that is changed with every packet. In stateful mode, the encryption dictionary is re-initialised every 256 packets or after the loss of any data and the key is changed every 256 packets. Stateless mode is less efficient but is better for unreliable transport layers. .It set mrru Op Ar value Setting this option enables Multi-link PPP negotiations, also known as Multi-link Protocol or MP. There is no default MRRU (Maximum Reconstructed Receive Unit) value. If no argument is given, multi-link mode is disabled. .It set mru Xo .Op max Ns Op imum .Op Ar value .Xc The default MRU (Maximum Receive Unit) is 1500. If it is increased, the other side *may* increase its MTU. In theory there is no point in decreasing the MRU to below the default as the .Em PPP protocol says implementations *must* be able to accept packets of at least 1500 octets. .Pp If the .Dq maximum keyword is used, .Nm will refuse to negotiate a higher value. The maximum MRU can be set to 2048 at most. Setting a maximum of less than 1500 violates the .Em PPP rfc, but may sometimes be necessary. For example, .Em PPPoE imposes a maximum of 1492 due to hardware limitations. .Pp If no argument is given, 1500 is assumed. A value must be given when .Dq maximum is specified. .It set mtu Xo .Op max Ns Op imum .Op Ar value .Xc The default MTU is 1500. At negotiation time, .Nm will accept whatever MRU the peer requests (assuming it is not less than 296 bytes or greater than the assigned maximum). If the MTU is set, .Nm will not accept MRU values less than .Ar value . When negotiations are complete, the MTU is used when writing to the interface, even if the peer requested a higher value MRU. This can be useful for limiting your packet size (giving better bandwidth sharing at the expense of more header data). .Pp If the .Dq maximum keyword is used, .Nm will refuse to negotiate a higher value. The maximum MTU can be set to 2048 at most. Note, it is necessary to use the .Dq maximum keyword to limit the MTU when using PPPoE. .Pp If no .Ar value is given, 1500, or whatever the peer asks for is used. A value must be given when .Dq maximum is specified. .It set nbns Op Ar x.x.x.x Op Ar y.y.y.y This option allows the setting of the Microsoft NetBIOS name server values to be returned at the peers request. If no values are given, .Nm will reject any such requests. .It set openmode active|passive Op Ar delay By default, .Ar openmode is always .Ar active with a one second .Ar delay . That is, .Nm will always initiate LCP/IPCP/CCP negotiation one second after the line comes up. If you want to wait for the peer to initiate negotiations, you can use the value .Ar passive . If you want to initiate negotiations immediately or after more than one second, the appropriate .Ar delay may be specified here in seconds. .It set parity odd|even|none|mark This allows the line parity to be set. The default value is .Ar none . .It set phone Ar telno Ns Xo .Oo \&| Ns Ar backupnumber Oc Ns ... Ns Oo : Ns Ar nextnumber Oc Ns ... Xc This allows the specification of the phone number to be used in place of the \\\\T string in the dial and login chat scripts. Multiple phone numbers may be given separated either by a pipe .Pq Dq \&| or a colon .Pq Dq \&: . .Pp Numbers after the pipe are only dialed if the dial or login script for the previous number failed. .Pp Numbers after the colon are tried sequentially, irrespective of the reason the line was dropped. .Pp If multiple numbers are given, .Nm will dial them according to these rules until a connection is made, retrying the maximum number of times specified by .Dq set redial below. In .Fl background mode, each number is attempted at most once. .It set pppoe Op standard|3Com This option configures the underlying .Xr ng_pppoe 4 node to either standard RFC2516 PPPoE or proprietary 3Com mode. If not set the system default will be used. .It set Oo proc Oc Ns Xo .No title Op Ar value .Xc The current process title as displayed by .Xr ps 1 is changed according to .Ar value . If .Ar value is not specified, the original process title is restored. All the word replacements done by the shell commands (see the .Dq bg command above) are done here too. .Pp Note, if USER is required in the process title, the .Dq set proctitle command must appear in .Pa ppp.linkup , as it is not known when the commands in .Pa ppp.conf are executed. .It set radius Op Ar config-file This command enables RADIUS support (if it is compiled in). .Ar config-file refers to the radius client configuration file as described in .Xr radius.conf 5 . If PAP, CHAP, MSCHAP or MSCHAPv2 are .Dq enable Ns No d , .Nm behaves as a .Em \&N Ns No etwork .Em \&A Ns No ccess .Em \&S Ns No erver and uses the configured RADIUS server to authenticate rather than authenticating from the .Pa ppp.secret file or from the passwd database. .Pp If none of PAP, CHAP, MSCHAP or MSCHAPv2 are enabled, .Dq set radius will do nothing. .Pp .Nm uses the following attributes from the RADIUS reply: .Bl -tag -width XXX -offset XXX .It RAD_FRAMED_IP_ADDRESS The peer IP address is set to the given value. .It RAD_FRAMED_IP_NETMASK The tun interface netmask is set to the given value. .It RAD_FRAMED_MTU If the given MTU is less than the peers MRU as agreed during LCP negotiation, *and* it is less that any configured MTU (see the .Dq set mru command), the tun interface MTU is set to the given value. .It RAD_FRAMED_COMPRESSION If the received compression type is .Dq 1 , .Nm will request VJ compression during IPCP negotiations despite any .Dq disable vj configuration command. .It RAD_FILTER_ID If this attribute is supplied, .Nm will attempt to use it as an additional label to load from the .Pa ppp.linkup and .Pa ppp.linkdown files. The load will be attempted before (and in addition to) the normal label search. If the label does not exist, no action is taken and .Nm proceeds to the normal load using the current label. .It RAD_FRAMED_ROUTE The received string is expected to be in the format .Ar dest Ns Op / Ns Ar bits .Ar gw .Op Ar metrics . Any specified metrics are ignored. .Dv MYADDR and .Dv HISADDR are understood as valid values for .Ar dest and .Ar gw , .Dq default can be used for .Ar dest to specify the default route, and .Dq 0.0.0.0 is understood to be the same as .Dq default for .Ar dest and .Dv HISADDR for .Ar gw . .Pp For example, a returned value of .Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400 would result in a routing table entry to the 1.2.3.0/24 network via .Dv HISADDR and a returned value of .Dq 0.0.0.0 0.0.0.0 or .Dq default HISADDR would result in a default route to .Dv HISADDR . .Pp All RADIUS routes are applied after any sticky routes are applied, making RADIUS routes override configured routes. This also applies for RADIUS routes that do not {include} the .Dv MYADDR or .Dv HISADDR keywords. .It RAD_FRAMED_IPV6_PREFIX If this attribute is supplied, the value is substituted for IPV6PREFIX in a command. You may pass it to an upper layer protocol such as DHCPv6 for delegating an IPv6 prefix to a peer. .It RAD_FRAMED_IPV6_ROUTE The received string is expected to be in the format .Ar dest Ns Op / Ns Ar bits .Ar gw .Op Ar metrics . Any specified metrics are ignored. .Dv MYADDR6 and .Dv HISADDR6 are understood as valid values for .Ar dest and .Ar gw , .Dq default can be used for .Ar dest to specify the default route, and .Dq :: is understood to be the same as .Dq default for .Ar dest and .Dv HISADDR6 for .Ar gw . .Pp For example, a returned value of .Dq 3ffe:505:abcd::/48 :: would result in a routing table entry to the 3ffe:505:abcd::/48 network via .Dv HISADDR6 and a returned value of .Dq :: :: or .Dq default HISADDR6 would result in a default route to .Dv HISADDR6 . .Pp All RADIUS IPv6 routes are applied after any sticky routes are applied, making RADIUS IPv6 routes override configured routes. This also applies for RADIUS IPv6 routes that do not {include} the .Dv MYADDR6 or .Dv HISADDR6 keywords. .It RAD_SESSION_TIMEOUT If supplied, the client connection is closed after the given number of seconds. .It RAD_REPLY_MESSAGE If supplied, this message is passed back to the peer as the authentication SUCCESS text. .It RAD_MICROSOFT_MS_CHAP_ERROR If this .Dv RAD_VENDOR_MICROSOFT vendor specific attribute is supplied, it is passed back to the peer as the authentication FAILURE text. .It RAD_MICROSOFT_MS_CHAP2_SUCCESS If this .Dv RAD_VENDOR_MICROSOFT vendor specific attribute is supplied and if MS-CHAPv2 authentication is being used, it is passed back to the peer as the authentication SUCCESS text. .It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY If this .Dv RAD_VENDOR_MICROSOFT vendor specific attribute is supplied and has a value of 2 (Required), .Nm will insist that MPPE encryption is used (even if no .Dq set mppe configuration command has been given with arguments). If it is supplied with a value of 1 (Allowed), encryption is made optional (despite any .Dq set mppe configuration commands with arguments). .It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES If this .Dv RAD_VENDOR_MICROSOFT vendor specific attribute is supplied, bits 1 and 2 are examined. If either or both are set, 40 bit and/or 128 bit (respectively) encryption options are set, overriding any given first argument to the .Dq set mppe command. Note, it is not currently possible for the RADIUS server to specify 56 bit encryption. .It RAD_MICROSOFT_MS_MPPE_RECV_KEY If this .Dv RAD_VENDOR_MICROSOFT vendor specific attribute is supplied, it is value is used as the master key for decryption of incoming data. When clients are authenticated using MSCHAPv2, the RADIUS server MUST provide this attribute if inbound MPPE is to function. .It RAD_MICROSOFT_MS_MPPE_SEND_KEY If this .Dv RAD_VENDOR_MICROSOFT vendor specific attribute is supplied, it is value is used as the master key for encryption of outgoing data. When clients are authenticated using MSCHAPv2, the RADIUS server MUST provide this attribute if outbound MPPE is to function. .El .Pp Values received from the RADIUS server may be viewed using .Dq show bundle . .It set rad_alive Ar timeout When RADIUS is configured, setting .Dq rad_alive to a non-zero .Ar timeout value will tell .Nm to sent RADIUS accounting information to the RADIUS server every .Ar timeout seconds. .It set rad_port_id Ar option When RADIUS is configured, setting the .Dq rad_port_id value specifies what should be sent to the RADIUS server as NAS-Port-Id. The .Ar option Ns No s are as follows: .Bl -tag -width Ds .It pid PID of the corresponding tunnel. .It tunnum .Xr tun 4 interface number. .It ifnum index of the interface as returned by .Xr if_nametoindex 3 . .It default keeps the default behavior. .El .It set reconnect Ar timeout ntries Should the line drop unexpectedly (due to loss of CD or LQR failure), a connection will be re-established after the given .Ar timeout . The line will be re-connected at most .Ar ntries times. .Ar Ntries defaults to zero. A value of .Ar random for .Ar timeout will result in a variable pause, somewhere between 1 and 30 seconds. .It set recvpipe Op Ar value This sets the routing table RECVPIPE value. The optimum value is just over twice the MTU value. If .Ar value is unspecified or zero, the default kernel controlled value is used. .It set redial Ar secs Ns Xo .Oo + Ns Ar inc Ns .Oo - Ns Ar max Ns Oc Oc Ns .Op . Ns Ar next .Op Ar attempts .Xc .Nm can be instructed to attempt to redial .Ar attempts times. If more than one phone number is specified (see .Dq set phone above), a pause of .Ar next is taken before dialing each number. A pause of .Ar secs is taken before starting at the first number again. A literal value of .Dq Li random may be used here in place of .Ar secs and .Ar next , causing a random delay of between 1 and 30 seconds. .Pp If .Ar inc is specified, its value is added onto .Ar secs each time .Nm tries a new number. .Ar secs will only be incremented at most .Ar max times. .Ar max defaults to 10. .Pp Note, the .Ar secs delay will be effective, even after .Ar attempts has been exceeded, so an immediate manual dial may appear to have done nothing. If an immediate dial is required, a .Dq !\& should immediately follow the .Dq open keyword. See the .Dq open description above for further details. .It set sendpipe Op Ar value This sets the routing table SENDPIPE value. The optimum value is just over twice the MTU value. If .Ar value is unspecified or zero, the default kernel controlled value is used. .It "set server|socket" Ar TcpPort Ns No \&| Ns Xo .Ar LocalName Ns No |none|open|closed .Op password Op Ar mask .Xc This command tells .Nm to listen on the given socket or .Sq diagnostic port for incoming command connections. .Pp The word .Dq none instructs .Nm to close any existing socket and clear the socket configuration. The word .Dq open instructs .Nm to attempt to re-open the port. The word .Dq closed instructs .Nm to close the open port. .Pp If you wish to specify a local domain socket, .Ar LocalName must be specified as an absolute file name, otherwise it is assumed to be the name or number of a TCP port. You may specify the octal umask to be used with a local domain socket. Refer to .Xr umask 2 for umask details. Refer to .Xr services 5 for details of how to translate TCP port names. .Pp You must also specify the password that must be entered by the client (using the .Dq passwd variable above) when connecting to this socket. If the password is specified as an empty string, no password is required for connecting clients. .Pp When specifying a local domain socket, the first .Dq %d sequence found in the socket name will be replaced with the current interface unit number. This is useful when you wish to use the same profile for more than one connection. .Pp In a similar manner TCP sockets may be prefixed with the .Dq + character, in which case the current interface unit number is added to the port number. .Pp When using .Nm with a server socket, the .Xr pppctl 8 command is the preferred mechanism of communications. Currently, .Xr telnet 1 can also be used, but link encryption may be implemented in the future, so .Xr telnet 1 should be avoided. .Pp Note; .Dv SIGUSR1 and .Dv SIGUSR2 interact with the diagnostic socket. .It set speed Ar value This sets the speed of the serial device. If speed is specified as .Dq sync , .Nm treats the device as a synchronous device. .Pp Certain device types will know whether they should be specified as synchronous or asynchronous. These devices will override incorrect settings and log a warning to this effect. .It set stopped Op Ar LCPseconds Op Ar CCPseconds If this option is set, .Nm will time out after the given FSM (Finite State Machine) has been in the stopped state for the given number of .Dq seconds . This option may be useful if the peer sends a terminate request, but never actually closes the connection despite our sending a terminate acknowledgement. This is also useful if you wish to .Dq set openmode passive and time out if the peer does not send a Configure Request within the given time. Use .Dq set log +lcp +ccp to make .Nm log the appropriate state transitions. .Pp The default value is zero, where .Nm does not time out in the stopped state. .Pp This value should not be set to less than the openmode delay (see .Dq set openmode above). .It set timeout Ar idleseconds Op Ar mintimeout This command allows the setting of the idle timer. Refer to the section titled .Sx SETTING THE IDLE TIMER for further details. .Pp If .Ar mintimeout is specified, .Nm will never idle out before the link has been up for at least that number of seconds. .It set urgent Xo .Op tcp|udp|none .Oo Op +|- Ns .Ar port .Oc No ... .Xc This command controls the ports that .Nm prioritizes when transmitting data. The default priority TCP ports are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell), 543 (klogin) and 544 (kshell). There are no priority UDP ports by default. See .Xr services 5 for details. .Pp If neither .Dq tcp or .Dq udp are specified, .Dq tcp is assumed. .Pp If no .Ar port Ns No s are given, the priority port lists are cleared (although if .Dq tcp or .Dq udp is specified, only that list is cleared). If the first .Ar port argument is prefixed with a plus .Pq Dq \&+ or a minus .Pq Dq \&- , the current list is adjusted, otherwise the list is reassigned. .Ar port Ns No s prefixed with a plus or not prefixed at all are added to the list and .Ar port Ns No s prefixed with a minus are removed from the list. .Pp If .Dq none is specified, all priority port lists are disabled and even .Dv IPTOS_LOWDELAY packets are not prioritised. .It set urgent length Ar length This command tells ppp to prioritize small packets up to .Ar length bytes. If .Ar length is not specified, or 0, this feature is disabled. .It set vj slotcomp on|off This command tells .Nm whether it should attempt to negotiate VJ slot compression. By default, slot compression is turned .Ar on . .It set vj slots Ar nslots This command sets the initial number of slots that .Nm will try to negotiate with the peer when VJ compression is enabled (see the .Sq enable command above). It defaults to a value of 16. .Ar Nslots must be between .Ar 4 and .Ar 16 inclusive. .El .It shell|! Op Ar command If .Ar command is not specified a shell is invoked according to the .Dv SHELL environment variable. Otherwise, the given .Ar command is executed. Word replacement is done in the same way as for the .Dq !bg command as described above. .Pp Use of the !\& character requires a following space as with any of the other commands. You should note that this command is executed in the foreground; .Nm will not continue running until this process has exited. Use the .Dv bg command if you wish processing to happen in the background. .It show Ar var This command allows the user to examine the following: .Bl -tag -width 2n .It show bundle Show the current bundle settings. .It show ccp Show the current CCP compression statistics. .It show compress Show the current VJ compression statistics. .It show escape Show the current escape characters. .It show filter Op Ar name List the current rules for the given filter. If .Ar name is not specified, all filters are shown. .It show hdlc Show the current HDLC statistics. .It show help|? Give a summary of available show commands. .It show iface Show the current interface information (the same as .Dq iface show ) . .It show ipcp Show the current IPCP statistics. .It show layers Show the protocol layers currently in use. .It show lcp Show the current LCP statistics. .It show Oo data Oc Ns Xo .No link .Xc Show high level link information. .It show links Show a list of available logical links. .It show log Show the current log values. .It show mem Show current memory statistics. .It show ncp Show the current NCP statistics. .It show physical Show low level link information. .It show mp Show Multi-link information. .It show proto Show current protocol totals. .It show route Show the current routing tables. .It show stopped Show the current stopped timeouts. .It show timer Show the active alarm timers. .It show version Show the current version number of .Nm . .El .It term Go into terminal mode. Characters typed at the keyboard are sent to the device. Characters read from the device are displayed on the screen. When a remote .Em PPP peer is detected, .Nm automatically enables Packet Mode and goes back into command mode. .El .Sh MORE DETAILS .Bl -bullet .It Read the example configuration files. They are a good source of information. .It Use .Dq help , .Dq nat \&? , .Dq enable \&? , .Dq set ?\& and .Dq show ?\& to get online information about what is available. .It The following URL contains useful information: .Bl -bullet -compact .It https://docs.freebsd.org/en/books/handbook/ppp-and-slip/ .El .El .Sh FILES .Nm refers to four files: .Pa ppp.conf , .Pa ppp.linkup , .Pa ppp.linkdown and .Pa ppp.secret . These files are placed in the .Pa /etc/ppp directory. .Bl -tag -width 2n .It Pa /etc/ppp/ppp.conf System default configuration file. .It Pa /etc/ppp/ppp.secret An authorisation file for each system. .It Pa /etc/ppp/ppp.linkup A file to check when .Nm establishes a network level connection. .It Pa /etc/ppp/ppp.linkdown A file to check when .Nm closes a network level connection. .It Pa /var/log/ppp.log Logging and debugging information file. Note, this name is specified in .Pa /etc/syslog.conf . See .Xr syslog.conf 5 for further details. .It Pa /var/spool/lock/LCK..* tty port locking file. Refer to .Xr uucplock 3 for further details. .It Pa /var/run/tunN.pid The process id (pid) of the .Nm program connected to the tunN device, where .Sq N is the number of the device. .It Pa /var/run/ttyXX.if The tun interface used by this port. Again, this file is only created in .Fl background , .Fl auto and .Fl ddial modes. .It Pa /etc/services Get port number if port number is using service name. .It Pa /var/run/ppp-authname-class-value In multi-link mode, local domain sockets are created using the peer authentication name .Pq Sq authname , the peer endpoint discriminator class .Pq Sq class and the peer endpoint discriminator value .Pq Sq value . As the endpoint discriminator value may be a binary value, it is turned to HEX to determine the actual file name. .Pp This socket is used to pass links between different instances of .Nm . .El .Sh SEE ALSO .Xr at 1 , .Xr ftp 1 , .Xr gzip 1 , .Xr hostname 1 , .Xr login 1 , .Xr tcpdump 1 , .Xr telnet 1 , .Xr kldload 2 , .Xr pipe 2 , .Xr socketpair 2 , .Xr libalias 3 , .Xr libradius 3 , .Xr syslog 3 , .Xr uucplock 3 , .Xr netgraph 4 , .Xr ng_pppoe 4 , .Xr crontab 5 , .Xr group 5 , .Xr passwd 5 , .Xr protocols 5 , .Xr radius.conf 5 , .Xr resolv.conf 5 , .Xr syslog.conf 5 , .Xr adduser 8 , .Xr chat 8 , .Xr getty 8 , .Xr inetd 8 , .Xr init 8 , .Xr ping 8 , .Xr pppctl 8 , .Xr pppoed 8 , .Xr route 8 , .Xr sshd 8 , .Xr syslogd 8 , .Xr traceroute 8 , .Xr vipw 8 .Sh HISTORY This program was originally written by .An Toshiharu OHNO Aq Mt tony-o@iij.ad.jp , and was submitted to .Fx 2.0.5 by .An Atsushi Murai Aq Mt amurai@spec.co.jp . .Pp It was substantially modified during 1997 by .An Brian Somers Aq Mt brian@Awfulhak.org , and was ported to .Ox in November that year (just after the 2.2 release). .Pp Most of the code was rewritten by .An Brian Somers in early 1998 when multi-link ppp support was added.