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.

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.

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:

The remote host authenticates the local host using CHAP.
authname overrides the local host name in the outgoing response. This allows you to supply a name other than the local host name for the remote host to look up in its authentication database (unless it chooses to override it with a different name).
The auth entry for the name in the received challenge packet (possibly overridden by peerauthname) must contain a peersecret. CHAP uses the secret and the random value from the received challenge packet to calculate the response value that it sends to the remote authenticator.
The local host authenticates the remote host using CHAP.
authname overrides the local host name in the outgoing challenge and in the outgoing acknowledgment of success or failure. This allows you to configure local servers to use the same name when authenticating incoming connections.
The auth entry for the name in the received response (possibly overridden by peerauthname) must contain a localsecret. CHAP uses the secret and the random value from its challenge packet to calculate an expected value to be compared with the response value that it has received from the remote host. If the expected value and the response value are the same, authentication of the remote host succeeds.
The remote host authenticates the local host using PAP.
authname overrides the local host name in the outgoing authentication request. This allows you to supply a name other than the local host name which the remote host will use to look up a password in its authentication database (unless it chooses to override the supplied name with a different name).
The auth entry for the defined authname must contain a peersecret (password).

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:

The remote host authenticates the local host using CHAP.
CHAP looks up a secret for peerauthname so that it can calculate a response value and send it to the remote host. Normally, CHAP would look for a secret corresponding to the name supplied by the remote host in the incoming challenge. This allows you to use a single name-secret pair for outgoing connections to a service provider who has several remote access servers which use different names to challenge your system.
The auth entry must contain a peersecret.
The local host authenticates the remote host using CHAP.
CHAP looks up a secret for peerauthname so that it can check the validity of a response value that it has received. Normally, CHAP would look for a secret corresponding to the name supplied by the remote host in the incoming response. This allows you to configure a single name-secret pair for authenticating several remote systems or users.
The auth entry must contain a localsecret.
The remote host authenticates the local host using PAP.
If peerauthname is set, PAP uses it to look up a password to send in an authentication request to the remote host. Normally, PAP would look up a password entry for the local host name, possibly overridden by authname. The name set in the outgoing authentication request is set to the local host name unless overridden by authname. This allows a different name-password pair to be used with each remote host for outgoing connections.
The auth entry must contain a peersecret.
The local host authenticates the remote host using PAP.
PAP uses peerauthname to look up a password to check against the one it has received in an authentication request. Normally, PAP would look up a password for the name supplied by the remote host in the incoming authentication request. This allows you to configure a single name-password pair for authenticating several remote systems or users.
The auth entry must contain a localsecret.

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.