pmc(8): PTP management client

pmc-ptpmgmt: PTP management client

SYNOPSIS

pmc-ptpmgmt [ -f config-file ] [ -2 | -4 | -6 | -u ] [ -b boundary-hops ] [ -d domain-number ] [ -i interface ] [ -s uds-address ] [ -t transport-specific-field ] [ long-options ] [ -v ] [ -z ] [ command ] …

DESCRIPTION

pmc-ptpmgmt is a program which implements a PTP management client according to IEEE standard 1588. The program reads from the standard input or from the command line actions specified by name and management ID, sends them over the selected transport and prints any received replies. There are three actions supported:

GET: retrieves the specified information,
SET: updates the specified information and
CMD (COMMAND): initiates the specified event.

By default the management commands are addressed to all ports. The TARGET command can be used to select a particular clock and port for the subsequent messages.

Command help can be used to get a list of supported actions and management IDs.

OPTIONS

-f config-file: Read configuration from the specified file. No configuration file is read by default.
-2: Select the IEEE 802.3 network transport.
-4

Select the UDP IPv4 network transport. This is the default transport.

-6: Select the UDP IPv6 network transport.
-u: Select the Unix Domain Socket transport.
-b boundary-hops: Specify the boundary hops value in sent messages. The default is 1.
-d domain-number: Specify the domain number in sent messages. The default is 0.
-i interface: Specify the network interface. The default for Unix Domain Sockets is /var/run/pmc.$pid for root user and /var/run/user/$uid/pmc.$pid for other users.
-s uds-address: Specifies the address of the server’s UNIX domain socket. The default is /var/run/ptp/ptp4l.
-t transport-specific-field: Specify the transport specific field in sent messages as a hexadecimal number. The default is 0x0.
-h: Display a help message.
-v: Prints the libptpmgmt version and exits.
-z: The official interpretation of the 1588 standard mandates sending GET actions with valid (but meaningless) TLV values. Therefore the pmc program normally sends GET requests with properly formed TLV values. This option enables the legacy option of sending zero length TLV values instead.

LONG OPTIONS

Each and every configuration file option (see below in sections PROGRAM OPTIONS and PORT OPTIONS) may also appear as a “long” style command line argument. For example, the transportSpecific option may be set using either of these two forms:

--transportSpecific 1

--transportSpecific=1

Option values given on the command line override values in the global section of the configuration file (which, in turn, overrides default values).

CONFIGURATION FILE

The configuration file is divided into sections. Each section starts with a line containing its name enclosed in brackets and it follows with settings. Each setting is placed on a separate line, it contains the name of the option and the value separated by whitespace characters. Empty lines and lines starting with # are ignored.

The global section (indicated as [global]) sets the global program options as well as the default port specific options. Other sections are port specific sections and they override the default port options. The name of the section is the name of the configured port (e.g. [enp0s25]).

PROGRAM OPTIONS

domainNumber: The domain attribute of the local clock. The default is 0.
sa_file: Specifies the location of the file containing Security Associations used for immediate security processing of the Authentication TLV in support of the optional security mechanism defined in ieee1588-2019 ch 14.16. See SECURITY ASSOCIATION OPTIONS in ptp4l(8) for information on how this file should be formatted. spp and active_key_id should be specifed for each port to indicate which Security Association from the sa_file should be used. The default is an empty string.
socket_priority: Configure the SO_PRIORITY of sockets. This is to support cases where a user wants to route pmc traffic using Linux qdiscs for the purpose of traffic shaping. This option is only available with the IEEE 802.3 transport (the -2 option) and is silently ignored when using the UDP IPv4/6 network transports. Must be in the range of 0 to 15, inclusive. The default is 0.
udp6_scope: Specifies the desired scope for the IPv6 multicast messages. This will be used as the second byte of the primary address. This option is only relevant with IPv6 transport. See RFC 4291. The default is 0x0E for the global scope.
uds_address: Specifies the address of the server’s UNIX domain socket, same as the -s option.

PORT OPTIONS

active_key_id

Used in conjunction with spp and sa_file directives to specify which key from the spp defined Security Association should be used for outbound icv calculations. All Security Assocations are read from the file specified by sa_file. Requires spp and sa_file directives. Must be in the range of 1 to 2^{^32}-1, inclusive. The default is 0 (disabled).

allow_unauth

Allows for pmc to accept unauthenticated management response and signaling messages when authentication is enabled and spp, active_key_id and sa_file are set. Possible values are:

0: normal receiving

1: accept mgmt resp/signaling without Authentication TLV

2: accept mgmt resp/signaling without Authentication TLV or with wrong Authentication TLV

The default is 0 (disabled).

network_transport: Select the network transport. Possible values are UDPv4, UDPv6, and L2. The default is UDPv4.
spp: Specifies the Security Parameters Pointer of the desired Security Association to be used for Authentication TLV support for a given port. Any port with an assigned spp will attach Authentication TLVs to all outbound messages and check for Authentication TLVs on all inbound messages in accordance to the corresponding security association sourced via the sa_file directive. Outbound Authentication TLVs are generated using the key specified by active_key_id. Not compatible with one step ports or advertised versions less then PTPv2.1. Requires sa_file and active_key_id directives. Must be in the range of 0 to 255, inclusive. The default is -1 (disabled).
ptp_dst_mac: The MAC address to which PTP management messages should be sent. Relevant only with L2 transport. The default is 01:1B:19:00:00:00.
transportSpecific: The transport specific field. Must be in the range 0 to 255. The default is 0.
udp_ttl: Specifies the Time to live (TTL) value for IPv4 multicast messages and the hop limit for IPv6 multicast messages. This option is only relevant with the IPv4 and IPv6 UDP transports. The default is 1 to restrict the messages sent by ptp4l to the same subnet.

MANAGEMENT IDS

pmc-ptpmgmt supports all PTP version 2 (IEEE Std 1588-2019) Management TLVs and those specific to the linuxptp implementation. Though build of GRANDMASTER_CLUSTER_TABLE, UNICAST_MASTER_TABLE, and ACCEPTABLE_MASTER_TABLE are not supported as they use tables.

WARNING

Be cautious when the same configuration file is used for both ptp4l and pmc. Keep in mind that values specified in the configuration file take precedence over their default values. If a certain option which is common to ptp4l and pmc is specified to a non-default value in the configuration file (e.g. for ptp4l), then this non-default value applies also for pmc. This might be not what is expected.

To avoid securely this unexpected behaviour, different configuration files for ptp4l and pmc are recommended.