ppphosts(SFF)

ppphosts -- point-to-point link endpoint configuration file

Format

Automatic dialup (outgoing):
local_addr:remote_addr [ uucp=name ] [ parameter ... ]

Manual dialup (outgoing):
local_addr:remote_addr attach=name [ uucp=system ] [ parameter ... ]

Remote access (incoming):
name [ remote=remote_addr [ local=local_addr ] ] [ parameter ... ]

Dedicated serial (incoming or outgoing):
local_addr:remote_addr staticdev=device [ speed=number ] [ parameters ... ]

Description

The /etc/ppphosts file contains the information about PPP endpoints that the PPP daemon (see pppd(ADMN)) requires to configure PPP links. There are four types of PPP link endpoint: automatic dialup (outgoing), manual dialup (outgoing), remote access (incoming), and dedicated serial (incoming or outgoing). The configuration data required depends on the type of endpoint.

The data items in each entry should be separated by a space or a single tab. A ``#'' indicates the beginning of a comment; subsequent characters in an entry are ignored. An entry can be extended over more than one line by making a ``\'' the last character of all lines of the entry but the last line. An entry can contain up to 2048 characters.

Parameters not shown in the ``Format'' section are optional for all entries, have default values or status, and can be omitted if the default value is acceptable.

For an automatic or manual dialup endpoint, remote_addr:local_addr can be host names or IP addresses. If a hostname is specified, it must be resolvable to an IP address without using the PPP link being built with the entry.

For a remote access endpoint, name must be a valid login name. It is prepended with ``''.

The following sets of parameters are provided:

Authentication parameters

auth=prot: Perform link authentication. If prot is set to pap, require the peer to use PAP authentication. If prot is set to chap, require the peer to use CHAP authentication. If prot is set to mschap, require the peer to use MSCHAP authentication. By default, no authentication is performed.
authtmout=timeout: Set the time that PPP waits for the peer to authenticate itself to timeout minutes. The default value is 1 minute.
name=hostid: Use the entry whose ``name'' field value is hostid when looking up a local host ID in /etc/pppauth during PAP or CHAP negotiation, If no host ID is specified, the /etc/pppauth entry that begins with ``'' is used.

Communication parameters

attach=name: Defines a name that can be used with the pppattach command to initiate establishment of a link. This parameter is valid only for manual dialup endpoints. It must appear on the same line as the remote_addr:local_addr details.
bypassframing: Disable on-card framing for an individual link and use in-kernel framing instead. By default, the PPP driver will try to configure on-card framing.
debug=num: Set the amount of debugging information about this link that is logged to syslog(SLIB). If num is 0 (default), no information is logged. If num is 1, information on the following is logged: Link Control Protocol, IP Network Control Protocol, and PAP and CHAP negotiation. If num is 2, PPP negotiation information and all PPP packets are logged in hexadecimal format.
filter=tag: Use the packet filter from /etc/pppfilter identified by tag if packet filtering is required on a link. See packetfilter(SFF).
flow=control: Select the type of flow control to use on a link. If control is set to rtscts, use hardware flow control. If control is set to xonxoff, use software flow control. No flow control is used by default.
old: Remote side uses SCO TCP/IP Release 1.2.0. By default, it is assumed that the remote side does not use SCO TCP/IP Release 1.2.0.
proxy: Have the PPP daemon insert a proxy ARP entry for this link's local and remote IP addresses into the local host's ARP table. The default is not to insert a proxy ARP entry.
speed=number: Set the serial line speed to number bits-per-second (bps). This parameter is valid for dedicated serial links only. Allowed values for number are: 50, 75, 110, 134, 150, 200, 300, 600, 1200, 2400, 4800, 9600 (default), 19200, 38400, 57600, 76800, 115200, 230400, 460800, and 921600.
staticdev=device: Configure the endpoint for a dedicated serial link to use the device named device. This parameter is required for dedicated serial links. It must appear on the same line as the remote_addr:local_addr details.
uucp=system: Use UUCP to connect to the remote host identified by a system name corresponding to an entry in the /usr/lib/uucp/Systems file. This parameter is valid for links from automatic and manual dialup endpoints only. The system name is set to the value of remote_addr if a uucp is not specified.

IP parameters

dns=addr [ dns=addr ]

Enable the PPP service to provide Domain Name Service (DNS) server addresses to clients. Addresses are provided only for incoming links and only if the client requests. addr must be an IP address, and can be specified for primary and secondary servers. If only one address is specified, it serves as both primary and secondary server.

forcefarip

If a remote IP address is configured, several attempts are made to negotiate this address. If these fail, IPCP negotiation will fail and the link will be torn down. If no remote address is configured, this parameter has no effect and the remote host can provide the remote IP address.

This option provides the remote IP address negotiation behavior that was used in previous releases.

forcenearip

If a local IP address is configured, several attempts are made to negotiate this address. If these fail, IPCP negotiation will fail and the link will be torn down. If no local address is configured, this parameter has no effect and the remote host can provide the local IP address.

This option provides the remote IP address negotiation behavior that was used in previous releases.

getdns

Request that the remote host provide addresses for DNS servers. This parameter is valid only for clients.

getfarip

Request that the remote host provide the remote IP address, overriding any locally configured value. If, after two requests, the remote will not provide a remote IP address, an existing locally configured remote address will be negotiated.

getnearip

Request that the remote host provide the local IP address, overriding any locally configured value. If, after two requests, the remote will not provide a local IP address, an existing locally configured local address will be negotiated.

mask=netmask

Set the subnet mask of the interface to netmask. If not specified, the default value is ``255.255.255.0''.

maxslot=slot

Set the number of Van Jacobson header compression slots. The value of slot must be from 3 to 16. The default value is 16.

noipaddr

Do not initiate IP address negotiation with the remote host. IP address negotiation can still occur if the remote host initiates it.

If this parameter is specified for an endpoint for remote access, the remote=remote_addr and local=local_addr parameters must also be specified.

By default, RFC 1332 IP address negotiation is initiated unless the rfc1172addr parameter is specified.

noslotcomp

Disable compression of slot IDs for Van Jacobson TCP/IP header compression. The default is to use VJ header compression.

novj

Do not initiate VJ TCP/IP header compression negotiation. By default, VJ TCP/IP header compression negotiation is initiated.

providefarip

Use IPCP negotiation with the remote host to request that it uses the configured remote IP address. If the remote host refuses this request or if no remote address is configured, the remote host can provide a remote address. If neither end of the link can provide the remote address, IPCP negotiation will fail and the link will be torn down.

providefarip is the default behavior for negotiating a remote IP address. If more than one of the parameters forcefarip, getfarip, or providefarip is specified, this will be interpreted as specifying providefarip.

providenearip

Use IPCP negotiation with the remote host to request that it uses the configured local IP address. If the remote host refuses this request or if no local address is configured, the remote host can provide a local address. If neither end of the link can provide the local address, IPCP negotiation will fail and the link will be torn down.

providenearip is the default behavior for negotiating a local IP address. If more than one of the parameters forcenearip, getnearip, or providenearip is specified, this will be interpreted as specifying providenearip.

remote=remote_addr [ local=local_addr ]

These parameters are used for specifying endpoints for remote access only. Use them in either of the following two ways:

Specify a remote host address as remote_addr and a local host address as local_addr. remote_addr and local_addr can be host names or IP addresses. Host names must be resolvable without the use of the PPP link being built with this entry. If either or both of these parameters are missing from such a specification, do not include the noipaddr parameter in the link configuration.
Specify +tag as the argument remote_addr to remote. tag identifies an address pool (a group of IP addresses) defined in /etc/ppppool (see ppppool(SFF)) from which pppd will try to obtain a pair of local and remote IP addresses to assign to a link. The parameter local can be omitted.

rfc1172addr

Use RFC 1172 IP address negotiation.

By default, RFC 1332 IP address negotiation is initiated provided that the noipaddr parameter is not specified.

wins=addr [ wins=addr ]

Enable the PPP service to provide Windows Internet Naming Service (WINS) server addresses. Addresses are provided only for incoming links and only if the client requests. addr must be an IP address, and can be specified for primary and secondary servers. If only one address is specified, it serves as both primary and secondary server.

Link parameters

accm=num

Set the asynchronous control character map (accm) to num, which must be a hexadecimal number. The default value is 0. The value of num is the initial accm value used by the local system during PPP negotiation. It can be negotiated to a different value.

mru=num

Set the maximum receive units to num. The default value is 1500 bytes.

noaccomp

Do not initiate address-control field compression negotiation. By default, address-control field compression negotiation is initiated.

nomgc

Do not initiate magic number negotiation By default, magic number negotiation is initiated.

noprotcomp

Do not initiate protocol field compression negotiation. By default, protocol field compression negotiation is initiated.

sh_hook=[program]

Invoke program to change an interface's static route if its IP address changes when it is brought up or deleted. This parameter is used for automatic dialup only.

By default, if sh_hook is not specified, pppd invokes the program /etc/ppphook.sh with these arguments:

event interface old_src old_dest new_src new_dest \
[ primary_dns secondary_dns ]

event is one of add, delete, down, or up. interface is the name of the interface; this argument is empty if the interface is deleted. old_src and old_dest are the old source and destination IP addresses. new_src and new_dest are the new source and destination IP addresses. If DNS addresses have been negotiated, primary_dns and secondary_dns are added to the list of arguments.

If the sh_hook parameter is present but no program argument is specified, this prevents any program being invoked.

Timer parameters

conf=num: Set the maximum number of PPP configure-request retries. The default value is 5.
idle=idle_time: Set the maximum link inactivity duration before automatic link shutdown to idle_time in minutes. The default value is ``forever''.
nak=num: Set the maximum number of PPP configure-nak retries to num. The default value is 10.
reqtmout=timeout: Set the amount of time to wait for a response to sent PPP configure-request and termination-request packets before resending to timeout in seconds. The default value is 3 seconds.
retry=num: set the UUCP retry number to num. This parameter is valid only for automatic and manual dialup. The default value is 2.
term=num: Set the maximum number of PPP termination-request retries to num. The default value is 2.

Signaling changes to /etc/ppphosts

Most of the values in the /etc/ppphosts file are used by pppd when it brings up a link. These parameters can be changed at any time and will take effect the next time the link, whose entry has been changed, is brought up. For the following changes to take effect, however, you must send a SIGHUP signal to the pppd process listed in /etc/pppd.pid:

add an entry for an automatic dialup, manual dialup, or dedicated serial endpoint
delete an entry for an automatic dialup, manual dialup, or dedicated serial endpoint
change any of the following parameters for a dedicated serial endpoint: remote_addr:local_addr, staticdev, speed, flow, filter, mask
change any of the following parameters for an automatic or manual dialup endpoint: remote_addr:local_addr, filter, mask
change the packet filter specification file, /etc/pppfilter

When it receives the SIGHUP, pppd rereads the /etc/ppphosts file and tears down and rebuilds the links for dedicated serial, or outgoing dialup entries that have changed since the last time it read the file.

Examples

Typical entry for an automatic dialup endpoint:

   ice_d:local_ppp uucp=ice idle=5 reqtmout=3 conf=10 term=2 nak=10\
            mru=296 accm=0 auth=chap rfc1172addr

Typical entry for a manual dialup endpoint:

   0.0.0.0:0.0.0.0 uucp=ice attach=internet idle=5 reqtmout=3 conf=10\
            term=2 nak=10 mru=296 accm=0 auth=chap rfc1172addr

Example entry for a manual dialup endpoint using a dynamic CHAP entry in /etc/pppauth:

   0.0.0.0:0.0.0.0 uucp=myisp name=MyCHAPname

In this example, there must be a wildcard entry (*) in /etc/pppauth that includes the CHAP secret corresponding to the CHAP name.

Typical entries for a remote access endpoint:

   *nppp idle=1 reqtmout=3 conf=10 term=2 nak=10 noprotcomp\
           noaccomp novj
   
   *n2ppp idle=1 reqtmout=3 conf=10 term=2 nak=10 mru=296 noipaddr\
           local=128.212.33.90 remote=avogadro

Typical entry for a dedicated serial endpoint:

   ice_s:128.212.33.90 staticdev=tty4a term=2 nak=10 mru=296\
           accm=0

UUCP file configuration

Because links from automatic and manual dialup endpoints are made using UUCP, they require shared information in /etc/ppphosts, /usr/lib/uucp/Systems, and /usr/lib/uucp/Devices. They may also require entries in /etc/hosts if this file is used to resolve host names to IP addresses.

Consider the following file entries for an automatic dialup endpoint that uses locally defined remote and local IP addresses:

In /etc/ppphosts:: ice_d:local_ppp uucp=ice idle=5
In /etc/hosts:: 128.2.129.5 ice_d
128.2.130.7 local_ppp
In /usr/lib/uucp/Systems:: ice Any ACU 9600 555-1234 "" \r ogin:--ogin: nppp word: clydenw
In /usr/lib/uucp/Devices:: ACU tty1A - 9600 dialTBIT \T
ACU tty1B - 9600 dialTBIT \T

In this example, the names of the remote host, ``ice_d'', and the local host, ``local_ppp'', in /etc/ppphosts have corresponding entries in the /etc/hosts file so that the names can be resolved to IP addresses.

The uucp name in /etc/ppphosts, ``ice'', has a corresponding entry in /usr/lib/uucp/Systems so that the device type, ``ACU'', and UUCP connection data can be located.

There must be at least one suitable device listed in /usr/lib/uucp/Devices that can be used to obtain a connection to the remote site listed in the Systems file. In this example, two suitable modems are available on ports /dev/tty1A and /dev/tty1B.

Limitations

The network administrator must ensure consistent entries in the /etc/ppphosts, /etc/hosts, /usr/lib/uucp/Systems, and /usr/lib/uucp/Devices files for the PPP hosts.

If the remotely assigned IP address for a local PPP interface is changed by the remote host, TCP/IP applications such as telnet which cause a PPP link to be brought up will use an incorrect source IP address in the header of outgoing IP datagrams. This will cause the applications to time out when the link is brought up. The next attempt to connect to the remote host should succeed because IPCP negotiation will have adjusted the source address of the interface by this time.

A sh_hook script such as /etc/ppphook.sh should not block because pppd waits for the script to complete before processing additional events.

If the inactivity timeout period is set to 1 minute (as controlled by the value of the idle parameter) a PPP link will shut down even though the link is active with network traffic. Setting the value of idle to 2 minutes overcomes this problem.

Files

/etc/hosts: static host name to IP address translation
/etc/ppphosts: PPP link definitions
/usr/lib/uucp/Systems: remote systems accessible using UUCP
/usr/lib/uucp/Devices: devices that can be used to access remote systems
/etc/pppfilter: packet filter definitions
/etc/pppauth: authentication information
/etc/ppppool: pairs of local and remote IP addresses that can be allocated automatically
/etc/pppstack: definitions of third-party PPP stacks for use with smart serial port devices