title: openl2tp_rpc(4)

summary: L2TP RPC Interface

text:
# openl2tp_rpc(4)

## NAME
openl2tp_rpc - L2TP RPC Interface

## SYNOPSIS
This document describes the RPC management interface of OpenL2TP.

The general user of OpenL2TP should find this document useful as it lists all parameters accessible over the interface.

## DESCRIPTION
An application wishing to control and/or obtain status information from OpenL2TP must implement all or part of this interface as an RPC client. The OpenL2TP RPC interface definition is defined in l2tp_rpc.x which is available in the application source distribution. This file may be processed by RPC tools such as rpcgen(1) to generate C, C++ or even Java source code that implements the interface.

The OpenL2TP application interface defines at least one structure per object type. For CREATE and MODIFY operations, the whole structure is filled in and passed to the application. In order to tell the application which fields have valid values, a flags field is present, which is a bitmask representing each valid field. For each request, the application checks that all mandatory parameters are set. This document does not list the bit definitions of the flags field since they are of no interest to the general user. Their definitions are available in the master l2tp_rpc.x interface definition.

CREATE, MODIFY, UNSET, and SHOW operations pass a structure that contains all managable parameters and status attributes of the object. For SHOW operations, the flags field tells which fields have non-default values, i.e. which fields have been explicitely set in CREATE or subsequent MODIFY commands for the lifetime of the object. For profiles, these flags may be unset using the UNSET command, which also returns the specified parameters to default values. Note that DELETE operations do not pass this structure: instead, parameters identify the object instance being deleted. LIST operations use another different structure suitable for returning a list of object-specific values which describe each instance of an object type. The LIST operation is used to obtain a list of instances of an object type, e.g. a list of tunnel profile names. The application may then walk the list and issue more command on specific instances. l2tpconfig(1) implements all of the interface described in this document.

## BUILDING CLIENT APPLICATIONS
You can safely skip this section if you are already familiar with Sun RPC.

There are several tools to help build Sun RPC client applications, some of which are proprietary and cost money. To build Java client applications, tools such as

```
http://netbula.com/
http://www.onc-rpc-xdr.com/
```

may be used. To build C applications, rpcgen(3) is available. l2tpconfig is an RPC client application implementing the interfaces of l2tp_rpc.x and is a good place to look for example code. rpcgen generates C code from the interface definition file, l2tp_rpc.x. When building client applications, rpcgen should generate client stubs and XDR (architecture independant structure serialization) which are simply linked with the client application code.

```
rpcgen -N -M -C -L -h -o l2tp_rpc.h l2tp_rpc.x
rpcgen -N -M -C -L -c -o l2tp_rpc_xdr.c l2tp_rpc.x
rpcgen -N -M -C -L -l -o l2tp_rpc_client.c l2tp_rpc.x
cc -o myapp myapp.o l2tp_rpc_xdr.o l2tp_rpc_client.o
```

The generated file l2tp_rpc.h defines C structures and function prototypes for all interfaces. The client application simply calls the functions as if they were linked directly with the application. Under the hood, RPC serializes the data and passes it (usually) over a network to the application server. When the response comes back, the client's RPC function call returns as if all the work were done locally.

Refer to rpc(3) for more details about RPC.

## INTERFACES
This section covers the details of the OpenL2TP interfaces.

### SYSTEM

```
Operations:-
struct app      APP_INFO_GET(void)
STATUS          SYSTEM_MODIFY(struct system params)
struct system   SYSTEM_GET(void)
```

Modifiable parameters:-

config.trace_flags

System-wide trace flags. This controls the generation of log messages that are not associated with specific tunnel, session or PPP instances.

config.trace_flags_mask

This is a bitmask of trace flags being set using values in trace_flags. When a bit is 1, the corresponding bit in the trace_flags parameter is applied. As a special case, a value 0 in this field indicates that the entire trace_flags value is applied. This field is meaningless on a read.

config.max_tunnels

Maximum number of tunnels permitted. Default=0 (no limit).

config.max_sessions

Maximum number of sessions permitted. Default=0 (no limit).

config.drain_tunnels

Enable the draining of existing tunnels. This prevents new tunnels from being created but does not delete those already present. This can be used to perform a soft shutdown of a system.

config.tunnel_establish_timeout

Timeout for tunnel establishment. Default=120 seconds..

config.session_establish_timeout

Timeout for session establishment. Default=120 seconds..

config.tunnel_persist_pend_timeout

The time (in seconds) to hold a downed persistent tunnel before attempting to automatically reestablish. Default=300 seconds

config.session_persist_pend_timeout

The time (in seconds) to hold a downed persistent session before attempting to automatically reestablish. Default=60 seconds

config.deny_local_tunnel_creates

Deny the creation of new tunnels by local request.

config.deny_remote_tunnel_creates

Deny the creation of new tunnels by remote peers.

reset_statistics

Reset system-wide statistics.

Read-only parameters:-

status.stats.short_frames

Total number of short frames received (no valid L2TP header).

status.stats.wrong_version_frames

Total number of L2TP frames received with an unsupported protocol version.

status.stats.unexpected_data_frames

All data frames are handled in the Linux kernel. If such frames are received by the userspace daemon, something has gone wrong in the kernel.

status.stats.bad_rcvd_frames

Total number of bad (illegal) L2TP control frames received.

status.stats.total_rcvd_control_frames

Total number of L2TP control frames received.

status.stats.total_sent_control_frames

Total number of L2TP control frames transmitted.

status.stats.total_control_frame_send_fails

The number of times we failed to transmit a control frame. This failure might occur if the local socket buffer overflows, probably because something has gone wrong in the kernel.

status.stats.total_retransmitted_control_frames

Total number of times a frame was retransmitted. L2TP runs a reliable transport protocol to deliver control frames to peers. Occasional retransmits are normal but excessive retransmits are indictors of low level link problems.

status.stats.no_control_frame_resources

The number of times we tried to allocate internal state to send a control frame but ran out of system resources. Should never happen unless the system is severely overloaded.

status.stats.no_peer_resources

The number of times we tried to allocate internal state to handle a new peer but ran out of system resources. Should never happen unless the system is severely overloaded.

status.stats.no_tunnel_resources

The number of times we tried to allocate internal state to handle a new tunnel but ran out of system resources. Should never happen unless the system is severely overloaded.

status.stats.no_session_resources

The number of times we tried to allocate internal state to handle a new session but ran out of system resources. Should never happen unless the system is severely overloaded.

status.stats.no_ppp_resources

The number of times we tried to allocate internal state to handle a PPP connection but ran out of system resources. Should never happen unless the system is severely overloaded.

status.stats.too_many_tunnels

The number of times a tunnel setup request was denied because the configured limit was reached.

status.stats.too_many_sessions

The number of times a session setup request was denied because the configured limit was reached.

status.stats.auth_fails

The number of times a tunnel setup request was denied because authentication failed.

status.stats.no_matching_tunnel_id_discards

The total number of received control frames that were discarded because they were directed at a tunnel_id that does not exist. This counter might increase when tunnels are torn down in the network because certain L2TP implementations might send frames to us after we have shut the tunnel down.

status.stats.no_matching_session_id_discards

The total number of received control frames that were discarded because they were directed at a session_id that does not exist. This counter might increase when sessions are torn down in the network because certain L2TP implementations might send frames to us after we have shut the session down.

status.stats.mismatched_tunnel_ids

Data in the received control message does not match local tunnel state. This will either be caused by a protocol error (bug) at the remote peer or a bug in OpenL2TP.

status.stats.mismatched_session_ids

Data in the received control message does not match local session state. This will either be caused by a protocol error (bug) at the remote peer or a bug in OpenL2TP.

status.stats.encode_message_fails

The number of times we failed to build an L2TP control message. Indicates a bug.

status.stats.tunnel_setup_failures

The total number of times a tunnel setup failed.

status.stats.session_setup_failures

The total number of times a session setup failed.

status.stats.event_queue_full_errors

OpenL2TP uses an internal event queue. If the queue overflows, internal events are lost and unexpected behavior may occur. Should always be 0.

status.stats.ignored_avps

The total number of Attribute Value Pairs (AVPs) received that have been ignored. OpenL2TP recognizes all standard AVPs so if this counter is non-zero, it indicates that the remote peer is non-standard or is buggy.

status.stats.vendor_avps

The total number of AVPs received that are marked as vendor-specific. These are ignored by OpenL2TP but do no harm; vendor AVPs allow vendors to exchange private information across L2TP between their own implementations.

status.stats.illegal_messages

The total number of illegal L2TP control messages received. Such messages are illegal either because a mandatory AVP is not present in a message or an AVP is flagged as mandatory that we don't recognize. Illegal messages cause OpenL2TP to tear down the tunnel.

status.stats.unsupported_messages

The total number of unsupported L2TP control messages received. These messages have legal message types but they are deprecated in the L2TP protocol specification. This counter might increase if the peer is an old L2TP implementation or is buggy.

status.stats.messages[]

Number of messages received and transmitted of each type. Unrecognized messages are counted in status.stats.unsupported_messages.

status.num_tunnels

Current number of active tunnels.

status.num_sessions

Current number of active sessions.

### PEER PROFILE

```
Operations:-
STATUS                   PEER_PROFILE_CREATE(struct peer_profile params)
STATUS                   PEER_PROFILE_DELETE(string profile_name)
STATUS                   PEER_PROFILE_MODIFY(struct peer_profile params)
struct peer_profile      PEER_PROFILE_GET(string profile_name)
struct peer_profile_list PEER_PROFILE_LIST(void)
STATUS                   PEER_PROFILE_UNSET(struct peer_profile_unset params)
```

Referenced by: profile_name

Create-only parameters:-

profile_name

The name of the profile which must be unique in the system.

Modifiable parameters:-

peer_ipaddr

IP address of peer

peer_port

UDP port with which to connect to peer. Default=1701.

netmask

IP netmask to be used when matching for peer_ipaddr. Default=255.255.255.255.

lac_lns

We can operate as a LAC or LNS or both.

tunnel_profile_name

Name of default Tunnel Profile. Default="default"

session_profile_name

Name of default Session Profile. Default="default"

ppp_profile_name

Name of default ppp Profile. Default="default"

Read-only parameters:-

### TUNNEL PROFILE

```
Operations:-
STATUS                     TUNNEL_PROFILE_CREATE(struct tunnel_profile params)
STATUS                     TUNNEL_PROFILE_DELETE(string profile_name)
STATUS                     TUNNEL_PROFILE_MODIFY(struct tunnel_profile params)
struct tunnel_profile      TUNNEL_PROFILE_GET(string profile_name)
struct tunnel_profile_list TUNNEL_PROFILE_LIST(void)
STATUS                     TUNNEL_PROFILE_UNSET(struct tunnel_profile_unset params)
```

Referenced by: profile_name

Create-only parameters:-

profile_name

The name of the profile which must be unique in the system.

Modifiable parameters:-

dest_ipaddr

Destination IP address.

src_ipaddr

Source IP address. May be used to force a tunnel to use a specific local interface. By default, the system chooses how to reach the destination by IP route table lookup.

udp_port

UDP port number with which to contact peer L2TP server. Default=1701

use_tiebreaker

Enable use of a tiebreaker when setting up the tunnel. Default=ON

allow_ppp_proxy

Allow PPP proxy. Not currently implemented.

framing_caps

Framing capabilities: sync, async, any. These are passed to the peer when the tunnel is set up to tell the capabilities of the network beyond the L2TP tunnel.

bearer_caps

Bearer capabilities: digital, analog, any. These are passed to the peer when the tunnel is set up to tell the capabilities of the network beyond the L2TP tunnel.

host_name

Name to advertise to the peer when setting up the tunnel. This name is passed in the HOST_NAME AVP and may be used by the peer to invoke local policies. Default=local system hostname.

secret

Optional secret which is shared with tunnel peer. Must be specified when hide_avps is enabled.

auth_mode

Tunnel authentication mode:-

none - no authentication, unless secret is given

simple - check peer hostname

challenge - require tunnel secret

hide_avps

Hide AVPs. Default OFF

pmtu_discovery

Do Path MTU Discovery. Default=OFF. Not yet implemented.

trace_flags

Trace flags, for debugging network problems

trace_flags_mask

This is a bitmask of trace flags being set using values in trace_flags. When a bit is 1, the corresponding bit in the trace_flags parameter is applied. As a special case, a value 0 in this field indicates that the entire trace_flags value is applied. This field is meaningless on a read.

use_udp_checksums

Use UDP checksums in data frames. Default=ON

hello_timeout

Set timeout used for periodic L2TP Hello messages (in seconds). Hello messages are sent only if no data or control frames have been sent or received since the last Hello was sent. Default=60.

max_retries

The maximum number of retransmits of unacknowledged control frames. Setting this too low may bring down a tunnel unecessarily if a brief network error occurs. Setting it too high delays the system responding to real network outages. Control messages are retransmitted on an exponentially increasing delay. Default=5.

rx_window_size

Receive window size. This is the maximum number of control messages that the system will queue for processing. It is the maximum number of unacknowledged messages. Must be 4 or greater.

tx_window_size

Transmit window size. This is the preferred maximum number of unacknowledged messages that the local system will send to the peer. It can be reduced if the peer's rx_window_size is smaller.

retry_timeout

Retry timeout. The delay (in seconds) before sending the first retry of unacknowledged control frames. Default=1.

idle_timeout

Idle timeout. The time (in seconds) that a tunnel will remain after its last session has been torn down. Default=0, tunnel remains forever when it has no sessions, until a local administrator or network request deletes it..

max_sessions

Maximum number of sessions allowed on tunnel. Default=0 (limited only by max_sessions limit in system parameters).

mtu

MTU for all sessions in tunnel. Default=1460.

tunnel_name

Administrative name of this tunnel. This name may be used when referring to specific tunnel instances in MODIFY, SHOW and DELETE requests.

peer_profile_name

Name of peer profile which will be used for default values of the tunnel's parameters.

session_profile_name

Name of session profile which will be used for default values of the tunnel's session parameters.

ppp_profile_name

Name of ppp profile which will be used for default values of the tunnel's session PPP parameters.

interface_name

Name of system interface for the tunnel. Default=l2tpN where N is tunnel_id.

Read-only parameters:-

### SESSION PROFILE

```
Operations:-
STATUS                      SESSION_PROFILE_CREATE(struct session_profile params)
STATUS                      SESSION_PROFILE_DELETE(string profile_name)
STATUS                      SESSION_PROFILE_MODIFY(struct session_profile params)
struct session_profile      SESSION_PROFILE_GET(string profile_name)
struct session_profile_list SESSION_PROFILE_LIST(void)
STATUS                      SESSION_PROFILE_UNSET(struct session_profile_unset params)
```

Referenced by: profile_name

Create-only parameters:-

profile_name

The name of the profile which must be unique in the system.

Modifiable parameters:-

tunnel_id

Tunnel ID on which to create session.

tunnel_name

Administrative name of tunnel on which to create session.

profile_name

Name of session profile

ppp_profile_name

Name of ppp profile to use for PPP parameters

session_name

Administrative name of this session. This name may be used when referring to specific session instances in MODIFY, SHOW and DELETE requests.

trace_flags

Trace flags, for debugging network problems. Default=NONE.

trace_flags_mask

This is a bitmask of trace flags being set using values in trace_flags. When a bit is 1, the corresponding bit in the trace_flags parameter is applied. As a special case, a value 0 in this field indicates that the entire trace_flags value is applied. This field is meaningless on a read.

sequencing_required

The use of sequence numbers in the data channel is mandatory.

use_sequence_numbers

Enable sequence numbers in the data channel if peer supports them.

no_ppp

Don't start PPP on the L2TP session.

reorder_timeout

Timeout to wait for out-of-sequence packets before discarding. Out-of-sequence packet reordering is not currently supported.

session_type

Session type: LAC Incoming (LAIC), LAC Outgoing (LAOC), LNS Incoming (LNIC), LNS Outgoing (LNOC). Default=derived from tunnel type.

priv_group_id

Private group ID, used to separate this session into a named administrative group

interface_name

PPP interface name. Not currently supported. Default=pppN

user_name

PPP user name.

user_password

PPP user password. To use non-ASCII characters, specify each non-ASCII character using octal or hex escape sequences, i.e.

```
 nnn or
```

framing_type

Framing type: sync, async or any. Default=any

bearer_type

Bearer type: digital, analog, any. Default=any

minimum_bps

Minimum bits/sec acceptable. Default=0

maximum_bps

Maximum bits/sec required. Default=no limit

connect_speed

Specified as speed[:txspeed], indicates connection speeds.

session_id

Session ID of session. Default=system chooses random ID.

Read-only parameters:-

### PPP PROFILE

```
Operations:-
STATUS                   PPP_PROFILE_CREATE(struct ppp_profile params)
STATUS                   PPP_PROFILE_DELETE(string profile_name)
STATUS                   PPP_PROFILE_MODIFY(struct ppp_profile params)
struct ppp_profile       PPP_PROFILE_GET(string profile_name)
struct ppp_profile_list  PPP_PROFILE_LIST(void)
STATUS                   PPP_PROFILE_UNSET(struct ppp_profile_unset params)
```

Referenced by: profile_name

Create-only parameters:-

profile_name

The name of the profile which must be unique in the system.

Modifiable parameters:-

trace_flags

Trace flags, for debugging network problems

trace_flags_mask

This is a bitmask of trace flags being set using values in trace_flags. When a bit is 1, the corresponding bit in the trace_flags parameter is applied. As a special case, a value 0 in this field indicates that the entire trace_flags value is applied. This field is meaningless on a read.

asyncmap

Async character map. Valid only if PPP is async mode.

mtu

Maximum Transmit Unit (MTU) or maximum packet size transmitted.

mru

Maximum Receive Unit (MRU) or maximum packet size passed when received.

sync_mode

Allow PPP sync/async operation.

auth_pap

Allow PPP PAP authentication. Default=YES

auth_chap

Allow PPP CHAP authentication. Default=YES

auth_mschapv1

Allow PPP MSCHAP authentication. Default=YES

auth_mschapv2

Allow PPP MSCHAPV2 authentication. Default=YES

auth_eap

Allow PPP EAP authentication. Default=YES

auth_none

Allow unauthenticated PPP users. Default=NO

chap_interval

Rechallenge the peer every chap_interval seconds. Default=0 (don't rechallenge).

chap_max_challenge

Maximum number of CHAP challenges to transmit without successful acknowledgment before declaring a failure. Default=10.

chap_restart

Retransmission timeout for CHAP challenges. Default=3.

pap_max_auth_reqs

Maximum number of PAP authenticate-request transmissions. Default=10.

pap_restart_interval

Retransmission timeout for PAP requests. Default=3.

pap_timeout

Maximum time to wait for peer to authenticate itself. Default=0 (no limit).

idle_timeout

Disconnect session if idle for more than N seconds. Default=0 (no limit).

ipcp_max_cfg_reqs

Maximum number of IPCP config-requests to transmit without successful acknowledgement before declaring a failure. Default=10.

ipcp_max_cfg_naks

Maximum number of IPCP config-naks to allow before starting to send config-rejects instead. Default=10.

ipcp_max_term_reqs

Maximum number of IPCP term-requests to send. Default=3.

ipcp_retransmit_interval

IPCP retransmission timeout. Default=3.

lcp_echo_fail_count

Number of LCP echo failures to accept before assuming peer is down. Default=5.

lcp_echo_interval

Send LCP echo-request to peer every N seconds. Default=0 (don't send).

lcp_max_cfg_reqs

Maximum number of LCP config-request transmissions. Default=10.

lcp_max_cfg_naks

Maximum number of LCP config-requests to transmit without successful acknowledgement before declaring a failure. Default=10.

lcp_max_term_reqs

Maximum number of LCP term-requests to send. Default=3.

lcp_retransmit_interval

LCP retransmission timeout. Default=3.

max_connect_time

Maximum connect time (in seconds) that the PPP session may stay in use.Default=0 (no limit)

local_ip_addr

The IP address to assign to the local end of the PPP link.

peer_ip_addr

The IP address to assign to the remote (peer) end of the PPP link.

dns_addr_1

Primary DNS address to use over the PPP link.

dns_addr_2

Secondary DNS address to use over the PPP link.

wins_addr_1

Primary WINS address to use over the PPP link.

wins_addr_2

Secondary WINS address to use over the PPP link.

ip_pool_name

The name of an IP pool from which to allocate local and remote IP addresses if not otherwise assigned. This value may be passed to RADIUS if RADIUS is configured. OpenL2TP does not provide IP pool functionality itself.

use_radius

Says whether PPP should use RADIUS to authenticate the user and obtain user parameters for the connection. RADIUS is the preferred method to derive values for IP addresses, DNS etc rather than using fixed values in PPP profiles.

radius_hint

An arbitrary string that is passed to PPP when RADIUS is enabled. The PPP implementation may use this string in any way. The bundled ppp_unix plugin for use with pppd applies this value to pppd's radius-config-file parameter.

default_route

Says whether the PPP interface should be configured as the host's default route. Useful for use at a LAC which expects to use the L2TP tunnel as its path to the global internet.

multilink

Enable PPP multilink. Default=off.

local_name

The name to use for the local side for authentication with the peer, unless overridden by user_name.

remote_name

The name to assume for the remote peer for authentication purposes, unless overridden by a PPP username via PPP protocol exchange..

Read-only parameters:-

### TUNNEL

```
Operations:-
STATUS             TUNNEL_CREATE(struct tunnel params)
STATUS             TUNNEL_DELETE(u_short tunnel_id, optstring tunnel_name)
STATUS             TUNNEL_MODIFY(struct tunnel params)
struct tunnel      TUNNEL_GET(u_short tunnel_id, optstring tunnel_name)
struct tunnel_list TUNNEL_LIST(void)
```

Referenced by: tunnel_id / tunnel_name

Create-only parameters:-

dest_ipaddr

Destination IP address

config_id

Optional configuration id, used to uniquify a tunnel when there is more the one tunnel between the same two IP addresses

tunnel_id

Optional tunnel id of new tunnel. Usually auto-generated. Use is discouraged.

profile_name

Name of tunnel profile which will be used for default values of this tunnel's parameters.

src_ipaddr

Source IP address

udp_port

UDP port number with which to contact peer L2TP server. Default=1701

mode

Indicates whether the local tunnel is a LAC or LNS.

use_tiebreaker

Enable use of a tiebreaker when setting up the tunnel. Default=ON

allow_ppp_proxy

Allow PPP proxy

framing_caps

Framing capabilities: sync, async, any. These are passed to the peer when the tunnel is set up to tell the capabilities of the network beyond the L2TP tunnel.

bearer_caps

Bearer capabilities: digital, analog, any. These are passed to the peer when the tunnel is set up to tell the capabilities of the network beyond the L2TP tunnel.

host_name

Name to advertise to peer when setting up the tunnel. This name is passed in the HOST_NAME AVP and may be used by the peer to invoke local policies. Default=local system hostname.

secret

Optional secret which is shared with tunnel peer. Must be specified when hide_avps is enabled.

auth_mode

Tunnel authentication mode:-

none - no authentication, unless secret is given

simple - check peer hostname

challenge - require tunnel secret

hide_avps

Hide AVPs. Default OFF

pmtu_discovery

Do Path MTU Discovery. Default=OFF. Not yet implemented.

trace_flags

Trace flags, for debugging network problems

trace_flags_mask

This is a bitmask of trace flags being set using values in trace_flags. When a bit is 1, the corresponding bit in the trace_flags parameter is applied. As a special case, a value 0 in this field indicates that the entire trace_flags value is applied. This field is meaningless on a read.

use_udp_checksums

Use UDP checksums in data frames. Default=ON

persist

Marks the tunnel as persistent. Persistent tunnels attempt to restore themselves if the tunnel fails for some reason. Any locally created sessions in persistent tunnels are also restored if/when the tunnel reestablishes. The period at which a down persistent tunnel will attempt to reestablish is 5 minutes but this can be modified by the system tunnel_persist_pend_timeout parameter.

max_retries

The maximum number of retransmits of unacknowledged control frames. Setting this too low may bring down a tunnel unecessarily if a brief network error occurs. Setting it too high delays the system responding to real network outages. Control messages are retransmitted on an exponentially increasing delay. Default=5.

rx_window_size

Receive window size. This is the maximum number of control messages that the system will queue for processing. It is the maximum number of unacknowledged messages. Must be 4 or greater.

tx_window_size

Transmit window size. This is the preferred maximum number of unacknowledged messages that the local system will send to the peer. It can be reduced if the peer's

mtu

MTU for all sessions in tunnel. Default=1460.

tunnel_name

Administrative name of this tunnel.

peer_profile_name

Name of peer profile which will be used for default values of the tunnel's parameters.

session_profile_name

Name of session profile which will be used for default values of the tunnel's session parameters.

Modifiable parameters:-

trace_flags

Trace flags, for debugging network problems

trace_flags_mask

This is a bitmask of trace flags being set using values in trace_flags. When a bit is 1, the corresponding bit in the trace_flags parameter is applied. As a special case, a value 0 in this field indicates that the entire trace_flags value is applied. This field is meaningless on a read.

use_udp_checksums

Use UDP checksums in data frames. Default=ON

persist

Marks the tunnel as persistent. Persistent tunnels attempt to restore themselves if the tunnel fails for some reason. Any locally created sessions in persistent tunnels are also restored if/when the tunnel reestablishes. The period at which a down persistent tunnel will attempt to reestablish is 5 minutes but this can be modified by the system tunnel_persist_pend_timeout parameter.

hello_timeout

Set timeout used for periodic L2TP Hello messages (in seconds). Hello messages are sent only if no data or control frames have been sent or received since the last Hello was sent. Default=60.

retry_timeout

Retry timeout. The delay (in seconds) before sending the first retry of unacknowledged control frames. Default=1.

idle_timeout

Idle timeout. The time (in seconds) that a tunnel will remain after its last session has been torn down. Default=0, tunnel remains forever when it has no sessions, until a local administrator or network request deletes it..

max_sessions

Maximum number of sessions allowed on tunnel. Default=0 (limited only by max_sessions limit in system parameters).

mtu

MTU for all sessions in tunnel. Default=1460.

tunnel_name

Administrative name of this tunnel. This name may be used when referring to specific tunnel instances in MODIFY, SHOW and DELETE requests.

peer_profile_name

Name of peer profile which will be used for default values of the tunnel's parameters.

session_profile_name

Name of session profile which will be used for default values of the tunnel's session parameters.

ppp_profile_name

Name of ppp profile which will be used for default values of the tunnel's session PPP parameters.

interface_name

Name of system interface for the tunnel. Not currently used. Default=l2tpN where N is tunnel_id.

Read-only parameters:-

create_time

Tells when the tunnel was created. It is returned as a text string to avoid problems with timezones in cases where remote management crosses timezones.

peer.framing_cap_sync

The peer supports synchronous framing.

peer.framing_cap_async

The peer supports asynchronous framing.

peer.bearer_cap_digital

The peer supports digital bearers, e.g. T1/E1, ethernet..

peer.bearer_cap_analog

The peer supports analog bearers, e.g. POTS modem.

peer.protocol_version_ver

The protocol version reported by the peer. For information only.

peer.protocol_version_rev

The protocol revision reported by the peer. For information only.

peer.rx_window_size

The receive window size of the peer. The local system sets its transmit window size to be no larger than this value.

peer.firmware_revision

The peer firmware revision. Vendor specific. For information only.

peer.host_name

The hostname of the peer.

peer.vendor_name

The peer's vendor name. For information only.

peer.tiebreaker<8>

The tiebreaker value being used by the peer.

peer.result_code_result

The last result code received from the peer. This is useful to diagnose tunnel setup problems, assuming the peer implementation puts useful values in its messages. See RFC2661 for a list of result codes.

peer.result_code_error

The last error code received from the peer. This is useful to diagnose tunnel setup problems, assuming the peer implementation puts useful values in its messages. See RFC2661 for a list of error codes.

peer.result_code_message

Sometimes the peer includes a text string in L2TP error messages to tell more information about the problem. If the peer includes such text when it sends an error, it will be stored here.

stats.retransmits

The total number of retransmitted control messages in this tunnel.

stats.tx_zlbs

The number of Zero Length Buffer (ZLB) messages transmitted through this tunnel. These messages are used to acknowledge the peer.

stats.tx_zlb_fails

If a local error occurs in transmitting a ZLB, perhaps due to resource error, it is counted.

stats.rx_zlbs

The number of ZLB messages received from the peer in this tunnel.

stats.duplicate_pkt_discards

The number of times a control frame was received which was a duplicate of one already processed. This might happen if the peer doesn't receive our ack and so resends it. If this counter increases, it means that some frames are getting lost in the network or the peer is buggy.

stats.rx_hellos

The number of L2TP HELLO messages received in this tunnel.

stats.tx_hellos

The number of L2TP HELLO messages transmitted in this tunnel.

stats.tx_hello_fails

The number times we failed to transmit a HELLO message due to a local resource failure.

stats.ns

The current Next Send sequence number.

stats.nr

The current Next Receive sequence number.

stats.peer_ns

The Next Send sequence number last reported by the peer.

stats.peer_nr

The Next Receive sequence number last reported by the peer.

stats.cwnd

Congestion Window. This is used by the Slow Start algorithm specified in RFC2661. For information only.

stats.ssthresh

Slow Start Threshold. This is used by the Slow Start algorithm specified in RFC2661. For information only.

stats.congpkt_acc

Congested Packet Accumulator. This is used by the Slow Start algorithm specified in RFC2661. For information only.

stats.control_rx_oos_packets

The total number of received control frames that were received out-of-sequence.

stats.control_rx_oos_discards

The total number of received control frames that were received out-of-sequence and have been discarded because packet reordering was either disabled or could not be completed within the configured reorder_timeout. This might happen if packets are occasionally reordered across the network; it does not necessarily indicate a bug.

stats.control_rx_packets

Total number of control frames received in this tunnel.

stats.control_rx_bytes

Total number of control bytes received in this tunnel.

stats.control_tx_packets

Total number of control frames transmitted in this tunnel.

stats.control_tx_bytes

Total number of control bytes transmitted in this tunnel.

stats.data_rx_packets Total number of data frames received in this tunnel.

stats.data_rx_oos_packets

The total number of received data frames that were received out-of-sequence.

stats.data_rx_oos_discards

The total number of received data frames that were received out-of-sequence and have been discarded because packet reordering was either disabled or could not be completed within the configured reorder_timeout. This might happen if packets are occasionally reordered across the network; it does not necessarily indicate a bug.

stats.data_rx_bytes

Total number of data bytes received in this tunnel.

stats.data_rx_errors

Total number of data frames received and discarded in this tunnel. This counter might indicate local congestion.

stats.data_tx_packets

Total number of data frames transmitted in this tunnel.

stats.data_tx_bytes

Total number of data bytes transmitted in this tunnel.

stats.data_tx_errors

Total number of data frames received and discarded in this tunnel. This counter might indicate local overload.

stats.using_ipsec

Tells whether the tunnel is secured using IPSec. Note that IPSec policies are configured outside openl2tpd. If IPSec configuration says to use IPSec for L2TP's UDP tunnel then this parameter will indicate so.

peer_tunnel_id

The peer's tunnel_id.

created_by_admin

Indicates whether this tunnel was created by a local administrator or by remote request from the network.

actual_tx_window_size

The actual transmit window size, negotiated with the peer.

num_sessions

The number of sessions in this tunnel.

num_establish_retries

A locally created tunnel will automatically try to reestablish itself if it fails. This is a count of the number of times it has retried. Not yet implemented, always 0.

state

The current state of the tunnel. The tunnel states are documented in RFC2661.

tiebreaker<8>

The tiebreaker we used when setting up the tunnel.

result_code_result

If a local error has occured, its result_code is reported here. See peer.result_code_result.

result_code_error

If a local error has occured, its error_code is reported here. See peer.result_code_error.

result_code_message

If a local error has occured, its error_message text is reported here. See peer.result_code_message.

### SESSION

```
Operations:-
STATUS              SESSION_CREATE(struct session params)
STATUS              SESSION_DELETE(u_short tunnel_id, optstring tunnel_name,

                                   u_short session_id, optstring session_name)
STATUS              SESSION_MODIFY(struct session params)
struct session      SESSION_GET(u_short tunnel_id, optstring tunnel_name,

                                u_short session_id, optstring session_name)
struct session_list SESSION_LIST(void)
```

Referenced by: tunnel_id / tunnel_name, session_id / session_name

Create-only parameters:-

tunnel_id

Tunnel ID on which to create session.

tunnel_name

Administrative name of tunnel on which to create session.

profile_name

Name of session profile. If not specified, the profile name is inherited from the tunnel or the peer profile.

ppp_profile_name

Name of ppp profile to use for PPP parameters. If not specified, the profile name is inherited from the tunnel or the peer profile.

session_name

Administrative name of this session. This may be used in subsequent MODIFY or SHOW requests to reference the session.

trace_flags

Trace flags, for debugging network problems

trace_flags_mask

This is a bitmask of trace flags being set using values in trace_flags. When a bit is 1, the corresponding bit in the trace_flags parameter is applied. As a special case, a value 0 in this field indicates that the entire trace_flags value is applied. This field is meaningless on a read.

sequencing_required

Says whether the use of sequence numbers in the data channel is mandatory. If set, the receipt of data packets without sequence numbers causes the session to be torn down.

use_sequence_numbers

Says to enable sequence numbers in the data channel if peer supports them.

no_ppp

Says to not start PPP on the L2TP session.

reorder_timeout

Timeout to wait for out-of-sequence packets before discarding. Data packet out-of-sequence reordering is not currently implemented.

session_type

Session type: LAC Incoming (LAIC), LAC Outgoing (LAOC), LNS Incoming (LNIC), LNS Outgoing (LNOC). Default=derived from tunnel type.

priv_group_id

Private group ID, used to separate this session into a named administrative group

interface_name

PPP interface name. Not currently supported. Default=pppN

user_name

PPP user name

user_password

PPP user password. To use non-ASCII characters, specify each non-ASCII character using octal or hex escape sequences, i.e.

```
 nnn or
```

framing_type

Framing type: sync, async or any. Default=any. These are passed to the peer when the session is set up to tell the capabilities of the network beyond the L2TP tunnel.

bearer_type

Bearer type: digital, analog, any. Default=any. These are passed to the peer when the session is set up to tell the capabilities of the network beyond the L2TP tunnel.

minimum_bps

Minimum bits/sec acceptable. Default=0 (don't care)

maximum_bps

Maximum bits/sec required. Default=9 (no limit)

connect_speed

Indicates transmit and receive connection speeds.

session_id

Session ID of session. Default=system chooses random ID.

Modifiable parameters:-

session_name

Administrative name of this session. This name may be used when referring to specific session instances in MODIFY, SHOW and DELETE requests.

trace_flags

Trace flags, for debugging network problems

trace_flags_mask

This is a bitmask of trace flags being set using values in trace_flags. When a bit is 1, the corresponding bit in the trace_flags parameter is applied. As a special case, a value 0 in this field indicates that the entire trace_flags value is applied. This field is meaningless on a read.

sequencing_required

Says whether the use of sequence numbers in the data channel is mandatory. If set, the receipt of data packets without sequence numbers causes the session to be torn down.

use_sequence_numbers

Says whether to enable sequence numbers in the data channel if peer supports them.

no_ppp

Says to not start PPP on the L2TP session.

reorder_timeout

Timeout to wait for out-of-sequence packets before discarding. Out-of-sequence packet reordering is not currently supported.

Read-only parameters:-

create_time

Tells when the session was created. It is returned as a text string to avoid problems with timezones in cases where remote management crosses timezones.

stats.data_rx_packets

Total number of data frames received from the peer in this session.

stats.data_rx_bytes

Total number of data bytes received from the peer in this session.

stats.data_rx_errors

Total number of data frames received but were discarded due to an error. This might be because of local congestion.

stats.data_tx_packets

Total number of data frames transmitted to the peer in this session.

stats.data_tx_bytes

Total number of data bytes transmitted to the peer in this session.

stats.data_tx_errors

Total number of data frames that we tried to transmit to the peer in this session but were discarded due to an error. This might be because of local system overload..

peer.result_code

The last result code received from the peer. This is useful to diagnose session setup problems, assuming the peer implementation puts useful values in its messages. See RFC2661 for a list of result codes.

peer.error_code

The last error code received from the peer. This is useful to diagnose session setup problems, assuming the peer implementation puts useful values in its messages. See RFC2661 for a list of error codes.

peer.error_message

Sometimes the peer includes a text string in L2TP session error messages to tell more information about the problem. If the peer includes such text when it sends an error, it will be stored here.

peer.minimum_bps

The minimum bits-per-sec (bps) requested by the peer. It can be used by the local system to allocate resources or even reject the tunnel setup if the local system cannot meet the requirement. OpenL2TP currently does nothing with this information.

peer.maximum_bps

The maximum bits-per-sec (bps) requested by the peer. It can be used by the local system to allocate resources or even reject the tunnel setup if the local system cannot meet the requirement. OpenL2TP currently does nothing with this information.

peer.connect_speed

The connection speed of the peer's physical interface. OpenL2TP currently does nothing with this information.

peer.rx_connect_speed

If the physical interface is asymmetric (different upstream and downstream speeds), the peer's receive connection speed is indicated here and peer.connect_speed indicates the transmit speed. OpenL2TP currently does nothing with this information.

peer.private_group_id

The private group name that the peer has requested us to put the session into. OpenL2TP currently does nothing with this information.

peer.framing_type_sync

Indicates whether the peer supports synchronous framing in this session.

peer.framing_type_async

Indicates whether the peer supports asynchronous framing in this session.

peer.bearer_type_digital

Indicates whether the peer supports digital bearers in this session.

peer.bearer_type_analog

Indicates whether the peer supports analog bearers in this session.

peer.sequencing_required

Indicates whether the peer requires sequence numbers in data packets that it receives in this session.

peer.call_serial_number

The call serial number assigned by the peer for this session. This is for information only. It is usually derived from a counter that is increased each time a session create is attempted.

peer.physical_channel_id

A number used by the peer to reference the physical channel used for this session.

peer.calling_number

The (telephone) number that the peer is calling. This can actually be any text string and is used to tell us how to place an outgoing call for forwarding the data on.

peer.called_number

The (telephone) number that the peer was called from. This can actually be any text string and may be used by us to assign local policy or to do local authentication.

peer.sub_address

Additional information to be used when making outgoing calls.

peer.q931_cause_code

The Q931 cause code reported by the peer. OpenL2TP currently does nothing with this information.

peer.q931_cause_msg

The Q931 cause message reported by the peer. OpenL2TP currently does nothing with this information.

peer.q931_advisory_msg

The Q931 advisory message reported by the peer. OpenL2TP currently does nothing with this information.

peer.call_errors

Call error statistics reported by the peer, including checksum errors and framing errors.

peer.send_accm

peer.recv_accm

peer_session_id

The peer's session_id.

state

The current session state, as specified in RFC2661. These states are different depending on session type: LAC Incoming Call, LAC Outgoing Call, LNS Incoming Call, LNS Outgoing Call.

created_by_admin

Indicates whether this session was created by local request or remote network request.

call_serial_number

A unique serial number assigned by the local system for this session. This number is reported to the peer and may be used in conjunction with peer.call_serial_number to cross-reference the session.

physical_channel_id

The physical channel assigned by the local system for this session.

### USER LIST

```
Operations:-
struct user_list USER_LIST(void)
```

Referenced by: none

Create-only parameters:-

Modifiable parameters:-

Read-only parameters:-

user_name

The PPP user name of the user.

tunnel_id

The tunnel_id of the L2TP tunnel over which the user's data is being carried. This may be used in additional RPC requests to obtain details about the tunnel.

session_id

The Isession_id of the L2TP tunnel over which the user's data is being carried. This may be used with tunnel_id in additional RPC requests to obtain details about the session.

create_time

Tells when the user (session) was created. It is returned as a text string to avoid problems with timezones in cases where remote management crosses timezones.

created_by_admin

Indicates whether this user was created by local administrative request or remote network request.

## LICENSE
OpenL2TP is dual-licensed. Users can choose to use the OpenL2TP software as an Open Source/Free Software product under the terms of the GNU General Public License (http://www.fsf.org/licenses/) or can purchase a commercial license from Katalix Systems Ltd. All applications written to the interface specified in this document fall under this license. Any application, even a closed source application, is deemed to be a derived work of OpenL2TP when it implements this interface. Users not wanting to have this restriction must purchase a commercial license. For details see the LICENSE file in the OpenL2TP source distribution.

## FILES
/usr/lib/openl2tp/l2tp_rpc.x

is the RPC interface definition source file. It may be used to generate C or Java API source code using appropriate tools.

## SEE ALSO
l2tpconfig(1), openl2tp(7), openl2tpd(8), rpc(3).


mwmrc

package: openmotif-mwm

title: mwmrc(4)

summary: the

text:
# mwmrc(4)

## NAME
mwmrc — the Motif Window Manager Resource Description File

## DESCRIPTION
The mwmrc file is a supplementary resource file that controls much of the behavior of the Motif window manager mwm. It contains descriptions of resources that cannot easily be written using standard X Window System, Version 11 resource syntax. The resource description file contains entries that are referred to by X resources in defaults files (for example, /usr/X11R6/lib/X11/app-defaults/Mwm) or in the RESOURCE_MANAGER property on the root window. For example, the resource description file enables you to specify different types of window menus; however, an X resource is used to specify which of these window menus mwm should use for a particular window.

### Location
The window manager searches for one of the following resource description files, where $LANG is the value of the language environment on a per-user basis:

```
$HOME/$LANG/.mwmrc
$HOME/.mwmrc
/etc/X11/mwm/$LANG/system.mwmrc
/etc/X11/mwm/system.mwmrc
```

The first file found is the first used. If no file is found, a set of built-in specifications is used. A particular resource description file can be selected using the configFile resource. The following shows how a different resource description file can be specified from the command line:

```
/usr/X11R6/bin/mwm -xrm "mwm*configFile: mymwmrc"
```

### Resource Types
The following types of resources can be described in the mwm resource description file:

Buttons

Window manager functions can be bound (associated) with button events.

Keys

Window manager functions can be bound (associated) with key press events.

Menus

Menu panes can be used for the window menu and other menus posted with key bindings and button bindings.

## MWM RESOURCE DESCRIPTION FILE SYNTAX
The mwm resource description file is a standard text file that contains items of information separated by blanks, tabs, and new lines characters. Blank lines are ignored. Items or characters can be quoted to avoid special interpretation (for example, the comment character can be quoted to prevent it from being interpreted as the comment character). A quoted item can be contained in double quotes (" "). Single characters can be quoted by preceding them by the back-slash character (\). If a line ends with a back-slash, the next line is considered a continuation of that line. All text from an unquoted # to the end of the line is regarded as a comment and is not interpreted as part of a resource description. If ! is the first character in a line, the line is regarded as a comment.

### Window Manager Functions
Window manager functions can be accessed with button and key bindings, and with window manager menus. Functions are indicated as part of the specifications for button and key binding sets, and menu panes. The function specification has the following syntax:

```
function = function_name [function_args]
function_name = window manager function
function_args = {quoted_item | unquoted_item}
```

The following functions are supported. If a function is specified that isn't one of the supported functions then it is interpreted by mwm as f.nop.

f.beep

This function causes a beep.

f.circle_down [ icon | window]

This function causes the window or icon that is on the top of the window stack to be put on the bottom of the window stack (so that it is no longer obscuring any other window or icon). This function affects only those windows and icons that are obscuring other windows and icons, or that are obscured by other windows and icons. Secondary windows (that is, transient windows) are restacked with their associated primary window. Secondary windows always stay on top of the associated primary window and there can be no other primary windows between the secondary windows and their primary window. If an icon function argument is specified, then the function applies only to icons. If a window function argument is specified then the function applies only to windows.

f.circle_up [ icon | window]

This function raises the window or icon on the bottom of the window stack (so that it is not obscured by any other windows). This function affects only those windows and icons that are obscuring other windows and icons, or that are obscured by other windows and icons. Secondary windows (that is, transient windows) are restacked with their associated primary window. If an icon function argument is specified then the function applies only to icons. If an window function argument is specified then the function applies only to windows.

f.exec command (or ! command)

This function causes command to be executed (using the value of the $MWMSHELL or $SHELL environment variable if set; otherwise, /bin/sh ). The ! notation can be used in place of the f.exec function name.

f.focus_color

This function sets the colormap focus to a client window. If this function is done in a root context, then the default colormap (setup by the X Window System for the screen where mwm is running) is installed and there is no specific client window colormap focus. This function is treated as f.nop if colormapFocusPolicy is not explicit.

f.focus_key

This function sets the keyboard input focus to a client window or icon. This function is treated as f.nop if keyboardFocusPolicy is not explicit or the function is executed in a root context.

f.kill

This function is used to close application windows. The actual processing that occurs depends on the protocols that the application observes. The application lists the protocols it observes in the WM_PROTOCOLS property on its top level window. If the application observes the WM_DELETE_WINDOW protocol, it is sent a message that requests the window be deleted. If the application observes both WM_DELETE_WINDOW and WM_SAVE_YOURSELF, it is sent one message requesting the window be deleted and another message advising it to save its state. If the application observes only the WM_SAVE_YOURSELFprotocol , it is sent a message advising it to save its state. After a delay (specified by the resource quitTimeout), the application's connection to the X server is terminated. If the application observes neither of these protocols, its connection to the X server is terminated.

f.lower [- client | within | freeFamily]

This function lowers a primary window to the bottom of the global window stack (where it obscures no other window) and lowers the secondary window (transient window or dialog box) within the client family. The arguments to this function are mutually exclusive. The client argument indicates the name or class of a client to lower. The name or class of a client appears in the WM_CLASS property on the client's top-level window. If the client argument is not specified, the context that the function was invoked in indicates the window or icon to lower. Specifying within lowers the secondary window within the family (staying above the parent) but does not lower the client family in the global window stack. Specifying freeFamily lowers the window to the bottom of the global windows stack from its local family stack.

f.maximize

This function causes a client window to be displayed with its maximum size. Refer to the maximumClientSize, maximumMaximumSize, and limitResize resources in mwm(1).

f.menu menu_name

This function associates a cascading (pull-right) menu with a menu pane entry or a menu with a button or key binding. The menu_name function argument identifies the menu to be used.

f.minimize

This function causes a client window to be minimized (iconified). When a window is minimized with no icon box in use, and if the lowerOnIconify resource has the value True (the default), the icon is placed on the bottom of the window stack (such that it obscures no other window). If an icon box is used, then the client's icon changes to its iconified form inside the icon box. Secondary windows (that is, transient windows) are minimized with their associated primary window. There is only one icon for a primary window and all its secondary windows.

f.move

This function initiates an interactive move of a client window.

f.next_cmap

This function installs the next colormap in the list of colormaps for the window with the colormap focus.

f.next_key [ icon | window | transient]

This function sets the keyboard input focus to the next window/icon in the set of windows/icons managed by the window manager (the ordering of this set is based on the stacking of windows on the screen). This function is treated as f.nop if keyboardFocusPolicy is not explicit. The keyboard input focus is only moved to windows that do not have an associated secondary window that is application modal. If the transient argument is specified, then transient (secondary) windows are traversed (otherwise, if only window is specified, traversal is done only to the last focused window in a transient group). If an icon function argument is specified, then the function applies only to icons. If a window function argument is specified, then the function applies only to windows.

f.nop

This function does nothing.

f.normalize

This function causes a client window to be displayed with its normal size. Secondary windows (that is, transient windows) are placed in their normal state along with their associated primary window.

f.normalize_and_raise

This function causes a client window to be displayed with its normal size and raised to the top of the window stack. Secondary windows (that is, transient windows) are placed in their normal state along with their associated primary window.

f.pack_icons

This function is used to relayout icons (based on the layout policy being used) on the root window or in the icon box. In general this causes icons to be "packed" into the icon grid.

f.pass_keys

This function is used to enable/disable (toggle) processing of key bindings for window manager functions. When it disables key binding processing all keys are passed on to the window with the keyboard input focus and no window manager functions are invoked. If the f.pass_keys function is invoked with a key binding to disable key binding processing the same key binding can be used to enable key binding processing.

f.post_wmenu

This function is used to post the window menu. If a key is used to post the window menu and a window menu button is present, the window menu is automatically placed with its top-left corner at the bottom-left corner of the window menu button for the client window. If no window menu button is present, the window menu is placed at the top-left corner of the client window.

f.prev_cmap

This function installs the previous colormap in the list of colormaps for the window with the colormap focus.

f.prev_key [ icon | window | transient]

This function sets the keyboard input focus to the previous window/icon in the set of windows/icons managed by the window manager (the ordering of this set is based on the stacking of windows on the screen). This function is treated as f.nop if keyboardFocusPolicy is not explicit. The keyboard input focus is only moved to windows that do not have an associated secondary window that is application modal. If the transient argument is specified, then transient (secondary) windows are traversed (otherwise, if only window is specified, traversal is done only to the last focused window in a transient group). If an icon function argument is specified then the function applies only to icons. If an window function argument is specified then the function applies only to windows.

f.quit_mwm

This function terminates mwm (but NOT the X window system).

f.raise [-client | within | freeFamily]

This function raises a primary window to the top of the global window stack (where it is obscured by no other window) and raises the secondary window (transient window or dialog box) within the client family. The arguments to this function are mutually exclusive. The client argument indicates the name or class of a client to lower. If the client is not specified, the context that the function was invoked in indicates the window or icon to lower. Specifying within raises the secondary window within the family but does not raise the client family in the global window stack. Specifying freeFamily raises the window to the top of its local family stack and raises the family to the top of the global window stack.

f.raise_lower [ within | freeFamily]

This function raises a primary window to the top of the global window stack if it is partially obscured by another window; otherwise, it lowers the window to the bottom of the window stack. The arguments to this function are mutually exclusive. Specifying within raises a secondary window within the family (staying above the parent window), if it is partially obscured by another window in the application's family; otherwise, it lowers the window to the bottom of the family stack. It has no effect on the global window stacking order. Specifying freeFamily raises the window to the top of its local family stack, if obscured by another window, and raises the family to the top of the global window stack; otherwise, it lowers the window to the bottom of its local family stack and lowers the family to the bottom of the global window stack.

f.refresh

This function causes all windows to be redrawn.

f.refresh_win

This function causes a client window to be redrawn.

f.resize

This function initiates an interactive resize of a client window.

f.restore

This function restores the previous state of an icon's associated window. If a maximized window is iconified, then f.restore restores it to its maximized state. If a normal window is iconified, then f.restore restores it to its normalized state.

f.restore_and_raise

This function restores the previous state of an icon's associated window and raises the window to the top of the window stack. If a maximized window is iconified, then f.restore_and_raise restores it to its maximized state and raises it to the top of the window stack. If a normal window is iconified, then f.restore_and_raise restores it to its normalized state and raises it to the top of the window stack.

f.restart

This function causes mwm to be restarted (effectively terminated and re-executed). Restart is necessary for mwm to incorporate changes in both the mwmrc file and X resources.

f.screen [ next | prev | back | screen_number]

This function causes the pointer to be warp to a specific screen number or to the next, previous, or last visited (back) screen. The arguments to this function are mutually exclusive. The screen_number argument indicates the screen number that the pointer is to be warped. Screens are numbered starting from screen 0. Specifying next cause the pointer to warp to the next managed screen (skipping over any unmanaged screens). Specifying prev cause the pointer to warp to the previous managed screen (skipping over any unmanaged screens). Specifying back cause the pointer to warp to the last visited screen.

f.send_msg message_number

This function sends an XClientMessageEvent of type _MOTIF_WM_MESSAGES with message_type set to message_number. The client message is sent only if message_number is included in the client's _MOTIF_WM_MESSAGES property. A menu item label is grayed out if the menu item is used to do f.send_msg of a message that is not included in the client's _MOTIF_WM_MESSAGES property.

f.separator

This function causes a menu separator to be put in the menu pane at the specified location (the label is ignored).

f.set_behavior

This function causes the window manager to restart with the default behavior (if a custom behavior is configured) or a custom behavior (if a default behavior is configured). By default this is bound to Shift Ctrl Alt <Key>!.

f.title

This function inserts a title in the menu pane at the specified location.

f.version

This function causes the window manager to display its release version in a dialog box.

### Function Constraints
Each function may be constrained as to which resource types can specify the function (for example, menu pane) and also what context the function can be used in (for example, the function is done to the selected client window). Function contexts are:

root

No client window or icon has been selected as an object for the function.

window

A client window has been selected as an object for the function. This includes the window's title bar and frame. Some functions are applied only when the window is in its normalized state (for example, f.maximize) or its maximized state (for example, f.normalize).

icon

An icon has been selected as an object for the function.

If a function is specified in a type of resource where it is not supported or is invoked in a context that does not apply then the function is treated as f.nop. The following table indicates the resource types and function contexts in which window manager functions apply.

Function

Contexts

Resources

f.beep

root,icon,window

button,key,menu

f.circle_down

root,icon,window

button,key,menu

f.circle_up

root,icon,window

button,key,menu

f.exec

root,icon,window

button,key,menu

f.focus_color

root,icon,window

button,key,menu

f.focus_key

root,icon,window

button,key,menu

f.kill

icon,window

button,key,menu

f.lower

root,icon,window

button,key,menu

f.maximize

icon,window(normal)

button,key,menu

f.menu

root,icon,window

button,key,menu

f.minimize

window

button,key,menu

f.move

icon,window

button,key,menu

f.next_cmap

root,icon,window

button,key,menu

f.next_key

root,icon,window

button,key,menu

f.nop

root,icon,window

button,key,menu

f.normalize

icon,window(maximized)

button,key,menu

f.normalize_and_raise

icon,window

button,key,menu

f.pack_icons

root,icon,window

button,key,menu

f.pass_keys

root,icon,window

button,key,menu

f.post_wmenu

root,icon,window

button,key

f.prev_cmap

root,icon,window

button,key,menu

f.prev_key

root,icon,window

button,key,menu

f.quit_mwm

root

button,key,menu (root only)

f.raise

root,icon,window

button,key,menu

f.raise_lower

icon,window

button,key,menu

f.refresh

root,icon,window

button,key,menu

f.refresh_win

window

button,key,menu

f.resize

window

button,key,menu

f.restart

root

button,key,menu (root only)

f.restore

icon,window

button,key,menu

f.restore_and_raise

icon,window

button,key,menu

f.screen

root,icon,window

button,key,menu

f.send_msg

icon,window

button,key,menu

f.separator

root,icon,window

menu

f.set_behavior

root,icon,window

button,key,menu

f.title

root,icon,window

menu

f.version

root,icon,window

button,key,menu

## WINDOW MANAGER EVENT SPECIFICATION
Events are indicated as part of the specifications for button and key binding sets, and menu panes. Button events have the following syntax:

```
button =~[modifier_list ]<button_event_name >
modifier_list =~modifier_name { modifier_name}
```

The following table indicates the values that can be used for modifier_name. Note that [Alt] and [Meta] can be used interchangably on some hardware.

Modifier

Description

Ctrl

Control Key

Shift

Shift Key

Alt

Alt Key

Meta

Meta Key

Mod1

Modifier1

Mod2

Modifier2

Mod3

Modifier3

Mod4

Modifier4

Mod5

Modifier5

Locking modifiers are ignored when processing button and key bindings. The following table lists keys that are interpreted as locking modifiers. The X server may map some of these symbols to the Mod1 - Mod5 modifier keys. These keys may or may not be available on your hardware: Key Symbol Caps Lock Shift Lock Kana Lock Num Lock Scroll Lock The following table indicates the values that can be used for button_event_name.

Button

Description

Btn1Down

Button 1 Press

Btn1Up

Button 1 Release

Btn1Click

Button 1 Press and Release

Btn1Click2

Button 1 Double Click

Btn2Down

Button 2 Press

Btn2Up

Button 2 Release

Btn2Click

Button 2 Press and Release

Btn2Click2

Button 2 Double Click

Btn3Down

Button 3 Press

Btn3Up

Button 3 Release

Btn3Click

Button 3 Press and Release

Btn3Click2

Button 3 Double Click

Btn4Down

Button 4 Press

Btn4Up

Button 4 Release

Btn4Click

Button 4 Press and Release

Btn4Click2

Button 4 Double Click

Btn5Down

Button 5 Press

Btn5Up

Button 5 Release

Btn5Click

Button 5 Press and Release

Btn5Click2

Button 5 Double Click

Key events that are used by the window manager for menu mnemonics and for binding to window manager functions are single key presses; key releases are ignored. Key events have the following syntax:

```
key =~[modifier_list] <Key>key_name
modifier_list =~modifier_name { modifier_name}
```

All modifiers specified are interpreted as being exclusive (this means that only the specified modifiers can be present when the key event occurs). Modifiers for keys are the same as those that apply to buttons. The key_name is an X11 keysym name. Keysym names can be found in the keysymdef.h file (remove the XK_ prefix).

## BUTTON BINDINGS
The buttonBindings resource value is the name of a set of button bindings that are used to configure window manager behavior. A window manager function can be done when a button press occurs with the pointer over a framed client window, an icon or the root window. The context for indicating where the button press applies is also the context for invoking the window manager function when the button press is done (significant for functions that are context sensitive). The button binding syntax is

```
Buttons bindings_set_name
{

    button    context    function

    button    context    function

    ...

    button    context    function
}
```

The syntax for the context specification is: context = object[| context] object = root | icon | window | title | frame | border | app The context specification indicates where the pointer must be for the button binding to be effective. For example, a context of window indicates that the pointer must be over a client window or window management frame for the button binding to be effective. The frame context is for the window management frame around a client window (including the border and titlebar), the border context is for the border part of the window management frame (not including the titlebar), the title context is for the title area of the window management frame, and the app context is for the application window (not including the window management frame). If an f.nop function is specified for a button binding, the button binding is not done.

## KEY BINDINGS
The keyBindings resource value is the name of a set of key bindings that are used to configure window manager behavior. A window manager function can be done when a particular key is pressed. The context in which the key binding applies is indicated in the key binding specification. The valid contexts are the same as those that apply to button bindings. The key binding syntax is:

```
Keys bindings_set_name
{

    key    context    function

    key    context    function

    ...

    key    context    function
}
```

If an f.nop function is specified for a key binding, the key binding is not done. If an f.post_wmenu or f.menu function is bound to a key, mwm automatically uses the same key for removing the menu from the screen after it has been popped up. The context specification syntax is the same as for button bindings with one addition. The context ifkey may be specified for binding keys that may not be available on all displays. If the key is not available and if ifkey is in the context, then reporting of the error message to the error log is suppressed. This feature is useful for networked, heterogeneous environments. For key bindings, the frame, title, border, and app contexts are equivalent to the window context. The context for a key event is the window or icon that has the keyboard input focus (root if no window or icon has the keyboard input focus).

## MENU PANES
Menus can be popped up using the f.post_wmenu and f.menu window manager functions. The context for window manager functions that are done from a menu is root, icon or window depending on how the menu was popped up. In the case of the window menu or menus popped up with a key binding, the location of the keyboard input focus indicates the context. For menus popped up using a button binding, the context of the button binding is the context of the menu. The menu pane specification syntax is:

```
Menu menu_name
{

    label  [mnemonic]  [accelerator ]   function

    label  [mnemonic]  [accelerator ]   function

    ...

    label  [mnemonic]  [accelerator ]   function
}
```

Each line in the Menu specification identifies the label for a menu item and the function to be done if the menu item is selected. Optionally a menu button mnemonic and a menu button keyboard accelerator may be specified. Mnemonics are functional only when the menu is posted and keyboard traversal applies. The label may be a string or a bitmap file. The label specification has the following syntax:

```
label = text | bitmap_file
bitmap_file = @file_name
text = quoted_item | unquoted_item
```

The string encoding for labels must be compatible with the menu font that is used. Labels are greyed out for menu items that do the f.nop function or an invalid function or a function that doesn't apply in the current context. A mnemonic specification has the following syntax:

```
mnemonic = _ character
```

The first matching character in the label is underlined. If there is no matching character in the label, no mnemonic is registered with the window manager for that label. Although the character must exactly match a character in the label, the mnemonic does not execute if any modifier (such as Shift) is pressed with the character key. The accelerator specification is a key event specification with the same syntax as is used for key bindings to window manager functions.

## INCLUDING FILES
You may include other files into your mwmrc file by using the include construct. For example,

```
INCLUDE
{

    /usr/local/shared/mwm.menus

    /home/kmt/personal/my.bindings
}
```

causes the files named to be read in and interpreted in order as an additional part of the mwmrc file. Include is a top-level construct. It cannot be nested inside another construct.

## WARNINGS
Errors that occur during the processing of the resource description file are recorded in: $HOME/.mwm/errorlog. Be sure to check this file if the appearance or behavior of mwm is not what you expect.

## FILES

```
$HOME/$LANG/.mwmrc
$HOME/.mwmrc
/etc/X11/mwm/$LANG/system.mwmrc
/etc/X11/mwm/system.mwmrc
```

## RELATED INFORMATION
mwm(1), X(1).


smbios-sys-info

package: smbios-utils

title: smbios-sys-info(4)

summary: Display System Info

text:
# smbios-sys-info(4)

## NAME
smbios-sys-info - Display System Info

## SYNOPSIS
smbios-sys-info

## DESCRIPTION
The smbios-sys-info utility will display the System Hardware ID, Service Tag, Asset Tag, Product Name and BIOS Version


doc

title: doc(4)

text:
# doc(4)

## NAME
Doc (Pilot standard text document) file format

## SYNOPSIS

```
struct doc_record0 {	/* 16 bytes total */
	Word	version;	/* 1 = plain text, 2 = compressed text */
	Word	reserved1;
	DWord	doc_size;	/* uncompressed size in bytes */
	Word	num_recs;	/* not counting itself */
	Word	rec_size;	/* in bytes: usually 4096 (4K) */
	DWord	reserved2;
};
```

## DESCRIPTION
The Doc file format is the standard text document format used by all models of the Palm Pilot. A Doc file is a pdb(4) file: this manual page describes only those aspects specific to Doc files.

A Doc file consists of 0 to num_recs records; record 0 is the header for the document. (This header is distinct from the pdb(4) header.) The remaining records contain text, either plain or compressed depending upon version.

### Word Sizes
In the synopsis above, the types ``Word'' and ``DWord'' are used just as in the Pilot headers. The type ``Word'' is 16 bits; the type ``DWord'' is 32 bits. Both are in big-endian format.

### Compression Format
A character ``c'' in a compressed record is in one of four classes:

01-08

Copy ``c'' bytes

00,09-7F

Self

80-BF

Sequence

C0-FF

A space plus the ASCII character ``c ^ 0x80''

## SEE ALSO
txt2pdbdoc(1)

Christopher Bey and Kathleen Dupre. Palm File Format Specification, Document Number 3008-003, Palm, Inc., May 16, 2000.

## AUTHOR
Paul J. Lucas <pauljlucas@mac.com>


extcap

package: wireshark-base

title: extcap(4)

summary: The external capture interface

text:
# extcap(4)

## NAME
extcap - The external capture interface

## DESCRIPTION
The extcap (external capture) interface is a versatile plugin interface that allows external binaries to act as capture interfaces directly in Wireshark. It is used in scenarios, where the source of the capture is not a traditional capture model (live capture from an interface, from a pipe, from a file, etc). The typical example is connecting esoteric hardware of some kind to the main Wireshark application.

Without extcap, a capture can always be achieved by directly writing to a capture file:

```
the-esoteric-binary --the-strange-flag --interface=stream1 --file dumpfile.pcap &
wireshark dumpfile.pcap
```

but the extcap interface allows for such a connection to be easily established and configured using the Wireshark GUI.

The extcap subsystem is made of multiple extcap binaries that are automatically called by the GUI in a row. In the following chapters we will refer to them as "the extcaps".

Extcaps may be any binary or script within the extcap/wireshark or extcap/stratoshark directories. Please note that scripts need to be executable without prefacing a script interpreter before the call.

WINDOWS USERS: Because of restrictions directly calling the script may not always work. In such a case, a batch file may be provided, which then in turn executes the script. Please refer to doc/extcap_example.py for more information.

When Wireshark launches an extcap, it automatically adds its installation path (normally C:\Program Files\Wireshark\) to the DLL search path so that the extcap library dependencies can be found (it is not designed to be launched by hand). This is done on purpose. There should only be extcap programs (executables, Python scripts, ...) in the extcap folder to reduce the startup time and not have Wireshark trying to execute other file types.

## GRAMMAR ELEMENTS
Grammar elements:

arg (options)

argument for CLI calling

number

Reference # of argument for other values, display order

call

Literal argument to call (--call=...)

display

Displayed name

default

Default value, in proper form for type

range

Range of valid values for UI checking (min,max) in proper form

type

Argument type for UI filtering for raw, or UI type for selector:

```
integer
unsigned
long (may include scientific / special notation)
double
string (display a textbox)
selector (display selector table, all values as strings)
editselector (selector table which can be overridden, all values as strings)
boolean (display checkbox)
booleanflag (display checkbox)
radio (display group of radio buttons with provided values, all values as strings)
fileselect (display a dialog to select a file from the filesystem, value as string)
multicheck (display a textbox for selecting multiple options, values as strings)
table (display a table that is populated by the user, selections can be configured, values as commandlines arguments)
password (display a textbox with masked text)
timestamp (display a calendar)
```

value (options)

```
Values for argument selection
arg     Argument # this value applies to
```

## EXAMPLES
Example 1:

```
arg {number=0}{call=--channel}{display=Wi-Fi Channel}{type=integer}{required=true}
arg {number=1}{call=--chanflags}{display=Channel Flags}{type=radio}
arg {number=2}{call=--interface}{display=Interface}{type=selector}
value {arg=0}{range=1,11}
value {arg=1}{value=ht40p}{display=HT40+}
value {arg=1}{value=ht40m}{display=HT40-}
value {arg=1}{value=ht20}{display=HT20}
value {arg=2}{value=wlan0}{display=wlan0}
```

Example 2:

```
arg {number=0}{call=--usbdevice}{USB Device}{type=selector}
value {arg=0}{call=/dev/sysfs/usb/foo/123}{display=Ubertooth One sn 1234}
value {arg=0}{call=/dev/sysfs/usb/foo/456}{display=Ubertooth One sn 8901}
```

Example 3:

```
arg {number=0}{call=--usbdevice}{USB Device}{type=selector}
arg {number=1}{call=--server}{display=IP address for log server}{type=string}{validation=(?:\d{1,3}\.){3}\d{1,3}}
flag {failure=Permission denied opening Ubertooth device}
```

Example 4:

```
arg {number=0}{call=--username}{display=Username}{type=string}
arg {number=1}{call=--password}{display=Password}{type=password}
```

Example 5: timestamp

```
arg {number=0}{call=--start}{display=Start Time}{type=timestamp}
arg {number=1}{call=--end}{display=End Time}{type=timestamp}
```

Example 6: multicheck

```
arg {number=0}{call=--device}{display=Device}{type=multicheck}
value {arg=0}{value=USBDEV}{display=USB devices}{enabled=false}
value {arg=0}{value=/dev/sysfs/usb/foo/123}{display=Ubertooth One sn 1234}{parent=USBDEV}
value {arg=0}{value=/dev/sysfs/usb/foo/456}{display=Ubertooth One sn 8901}{parent=USBDEV}
value {arg=0}{value=PCIDEV}{display=PCI devices}{enabled=false}
value {arg=0}{value=/sys/devices/pci123}{display=Device 1}{parent=PCIDEV}
value {arg=0}{value=/sys/devices/pci456}{display=Device 2}{parent=PCIDEV}
```

## TABLE FIELD
The "table" field is a bit different, in that its values can have additional configuration options. The values can either be entered manually by the user, or a list of available values can be provided using the same API as "multicheck". Unlike most APIs, the value is provided using a commandline-like API, separated by spaces instead of comas. For instance, a configured "myparam" attribute where the user selected three values (1, 2 and 3) would receive:

```
--myparam "1 2 3"
```

If a "prefix" is configured to be "--p", it would receive the following:

```
--myparam "--p 1 --p 2 --p 3"
```

The values selected in a table field may have specific configuration options, if "configurable=true" for the "multicheck" field. In this case, the extcap will be called again when the user presses the configuration wheel that matches a value in the table, with the additional "--extcap-config-option-name <option_name> --extcap-config-option-value <option_value>" with no prefix. An extcap program should respond with an additional set of arguments, which will be opened in a popup. Once those are configured, the extcap might get the following, assuming for instance that an additional "param1" is requested when value is 1, and "param2" when value is 2.

```
--myparam "--p 1 --param1 1 --p 2 --param2 true --p 3"
```

## SECURITY CONSIDERATIONS
•If you’re running Wireshark as root, we can’t save you.

•Dumpcap retains suid/setgid and group execute permissions for users in the “wireshark” group only.

•Third-party capture programs run with whatever privileges they’re installed with.

•If an attacker can write to a system binary directory, it’s game over.

•You can find your local extcap directory in About › Folders.

## SEE ALSO
wireshark(1), tshark(1), dumpcap(1), androiddump(1), sshdig(1), sshdump(1), randpktdump(1)

## NOTES
Extcap is feature of Wireshark. The latest version of Wireshark can be found at <https://www.wireshark.org>.

HTML versions of the Wireshark project man pages are available at <https://www.wireshark.org/docs/man-pages>.