ppptalk(1M)


ppptalk -- administrative interface to the PPP subsystem

Synopsis

ppptalk [ command arg... ]

pppd [ -l logfile ] [ -a ] [ -d ]

Description

ppptalk is the administration interface to the PPP subsystem including control of the operation of the PPP daemon, pppd. ppptalk reads the PPP configuration file to initialize PPP, and communicates with the PPP daemon to build the PPP stack, negotiate control protocols, implement bandwidth allocation, and place calls.


NOTE: Do not edit the PPP configuration file directly. To modify the configuration of PPP, use ppptalk or the PPP Manager.

ppptalk allows you to manage all aspects of the PPP configuration from the command line, or, by redirecting the standard input, to read commands from a file. You can use ppptalk interactively to alter the status of links, bring links up and down, and so on.

See ``ppptalk commands'' for a description of ppptalk's internal commands. See ``PPP configuration definitions'' for the syntax of PPP configuration definitions.

ppptalk commands

ppptalk understands the following commands which can be entered interactively, or can be specified as command-line arguments, or can be present in the configuration file:

! [command]
Run a shell command. The default command is a shell (sh).

attach bundle_tag
Initiate the bringing up of an outgoing connection over the specified bundle. This command may complete before the bundle is ready to accept network layer traffic but not before the attempt to physically connect has either succeeded or failed.

auth tag {

parameter=value

...

}
Define an auth database entry identified by tag (see ``Authentication definitions'').

auth tag parameter=value
Assign value to parameter within the auth definition specified by tag (see ``Authentication definitions'').

bundle tag {

parameter=value

...

}
Define a bundle identified by tag (see ``Bundle definitions'').

bundle tag parameter=value
Assign value to parameter within the bundle definition specified by tag (see ``Bundle definitions''). Enter the command reset bundle tag to have the change take effect.

calls [num]
Display a call history with most recent events shown first. The level of detail displayed depends on the current verbosity (see the description of the verbose command). The history can store up to 20 entries. Once this limit is reached, the oldest entries are discarded as new ones are added.

The optional num parameter specifies the maximum number of history entries to be displayed. If omitted, the default is 2 for low verbosity, and 15 for high verbosity.


clear
Delete the contents of the call history.

debug debug_level bundle | link tag [ protocol_tag ]
Set the debugging level on a bundle or a link specified by tag, or on a protocol specified by protocol_tag associated with a link specified by tag. Available debugging levels are:

none
Turn off debugging.

low
Generate a small amount of output debugging information including negotiated values.

med
Generate an intermediate amount of debugging information.

high
Display all packets and their contents.

wire
Display packets as they are passed from one layer in the protocol stack to another.
Debugging output is sent to the PPP log file. By default, this is /var/adm/log/ppp.log and may be changed using the -l logfile option to pppd.

defprompt string
Change the ppptalk command prompt within definitions to string.

del auth | bundle | link | protocol | algorithm | global tag
Remove the specified configuration definition. If the tag refers to an active link or bundle that has an established connection, the connection is dropped and the definition is removed. If the link or bundle is not active, it must be reset for the change to take effect.

detach bundle_tag
Initiate the closing of any connected links associated with a bundle. This will also destroy the interfaces for a manual dial-up link.

emacs
Select emacs-style command line editing and history as in ksh(1). ppptalk enables this mode on startup if the environment variable EDITOR is defined to be emacs.

global bundle {

parameter=value

...

}
Redefine the global bundle (see ``Global bundle definitions'').

global bundle parameter=value
Assign value to parameter within the global bundle definition (see ``Global bundle definitions'').

help
Display a list of available commands and definition keywords.

help algorithm name
Display available options for an algorithm.

help auth | bundle | link
Display available options for auth, bundle, or link definitions.

help command
Display further information about a command.

help protocol name
Display available options for a protocol such as ip.

link tag {

parameter=value

...

}
Define a link identified by tag (see ``Link device definitions'').

link tag parameter=value
Assign value to parameter within the link definition specified by tag (see ``Link device definitions''). Enter the command reset link tag to have the change take effect.

linkadd bundle_tag [ link_tag ]
Add a link to an existing multilink bundle. The link to be added will become the first available link in the bundle. If no link tag is specified, the first available link in the bundle definition will be used. This establishes an outgoing connection.

linkdrop bundle_tag [ link_tag ]
Drop the specified link from a multilink bundle. If no link is specified, drop the link with the lowest relative bandwidth. If dropping a link would cause the total number of links to fall below the value of minlinks defined for the bundle and no link was specified, an error is output rather than a link being dropped.

list auth | bundle | link | protocol | algorithm | global [ tag ]
Display the definition of tag of the specified type. If tag is not specified, list all configured definitions of the specified type.

list global bundle
Display the definition of the global bundle.

prompt string
Change the ppptalk command prompt to string. The default prompt is ppp >.

protocol tag {

parameter=value

...

}
Define a protocol identified by tag (see ``Protocol definitions'').

protocol tag parameter=value
Assign value to parameter within the protocol definition specified by tag (see ``Protocol definitions''). You must reset any bundles or links that use the protocol definition for the change take effect.

quit
Exit the ppptalk session. Alternatively, you can enter <Ctrl>D if this is defined as the end-of-file character.


NOTE: The state of PPP is held in the daemon rather than in ppptalk, so you must issue an explicit save to write its configuration information to a file.


reset bundle | link [ tag ]
Destroy any established connection on the specified bundle or link, and then update the active configuration.


NOTE: You must issue a reset on a bundle or a link after changing its configuration to have the changes take effect. This also applies when you change other definitions to which a bundle or link refers.

If the tag is omitted, all bundle or link definitions are reset.


save
Save the current configuration of the PPP daemon. If the daemon is stopped and restarted, it will load the saved configuration automatically.

stats bundle | link [ tag ]
Display statistics for an active bundle or link.

status bundle | link [ tag ]
Display the status of an active link or bundle including all active links and protocols implied by the tag. If tag is not specified, display a list of all active bundles or links.

stop
Stop the PPP daemon and exit ppptalk. This completely stops PPP and closes all open links.

verbose
Toggle between low (default) and high levels of status output.

version
Display PPP version number.

vi
Select vi-style command line editing and history as in ksh(1). ppptalk enables this mode on startup if the environment variable EDITOR is defined to be vi.
The output of all commands can be piped through an external program such as more or cat. For example, the command list bundle | more would list all bundle definitions through the more pager.

PPP configuration definitions

A single PPP incoming and/or outgoing link is defined as a ``bundle''. If a bundle is defined as using several physical ``link'' devices of the same type (modems, asynchronous ISDN channels, or synchronous ISDN channels), it can be configured to use these devices co-operatively. Such a ``multilink'' bundle uses several devices in tandem to increase the effective bandwidth of the PPP link. A multilink bundle can also be tuned so that it adds and drops devices as demand for bandwidth increases or decreases on the link. Note that multilink PPP requires that the remote host must also have this capability. The hosts at each end of the link must have compatible types of link devices, and there must be sufficient devices available at each end of the PPP link. For example, a multilink bundle that is configured to use two ISDN B channels requires that the host at each end of the link must have two such channels available and configured for use.

In addition to bundle and link (physical device) definitions, there may also be definitions for global bundle characteristics, authentication database entries (CHAP and/or PAP), Link Control Protocol (LCP), and various other protocols.

The configuration data that is required depends on the type of PPP links that are required.

Tag names can be up to 40 characters long. They must not contain control characters (ASCII values 0 through 31), tabs or spaces.

on and enabled are alternative values for true. off and disabled are alternative values for false.

The maximum line length is 1024 characters.

The following sets of characteristics may be defined:

``Finite state machine parameters'' describes parameters which control the operation of the PPP finite state machine. These parameters are common to several control protocol modules. In these sections, parameters shown in square brackets are optional for all entries.

The top layer of definition is a bundle. link definitions are attributes of a bundle. Depending on their type, protocol definitions are attributes of a bundle or of a link.

Bundle definitions

A bundle defines the top layer of PPP links. A bundle definition can define one user for an incoming PPP connection and/or one system for an outgoing PPP connection. The bundle may also reference shared sets of link device and protocol characteristics, or it can reference sets that are defined specifically for its exclusive use. Bundles may be also be defined that can establish PPP links over multiple physical links (``multilink'' PPP). The syntax of a bundle definition is shown below:

bundle bundle_tag {
protocols = protocol_tag [ protocol_tag ]...

[ authid = name [ name ]... ]
[ bringup = automatic | manual ]
[ callback = true | false ]
[ callerid = identifier [ identifier ]... ]
[ cbdelay = tenths_of_seconds ]
[ debug = none | low | med | high | wire ]
[ enabled = true | false ]
[ links = link_tag [ link_tag ]... ]
[ login = name [ name ]... ]
[ maxidle = seconds ]
[ phone = number ]
[ remotesys = Systems_entry ]
[ type = in | out | bi-directional ]

# Authentication characteristics for outgoing connections

[ authname = name ]
[ authtmout = seconds ]
[ peerauthname = peername ]
[ requirechap = true | false ]
[ requirepap = true | false ]

# Multilink-specific bundle characteristics

[ addload = percentage ]
[ addsample = seconds ]
[ bodmg = both | caller | local | peer ]
[ bodpay = both | caller | peer ]
[ dropload = percentage ]
[ dropsample = seconds ]
[ linkidle = seconds ]
[ maxfrags = number ]
[ maxlinks = number ]
[ minfrag = number ]
[ minlinks = number ]
[ nocp = true | false ]
[ nulls = true | false ]
[ thrashtime = seconds ]

# Multilink-specific bundle characteristics for outgoing connections

[ ed = true | false ]
[ mrru = bytes ]
[ ssn = true | false ]

}

The following characteristics are applicable to all bundles:


protocols = protocol_tag [ protocol_tag ]...
Defines the set of protocol definitions referenced by their tags. Protocol types allowed for a bundle are ipcp and ccp. See ``Protocol definitions''.

authid = name [ name ]...
Defines the identity of one or more permitted incoming callers to this bundle. These are compared with the name determined from a received CHAP or PAP packet. If more than one authentication ID is specified, these must be separated by spaces. The wildcard name ``*'' will match any caller provided that they have been authenticated using CHAP or PAP.

bringup = automatic | manual
Defines how the link is brought up. Possible values are:

automatic
A PPP link is established automatically when the remote system needs to be accessed by a networking application. The link remains established until it becomes idle for a certain time, or it is manually torn down using pppdetach(1M).

manual
pppattach(1M) is used to establish the PPP link to the remote system. pppdetach(1M) is used to tear down the PPP link to the remote system.
The default value is automatic.

callback = true | false
If enabled (true) and the bundle's type is bi-directional, the connection will be dropped on reception of an incoming call and an outgoing connection will be made to the remote calling system after the time specified by cbdelay.

callerid = identifier [ identifier ]...
Defines the identity of one or more permitted incoming caller(s) to this bundle. These are compared with the ID determined from the call information that is obtained from the physical layer, such as the telephone number at the remote end of the link. If more than one caller ID is specified, these must be separated by spaces.

cbdelay = tenths_of_seconds
Specifies the length of time (in tenths of a second) that will elapse before an attempt is made to call back a remote system. The default value is 300 (30 seconds). The minimum and maximum values are 1 and 32767.

debug = none | low | med | high | wire
Define a debugging level for the bundle and its protocols. Available debugging levels are:

none
Turn off debugging.

low
Generate a small amount of output debugging information including negotiated values.

med
Generate an intermediate amount of debugging information.

high
Display all packets and their contents.

wire
Display packets as they are passed from one layer in the protocol stack to another.

enabled = true | false
Enables or disables the bundle definition. The bundle definition will be disabled if set to false. The default value is true.

links = link_tag [ link_tag ]...
Defines the set of links that may be members of the bundle referenced by their tags. See ``Link device definitions''. The links defined for a bundle will be tried in the order that they are specified. For example, you could list ISDN_SYNC devices (ISDN channels in synchronous mode) before ACU devices (analog modems) if you preferred that a bundle should use ISDN lines. If the ISDN lines were unavailable, the bundle would then fall back to using analog lines.

login = name [ name ]...
Defines the user names of one or more permitted incoming caller(s) to this bundle. These are compared with the name specified to login(1) before the PPP shell is invoked (see pppsh(1M)). If more than one user is specified, these must be separated by spaces. The wildcard name ``*'' will match any caller provided that they can successfully log in.

maxidle = seconds
Defines the period in seconds for which a bundle must be inactive before its member links are closed. The minimum and default value is 0 which means timeout is disabled. The maximum value is 32768 seconds. A bundle is defined to be inactive if all network control protocols detect they are idle.

remotesys = Systems_entry
Defines the name of a remote system by reference to its entry in the Systems(4bnu) file.


NOTE: Only one remote system may be specified in a bundle.


phone = number
Specifies the telephone number to be called. If not specified, the number(s) specified for remotesys in the Systems(4bnu) file will be used.

type = in | out | bi-directional
Defines how the bundle will be used. The possible values are:

bi-directional
The bundle may be used for both incoming and outgoing connections. This is the default value.

in
The bundle may only be used for incoming connections.

out
The bundle may only be used for outgoing connections.
For incoming connections to be accepted, type must be set to in or bi-directional and at least one of authid, callerid, or login must be specified. If any of authid, callerid, and login are specified, the incoming connection must match the value of these attributes exactly for it to be accepted.

The following authentication characteristics only apply to outgoing connections:


authname = name
If specified, use name instead of the local host name in outgoing CHAP or PAP packets. It may be necessary to use this attribute in the following cases: See pppauth(7) for a basic discussion of the operation of CHAP and PAP.

authtmout = seconds
Specifies the time allowed for authentication to be performed. The default value is 60 seconds. The minimum and maximum allowed values are 5 and 300 seconds respectively.

peerauthname = peername
If specified, look up a secret or password for peername. This can be used to override the name that the remote host set in an incoming CHAP or PAP packet. It can also be used to look up a PAP password to supply to a remote authenticator instead of looking up a password for the local host name (possibly overridden by an authname in the bundle). It may be necessary to use this attribute in the following cases: See pppauth(7) for a basic discussion of the operation of CHAP and PAP.

requirechap = true | false
Specifies whether the local host authenticates the remote host using CHAP. The default value is false.

requirepap = true | false
Specifies whether the local host authenticates the remote host using PAP. The default value is false.
If requirechap and requirepap are both true, the local host may authenticate the remote host using either CHAP or PAP. If the remote host supports both, CHAP will be used.

The authentication characteristics for incoming connections are set in the global bundle.

The following characteristics only apply to multilinks (that is, the value of maxlinks is greater than 1):


addload = percentage
The load percentage above which links should be added. The default value is 60. The minimum and maximum values are 1 and 100 respectively.

addsample = seconds
The time in seconds over which the average loading value for adding links is calculated. The default value is 60 seconds. The minimum and maximum values are 2 and 4000 respectively.

bodmg = both | caller | local | peer
Configure which end of the link should manage bandwidth on demand. This value is only used if a bandwidth allocation protocol (such as BAP controlled by BACP) is available and has been negotiated.

The possible values are:


both
Allow either end to make decisions about bandwidth allocation.

caller
The initiator of the multilink connection should make decisions about bandwidth allocation. This is the default policy.

local
Only the local host should make decisions about bandwidth allocation.

peer
Allow the remote host to make decisions about bandwidth allocation.
This characteristic is used in conjunction with bodpay.

bodpay = both | caller | peer
Define which end of the link should make additional calls when extra bandwidth (more links in the bundle) is required.

The possible values are:


both
Either end of the link may make additional calls.

caller
Only the initiator of the bundle should make additional calls. This is the default value.

peer
The remote host is expected to make additional calls. The local host will not.
This characteristic is used in conjunction with bodmg.

dropload = percentage
The load percentage below which links should be dropped. The default value is 20. The minimum and maximum values are 1 and 100 respectively.

dropsample = seconds
The time in seconds over which the average loading value for dropping links is calculated. The default value is 60 seconds. The minimum and maximum values are 2 and 4000 respectively.

linkidle = seconds
Determines for how many seconds a multilink bundle can be inactive before null packet fragments will be sent on the member links. This allows the loss of packets or links to be detected. The default value is 4 seconds. The minimum and maximum values are 1 and 30 respectively. Note that null fragments will not be transmitted if nulls is set to false.

maxfrags = number
Defines the maximum number of fragments that may be queued for reassembly per active (open to traffic) link in a bundle. The default value is 5. The minimum and maximum values are 1 and 100 respectively.

maxlinks = number
Defines the maximum number of links that can be active in a multilink bundle. A number greater than 1 (the default) indicates the use of a multilink bundle. The value of number must be less than or equal to the number of links configured for the bundle. The minimum and maximum values are 1 and 1024 respectively.

minfrag = bytes
Defines the minimum fragmentation size for a link. The default value is 100 bytes. The minimum and maximum values are 50 and 4096 respectively.

minlinks = number
The minimum number of links that can remain in a bundle when bandwidth on demand has removed excess capacity. The value of number must be less than or equal to the number of links configured for the bundle. The default value is 1 link.

nocp = true | false
If set to false (the default), Control Protocol packets are encapsulated within the multilink header. Setting this parameter to true for a multilink bundle allows PPP in UnixWare® 7 to interoperate with other PPP implementations that cannot interpret encapsulated Control Protocol packets.

nulls = true | false
Controls whether null packet fragments can be transmitted on a multilink bundle (see the description of linkidle).

thrashtime = seconds
Defines the minimum time period that must expire before a link can be added to or dropped from a multilink bundle from the time that a link was last dropped from or added to that bundle respectively. The default value is 60 seconds. The minimum and maximum values are 5 and 4000 respectively.


NOTE: Multilink PPP is not supported over dedicated directly connected serial lines.

The following multilink-specific characteristics only apply to outgoing connections:


ed = true | false
Defines whether endpoint discrimination is enabled (true) or disabled (false). The default value is true. A system's endpoint discriminator identifies it to its peer when it tries to create a new multilink bundle or to add a link to an existing multilink bundle. (See RFC 1990 for more information.)

mrru = bytes
Defines the size of the Maximum Received Reconstructed Unit (the maximum size of the information fields of reassembled packets). This must be defined if multilink connections are required (see RFC 1990 for a description). The default value is 1500 bytes. The minimum and maximum values are 256 and 16384 respectively.


NOTE: To prevent fragmentation over a single link in a multilink bundle, mrru should be set to a value that is at least 6 bytes less than the maximum receive unit (mru) that is defined in the Link Control Protocol for the member links of the bundle.


ssn = true | false
Defines whether Short Sequence Numbering is enabled (true) or disabled (false) (see RFC 1990 for a description). If enabled, PPP informs the remote host that it wishes to receive fragments with short, 12-bit sequence numbers rather than 24-bit sequence numbers. The default value is false.
The ed, mrru, and ssn attributes defined in the global bundle set values to be offered on incoming connections. These options can reduce LCP negotiation times by providing a ``good'' starting point for negotiation.

Link device definitions

Link device characteristics define the configuration of a physical device that is available for establishing incoming or outgoing connections. The syntax of a link device definition is shown below:

link link_tag {
protocols = protocol_tag [ protocol_tag ]...
[ bandwidth = bits_per_second ]
[ debug = none | low | med | high | wire ]
[ dev = device ]
[ enabled = true | false ]
[ flow = hardware | software | none ]
[ phone = telephone_number ]
[ pop = module [ module]... ]
[ push = module [ module]... ]
[ type = ACU | ISDN_SYNC | ISDN_ASYNC | Direct ]
[uniquedigits = number]
}

The following characteristics may be defined for link devices:


protocols = protocol_tag [ protocol_tag ]...
Defines the set of protocol definitions referenced by their tags. Protocol types allowed for a link are ccp, and lcp. This characteristic must be defined. There is no default value. See ``Protocol definitions''.

bandwidth = bits_per_second
Defines an estimate of the available bandwidth in bits per second. The default value is obtained using the Call Services Subsystem from the Devices(4bnu) and Systems(4bnu) files. The minimum and maximum values are 0 and 32767.

debug = none | low | med | high | wire
Define a debugging level for the link and its protocols. Available debugging levels are:

none
Turn off debugging.

low
Generate a small amount of output debugging information including negotiated values.

med
Generate an intermediate amount of debugging information.

high
Display all packets and their contents.

wire
Display packets as they are passed from one layer in the protocol stack to another.

dev = device
Defines the device file associated with a link device. There is no default value.

enabled = true | false
Enables or disables the link definition. The link definition will be disabled if set to false. The default value is true.

flow = hardware | software | none
Defines the type of flow control that will be used between the data terminal equipment (DTE; a local computer) and the data circuit-terminating equipment (DCE; a modem or ISDN device), or on a dedicated serial line. Possible values are:

hardware
RTS/CTS flow control.

software
XON/XOFF flow control.

none
No flow control.


NOTE: Flow control has no effect on synchronous mode connection types such as ISDN_SYNC.


phone = telephone_number
Defines the telephone number that may be used to access this link from elsewhere. The number is passed to a remote system so that it can access the defined link. The default value is the null string.

pop = module [ module]...
Defines a list of streams modules and drivers that must be ``popped'' (see I_POP) from the device before it can be used. The modules and drivers will be removed in the order specified. The default modules for the ACU, Direct and ISDN_ASYNC link types are ttcompat and ldterm.

push = module [ module]...
Defines a list of streams modules that must be ``pushed'' (see I_PUSH) onto the device before it can be used by PPP traffic. The modules and drivers will be added in the order specified. The default module for the ACU, Direct and ISDN_ASYNC link types is asyh.

type = ACU | ISDN_SYNC | ISDN_ASYNC | Direct
Defines the type of the link device. This can be one of the following:

ACU
Public switched telephone network (PSTN or standard analog telephone lines). This is the default link type.

ISDN_SYNC
Integrated services digital network (ISDN) in synchronous mode.

ISDN_ASYNC
ISDN in V.120 asynchronous mode. This may not be supported by some ISDN adapters.

Direct
Dedicated directly connected serial line (no dialing is performed).


NOTE: Multilink PPP is not supported over dedicated directly connected serial lines.

A basic rate interface (BRI) ISDN adapter has two 64kbps B channels and one 16kbps D channel. Some ISDN modems, however, only allow a single 64kbps B channel to be used for data communication. A separate link definition is required for each channel of an ISDN device that you want to use for PPP. As all ISDN channels for an ISDN device in a given mode (synchronous or asynchronous) generally share the same device file, their link definitions will normally only differ in their tag name.


uniquedigits = string
The unique digits of the advertised phone number that identify this physical device among those sharing a common prefix number. See the description of commonprefix and uniquedigits in ``Global bundle definitions''. By default, no unique digits are configured.

Protocol definitions

Protocol definitions may be configured and assigned to specific bundle definitions. This allows specific protocol requirements to be tailored to certain groups of connections. The syntax of protocol definitions is shown below:

# Compression Control Protocol characteristics

protocol protocol_tag {
protocol = ccp
[ algorithms = algorithm_tag ... ]
[ debug = none | low | medium | high |wire ]
[ rxalgorithms = algorithm_tag ... ]
[ txalgorithms = algorithm_tag ... ]
[ finite state machine parameters ]
}

algorithm algorithm_tag {
algorithm = type
algorithm-specific characteristics
}

# Internet Protocol Control Protocol characteristics

protocol protocol_tag {
protocol = ip
[ advdns = IP_address ]
[ advdns2 = IP_address ]
[ advdnsopt = addr | local | none ]
[ bringup = filter_tag ]
[ defaultroute = true | false ]
[ debug = none | low | medium | high |wire ]
[ exec = pathname ]
[ getdns = true | false ]
[ keepup = filter_tag ]
[ localaddr = address | pool_tag ]
[ localopt = any | force | pool | prefer ]
[ logpkt = 0 | 1 | 2 ]
[ netmask = mask ]
[ passin = filter_tag ]
[ passout = filter_tag ]
[ peeraddr = address | pool_tag ]
[ peeropt = any | force | pool | prefer ]
[ proxyarp = true | false ]
[ vjcompress = true | false ]
[ vjslotcomp = true | false ]
[ vjmaxslot = number ]
[ finite state machine parameters ]
}

# Link Control Protocol characteristics

protocol protocol_tag {
protocol = lcp
[ acfc = true | false ]
[ accm = hexadecimal ]
[ debug = none | low | medium | high |wire ]
[ echofails = number ]
[ echoperiod = seconds ]
[ echosample = number ]
[ identification = true | false ]
[ magic = true | false ]
[ mru = bytes ]
[ pfc = true | false ]
[ finite state machine parameters ]
}

The debug parameter sets the debugging level for a protocol definition. Available debugging levels are:


none
Turn off debugging. This is the default.

low
Generate a small amount of output debugging information including negotiated values.

med
Generate an intermediate amount of debugging information.

high
Display all packets and their contents.

wire
Display packets as they are passed from one layer in the protocol stack to another.


NOTE: If the debugging level of the parent bundle or link definition is set to a higher level, it will override the level that is set for a protocol.

The following characteristics are specific to the Compression Control Protocol:


protocol = ccp
Identifies the Compression Control Protocol (CCP).

algorithms = algorithm_tag ...
Defines the compression algorithms that are available when sending or receiving frames.

rxalgorithms = algorithm_tag ...
Defines the compression algorithms that are available when receiving frames.

txalgorithms = algorithm_tag ...
Defines the compression algorithms that are available when sending frames.
Characteristics for available compression algorithms may be defined using the algorithm statement. The following characteristics are specific to the Internet Protocol Control Protocol:

protocol = ip
Defines the internetworking protocol to be used over the PPP link. Only the Internet Protocol (ip) is currently supported.

advdns = IP_address
The IP address of the advertised DNS name server. If the value is null or 0.0.0.0, it will not be advertised.

advdns2 = IP_address
The IP address of the advertised alternative DNS name server. If the value is null or 0.0.0.0, it will not be advertised.

advdnsopt = addr | local | none
Specifies how to obtain the IP addresses of DNS name servers that are to be advertised:

addr
The IP addresses are defined using the advdns and advdns2 configuration statements.

local
Use the IP addresses of name servers that are configured in /etc/resolv.conf.

none
Do not advertise DNS name servers. This is the default value.

bringup = filter_tag
Filter outgoing packets using the specified filter if a transport is not available. If they are passed, they will be allowed to bring up a PPP link. The default filter tag is bringup.

compression = true | false
Defines whether header compression is enabled (true) or disabled (false). The default value is true.

defaultroute = true | false
Specifies whether this interface provides the default route for IP packets. The default value is false.

exec = pathname
Defines a program (shell script or binary) that must be executed if a PPP link comes up, goes down, is added or is deleted. The program will be invoked with the following arguments:

event interface local peer oldlocal oldpeer dnsaddr dnsaddr2 default

The arguments are:


event
One of up, down, add, delete according to whether the link is being brought up, taken down, added or deleted.

interface
The name of the interface; this argument is null if the interface is deleted.

local
The new local IP address.

peer
The new remote IP address.

oldlocal
The previous local IP address.

oldpeer
The previous remote IP address.

dnsaddr
The IP address of a DNS name server.

dnsaddr2
The IP address of an alternative DNS name server.

default
This interface is the default route for IP packets if set to default; otherwise, it should be set to ``-''.
IP addresses that are passed to the exec program should be in dotted decimal notation. The program should either perform its actions quickly and not block, or put itself in the background because the PPP daemon will wait for it to exit before processing additional events.

The default program that will be executed is /usr/lib/ppp/psm/ipexec.sh. This is a shell script that updates a static route referring to either end of the PPP link when the interface changes state. The actions on the new states are:


add
If the interface is declared as the default route (defaultroute = true), add a default route to the remote address.

delete
If the interface is declared as the default route, remove this entry from the routing table.

down
No action required.

up
Rewrite static routes via the remote address as necessary.

If getdns is enabled (true), and addresses of DNS name servers are obtained, a resolv.conf(4tcp) file will be created which contains corresponding nameserver entries.


getdns = true | false
Obtain the addresses of DNS name servers, if available. The default value is true.

keepup = filter_tag
Filter outgoing packets using the specified filter if a transport is available. If they are passed, they will reset the PPP link's ``time without data'' counter to 0. If the counter reaches maxidle, the bundle may be closed depending on the number of network control protocols that are idle in the bundle. The default filter tag is keepup.

localaddr = address | pool_tag
Defines the IP address (or resolvable name) for the local end of a PPP link. If a pool_tag is specified, the value of localopt must be set to pool.

localopt = any | force | pool | prefer
Defines how the IP address of the local end of a PPP link is to be negotiated:

any
The remote end of the PPP link must specify the local IP address. This is the default behavior.

force
Only the IP address specified by localaddr may be used.

pool
Use any IP address from the Address Allocation Server pool_tag specified by localaddr.

prefer
The IP address specified by localaddr is preferred but the remote end of the PPP link may specify the local IP address.

logpkt = 0 | 1 | 2
Control logging of IP datagrams:

0
Turn off packet logging (default).

1
Decode and log TCP and UDP packets to the PPP log file (usually /var/adm/log/ppp.log).

2
Log packets that cause a bundle to dial out when bringup is set to automatic.
Logging of IP datagrams may be enabled or disabled for an individual PPP interface by specifying the dblevel parameter to ifconfig(1Mtcp).

netmask = mask
Defines the network mask in dotted-decimal notation (for example, 255.255.255.0) that will be used for the PPP interface.


NOTE: If either end of the PPP link is configured as a proxy (see proxyarp) for ARP requests on behalf of the other end of the link, configure the network mask of the PPP interface at each end of the link to be the same.

If the RIPv1 rather than the RIPv2 routing protocol is in use over the link, it may also be necessary to configure the network mask of the PPP interface at each end of the link to be the same.



passin = filter_tag
Filter incoming packets using the specified filter.

passout = filter_tag
Filter outgoing packets using the specified filter.

peeraddr = address | pool_tag
Defines the IP address (or resolvable name) for the remote end of a PPP link. If a pool_tag is specified, the value of peeropt must be set to pool.

peeropt = any | force | pool | prefer
Defines how the IP address of the remote end of a PPP link is to be negotiated:

any
The remote end of the PPP link must specify its IP address. This is the default behavior.

force
Only the IP address specified by remoteaddr may be used.

pool
Use any IP address from the Address Allocation Server pool_tag specified by peeraddr.

prefer
The IP address specified by peeraddr is preferred but the remote end of the PPP link may specify its IP address.

proxyarp = true | false
Selects whether to configure a proxy entry in the local ARP table for the remote end of the PPP link. This allows other hosts on a subnet to ``see'' a host that is connected via a PPP link and which has an address on the same subnet. The local host will respond with its own hardware MAC address when asked for that corresponding to the remote IP address. If the host is also configured as a router, it will forward packets that are destined for the remote address. By default, proxy ARP is disabled (false).

vjcompress = true | false
Defines whether Van Jacobson (VJ) header compression should be used. The default value is false.


NOTE: VJ header compression is not recommended for PPP over ISDN links.


vjslotcomp = true | false
Defines whether slot compression should be used if VJ header compression is enabled. The default value is true. This is suitable when the transport may be unreliable but the asyh driver can report lost frames. Set vjslotcomp to false if a third-party framing driver cannot report frame loss.

vjmaxslot = number
Defines the maximum number of slots available to the VJ header compression algorithm. The default value is 16. The minimum and maximum allowed values are 3 and 255.


NOTE: If you require the PPP link to be brought up on demand, you must supply IP addresses for localaddr and peeraddr even if the remote side will override these values during negotiation.

The following characteristics are specific to the Link Control Protocol:


protocol = lcp
Identifies the Link Control Protocol (LCP).

acfc = true | false
Defines whether address and control field compression is supported (true) or not (false). The default value is true.

RFC 1662 suggests that acfc should be set to true for low speed or asynchronous links. For high speed links, it should be set to false.


accm = hexadecimal
Defines the asynchronous control character map (ACCM) that will used as a starting point for negotiating the transmission and reception of ACCMs for the link. An ACCM indicates which of the ASCII control characters with values from 0 to 0x1f need to be specially handled so that they can be transmitted over the link without affecting its operation. For example, an ACCM value of 0xffffffff would map all characters in this range, while a value of 0xa0000 (bits 17 and 19 set to 1) would only remap the ASCII characters 0x11 (XON) and 0x13 (XOFF).

The default and maximum value is 0xffffffff. RFC 1662 suggests this value for links that use software flow control and for low speed links.

The minimum value is 0 (no mapping). RFC 1662 suggests this value for links that use hardware flow control to improve performance.


NOTE: The mapping does not solve the problem of receivers that cannot handle all non-control characters, or of transmitters that cannot handle 8-bit characters.


echofails = number
Defines the maximum number of failed samples that are acceptable in the number specified by echosample. The default value is 2. The minimum and maximum values are 1 and 1000.

echoperiod = seconds
Defines the time in seconds between echo requests. If this value is greater than 0, LCP echo requests will be generated to determine link quality every echoperiod seconds. If the remote host fails to respond more than echofails out of echosample, the link will be dropped. The default value is 0 seconds. The minimum and maximum values are 0 and 100.

echosample = number
Defines the number of samples that are used to determine link quality. The default value is 5. The minimum and maximum values are 1 and 100.

identification = true | false
Enables the sending of LCP messages. The default value is true.

magic = true | false
Defines whether magic number negotiation is enabled (true) or disabled (false). The default value is true. The magic numbers generated by each end of a link should be different. If they are the same, it is probable that the host is trying to create a PPP link to itself. The usual reason for this is that the UUCP chat script (see Systems(4bnu)) has failed to log in, or PPP on the remote system has failed to start correctly.

RFC 1662 suggests that magic should be set to true for all links.


mru = bytes
Defines the maximum receive unit (MRU) size for this end of the PPP link (see RFC 1661 for a description). Increasing the value of mru will generally improve performance on non-interactive sessions as it reduces the percentage of header bytes transmitted. The default value is 1500 bytes. The minimum and maximum values are 256 and 16384.


NOTE: To prevent fragmentation over a single link in a multilink bundle, mru should be set to a value that is at least 6 bytes greater than the maximum received reconstructed unit (mrru) that is configured in the bundle for outgoing connections, or in the global bundle for incoming connections.


pfc = true | false
Defines whether protocol field compression is enabled. The default value is true.

RFC 1662 suggests that pfc should be set to true for low speed or asynchronous links. For high speed links, it should be set to false.

Authentication definitions

Authentication definitions are used to construct a local authentication database. The syntax of authentication database definitions is shown below:

auth auth_tag {
name = name | peer-id
[ localsecret = secret | password ]
[ peersecret = secret | password ]
[ protocol = chap | pap ]
}

The following characteristics are specific to authentication using the Challenge-Handshake Authentication Protocol (CHAP) and the Password Authentication Protocol (PAP):


name = name | peer-id
The value assigned to name must either be a name corresponding to the ``Name'' field of a CHAP challenge or response, or it must be a peer-id corresponding to the ``Peer-ID'' field of a PAP authentication request.

localsecret = secret | password

peersecret = secret | password
localsecret defines the CHAP secret or the PAP password that a remote host (the peer) must know to authenticate itself with the local host (the authenticator).

peersecret defines the CHAP secret or the PAP password that the remote host (the authenticator) knows when the local host (the peer) authenticates with it.

The value must either be a secret that is used to compute the ``Value'' field of a CHAP response, or it must be a password corresponding to the ``Password'' field of a PAP authentication request. It must not contain any NULL characters. Non-printing characters may be specified using one of the following codes:


\ooo
where ooo is an octal number

\xhh
where hh is a hexadecimal number
A backslash should be entered as \\.

protocol = chap | pap
Selects whether the name-secret pair will be used for CHAP or PAP authentication.


NOTE: RFC 1334 advises that CHAP secrets and PAP passwords be different for the same name.

See pppauth(7) for a basic discussion of the operation of CHAP and PAP.

Global bundle definitions

These characteristics define authentication and multilink policies for all incoming bundles. The syntax of the global bundle definition is shown below:

global bundle {
type = bundle
[ authname = name ]
[ authtmout = seconds ]
[ commonprefix = string ]
[ ed = true | false ]
[ mrru = bytes ]
[ peerauthname = peername ]
[ requirechap = true | false ]
[ requirepap = true | false ]
[ ssn = true | false ]
[ uniquedigits = number ]
}

The tag name and the type attribute must be specified as bundle. See ``Bundle definitions'' for a description of the authname, authtmout, ed, mrru, peerauthname, requirechap, requirepap, and ssn attributes.

The following attributes are unique to the global bundle:


commonprefix = string
The common prefix for advertised phone numbers. This is used when BAP/BACP is available and has been negotiated. Only link devices which have phone numbers that share the prefix can be used to add links to a multilink bundle. This may be used to prevent other remote access servers at the same site being dialed in error. By default, no common prefix string is configured.

uniquedigits = number
The number of unique digits that may be appended to the common prefix for advertised phone numbers (see the description of commonprefix). The default and minimum value is 0. The maximum value is 40.
The commonprefix and uniquedigits attributes are used in conjunction with the uniquedigits attribute in link device definitions.

Finite state machine parameters

The PPP finite state machine (FSM) provides the underlying support for PPP's control protocols. In order to establish communications over a PPP link, each end of the link must first send Link Control Protocol (LCP) packets to configure the data link. Next, PPP must send Network Control Protocol (NCP) packets to choose and configure one or more network-layer protocols. The PPP link remains configured for communications until LCP packets explicitly close the link or the physical link is dropped. The FSM controls the sequencing of link establishment, network configuration and link termination. Whenever an event occurs, such as receipt of a packet, the control protocol calls the FSM for the state transition and the appropriate action is invoked.

The configuration definitions of all control protocols (IPCP, LCP and CCP) can specify the following parameters that control the operation of the FSM:


maxcfg = number
The maximum number of retries allowed for configuration requests. The default value is 10. The maximum and minimum values are 1 and 100.

maxfail = number
The maximum number of NAKs that can be sent without sending an ACK before assuming that configuration has failed. The default value is 5. The maximum and minimum values are 1 and 100.

maxterm = number
The maximum number of retries allowed for termination request. The default value is 2. The maximum and minimum values are 1 and 100.

reqtmout = seconds
The time allowed for responses to configuration-request and termination-request packets. The default value is 3 seconds. The maximum and minimum values are 1 and 300.
reqtmout should be set to a value that reflects the speed of the physical link. The default value (3 seconds) is suitable for low-speed links (ACU or Direct) but a value of 1 second is probably more suitable for high-speed links (ISDN_SYNC and ISDN_ASYNC).

The PPP daemon

The PPP daemon, pppd, is the server process that is responsible for managing and negotiating PPP links. All incoming PPP control packets that the PPP driver receives are passed along a single control stream for processing in the PPP daemon. The daemon passes down all control packets that it wishes to send to the driver for transmission. It is also responsible for all PPP control protocol negotiations. Once the negotiations for a link have finished, the daemon sets up the driver according to the negotiated parameters. After this, data flows directly between the PPP driver and the network layer driver (such as IP) without passing through the daemon.

In previous releases, there were multiple PPP daemons. The parent PPP daemon spawned a new daemon for each PPP interface. In this release, the PPP daemon is invoked as a single multithreaded process.

The operation of pppd is normally controlled using ppptalk. If you stop pppd using the stop command in ppptalk, you can restart it from the command line. You may want to do this to specify a different log file using the -l option to pppd. The default log file is /var/adm/log/ppp.log.

You can change the values in the PPP configuration file using ppptalk or the PPP Manager. If you run ppptalk to edit a link or bundle definition, use the reset command so that any changes will take effect when the link or bundle is next brought up.

The -a option to pppd creates log entries for each bundle connection or disconnection. The amount of data transferred over the link and the connect time are recorded on disconnection.

The -d option enables debug logging for all links and bundles. Do not use this option unless you are expert at interpreting the debug output that it produces. In preference, use the debug command within ppptalk to control the debugging level on individual links and bundles.

Files


/etc/bpf.d/IP/ppp
packet filter definitions

/etc/hosts
static host name to IP address translation

/etc/ppp.d/.pppcfg
default PPP configuration file

/etc/uucp/Systems
remote systems accessible using UUCP

/etc/uucp/Devices
devices that can be used to access remote systems

/var/adm/log/ppp.log
default PPP log file

References

Devices(4bnu), hosts(4tcp), filter(4), pppattach(1M), pppauth(7), pppdetach(1M), ppplinkadd(1M), ppplinkdrop(1M), pppsh(1M), pppstatus(1M), Systems(4bnu), uucp(1bnu)

RFC 1144, RFC 1172, RFC 1332, RFC 1334, RFC 1548, RFC 1618, RFC 1661, RFC 1662, RFC 1877, RFC 1962, RFC 1990

Notices

You can start the PPP Manager from the WAN view of the Network Configuration Manager.

You can use the PPP Outgoing Connection Wizard to quickly set up outgoing PPP link definitions to remote systems. The PPP Incoming Connection Wizard allows you to quickly set up a system as a remote access server for dial-in PPP users.

Do not edit the PPP configuration file directly. Use the PPP Manager or ppptalk to configure PPP. You can also use the WAN view of the Network Configuration Manager to configure modems, ISDN hardware, and entries in UUCP configuration files for incoming and outgoing connections.

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.

Examples

The following are example protocol definitions:
# LCP definitions
protocol lcp_A {
	protocol = lcp
	accm = 0x0
	mru = 1500
	acfc = enabled
	pfc = enabled
	magic = enabled
}

# CCP definitions protocol ccp_A { protocol = ccp algorithms = pred1 }

protocol ccp_B { protocol = ccp algorithms = pred1 }

algorithm pred1 { algorithm = predictor-1 }

# IPCP definitions protocol IP1 { protocol = ip localaddr = 160.136.240.7 localopt = force peeraddr = 160.136.240.8 peeropt = force }

The following are example authentication definitions:
# Authentication definition
auth tag_for_xxx {
	name = xxx
	peersecret = xxx_secret
	protocol = chap
}

# Default authentication entry used when a peer # requests that we authenticate ourselves auth tag_for_this_host { name = myname localsecret = clydenw protocol = chap }

The following are example link definitions:
# Link definitions

# synchronous ISDN line - first B channel link LinkA { type = ISDN_SYNC dev = /dev/is0 push = pppdlpi phone = 0800 112 358 protocols = lcp_A ccp_A }

# synchronous ISDN line - second B channel link LinkB { # differs from LinkA in tag name, device and phone number type = ISDN_SYNC dev = /dev/is1 push = pppdlpi phone = 0800 112 359 protocols = lcp_A ccp_A }

link LinkC { # modem on analog telephone line type = pstn dev = /dev/term/a01m phone = 0800 314 159 pop = ttcompat ldterm push = asyh flow = hardware protocols = lcp_A }

link LinkD { # modem on analog telephone line type = pstn dev = /dev/term/a02m phone = 0800 314 160 pop = ttcompat ldterm push = asyh flow = hardware protocols = lcp_A }

The following is an example bundle definition that uses some of the previous definitions:
# bundle definition
bundle Bundle1 {
	type = bi-directional
	protocols = IP1
	mrru = 1000
	remotesys = annex		# name of remote site in Systems file
	bringup = automatic		# bring up link automatically
	login = tom			# user authenticated by login
	links = LinkA LinkB LinkC LinkD	# all these links can be used
	maxlinks = 2			# but only up to two at a time
}

UUCP file configuration

Because outgoing PPP links are initiated using UUCP, they require shared information in /etc/uucp/Devices, /etc/uucp/Systems, and in PPP. They may also require entries in DNS or in /etc/hosts if this file is used to resolve host names to IP addresses.

Consider the following file entries for an outgoing PPP link that must use locally defined remote and local IP addresses:


In PPP:
# IPCP definitions
protocol IP1 {
        protocol = ip
        localaddr = local_ppp
	localopt = force
        peeraddr = ice_d
	peeropt = force
}

bundle Bundle1 { type = out protocols = IP1 remotesys = ice bringup = automatic links = LinkA LinkB maxlinks = 2 maxidle = 300 }

link LinkA { type = pstn dev = /dev/term/a01m flow = hardware }

link LinkB { type = pstn dev = /dev/term/a02m flow = hardware }


In /etc/hosts:
128.2.129.5     ice_d
128.2.130.7     local_ppp

In /etc/uucp/Systems:
ice  Any ACU 9600 555-1234 "" \r ogin:--ogin: nppp word: Secret1

In /etc/uucp/Devices:
ACU term/a01m - 9600 dialTBIT \T
ACU term/a02m - 9600 dialTBIT \T
In this example, the names of the remote host, ice_d, and the local host, local_ppp, must be resolvable to IP addresses.

The remotesys name in the PPP configuration file, ice, has a corresponding entry in /etc/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 /etc/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/term/a01m and /dev/term/a02m.


© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004