title: ptp4l(8)

text:
# ptp4l(8)

## NAME
ptp4l - PTP Boundary/Ordinary/Transparent Clock

## SYNOPSIS
ptp4l [ -AEP246HSLmqsv ] [ -f config ] [ -p phc-device ] [ -l print-level ] [ -i interface ] [ long-options ] ...

## DESCRIPTION
ptp4l is an implementation of the Precision Time Protocol (PTP) according to IEEE standard 1588 for Linux. It implements Boundary Clock (BC), Ordinary Clock (OC), and Transparent Clock (TC).

## OPTIONS
-A

Select the delay mechanism automatically. Start with E2E and switch to P2P when a peer delay request is received.

-E

Select the delay request-response (E2E) mechanism. This is the default mechanism. All clocks on single PTP communication path must use the same mechanism. A warning will be printed when a peer delay request is received on port using the E2E mechanism.

-P

Select the peer delay (P2P) mechanism. A warning will be printed when a delay request is received on port using the P2P mechanism.

-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.

-H

Select the hardware time stamping. All ports specified by the -i option and in the configuration file must be attached to the same PTP hardware clock (PHC). This is the default time stamping.

-S

Select the software time stamping.

-L

Select the legacy hardware time stamping.

-f config

Read configuration from the specified file. No configuration file is read by default.

-i interface

Specify a PTP port, it may be used multiple times. At least one port must be specified by this option or in the configuration file.

-p phc-device

(This option is deprecated.) Before Linux kernel v3.5 there was no way to discover the PHC device associated with a network interface. This option specifies the PHC device (e.g. /dev/ptp0) to be used when running on legacy kernels.

-s

Enable the clientOnly mode.

-l print-level

Set the maximum syslog level of messages which should be printed or sent to the system logger. The default is 6 (LOG_INFO).

-m

Print messages to the standard output.

-q

Don't send messages to the system logger.

-v

Prints the software version and exits.

-h

Display a help message.

## LONG OPTIONS
Each and every configuration file option (see below) may also appear as a "long" style command line argument. For example, the clientOnly option may be set using either of these two forms.

--clientOnly 1 --clientOnly=1

Option values given on the command line override values in the global section of the configuration file.

## 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.

There are three different section types.

1.

The global section (indicated as [global]) sets the program options, clock options and default port options. Other sections are port specific sections and they override the default port options.

2.

Port sections give the name of the configured port (e.g. [eth0]). Ports specified in the configuration file don't need to be specified by the -i option. An empty port section can be used to replace the command line option.

3.

Tables for configuring unicast discovery begin with [unicast_master_table]. See UNICAST DISCOVERY OPTIONS, below.

## PORT OPTIONS
announceReceiptTimeout

The number of missed Announce messages before the last Announce messages expires. The default is 3.

boundary_clock_jbod

When running as a boundary clock (that is, when more than one network interface is configured), ptp4l performs a sanity check to make sure that all of the ports share the same hardware clock device. This option allows ptp4l to work as a boundary clock using "just a bunch of devices" that are not synchronized to each other. For this mode, the collection of clocks must be synchronized by an external program, for example phc2sys(8) in "automatic" mode. The default is 0 (disabled).

delayAsymmetry

The time difference in nanoseconds of the transmit and receive paths. This value should be positive when the server-to-client propagation time is longer and negative when the client-to-server time is longer. The default is 0 nanoseconds.

delay_filter

Select the algorithm used to filter the measured delay and peer delay. Possible values are moving_average and moving_median. The default is moving_median.

delay_filter_length

The length of the delay filter in samples. The default is 10.

delay_mechanism

Select the delay mechanism. Possible values are E2E, P2P, NONE and Auto. The default is E2E.

delay_response_timeout

The number of delay response messages that may go missing before triggering a synchronization fault. Setting this option to zero will disable the delay response timeout. The default is 0 or disabled.

egressLatency

Specifies the difference in nanoseconds between the actual transmission time at the reference plane and the reported transmit time stamp. This value will be added to egress time stamps obtained from the hardware. The default is 0.

fault_badpeernet_interval

The time in seconds between the detection of a peer network misconfiguration and the fault being reset. The port is disabled for the duration of the interval. The value is in seconds and the special key word ASAP will let the fault be reset immediately. The default is 16 seconds.

fault_reset_interval

The time in seconds between the detection of a port's fault and the fault being reset. This value is expressed as a power of two. Setting this value to -128 or to the special key word "ASAP" will let the fault be reset immediately. The default is 4 (16 seconds).

follow_up_info

Include the 802.1AS data in the Follow_Up messages if enabled. The default is 0 (disabled).

G.8275.portDS.localPriority

The Telecom Profiles (ITU-T G.8275.1 and G.8275.2) specify an alternate Best Master Clock Algorithm (BMCA) with a unique data set comparison algorithm. The value of this option is associated with Announce messages arriving on a particular port and is used as a tie breaker whenever clockClass, clockAccuracy, offsetScaledLogVariance, and priority2 are equal. This option is only used when "dataset_comparison" is set to "G.8275.x". The default value is 128. Warning: the BMCA is guaranteed to produce a spanning tree (that is, a timing network without loops) only when using the default values of G.8275.defaultDS.localPriority and G.8275.portDS.localPriority. Careful network engineering is needed when using non-default values.

hybrid_e2e

Enables the "hybrid" delay mechanism from the draft Enterprise Profile. When enabled, ports in the client state send their delay request messages to the unicast address taken from the server's announce message. Ports in the server state will reply to unicast delay requests using unicast delay responses. This option has no effect if the delay_mechanism is set to P2P. The default is 0 (disabled).

ignore_transport_specific

By default, incoming messages are dropped if their transportSpecific field does not match the configured value. However, many of transports specified in the 1588 standard mandate ignoring this field. Moreover, some equipment is known to set the reserved bits. Configuring this option as 1 causes this field to be ignored completely on receive. The default is 0.

ingressLatency

Specifies the difference in nanoseconds between the reported receive time stamp and the actual reception time at reference plane. This value will be subtracted from ingress time stamps obtained from the hardware. The default is 0.

inhibit_delay_req

Don't send any delay requests. This will need the asCapable config option to be set to 'true'. This is useful when running as a designated server who does not need to calculate offset from client. The default is 0 (disabled).

inhibit_multicast_service

Some unicast mode profiles insist that no multicast message are ever transmitted. Setting this option inhibits multicast transmission. The default is 0 (mutlicast enabled).

logAnnounceInterval

The mean time interval between Announce messages. A shorter interval makes ptp4l react faster to the changes in the client/server hierarchy. The interval should be the same in the whole domain. It's specified as a power of two in seconds. The default is 1 (2 seconds).

logMinDelayReqInterval

The minimum permitted mean time interval between Delay_Req messages. A shorter interval makes ptp4l react faster to the changes in the path delay. It's specified as a power of two in seconds. The default is 0 (1 second).

logMinPdelayReqInterval

The minimum permitted mean time interval between Pdelay_Req messages. It's specified as a power of two in seconds. The default is 0 (1 second).

logSyncInterval

The mean time interval between Sync messages. A shorter interval may improve accuracy of the local clock. It's specified as a power of two in seconds. The default is 0 (1 second).

masterOnly

This option is deprecated and will be removed in a future release. Use "serverOnly" instead.

min_neighbor_prop_delay

Lower limit for peer delay in nanoseconds. If the estimated peer delay is smaller than this value the port is marked as not 802.1AS capable.

neighborPropDelayThresh

Upper limit for peer delay in nanoseconds. If the estimated peer delay is greater than this value the port is marked as not 802.1AS capable.

network_transport

Select the network transport. Possible values are UDPv4, UDPv6 and L2. The default is UDPv4.

net_sync_monitor

Enables the NetSync Monitor (NSM) protocol. The NSM protocol allows a station to measure how well another node is synchronized. The monitor sends a unicast delay request to the node, which replies unconditionally with unicast delay response, sync, and follow up messages. If the monitor is synchronized to the GM, it can use the time stamps in the message to estimate the node's offset. This option requires that the 'hybrid_e2e' option be enabled as well. The default is 0 (disabled).

operLogPdelayReqInterval

The Pdelay Request messages interval to be used once the clock enters the SERVO_LOCKED_STABLE state. If the 'msg_interval_request' option is set, then the local client port will adopt this rate when the local clock enters the "locked stable" state. This option is specified as a power of two in seconds, and the default value is 0 (1 second).

operLogSyncInterval

The Sync message interval to be requested once the clock enters the SERVO_LOCKED_STABLE state. If the 'msg_interval_request' option is set, then the local client port will request the remote server to switch to the given message rate via a signaling message containing a Message interval request TLV. This option is specified as a power of two in seconds, and default value is 0 (1 second).

path_trace_enabled

Enable the mechanism used to trace the route of the Announce messages. The default is 0 (disabled).

phc_index

Specifies the index of the PHC to be used for synchronization with hardware timestamping. This option is useful with virtual clocks running on top of a free-running physical clock (created by writing to /sys/class/ptp/ptp*/n_vclocks). The default is -1, which means the index will be set to the PHC associated with the interface, or the device specified by the -p option.

power_profile.2011.grandmasterTimeInaccuracy

Specifies the time inaccuracy of the GM in nanoseconds. Relevant only when power_profile.version is 2011. This value may be changed dynamically using the POWER_PROFILE_SETTINGS_NP management message. The default is -1 meaning unknown inaccuracy.

power_profile.2011.networkTimeInaccuracy

Specifies the time inaccuracy of the network in nanoseconds. Relevant only when power_profile.version is 2011. This value may be changed dynamically using the POWER_PROFILE_SETTINGS_NP management message. The default is -1 meaning unknown inaccuracy.

power_profile.2017.totalTimeInaccuracy

Specifies the sum of the GM, network, and local node inaccuracies in nanoseconds. Relevant only when power_profile.version is 2017. This value may be changed dynamically using the POWER_PROFILE_SETTINGS_NP management message. The default is -1 meaning unknown inaccuracy.

power_profile.grandmasterID

Specifies an optional, non-zero identification code for the GM. Note that the code is an arbitrary, power profile specific integer, not necessarily related to the clockIdentity in any way. This value may be changed dynamically using the POWER_PROFILE_SETTINGS_NP management message. The default is 0 meaning unused.

power_profile.version

Specifies the power profile version to be used. Valid values are "none", "2011", or "2017". This value may be changed dynamically using the POWER_PROFILE_SETTINGS_NP management message. The default is "none".

ptp_dst_mac

The MAC address to which PTP messages should be sent. Relevant only with L2 transport. The default is 01:1B:19:00:00:00.

p2p_dst_mac

The MAC address to which peer delay messages should be sent. Relevant only with L2 transport. The default is 01:80:C2:00:00:0E.

serverOnly

Setting this option to one (1) prevents the port from entering the client state. In addition, the local clock will ignore Announce messages received on this port. This option's intended use is to support the Telecom Profiles according to ITU-T G.8265.1, G.8275.1, and G.8275.2. The default value is zero or false.

syncReceiptTimeout

The number of sync/follow up messages that may go missing before triggering a Best Master Clock election. This option is used for running in gPTP mode according to the 802.1AS-2011 standard. Setting this option to zero will disable the sync message timeout. The default is 0 or disabled.

transportSpecific

The transport specific field. Must be in the range 0 to 255. The default is 0.

tsproc_mode

Select the time stamp processing mode used to calculate offset and delay. Possible values are filter, raw, filter_weight, raw_weight. Raw modes perform well when the rate of sync messages (logSyncInterval) is similar to the rate of delay messages (logMinDelayReqInterval or logMinPdelayReqInterval). Weighting is useful with larger network jitters (e.g. software time stamping). The default is filter.

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.

unicast_listen

When enabled, this option allows the port to grant unicast message contracts. Incoming requests for will be granted limited only by the amount of memory available. The default is 0 (disabled).

unicast_master_table

When set to a positive integer, this option specifies the table id to be used for unicast discovery. Each table lives in its own section and has a unique, positive numerical ID. Entries in the table are a pair of transport type and protocol address. The default is 0 (unicast discovery disabled).

unicast_req_duration

The service time in seconds to be requested during unicast discovery. Note that the remote node is free to grant a different duration. The default is 3600 seconds or one hour.

## PROGRAM AND CLOCK OPTIONS
asCapable

If set to 'true', all the checks which can unset asCapable variable (as described in Section 10.2.4.1 of 802.1AS) are skipped. If set to 'auto', asCapable is initialized to 'false' and will be set to 'true' after the relevant checks have passed. The default value is 'auto'.

assume_two_step

Treat one-step responses as two-step if enabled. It is used to work around buggy 802.1AS switches. The default is 0 (disabled).

BMCA

This option enables use of static roles for server and client devices instead of running the best master clock algorithm (BMCA) described in 1588 profile. This can be used to speed up the start time for servers and clients when you know the roles of the devices in advance. When set to ´noop', the traditional BMCA algorithm used by 1588 is skipped. masterOnly and clientOnly will be used to determine the server or client role for the device. In a bridge, clientOnly (which is a global option) can be set to make all ports assume the client role. masterOnly (which is a per-port config option) can then be used to set individual ports to take on the server role. The default value is 'ptp' which runs the BMCA related state machines.

check_fup_sync

Because of packet reordering that can occur in the network, in the hardware, or in the networking stack, a follow up message can appear to arrive in the application before the matching sync message. As this is a normal occurrence, and the sequenceID message field ensures proper matching, the ptp4l program accepts out of order packets. This option adds an additional check using the software time stamps from the networking stack to verify that the sync message did arrive first. This option is only useful if you do not trust the sequence IDs generated by the server. The default is 0 (disabled).

clientOnly

The local clock is a client-only clock if enabled. The default is 0 (disabled).

clockAccuracy

The clockAccuracy attribute of the local clock. It is used in the PTP server selection algorithm. The default is 0xFE.

clockClass

The clockClass attribute of the local clock. It denotes the traceability of the time distributed by the grandmaster clock. The default is 248.

clock_class_threshold

The maximum clock class value from master, acceptible to sub-ordinate clock beyond which it moves out of lock state. The default value is 248.

clockIdentity

The clockIdentity attribute of the local clock. The clockIdentity is an 8-octet array and should in this configuration be written in textual form, see default. It should be unique since it is used to identify the specific clock. If default is used or if not set at all, the clockIdentity will be automtically generated. The default is "000000.0000.000000"

clock_servo

The servo which is used to synchronize the local clock. Valid values are "pi" for a PI controller, "linreg" for an adaptive controller using linear regression, "ntpshm" and "refclock_sock" for the NTP SHM and chrony SOCK reference clocks respectively to allow another process to synchronize the local clock, and "nullf" for a servo that always dials frequency offset zero (for use in SyncE nodes). The default is "pi."

clock_type

Specifies the kind of PTP clock. Valid values are "OC" for ordinary clock, "BC" for boundary clock, "P2P_TC" for peer to peer transparent clock, and "E2E_TC" for end to end transparent clock. An multi-port ordinary clock will automatically be configured as a boundary clock. The default is "OC".

dataset_comparison

Specifies the method to be used when comparing data sets during the Best Master Clock Algorithm. The possible values are "ieee1588" and "G.8275.x". The default is "ieee1588".

domainNumber

The domain attribute of the local clock. The default is 0.

dscp_event

Defines the Differentiated Services Codepoint (DSCP) to be used for PTP event messages. Must be a value between 0 and 63. There are several media streaming standards out there that require specific values for this option. For example 46 (EF PHB) in AES67 or 48 (CS6 PHB) in RAVENNA. The default is 0.

dscp_general

Defines the Differentiated Services Codepoint (DSCP) to be used for PTP general messages. Must be a value between 0 and 63. There are several media streaming standards out there that recommend specific values for this option. For example 34 (AF41 PHB) in AES67 or 46 (EF PHB) in RAVENNA. The default is 0.

first_step_threshold

The maximum offset the servo will correct by changing the clock frequency (phase when using nullf servo) instead of stepping the clock. This is only applied on the first update. It's specified in seconds. When set to 0.0, the servo won't step the clock on start. The default is 0.00002 (20 microseconds). This option used to be called pi_f_offset_const.

free_running

Don't adjust the local clock if enabled. The default is 0 (disabled).

freq_est_interval

The time interval over which is estimated the ratio of the local and peer clock frequencies. It is specified as a power of two in seconds. The default is 1 (2 seconds).

G.8275.defaultDS.localPriority

The Telecom Profiles (ITU-T G.8275.1 and G.8275.2) specify an alternate Best Master Clock Algorithm (BMCA) with a unique data set comparison algorithm. The value of this option is associated with the local clock and is used as a tie breaker whenever clockClass, clockAccuracy, offsetScaledLogVariance, and priority2 are equal. This option is only used when "dataset_comparison" is set to "G.8275.x". The default value is 128. Warning: the BMCA is guaranteed to produce a spanning tree (that is, a timing network without loops) only when using the default values of G.8275.defaultDS.localPriority and G.8275.portDS.localPriority. Careful network engineering is needed when using non-default values.

gmCapable

If this option is enabled, then the local clock is able to become grand master. This is only for use with 802.1AS clocks and has no effect on 1588 clocks. The default is 1 (enabled).

ignore_source_id

This will disable source port identity checking for Sync and Follow_Up messages. This is useful when the announce messages are disabled in the server and the client does not have any way to know the server's identity. The default is 0 (disabled).

inhibit_announce

This will disable the timer for announce messages (i.e. FD_MANNO_TIMER) and also the announce message timeout timer (i.e. FD_ANNOUNCE_TIMER). This is used by the Automotive profile as part of switching over to a static BMCA. If this option is enabled, ignore_source_id has to be enabled in the client because it has no way to identify the server in the Sync and Follow_Up messages. The default is 0 (disabled).

initial_delay

The initial path delay of the clock in nanoseconds used for synchronization of the clock before the delay is measured using the E2E or P2P delay mechanism. If set to 0, the clock will not be updated until the delay is measured. The default is 0.

interface_rate_tlv

When the client and server are operating are operating at different interface rate, delay asymmetry caused due to different interface rate needs to be compensated. The server sends its interface rate using interface rate TLV as per G.8275.2 Annex D. The default is 0 (does not support interface rate tlv).

hwts_filter

Select the hardware time stamp filter setting mode. Possible values are normal, check, full. Normal mode set the filters as needed. Check mode only check but do not set. Full mode set the receive filter to mark all packets with hardware time stamp,

so all applications can get them. The default is normal.

kernel_leap

When a leap second is announced, let the kernel apply it by stepping the clock instead of correcting the one-second offset with servo, which would correct the one-second offset slowly by changing the clock frequency (unless the step_threshold option is set to correct such offset by stepping). Relevant only with software time stamping. The default is 1 (enabled).

logging_level

The maximum logging level of messages which should be printed. The default is 6 (LOG_INFO).

manufacturerIdentity

The manufacturer id which should be an OUI owned by the manufacturer. The default is 00:00:00.

max_frequency

The maximum allowed frequency adjustment of the clock in parts per billion (ppb). This is an additional limit to the maximum allowed by the hardware. When set to 0, the hardware limit will be used. The default is 900000000 (90%). This option used to be called pi_max_frequency.

maxStepsRemoved

When using this option, if the value of stepsRemoved of an Announce message is greater than or equal to the value of maxStepsRemoved the Announce message is not considered in the operation of the BMCA. The default value is 255.

message_tag

The tag which is added to all messages printed to the standard output or system log. If the tag contains the string "{level}", it will be replaced with the log level of the message as a number. The default is an empty string (which cannot be set in the configuration file as the option requires an argument).

msg_interval_request

This option, when set, will trigger an adjustment to the Sync and peer delay request message intervals when the clock servo transitions into the SERVO_LOCKED_STABLE state. The Sync interval will be adjusted via the signaling mechanism while the pdelay request interval is simply adjusted locally. The values to use for the new Sync and peer delay request intervals are specified by the operLogSyncInterval and operLogPdelayReqInterval options, respectively. The default value of msg_interval_request is 0 (disabled).

ntpshm_segment

The number of the SHM segment used by ntpshm servo. The default is 0.

offsetScaledLogVariance

The offsetScaledLogVariance attribute of the local clock. It characterizes the stability of the clock. The default is 0xFFFF.

pi_integral_const

The integral constant of the PI controller. When set to 0.0, the integral constant will be set by the following formula from the current sync interval. The default is 0.0. ki = min(ki_scale * sync^ki_exponent, ki_norm_max / sync)

pi_integral_exponent

The ki_exponent constant in the formula used to set the integral constant of the PI controller from the sync interval. The default is 0.4.

pi_integral_norm_max

The ki_norm_max constant in the formula used to set the integral constant of the PI controller from the sync interval. The default is 0.3.

pi_integral_scale

The ki_scale constant in the formula used to set the integral constant of the PI controller from the sync interval. When set to 0.0, the value will be selected from 0.3 and 0.001 for the hardware and software time stamping respectively. The default is 0.0.

pi_proportional_const

The proportional constant of the PI controller. When set to 0.0, the proportional constant will be set by the following formula from the current sync interval. The default is 0.0. kp = min(kp_scale * sync^kp_exponent, kp_norm_max / sync)

pi_proportional_exponent

The kp_exponent constant in the formula used to set the proportional constant of the PI controller from the sync interval. The default is -0.3.

pi_proportional_norm_max

The kp_norm_max constant in the formula used to set the proportional constant of the PI controller from the sync interval. The default is 0.7

pi_proportional_scale

The kp_scale constant in the formula used to set the proportional constant of the PI controller from the sync interval. When set to 0.0, the value will be selected from 0.7 and 0.1 for the hardware and software time stamping respectively. The default is 0.0.

productDescription

The product description string. Allowed values must be of the form manufacturerName;modelNumber;instanceIdentifier and contain at most 64 utf8 symbols. The default is ";;".

priority1

The priority1 attribute of the local clock. It is used in the PTP server selection algorithm, lower values take precedence. Must be in the range 0 to 255. The default is 128.

priority2

The priority2 attribute of the local clock. It is used in the PTP server selection algorithm, lower values take precedence. Must be in the range 0 to 255. The default is 128.

ptp_minor_version

This option sets the minorVersionPTP in the common PTP message header. The default is 1.

refclock_sock_address

The address of the UNIX domain socket to be used by the refclock_sock servo. The default is /run/refclock.ptp.sock.

revisionData

The revision description string which contains the revisions for node hardware (HW), firmware (FW), and software (SW). Allowed values are of the form HW;FW;SW and contain at most 32 utf8 symbols. The default is an ";;".

sanity_freq_limit

The maximum allowed frequency offset between uncorrected clock and the system monotonic clock in parts per billion (ppb). This is used as a sanity check of the synchronized clock. When a larger offset is measured, a warning message will be printed and the servo will be reset. If the frequency correction set by ptp4l changes unexpectedly between updates of the clock (e.g. due to another process trying to control the clock), a warning message will be printed. When set to 0, the sanity check is disabled. The default is 200000000 (20%).

servo_num_offset_values

The number of offset values considered in order to transition from the SERVO_LOCKED to the SERVO_LOCKED_STABLE state. The transition occurs once the last 'servo_num_offset_values' offsets are all below the 'servo_offset_threshold' value. The default value is 10.

servo_offset_threshold

The offset threshold used in order to transition from the SERVO_LOCKED to the SERVO_LOCKED_STABLE state. The transition occurs once the last 'servo_num_offset_values' offsets are all below the threshold value. The default value of offset_threshold is 0 (disabled).

slave_event_monitor

Specifies the address of a UNIX domain socket for event monitoring. A local monitoring client bound to this address will receive SLAVE_RX_SYNC_TIMING_DATA and SLAVE_DELAY_TIMING_DATA_NP TLVs. The default is the empty string (disabled).

slaveOnly

This option is deprecated and will be removed in a future release. Use "clientOnly" instead.

socket_priority

Configure the SO_PRIORITY of sockets. This is to support cases where a user wants to route ptp4l 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.

step_threshold

The maximum offset the servo will correct by changing the clock frequency (phase when using nullf servo) instead of stepping the clock. When set to 0.0, the servo will never step the clock except on start. It's specified in seconds. The default is 0.0. This option used to be called pi_offset_const.

step_window

When set, indicates the number of Sync events after a clock step that the clock will not do any frequency or step adjustments. This is used in situations where clock stepping is unable to happen instantaneously so there is a lag before the timestamps can settle properly to reflect the clock step. The default is 0 (disabled).

summary_interval

The time interval in which are printed summary statistics of the clock. It is specified as a power of two in seconds. The statistics include offset root mean square (RMS), maximum absolute offset, frequency offset mean and standard deviation, and path delay mean and standard deviation. The units are nanoseconds and parts per billion (ppb). If there is only one clock update in the interval, the sample will be printed instead of the statistics. The messages are printed at the LOG_INFO level. The default is 0 (1 second).

tc_spanning_tree

When running as a Transparent Clock, increment the "stepsRemoved" field of Announce messages that pass through the switch. Enabling this option ensures that PTP message loops never form, provided the switches all implement this option together with the BMCA.

timeSource

The time source is a single byte code that gives an idea of the kind of local clock in use. The value is purely informational, having no effect on the outcome of the Best Master Clock algorithm, and is advertised when the clock becomes grand master.

time_stamping

The time stamping method to be used. The allowed values are hardware, software, legacy, onestep, and p2p1step. The default is hardware.

twoStepFlag

Enable two-step mode for sync messages. One-step mode can be used only with hardware time stamping. The default is 1 (enabled).

tx_timestamp_timeout

The number of milliseconds to poll waiting for the tx time stamp from the kernel when a message has recently been sent. The default is 10.

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 UNIX domain socket for receiving local management messages. The default is /run/ptp4l.

uds_file_mode

File mode of the UNIX domain socket used for receiving local management messages. The mode should be specified as an octal number, i.e. it should start with a 0 literal. The default mode is 0660.

uds_ro_address

Specifies the address of the second UNIX domain socket for receiving local management messages, which is restricted to GET actions and does not forward messages to other ports. Access to this socket can be given to untrusted applications for monitoring purposes. The default is /run/ptp4lro.

uds_ro_file_mode

File mode of the second (read-only) UNIX domain socket used for receiving local management messages. The mode should be specified as an octal number, i.e. it should start with a 0 literal. The default mode is 0666.

use_syslog

Print messages to the system log if enabled. The default is 1 (enabled).

userDescription

The user description string. Allowed values are of the form name;location and contain at most 128 utf8 symbols. The default is an empty string.

utc_offset

The current offset between TAI and UTC. The default is 37.

verbose

Print messages to the standard output if enabled. The default is 0 (disabled).

write_phase_mode

This option enables using the "write phase" feature of a PTP Hardware Clock. If supported by the device, this mode uses the hardware's built in phase offset control instead of frequency offset control. The default value is 0 (disabled).

## UNICAST DISCOVERY OPTIONS
L2|UDPv4|UDPv6

Each table entry specifies the transport type and network address of a potential remote server. If multiple servers are specified, then unicast negotiation will be performed with each if them.

logQueryInterval

This option configures the time to wait between unicast negotiation attempts. It is specified as a power of two in seconds. The default is 0 (1 second).

peer_address

This option specifies the unicast address of the peer for use with the peer to peer delay mechanism. If specified, the port owning the table will negotiate unicast peer delay responses from the machine at the given remote address, otherwise the port will send multicast peer delay requests.

table_id

Each table must begin with a unique, positive table ID. The port that claims a given table does so by including the ID as the value of its 'unicast_master_table' option.

## TIME SCALE USAGE
When ptp4l acts as the domain server, it either uses the PTP or the UTC time scale depending on time stamping mode. In software and legacy time stamping modes it announces Arbitrary time scale mode, which is effectively UTC here. In hardware time stamping mode it announces use of PTP time scale.

When ptp4l is the domain server using hardware time stamping, it is up to phc2sys to maintain the correct offset between UTC and PTP times. See phc2sys(8) manual page for more details.

## KTHREAD PRIORITY
In case of following log,

timed out while polling for tx timestamp increasing tx_timestamp_timeout or increasing kworker priority may correct this issue, but a driver bug likely causes it

one possible cause is that the kworker which processes timestamps is being starved. The system admin might try manually increasing the priority of the kworker.

Many device drivers use kworker threads created by the PTP stack. Such kworkers are named:

ptp<decimal number of clock>

The system admin can manually bump the priority of the kworker process using chrt.

Example:

pgrep -f "ptp[0-9]+" | xargs -I {} sudo chrt -f --pid 75 {}

Intel ice driver may create multiple kworkers for one physical NIC and names those processes differently.

Example for Intel E810 card:

pgrep -f ice-ptp | xargs -I {} sudo chrt -f --pid 75 {}

Assigning priority needs careful consideration as assigning too high priority to any task might make system unstable.

## SEE ALSO
pmc(8), phc2sys(8)


timemaster

package: linuxptp

title: timemaster(8)

text:
# timemaster(8)

## NAME
timemaster - run NTP with PTP as reference clocks

## SYNOPSIS
timemaster [ -nmqv ] [ -l print-level ] -f file

## DESCRIPTION
timemaster is a program that uses ptp4l and phc2sys in combination with chronyd or ntpd to synchronize the system clock to NTP and PTP time sources. The PTP time is provided by phc2sys and ptp4l via SOCK reference clock to chronyd or SHM reference clock to ntpd, which can compare all time sources and use the best sources to synchronize the system clock.

On start, timemaster reads a configuration file that specifies the NTP and PTP time sources, checks which network interfaces have and share a PTP hardware clock (PHC), generates configuration files for ptp4l and chronyd/ntpd, and start the ptp4l, phc2sys, chronyd/ntpd processes as needed. Then, it waits for a signal to kill the processes, remove the generated configuration files and exit.

## OPTIONS
-f file

Specify the path to the timemaster configuration file.

-n

Don't start the programs, only print their configuration files and the commands that would be executed if this option wasn't specified.

-l level

Set the maximum syslog level of messages which should be printed or sent to the system logger. The default value is 6 (LOG_INFO).

-m

Print messages to the standard output.

-q

Don't send messages to the system logger.

-v

Print the software version and exit.

-h

Display a help message and exit.

## 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.

Sections that can used in the configuration file and options that can be set in them are described below.

### [timemaster]
ntp_program

Select which NTP implementation should be used. Possible values are chronyd and ntpd. The default value is chronyd. Limitations of the implementations relevant to the timemaster configuration are listed in NOTES.

rundir

Specify the directory where should be generated chronyd, ntpd and ptp4l configuration files and sockets. The directory will be created if it doesn't exist. The default value is /run/timemaster.

first_shm_segment

Specify the first number in a sequence of SHM segments that will be used by ptp4l and phc2sys. The default value is 0. Increasing the number can be useful to avoid conflicts with time sources that are not started by timemaster, e.g. gpsd using segments number 0 and 1.

restart_processes

Enable or disable restarting of processes started by timemaster. If the option is set to a non-zero value, all processes except chronyd and ntpd will be automatically restarted when terminated and timemaster is running for at least one second (i.e. the process did not terminate due to a configuration error). If a process was terminated and is not started again, timemaster will kill the other processes and exit with a non-zero status. The default value is 1 (enabled).

use_vclocks

Enable or disable synchronization with virtual clocks. If enabled, timemaster will create virtual clocks running on top of physical clocks needed by configured PTP domains. This enables hardware time stamping for multiple ptp4l instances using the same network interface. The default value is -1, which enables the virtual clocks if running on Linux 5.18 or later.

### [ntp_server address]
The ntp_server section specifies an NTP server that should be used as a time source. The address of the server is included in the name of the section.

minpoll

maxpoll

Specify the minimum and maximum NTP polling interval as powers of two in seconds. The default values are 6 (64 seconds) and 10 (1024 seconds) respectively. Shorter polling intervals usually improve the accuracy significantly, but they should be used only when allowed by the operators of the NTP service (public NTP servers generally don't allow too frequent queries). If the NTP server is located on the same LAN, polling intervals around 4 (16 seconds) might give best accuracy.

iburst

Enable or disable sending a burst of NTP packets on start to speed up the initial synchronization. Possible values are 1 and 0. The default value is 0 (disabled).

ntp_options

Specify extra options that should be added for this source to the server directive in the configuration file of the selected NTP implementation. No extra options are added by default.

### [ptp_domain number]
The ptp_domain section specifies a PTP domain that should be used as a time source. The PTP domain number is included in the name of the section. The ptp4l instances are configured to run in the clientOnly mode. In this section at least the interfaces option needs to be set, other options are optional.

interfaces

Specify which network interfaces should be used for this PTP domain. A separate ptp4l instance will be started for each group of interfaces sharing the same PHC and for each interface that supports only SW time stamping. HW time stamping is enabled automatically. If an interface with HW time stamping is specified also in other PTP domains and virtual clocks are disabled, only the ptp4l instance from the first PTP domain will be using HW time stamping.

ntp_poll

Specify the polling interval of the SOCK/SHM reference clock reading samples from ptp4l or phc2sys. It's specified as a power of two in seconds. The default value is 2 (4 seconds).

phc2sys_poll

Specify the polling interval used by phc2sys to read a PTP clock synchronized by ptp4l and update the SOCK/SHM sample for chronyd/ntpd. It's specified as a power of two in seconds. The default value is 0 (1 second).

delay

Specify the maximum assumed roundtrip delay to the primary source of the time in this PTP domain. This value is included in the distance used by chronyd in the source selection algorithm to detect falsetickers and assign weights for source combining. The default value is 1e-4 (100 microseconds). With ntpd, the tos mindist command can be used to set a limit with similar purpose globally for all time sources.

ntp_options

Specify extra options that should be added for this source to the refclock or server directives in the configuration file of the selected NTP implementation. No extra options are added by default.

ptp4l_option

Specify an extra ptp4l option specific to this PTP domain that should be added to the configuration files generated for ptp4l. This option may be used multiple times in one ptp_domain section.

### [chronyd]
path

Specify the path to the chronyd binary. The default value is chronyd to search for the binary in PATH.

options

Specify extra options that should be added to the chronyd command line. No extra options are added by default.

### [chrony.conf]
Settings specified in this section are copied directly to the configuration file generated for chronyd. If this section is not present in the timemaster configuration file, the following setting will be added:

```
makestep 1 3
```

This configures chronyd to step the system clock in the first three updates if the offset is larger than 1 second.

### [ntpd]
path

Specify the path to the ntpd binary. The default value is ntpd to search for the binary in PATH.

options

Specify extra options that should be added to the ntpd command line. No extra options are added by default.

### [ntp.conf]
Settings specified in this section are copied directly to the configuration file generated for ntpd. If this section is not present in the timemaster configuration file, the following settings will be added:

```
restrict default nomodify notrap nopeer noquery
restrict 127.0.0.1
restrict ::1
```

This configures ntpd to use safe default restrictions.

### [phc2sys]
path

Specify the path to the phc2sys binary. The default value is phc2sys to search for the binary in PATH.

options

Specify extra options that should be added to all phc2sys command lines. By default, -l 5 is added to the command lines.

### [ptp4l]
path

Specify the path to the ptp4l binary. The default value is ptp4l to search for the binary in PATH.

options

Specify extra options that should be added to all ptp4l command lines. By default, -l 5 is added to the command lines.

### [ptp4l.conf]
Settings specified in this section are copied directly to the global section of the configuration files generated for all ptp4l instances. There is no default content of this section.

Other sections (e.g. [unicast_master_table]) may be specified here, but lines beginning with the bracket need to be prefixed with the > character to prevent timemaster from parsing it as a beginning of another section.

## NOTES
For best accuracy, chronyd is usually preferred over ntpd, it also synchronizes the system clock faster. Both NTP implementations, however, have some limitations that need to be considered before choosing the one to be used in a given timemaster configuration.

The chronyd limitations are:

In version 1.31 and older, the maximum number of reference clocks used at the same time is 8. This limits the number of PHCs and interfaces using SW time stamping that can be used for PTP. Using polling intervals (minpoll, maxpoll, ntp_poll options) shorter than 2 (4 seconds) is not recommended with versions before 1.30. With 1.30 and later values of 0 or 1 can be used for NTP sources and negative values for PTP sources (ntp_poll) to specify a subsecond interval.

The ntpd limitations are:

In versions before 4.2.8p1, only the first two shared-memory segments created by the ntpd SHM refclock driver have owner-only access. Other segments are created with world access, which allows any user on the system to write to the segments and disrupt or take control over the synchronization of the clock. In 4.2.8p1 the access was made configurable with the mode option, which is set by timemaster for owner-ownly access. The shortest polling interval for all sources is 3 (8 seconds).

Nanosecond resolution in the SHM refclock driver is supported in version 4.2.7p303 and later, older versions have only microsecond resolution.

## EXAMPLES
A minimal configuration file using one NTP source and two PTP sources would be:

```
[ntp_server 10.1.1.1]
[ptp_domain 0]
interfaces eth0
[ptp_domain 1]
interfaces eth1
```

A more complex example using all timemaster options would be:

```
[ntp_server 10.1.1.1]
minpoll 3
maxpoll 4
iburst 1
ntp_options key 12
[ptp_domain 0]
interfaces eth0 eth1
ntp_poll 0
phc2sys_poll -2
delay 10e-6
ntp_options prefer
ptp4l_option clock_servo linreg
ptp4l_option delay_mechanism P2P
[timemaster]
ntp_program chronyd
rundir /run/timemaster
first_shm_segment 1
restart_processes 0
use_vclocks 0
[chronyd]
path /usr/sbin/chronyd
options
[chrony.conf]
makestep 1 3
logchange 0.5
rtcsync
driftfile /var/lib/chrony/drift
[ntpd]
path /usr/sbin/ntpd
options -u ntp:ntp
[ntp.conf]
restrict default nomodify notrap nopeer noquery
restrict 127.0.0.1
restrict ::1
driftfile /var/lib/ntp/drift
[phc2sys]
path /usr/sbin/phc2sys
options -l 5
[ptp4l]
path /usr/sbin/ptp4l
options
[ptp4l.conf]
logging_level 5
```

## SEE ALSO
chronyd(8), ntpd(8), phc2sys(8), ptp4l(8)


title: ts2phc(8)

text:
# ts2phc(8)

## NAME
ts2phc - Synchronizes one or more PTP Hardware Clocks using external time stamps.

## SYNOPSIS
ts2phc [ -hmqv ] [ -c device|name ] [ -f config ] [ -l print-level ] [ -s device|name ] [ long-options ] ...

## DESCRIPTION
ts2phc synchronizes PTP Hardware Clocks (PHC) to external time stamp signals. A single source may be used to distribute time to one or more PHC devices.

## OPTIONS
-a

Adjust the direction of synchronization automatically. The program determines which PHC should the reference clock for time distribution and which should be the destinations by querying the port states from the running instance of ptp4l. Note that using this option, the PPS signal distribution hierarchy still remains fixed as per the configuration file. This implies that using this option, a PPS source of the PHC kind may become a target clock, and a PPS sink may become a reference clock. Other, non-PHC types of PPS sources (generic, NMEA) cannot become target clocks. Clocks which are not part of ptp4l's list of ports are not synchronized. This option is useful when the boundary_clock_jbod option of ptp4l is also enabled.

-c device|name

Specifies a PHC to be synchronized. The clock may be identified by its character device (like /dev/ptp0) or its associated network interface (like eth0). This option may be given multiple times.

-f config

Read configuration from the specified file. No configuration file is read by default.

-h

Displays the command line help summary.

-l print-level

Sets the maximum syslog level of messages which should be printed or sent to the system logger. The default is 6 (LOG_INFO).

-m

Prints log messages to the standard output.

-q

Prevents sending log messages to the system logger.

-s device|name

Specifies the source of the Time of Day (ToD) data. Use the key word "generic" for an external 1-PPS without ToD information. When using a PHC as the time source, the clock may be identified by its character device (like /dev/ptp0) or its associated network interface (like eth0). Use the key word "nmea" for an external 1-PPS from a GPS providing ToD information via the RMC NMEA sentence.

-v

Prints the software version and exits.

## LONG OPTIONS
Each and every configuration file option (see below) may also appear as a "long" style command line argument. For example, the use_syslog option may be set using either of these two forms.

--use_syslog 1 --use_syslog=1

Option values given on the command line override values in the global section of the configuration file.

## 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.

There are two different section types.

1.

The global section (indicated as [global]) sets the program options and the default time sink options. Other sections are clock specific sections, and they override the default options.

2.

Time sink sections give the name of the configured PHC (e.g. [eth0]). Time sinks specified in the configuration file need not be specified with the -c command line option.

## GLOBAL OPTIONS
first_step_threshold

The maximum offset, specified in seconds, that the servo will correct by changing the clock frequency (phase when using nullf servo) instead of stepping the clock. This is only applied on the first update. When set to 0.0, the servo will not step the clock on start. The default is 0.00002 (20 microseconds).

free_running

When set to 1, no PHC will be adjusted. This option can be useful in test scenarios, for example to determine how well synchronized a group of local clocks are to each other. The default is 0 (adjust the clocks).

leapfile

The path to the current leap seconds definition file. In a Debian system this file is provided by the tzdata package and can be found at /usr/share/zoneinfo/leap-seconds.list. If a leapfile is configured it will be reloaded if modified. The default is an empty string, which causes the program to use a hard coded table that reflects the known leap seconds on the date of the software's release.

logging_level

The maximum logging level of messages which should be printed. The default is 6 (LOG_INFO).

max_frequency

The maximum allowed frequency adjustment of the clock in parts per billion. This is an additional limit to the maximum allowed by the hardware. When set to 0, the hardware limit will be used. The default is 900000000 (90%).

message_tag

The tag which is added to all messages printed to the standard output or system log. If the tag contains the string "{level}", it will be replaced with the log level of the message as a number. The default is an empty string (which cannot be set in the configuration file as the option requires an argument).

step_threshold

The maximum offset, specified in seconds, that the servo will correct by changing the clock frequency instead of stepping the clock. When set to 0.0, the servo will never step the clock except on start. The default is 0.0.

ts2phc.nmea_remote_host, ts2phc.nmea_remote_port

Specifies the remote host providing ToD information when using the "nmea" PPS signal source. Note that if these two options are both specified, then the given remote connection will be used in preference to the configured serial port. These options default to the empty string, that is, not specified.

ts2phc.nmea_serialport, ts2phc.nmea_baudrate

Specifies the serial port and baudrate in bps for character device providing ToD information when using the "nmea" PPS signal source. Note that if the options, ts2phc.nmea_remote_host and ts2phc.nmea_remote_port, are both specified, then the given remote connection will be used in preference to the configured serial port. The default serial port is "/dev/ttyS0". The default baudrate is 9600 bps.

ts2phc.perout_phase

Configures the offset between the beginning of the second and the PPS source's rising edge. Available only for the PHC kind of PPS source. The supported range is 0 to 999999999 nanoseconds. The default is 0 nanoseconds, but leaving this option unspecified will not transmit the phase to the kernel, instead PPS will be requested to start at an absolute time equal to the nearest 2nd full second since the start of the program. This should yield the same effect, but may not work with drivers that do not support starting periodic output at an absolute time.

ts2phc.pulsewidth

The pulse width of the external PPS signal in nanoseconds. When 'ts2phc.extts_polarity' is "both", the given pulse width is used to detect and discard the time stamp of the unwanted edge. In case the PPS source is of the PHC kind, an attempt is made to request the kernel to actually emit using this pulse width. If this fails, it is assumed that the specified pulse width is correct, and the value is used in the edge rejection algorithm. The supported range is 1000000 to 990000000 nanoseconds. The default is 500000000 nanoseconds.

ts2phc.tod_source

Specifies the source of Time of Day (ToD) data. Use the key word "generic" for an external 1-PPS without ToD information. When using a PHC as the time source, the clock may be identified by its character device (like /dev/ptp0) or its associated network interface (like eth0). Use the key word "nmea" for an external 1-PPS from a GPS providing ToD information via the RMC NMEA sentence. The default is "generic"

use_syslog

Print messages to the system log if enabled. The default is 1 (enabled).

verbose

Print messages to the standard output if enabled. The default is 0 (disabled).

## TIME SINK OPTIONS
ts2phc.channel

The external time stamping or periodic output channel to be used. Some PHC devices feature programmable pins and one or more time stamping channels. This option allows selecting a particular channel to be used. When using a PHC device as the PPS source, this option selects the periodic output channel. The default is channel 0.

ts2phc.extts_correction

The value, in nanoseconds, to be added to each PPS time stamp. The default is 0 (no correction).

ts2phc.extts_polarity

The polarity of the external PPS signal, either "rising" or "falling". Some PHC devices always time stamp both edges. Setting this option to "both" will allow the ts2phc program to work with such devices by detecting and ignoring the unwanted edge. In this case be sure to set 'ts2phc.pulsewidth' to the correct value. The default is "rising".

ts2phc.master

Setting this option to 1 configures the given PHC device as the source of the PPS signal. The default is 0 for the time sink role.

ts2phc.pin_index

The pin index to be used. Some PHC devices feature programmable pins, and this option allows configuration of a particular pin for the external time stamping or periodic output function. The default is pin index 0.

## WARNING
Be cautious when sharing the same configuration file between ptp4l, phc2sys, and ts2phc. Keep in mind that values specified in the configuration file take precedence over the default values. If an option which is common to the other programs is set in the configuration file, then the value will be applied to all the programs using the file, and this might not be what is expected.

It is recommended to use separate configuration files for ptp4l, phc2sys, and ts2phc in order to avoid any unexpected behavior.

## SEE ALSO
phc2sys(8) ptp4l(8)


title: tz2alt(8)

text:
# tz2alt(8)

## NAME
tz2alt - Monitors daylight savings time changes and publishes them to PTP stack.

## SYNOPSIS
ts2alt [ -hmqv ] [ -f conf ] [ -k key ] [ -p period ] [ -w window ] [ -z timezone ] [ long-options ] ...

## DESCRIPTION
tz2alt leverages the local time zone database to monitor for changes in daylight savings time and publishes the pending changes to the PTP stack.

## OPTIONS
-f config

Read configuration from the specified file. No configuration file is read by default.

-h

Displays the command line help summary.

-l print-level

Sets the maximum syslog level of messages which should be printed or sent to the system logger. The default is 6 (LOG_INFO).

-m

Prints log messages to the standard output.

-q

Prevents sending log messages to the system logger.

-v

Prints the software version and exits.

## LONG OPTIONS
Each and every configuration file option (see below) may also appear as a "long" style command line argument. For example, the use_syslog option may be set using either of these two forms.

--use_syslog 1 --use_syslog=1

Option values given on the command line override values in the global section of the configuration file.

## 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.

## GLOBAL OPTIONS
domainNumber

The domain attribute of the local clock. The default is 0.

leapfile

The path to the current leap seconds definition file. In a Debian system this file is provided by the tzdata package and can be found at /usr/share/zoneinfo/leap-seconds.list. If a leapfile is configured it will be reloaded if modified. The default is an empty string, which causes the program to use a hard coded table that reflects the known leap seconds on the date of the software's release.

logging_level

The maximum logging level of messages which should be printed. The default is 6 (LOG_INFO).

message_tag

The tag which is added to all messages printed to the standard output or system log. If the tag contains the string "{level}", it will be replaced with the log level of the message as a number. The default is an empty string (which cannot be set in the configuration file as the option requires an argument).

transportSpecific

The transport specific field. Must be in the range 0 to 255. The default is 0.

use_syslog

Print messages to the system log if enabled. The default is 1 (enabled).

verbose

Print messages to the standard output if enabled. The default is 0 (disabled).

## WARNING
Be cautious when sharing the same configuration file between ptp4l, phc2sys, and tz2alt. Keep in mind that values specified in the configuration file take precedence over the default values. If an option which is common to the other programs is set in the configuration file, then the value will be applied to all the programs using the file, and this might not be what is expected.

It is recommended to use separate configuration files for ptp4l, phc2sys, and tz2alt in order to avoid any unexpected behavior.

## SEE ALSO
ptp4l(8)


liquidctl

package: liquidctl

title: liquidctl(8)

text:
# liquidctl(8)

## NAME
liquidctl - monitor and control liquid coolers and other devices

## SYNOPSIS
liquidctl

[options] list

liquidctl

[options] initialize [all]

liquidctl

[options] status

liquidctl

[options] set channel speed (temperature percentage) ...

liquidctl

[options] set channel speed percentage

liquidctl

[options] set channel color mode [color ...]

liquidctl

--version

liquidctl

--help

## DESCRIPTION
liquidctl is a utility for overseeing and controlling some hardware monitoring devices not yet supported at the kernel level. Because liquidctl directly accesses the hardware devices, root privileges are generally required, though this can be avoided with appropriate udev rules.

liquidctl list outputs all compatible devices found on the system. In case more than one device is found, the desired one can be selected for later invocations with --match=substring, where substring matches part of the desired device's description using a case insensitive comparison.

liquidctl list --verbose enables the display of additional identifiers and addresses that can also be used to select specific devices. These can be better suited for certain use cases, such as non-interactive scripts.

liquidctl initialize prepares a device for later commands, and most devices must be initialized after every boot or when resuming from a suspended state. Unless finer control is required, all devices can be initialized at once with liquidctl initialize all. Some devices may output some information at this stage.

liquidctl status displays the status of all devices that match the provided filtering options.

liquidctl set channel speed allows the user to set fan and pump speeds. These, depending on the device, can be set to fixed duty values, variable temperature\[u2013]duty curves, or both.

liquidctl set channel color allows the user to configure and set lighting modes. Supported lighting modes and additional options vary by device and are listed in later sections of this manual. Each color can be specified as:

- hexadecimal RGB with or without prefix '0x': ff7f3f;

- decimal RGB triple, R,G,B ∊ [0, 255]: rgb(255,127,63);

- hue-saturation-value HSV triple, H ∊ [0, 360], S,V ∊ [0, 100]: hsv(20,75,100);

- hue-saturation-lightness HSL triple, H ∊ [0, 360], S,L ∊ [0, 100]: hsl(20,100,62).

liquidctl set channel screen allows the user to configure the LCD screen integrated into some AIO models.

liquidctl automatically detects when a kernel driver is bound to the device and, whenever possible, uses it instead of directly accessing the device. Alternatively, direct access to the device can be forced with --direct-access.

## OPTIONS

### Device selection options
Devices can be selected using one or more values taken from list --verbose.

-m substring, --match=substring

Filter devices by case insensitive substring of device description.

-n number, --pick=number

Pick among many results for a given filter.

--vendor=id

Filter devices by hexadecimal vendor id.

--product=id

Filter devices by hexadecimal product id.

--release=number

Filter devices by hexadecimal release number.

--serial=number

Filter devices by serial number.

--bus=bus

Filter devices by bus.

--address=address

Filter devices by address in bus.

--usb-port=port

Filter devices by USB port in bus.

-d index, --device=index

(Deprecated), select device by listing index.

### Animation options
Some devices and animation modes support additional options.

--speed=value

Abstract animation speed (device/mode specific).

--time-per-color=value

Time to wait on each color (seconds).

--time-off=value

Time to wait with the LED turned off (seconds).

--alert-threshold=number

Threshold temperature for a visual alert (degrees Celsius).

--alert-color=color

Color used by the visual high temperature alert.

--direction=string

If the pattern should move forward or backward.

--start-led=number

The first led to start the effect at.

--maximum-leds=number

The number of LED's the effect should apply to.

### Other options
--fan-mode=channel:mode[,...]

Set the fan modes.

--single-12v-ocp

Enable single rail +12V OCP.

--pump-mode=mode

Set the pump mode.

--temperature-sensor=number

The temperature sensor number for the Commander Pro.

--legacy-690lc

Use Asetek 690LC in legacy mode (old Krakens).

--non-volatile

Store on non-volatile controller memory.

--direct-access

Directly access the device despite kernel drivers.

--unsafe=features

Comman-separated bleeding-edge features to enable.

-v, --verbose

Output additional information.

-g, --debug

Show debug information on stderr.

--json

Output machine-readable JSON. Only supported with list, initialize and status.

--version

Display the version number.

--help

Show the embedded help.

## EXIT STATUS
1 if there was an error, 0 otherwise.

## ENVIRONMENT
If LANG is set to C, non-ASCII characters are escaped from the output of --json.

## FILES
$XDG_RUNTIME_DIR/liquidctl/*, /var/run/liquidctl/*, /tmp/liquidctl/*

Internal data used by some drivers.

## EXAMPLE
liquidctl

list --verbose

liquidctl

initialize all

liquidctl

--match kraken set pump speed 90

liquidctl

--product 170e set led color fading 350017 ff2608

liquidctl

status

## DEVICE SPECIFICS

### Aquacomputer Quadro
Cooling channels: (D5 Next:) fan, pump; (Octo:) fan[1-8]; (Quadro:) fan[1-4]; (Farbwerk/Farbwerk 360:) not applicable.

Lighting channels: not yet supported.

### ASUS Ryujin II 360
Cooling channels: pump, fans, pump-fan, external-fans.

### ASUS Ryujin III 360, EVA, Extreme, White
Cooling channels: pump, pump-fan.

Screen: not yet supported.

### ASUS Ryuo II 240
Cooling channels: fans, fan. There is only a single fan channel.

### Corsair Commander ST
Cooling channels: fans, fan[1-6]; (only non-XT/Elite Capellix:) pump.

Lighting channels: not yet supported.

### Corsair Obsidian 1000D
Cooling channels (only Commander Pro and Obsidian 1000D): sync, fan[1-6].

Where the fan connection types can be set with --fan-mode=channel:mode[,...], where the allowed modes are: off, dc, pwm.

Lighting channels: (only Lighting Node Core:) led; (only Commander Pro and Lighting Node Pro:) sync, led[1-2].

Mode

\#colors

clear

0

off

0

fixed

1

color_shift

2

color_pulse

2

color_wave

2

visor

2

blink

2

marquee

1

sequential

1

rainbow

0

rainbow2

0

When applicable the animation speed can be set with --speed=value, where the allowed values are: fast, medium, slow.

The animation direction can be set with --direction=value, where the allowed values are: forward or backward. --start-led=number, the first LED that the lighting effect should be for. --start-led=number, the first LED that the lighting effect should be for. --maximum-led=number, the number of LEDs that the lighting effect should applied to. --temperature-sensor=number, The temperature sensor that should be used to control the fan curves, probe 1 by default.

### Corsair Hydro H110i GT
Cooling channels: fan1, fan2.

Pump mode (initialize --pump-mode mode): quiet (default), extreme.

Lighting channels: not yet supported.

### EVGA CLC 120 (CL12), 240, 280, 360
Cooling channels: pump, fan.

Lighting channels: logo.

Mode

\#colors

notes

rainbow

0

only available on EVGA coolers

fading

2

blinking

1

fixed

1

blackout

0

no high-temperature alerts

The rainbow mode speed can be configured with --speed=[1–6]. The speed of the other modes is instead customized with --time-per-color (fading and blinking) and --time-off (blinking only).

All modes except blackout support a visual high-temperature alert configured with --alert-threshold and --alert-color.

All current settings can be saved on non-volatile on-board memory by passing --non-volatile to any write command. However, since write-cycles are limited, this option should be used sparingly.

### Corsair H100i Pro, H115i Pro, H150i Pro
Cooling channels: fan, fan[1–2]; (only H150i Pro:) fan3.

Pump mode (initialize --pump-mode mode): quiet, balanced (default), performance.

Lighting channel: logo.

Mode

\#colors

alert

3

shift

2–4

pulse

1–4

blinking

1–4

fixed

1

### Corsair Hydro H100i, H115i, H150i Elite RGB
Cooling channels: fan, fan[1–2]; (only H150i Pro XT/Elite RGB:) fan3.

Pump mode (initialize --pump-mode mode): quiet, balanced (default), extreme.

Lighting channels: sync, led.

Channel

Mode

\#colors (Platinum)

\#colors (Pro XT/Elite RGB)

\#colors (Platinum SE)

led

off

0

0

0

led

fixed

1

1

1

led

super-fixed

24

16

48

### Lian Li Uni SL, SL v2, AL, AL v2, SL-Infinity
Cooling channels: fan[1–4].

Lighting channels: none.

### MSI MPG Coreliquid K360
Cooling channels: fan1, fan2, fan3, fans, waterblock-fan, pump.

Lighting channels: sync.

LCD screens: lcd.

Mode

\#colors

disable

0

steady

1

blink

0

breathing

1

clock

2

color pulse

0

color ring

0

color ring double flashing

0

color ring flashing

0

color shift

0

color wave

2

corsair ique

0

disable2

0

double flashing

1

double meteor

0

energy

0

fan control

0

fire

2

flashing

1

jazz

0

jrainbow

0

lava

0

lightning

1

marquee

1

meteor

1–2

movie

0

msi marquee

1

msi rainbow

0

planetary

0

play

0

pop

0

rainbow

0

rainbow double flashing

0

rainbow flashing

0

rainbow wave

0

random

0

rap

0

stack

1

visor

2

water drop

1

When applicable the animation speed can be set with --speed=value, where the allowed values are: 0, 1 and 2. The LCD screen settings can be controlled with the settings flag, that requires the arguments "brightness;direction" where an allowed brightness is an integer in the range 0-100, and orientations 0-3 correspond to the orientations up, right, down and left.

### NZXT Kraken X31, X41, X61
Supports the same modes and options as a Corsair Hydro H80i GT (or similar), but requires --legacy-690lc to be passed on all invocations.

### NZXT Kraken X42, X52, X62, X72
Cooling channels (only X42, X52, X62, X72): pump, fan.

Lighting channels: logo, ring, sync.

Mode

logo

ring

\#colors

off

yes

yes

0

fixed

yes

yes

1

super-fixed

yes

yes

1–9

fading

yes

yes

2–8

alternating

no

yes

2

breathing

yes

yes

1–8

super-breathing

yes

yes

1–9

pulse

yes

yes

1–8

tai-chi

no

yes

2

water-cooler

no

yes

0

loading

no

yes

1

wings

no

yes

1

When applicable the animation speed can be set with --speed=value, where the allowed values are: slowest, slower, normal, faster, fastest. The animation direction can be set with --direction=value, where the allowed values are: forward or backward.

### NZXT Kraken X53, X63, X73
Cooling channels: pump.

Lighting channels: external, ring, logo, sync.

### NZXT Kraken Z53, Z63, Z73
Cooling channels: pump, fan.

Lighting channels: external.

LCD screens: lcd.

### NZXT Kraken 2024 Plus
Cooling channels: pump, fan.

Lighting channels: none.

LCD screens: lcd.

Mode

\#colors

off

0

fixed

1

fading

2–8

super-fixed

1–40

alternating-[3-6]

1–2

pulse

1–8

breathing

1–8

super-breathing

1–40

candle

1

starry-night

1

loading

1

tai-chi

1–2

water-cooler

2

wings

1

When applicable the animation speed can be set with --speed=value, where the allowed values are: slowest, slower, normal, faster, fastest. The animation direction can be set with --direction=value, where the allowed values are: forward or backward.

### Corsair RM650i, RM750i, RM850i, RM1000i
Cooling channels: fan.

Lighting channels: none.

Setting a fixed fan speed changes the fan mode to software control. To revert back to hardware control, run initialize again.

(Experimental feature) The +12V rails normally function in multiple-rail mode. Single-rail mode can be selected by passing --single-12v-ocp to initialize. To revert back to multiple-rail mode, run initialize again without that flag.

### NZXT E500, E650, E850
Cooling channels: none (feature not supported yet).

Lighting channels: none.

### NZXT Grid+ V3
Cooling channels: fan[1–6], sync.

Lighting channels: none.

### NZXT Smart Device (V1)
Cooling channels: fan[1–3], sync.

Lighting channels: led.

Mode

\#colors

off

0

fixed

1

super-fixed

1–40

fading

2–8

alternating

2

breathing

1–8

super-breathing

1–40

pulse

1–8

candle

1

wings

1

When applicable the animation speed can be set with --speed=value, where the allowed values are: slowest, slower, normal, faster, fastest. The animation direction can be set with --direction=value, where the allowed values are: forward or backward.

### NZXT 2023 RGB Controller
Cooling channels (only Smart Device V2, H1 V2 and RGB & Fan Controllers): fan[1–3].

Lighting channels (all but H1 V2): led[1–6], sync.

Mode

\#colors

off

0

fixed

1

super-fixed

1–40

fading

2–8

alternating-[3-6]

2

pulse

1–8

breathing

1–8

super-breathing

1–40

candle

1

starry-night

1

wings

1

When applicable the animation speed can be set with --speed=value, where the allowed values are: slowest, slower, normal, faster, fastest. The animation direction can be set with --direction=value, where the allowed values are: forward or backward.

### ASUS TUF RTX 3060 Ti OC
Cooling channels: none.

Lighting channels: led.

Mode

\#colors

off

0

fixed

1

flash

1

breathing

1

rainbow

0

### Corsair Vengeance RGB
Cooling channels: none.

Lighting channels: led.

Mode

\#colors

off

0

fixed

1

breathing

1–7

fading

2–7

When applicable the animation speed can be set with --speed=value, where the allowed values are: slowest, slower, normal, faster, fastest.

### ASUS Aura LED Controller
Cooling channels: none.

Lighting channels: led[1–4], sync.

Mode

\#colors

off

0

static

1

breathing

1

flashing

1

spectrum_cycle

0

rainbow

0

spectrum_cycle_breathing

0

chase_fade

1

spectrum_cycle_chase_fade

0

chase

1

spectrum_cycle_chase

0

spectrum_cycle_wave

0

chase_rainbow_pulse

0

rainbow_flicker

0

gentle_transition

0

wave_propagation

0

wave_propagation_pause

0

red_pulse

0

### Gigabyte RGB Fusion 2.0 8297 Controller
Cooling channels: none.

Lighting channels: led[1–8], sync.

Mode

\#colors

off

0

fixed

1

pulse

1

(double-)?flash

1

color-cycle

0

When applicable the animation speed can be set with --speed=value, where the allowed values are: slowest, slower, normal, faster, fastest, ludicrous.

### EVGA GTX 1080 FTW
Cooling channels: none.

Lighting channels: led.

Mode

\#colors

off

0

fixed

1

breathing

1

rainbow

0

### Lian Li GA II LCD
Cooling channels: pump, fan.

This device does not support speed profiles for any channels, only fixed speeds are supported.

Lighting channels: pump, fan.

Mode

pump

fan

\#colors

rainbow

yes

yes

0

rainbow-morph

yes

yes

0

static

yes

yes

1

breathing

yes

yes

1

runway

yes

yes

2

meteor

yes

yes

4

ticker-tape

yes

no

4

fluctuation

yes

no

4

transmit

yes

no

2

colorful-starry-night

yes

no

0

static-starry-night

yes

no

1

big-bang

yes

no

4

burst

yes

no

1

color-morph

yes

no

0

bounce

yes

no

4

When applicable the animation speed can be set with --speed=value, where the allowed values are: slowest, slower, normal, faster, fastest. The animation direction can be set with --direction=value, where the allowed values are: forward or backward.

## SEE ALSO
The complete documentation is available in the project's sources and homepage.


lircd

package: lirc

title: lircd(8)

text:
# lircd(8)

## NAME
lircd - Decode infrared signals and provide them on a socket.

## SYNOPSIS
lircd [options] [config file]

## DESCRIPTION
The main task of lircd is to decode the infrared signals and provide an uniform interface for client applications. Clients can connect to lircd through a Unix domain socket, by default /var/run/lirc/lircd. Using this socket they will get the infrared codes received by lircd and they can send commands to lircd.

## ARGUMENTS
config file

The configuration file, by default /etc/lirc/lircd.conf. A relative path is interpreted from /etc/lirc. The default configuration file includes all files in /etc/lircd.conf.d.

Each remote which should be decoded by lircd usually requires that a specific file is used e. g., by copying it to /etc/lirc/lirc.conf.d/. The format is described in lircd.conf(5). Configuration files could be found using irdb-get(1) or lirc-setup(1). It's also possible to generate a config file using irrecord(1)

## OPTIONS
Common options:

-d, --device <device>

Select the character device which lircd should read from. The default is currently /dev/lirc0 on most systems.

Some drivers, including the default devinput driver, supports the auto device which picks the first usable device found for the actual driver.

When using the devinput driver name=STRING or phys=STRING can be used to select the device; lircd will look in /dev/input to find a device with a matching description. This is useful in case the device name isn't fixed. STRING may contain the '*' and '?' wildcards and '\' to mark them as literal. Use mode2 --driver devinput --list-devices to list the actual devices.

-H, --driver <driver>

The driver to use. Using --driver help lists all available drivers, see DRIVER LOADING below.

-h, --help

Displays short help message.

Other options:

-a, --allow-simulate

Enable the SIMULATE command which can be issued using irsend(1) or the client API. This will allow simulating arbitrary IR events from the command line. Use this option with caution because it will give all users with access to the lircd socket wide control over the system. E.g., if you have configured your system to shut down by a button press on your remote control, everybody will be able to shut down your system from the command line.

-c, --connect [host[:port]][,[host[:port]]]

Connects to other lircd servers that provide a network socket at the given host and port number (see --listen). The number of such connections is currently limited to 100. The connecting lircd instance will receive IR events from the lircd instance it connects to. To connect to multiple servers, add them as a comma separated list.

-e, --effective-user <uid>

If started as user root, lircd drops it privileges and runs as user <uid> after opening files etc.

-i, --immediate-init

Lircd normally initializes the driver when the first client connects. If this option is selected, the driver is instead initialized immediately at start.

-A, --driver-options key:value[|key:value...]

Set one or more options for the driver. The argument is a list of key:value pairs delimited by '|'. The key can not contain spaces, but such are allowed in the value part. Certain characters including '#' and ';' are used as comment markers in the config file and are not allowed anywhere.

-Y, --dynamic-codes [EXPERIMENTAL]

Allows use of codes which have been decoded for one remote but are not defined in lircd.conf. New codes are dynamically created with a default name. This feature is experimental and subject to all sorts of changes. It has not ben tested thoroughly.

-l, --listen [[address:]port]]

Let lircd listen for network connections on the given address/port. The default address is 0.0.0.0, which means that connections on all network interfaces will be accepted. The address must be given in dotted numerical form. Port defaults to 8765. The listening lircd instance will send all IR events to the connecting lircd instances without any security checks.

On non-glibc platforms the address:port argument is mandatory, but can be given as an empty string e. g. --listen= which then defaults to 0.0.0.0:8765.

-L, --logfile <logfile path>

Select the lircd daemon log file. logfile is either the string 'syslog' indicating that syslog(1) should be used or a log file path. The default is to use syslog.

-D, --loglevel [level]

Determine the amount of logging information. level can be a symbolic syslog level: 'error','warning, 'info', 'notice' or 'debug'. lircd also defines three additional levels 'trace', 'trace1' and 'trace2' which gives even more messages ('trace2' bringing the most). However, in the log these messages are marked as 'debug'.

On non-glibc platforms the level argument is mandatory, but can be given as an empty string e. g. --loglevel= which then defaults to debug.

The level can also be an integer in the range 3 (almost no messages) to 10.

-O, --options-file <path>

File containing default values for all options. A relative path is interpreted from current directory. See [FILES] below.

-o, --output <output socket>

Select Unix domain socket, which lircd will write remote key codes to. The default currently is /var/run/lirc/lircd.

-p, --permission <perm>

Gives the file permission of the output socket if it has to be created in octal representation. See chmod(1). If no --permission option is given when the socket is initially created the default is to give all users read and write permissions (0666 in octal representation). If the socket already exists this option has no effect.

-p, --pidfile <path>

Select the lircd daemon pid file, defaults to /var/run/lirc/lircd.pid.

-U --plugindir <path>

Sets the directory from which lircd loads it's userspace drivers. These are *.so files, by default found as described under DRIVER LOADING. The argument is a :-separated search path.

-r, --release [suffix]

This option is deprecated and will be removed in an upcoming release. See lircd-uinput(8) for a replacement.

Enables automatic generation of release events for each button press. lircd will append the given suffix to the button name for each release event. If no suffix is given the default suffix is '_EVUP'.

Note the suffix _UP, which was used by lircd prior to 0.10.0, is used by the linux kernel for other purposes since 4.7.

-R, --repeat-max <limit>

Sets an upper limit to the number of repeats when sending a signal. The current default is 600. A SEND_START request will repeat the signal this many times. Also, if the number of repeats in a SEND_ONCE request exceeds this number, it will be replaced by this number.

## SOCKET BROADCAST MESSAGES FORMAT
When decoding a button press or receiving a SIGHUP signal lircd.conf lircd broadcasts messages to all connected clients.

For each decoded button press a package is made available on the socket. This is printable data formatted as:

```
        <code> <repeat count> <button name> <remote control name>
```

e.g.,

```
        0000000000f40bf0 00 KEY_UP ANIMAX
```

The fields are:

code

A 16 hexadecimal digits number encoding of the IR signal. It's usage in applications is deprecated and it should be ignored.

repeat count

shows how long the user has been holding down a button. The counter will start at 0 and increment each time a new IR signal has been received.

button name

is the name of a key defined in the lircd.conf file.

remote control name

is the mandatory name attribute in the lircd.conf config file.

These packets are broadcasted to all clients. The only other situation when lircd broadcasts to all clients is when it receives the SIGHUP signal and successfully re-reads its config file. Then it will send a SIGHUP packet to its clients indicating that its configuration might have changed. The sighup packet is three lines

```
        BEGIN

        SIGHUP

        END
```

## SOCKET COMMAND INTERFACE
Applications can also send commands to lircd over the socket interface. The most common task is sending data, but there are also other commands. Each command is a single printable line, terminated with a newline. For each command, lircd replies with a reply package.

Supported commands:

SEND_ONCE <remote control> <button name> [repeats]

Tell lircd to send the IR signal associated with the given remote control and button name, and then repeat it repeats times. repeats is a decimal number between 0 and repeat_max. The latter can be given as a --repeat-max command line argument to lircd, and defaults to 600. If repeats is not specified or is less than the minimum number of repeats for the selected remote control, the minimum value will be used.

SEND_START <remote control name> <button name>

Tell lircd to start repeating the given button until it receives a SEND_STOP command. However, the number of repeats is limited to repeat_max. lircd won't accept any new send commands while it is repeating.

SEND_STOP <remote control name> <button name>

Tell lircd to abort a SEND_START command.

LIST [remote control]

Without arguments lircd replies with a list of all defined remote controls. Given a remote control argument, lircd replies with a list of all keys defined in the given remote.

SET_INPUTLOG [path]

Given a path, lircd will start logging all received data on that file. The log is printable lines as defined in mode2(1) describing pulse/space durations. Without a path, current logfile is closed and the logging is stopped.

DRV_OPTION key value

Make lircd invoke the drvctl_func(DRVCTL_SET_OPTION, option) with option being made up by the parsed key and value. The return package reflects the outcome of the drvctl_func call.

SIMULATE key data

Given key data, instructs lircd to send this to all clients i. e., to simulate that this key has been decoded. The key data must be formatted exactly as the packet described in [SOCKET BROADCAST MESSAGES FORMAT], notably is the number of digits in code and repeat count hardcoded. This command is only accepted if the --allow-simulate command line option is active.

SET_TRANSMITTERS transmitter mask

Make lircd invoke the drvctl_func(LIRC_SET_TRANSMITTER_MASK, &channels), where channels is the decoded value of transmitter mask. See lirc(4) for more information.

VERSION

Tell lircd to send a version packet response.

The protocol guarantees that broadcasted messages won't interfere with reply packets. But broadcasts may appear at any point between packets. The only exception are SIGHUP packages. These may appear just after you have sent a command to lircd, so you have to make sure you don't confuse them with replies.

The format of the reply packet is

```
  BEGIN

  <command>

  [SUCCESS|ERROR]

  [DATA

  n

  n lines of data]

  END
```

If the command was successful, data is only sent for the commands that return some information. Note that a packet containing 0 lines of data can be a valid reply.

## RUNNING AS REGULAR USER
Traditionally lircd has been running as root since accessing kernel devices like /dev/lirc0 by default requires root privileges. However, running a long-running service like this is a major security issue.

The lirc distribution contains example udev rules which makes /dev/lirc[0-9] , USB and serial devices accessible by the lirc user. Using these rules, it is possible to run lircd as a regular user and group such as lirc.

## FILES
/etc/lirc/lircd.conf

Main config file, see lircd.conf(5).

/etc/lirc/lirc_options.conf

The options file. lircd handles the values under the [lircd] section in this file. The location can be changed using the -O/--options-file command-line option or using the environment variable LIRC_OPTIONS_PATH. The values here are used as defaults for any option not present on command line.

## ENVIRONMENT
LIRC_OPTIONS_PATH

Options file path, see FILES.

LIRC_PLUGINDIR

Plugin load path, se DRIVER LOADING.

LIRC_DEBUG_OPTIONS

If set, enables debugging in early stages when the --debug option is yet not parsed.

## DRIVER LOADING
Drivers are loaded dynamically. This is done from a traditional *ux ´:´-separated path where each component in the path is searched (leading part first, trailing last).

The path used for this is determined by (falling priority):

- The --plugindir option.

- The 'plugindir' entry in the [lircd] section of the lirc_options.conf file.

- The environment variable LIRC_PLUGINDIR.

- A hardcoded default (/usr/lib64/lirc/plugins).

## SIGNALS
HUP

On receiving SIGHUP lircd re-reads the lircd.conf configuration file (but not lirc_options.conf) and adjusts itself if the file has changed.

USR1

On receiving SIGUSR1 lircd makes a clean exit.

## DAEMONS
lircd is a daemon. It should be started in some system-dependent init script. By default, lirc ships with systemd files enabling user to control the lircd service.

## SEE ALSO
irdb-get(1)

lirc-setup(1)

lircd.conf(5)

irrecord(1)

lirc(4)

lircd-uinput(8)


lircd-setup

title: lircd-setup(8)

text:
# lircd-setup(8)

## NAME
lircd-setup - Run setup commands in lirc_options.conf

## SYNOPSIS
lircd-setup <config-file>

## DESCRIPTION
This program runs commands defined in the keys code and code1 .. code10 in the modinit section of the config file.

It's used as a one-shot service invoked before lircd(8) , running code which needs root privileges.

The config file defaults to /etc/lirc/lirc_options.conf if not given as command line argument.

## SEE ALSO
lircd(8)


lircd-uinput

title: lircd-uinput(8)

text:
# lircd-uinput(8)

## NAME
lircd-uinput - Forward lirc button presses as uinput events

## SYNOPSIS
lircd-uinput [options]... [lircd output socket]

lircd-uinput [options]... [file]

## DESCRIPTION
lircd-uinput reads decoded button press events from a lircd(8) output socket and injects these as key events to the kernel uinput device. The kernel makes these events available to other applications on a /dev/input/event device, just as for regular input hardware.

lircd-uinput is designed to run as a systemd service.

The lircd output socket argument is an optional path to the lircd output socket. It defaults to the output value in the [lircd] section of the lirc_options config file, falling back to /var/run/lirc/lircd.

If a plain file is given instead of a socket it is supposed to contain button press events formatted as documented in lircd(8) . lircd-uinput will in this case send the codes in this file and exit.

In order to work, release events must be sent to the uinput device. See REPEAT HANDLING.

lircd-uinput can only handle button events named using the official namespace i. e., buttons known to the kernel. See NOTES.

Unless the /dev/uinput default permissions are changed lirc-uinput needs to run as root. See NOTES.

The /dev/input/event device created by the kernel can be tricky to locate, and is not stable. See NOTES.

## OPTIONS
-u --uinput <device>

uinput kernel device, defaults to /dev/uinput.

-r --release-suffix <suffix>

lircd-uinput generates different events depending on if the button name ends with the release-suffix or not. Defaults to _EVUP . See REPEAT HANDLING

-R --repeat <delay[,period] | ,period>

Set kernel autorepeat parameters of the created /dev/input/event device. delay is the time before repeating a key event, period is the time between repeated key events. Both values are in milliseconds, separated by a comma. Any value can be omitted or set to 0 in which case the kernel/system defaults are used. See REPEAT HANDLING.

-a --add-release-events

Generate synthetic release events. This option is mandatory unless lircd is using the deprecated --release option. The timeout used can be modified using the release-timeout key in the lircd-uinput section of the lirc_options.conf file. Useless if used with a text file as input. . See REPEAT HANDLING

-d --disabled <disabled buttons file path>

The path of a file which contains name of buttons to be disabled, one per line. By default, lircd-uinput sends all buttons found in input. See NOTES.

-O --options-file <path>

Options file holding default values. Defaults to /etc/lircd/lirc_options.conf

-L, --logfile <logfile path>

Select the log file, either the string 'syslog' indicating that syslog(1) should be used or a log file path. The default is to use syslog.

-D, --loglevel [level]

Determine the amount of logging information. level can be a symbolic syslog level: 'error','warning, 'info', 'notice' or ´debug'. lircd-uinput also defines three additional levels 'trace', 'trace1' and 'trace2' which gives even more messages ('trace2' bringing the most). However, in the log these messages are marked as 'debug'.

-h --help

Display usage summary.

-v --version

Display version info.

## REPEAT HANDLING
After receiving a keypress event the kernel will start emitting repeat events to applications until lircd-uinput emits a corresponding release event. The release events could be created by lircd(8) using the deprecated --release option. Such events typically has an _EVUP suffix appended to the original keypress event.

The preferred way is that lircd-uinput creates release events using the --add-release-events option. Combining both of these options might give unexpected results.

Note that the linux kernel uses the suffix _UP (which was used py lircd prior to 0.10.0) for other purposes since 4.7.

In any case, the repeat events generated by the kernel can be tweaked using the --repeat option. This can set the time between the keypress event and the first repeat event and the time between each repeat event. The --repeat option should only be used if no other program or udev rule is automatically setting up key repeat parameters. By design the repeat parameters can't be set in an atomic way during input device registration so this option is prone to race conditions.

Note that the lircd-uinput repeat-event handling differs from lircd(8) which implements (emulates) hardware autorepeat in the events sent to uinput (event.value == 2). lircd-uinput only sends keypress and release events, trusting the kernel autorepeat support.

## NOTES
By default, the dev/uinput device is not writable for regular users. Thus lircd-uinput needs to run as root unless these permissions are changed.

One way to achieve this is an udev rule. The lirc distribution contains an example rule which makes the lircd-uinput device writable for users in the group lirc. Another way is to use lircd-setup(8) to change the permissions. As distributed, the lirc_options.conf file contains an commented example using setfacl(1) .

lircd-uinput can only forward lircd button events with names from the legal namespace defined by the kernel. A complete list of possible button names is available in /usr/include/linux/input-event-codes.h and also using irrecord -l . Other button names are silently dropped.

The event keycode depends on the name that was given a button in the lircd config file e.g., if the button is named KEY_1 the keycode 1 will be generated.

The kernel makes the events generated by lircd-uinput available on a /dev/input device like /dev/input/event12. This device name is not stable and typically varies after a reboot. The lirc distribution contains a udev rule which if installed creates a device link named /dev/lircd-uinput which always can be used.

lircd-uinput is designed to replace the currently deprecated --uinput option to lircd(8). However, lircd-uinput forwards all events unless blocked by the --disabled option. On the other hand, lircd --uinput does not forward all events - the heuristics used has been changed over versions.

## BUGS
Since the device name is fixed, only one instance of lircd-uinput can run on a system.

## SEE ALSO
lircd(8)

irrecord(1)

http://www.kernel.org/doc/Documentation/input/event-codes.txt


lircmd

title: lircmd(8)

text:
# lircmd(8)

## NAME
lircmd - Translate infrared signals into mouse events.

## SYNOPSIS
lircmd [options] [config-file]

## DESCRIPTION
lircmd reads decoded buttonpress events from a lircd(8) output socket and converts them to mouse events. These events are made available either on the lircmd output socket (by default /var/run/lirc/lircmd ) or, using the --uinput option, on a /dev/input device like /dev/input/event12 .

This daemon can simulate a MouseSystems, IntelliMouse or IMPS/2 type mouse. The function depends on a configuration file, by default /etc/lirc/lircmd.conf . This file determines which button from which remote causes a mouse move or a mouse button click. Special button which activates or deactivates the mouse mode can also be defined.

The normal usage is to configure X11 to use the events produced by lircmd as an input source. See SEE ALSO.

Using the --uinput option the user device created by the kernel has a dynamic name which typically changes after a reboot. The lirc distribution contains a udev rule which, if installed, creates a fixed link named /dev/lircmd which always can be used.

By default, using the --uinput option requires lircmd to run as root since the /dev/uinput device can be accessed only by root. The lirc distribution contains example udev rules and lircd-setup(8) configurations which can be used to make the device accessible by other users. In this way, lircmd can be run as a regular user.

## OPTIONS
-h --help

Display help message.

-v --version

Display version.

-n --nodaemon

Don't fork to background.

-s --socket <socket path>

Use alternate lircd socket path (the lircmd input source). Defaults to the output key in the [lircd] section of the lirc_options.conf config file, falling back to /var/run/lirc/lircd.

-O --options-file=file

Alternative default options file, usually defaults to /etc/lirc/lirc_options.conf.

-u --uinput

On Linux systems the --uinput option will enable automatic generation of Linux input events. lircmd will open /dev/input/uinput and inject the simulated mouse events into the Linux kernel rather than creating the /dev/lircm device. The kernel makes these events available to other applications on a /dev/input device, just like any other kernel input device.

-D --loglevel=[level]

Determine the amount of logging information. [level] can be a symbolic syslog level: 'error','warning, 'info', 'notice' or 'debug'. lircd also defines three additional levels 'trace', 'trace1' and 'trace2' which gives even more messages ('trace2' bringing the most). However, in the log these messages are marked as 'debug'.

## SOCKET PROTOCOL
The socket protocol contains undocumented parts. The data on the output socket is

MouseSystems

5 byte packets:

- Byte 1: Button information.

- Byte 2: X-axis change.

- Byte 3: Y-axis change.

- Byte 4 and 5: 0.

IMPS/2

4 byte packets. Please refer to the lircmd source code for details.

IntelliMouse

4 byte packets. Please refer to the lircmd source code for details.

## FILES
lircmd will use syslogd to output error messages. It depends on your system configuration where they will show up.

The options file is by default /etc/lirc/lirc_options.conf; lircmd handles the values under the [lircmd] section in this file. The location can be changed using the -O/--options-file command-line option or using the environment variable LIRC_OPTIONS_PATH. The values here are used as defaults for any option not present on command line.

## DAEMONS
lircmd is a daemon. It should be started in some system-dependent init script. Besides the systemd setup which is installed by default there are also example scripts for other distros and init systems in the contrib directory. lircmd has to be started after lircd as it connects to the socket lircd provides.

## BUGS
Since the device name used when registrating the --uinput device is fixed, only one instance of lircmd using this option can run on a given system.

The socket protocol is a documentation-wise mess.

## SEE ALSO
http://lirc.org/html/configure.html#lircmd.conf

lircd(8)

lircd-setup(8)