Provided by: ptpd_2.3.1-debian1-3_amd64 bug

NAME

       ptpd - Precision Time Protocol daemon (1588-2008)

SYNOPSIS

       ptpd  [ -?hH ] [ -e SETTING ] [ -kvOLAl ] [ -smMyEPanCV ] [ -c FILE ] [ -R DIR ] [ -f FILE
       ] [ -S FILE ] [ -d DOMAIN ] [ -u ADDRESS ] [ -r NUMBER ] -i INTERFACE

DESCRIPTION

       PTPd is a daemon that implements the Precision Time Protocol (PTP) Version 2 as defined by
       the  IEEE  1588-2008 standard. PTP was developed to provide very precise time coordination
       of LAN connected computers.  The daemon must run as root in order to be able to manipluate
       the system clock and use low port numbers.  PTPd is feature rich, supports IPv4 multicast,
       unicast and hybrid mode (mixed) operation, as well as Ethernet mode. Even without hardware
       assistance,  PTPd  is  able to achieve and maintain sub-microsecond level timing precision
       and is able to withstand PTP  Grandmaster  failovers,  link  failures  and  restarts  with
       minimal  impact  to  timing  performance.   PTPd  is  lightweight,  portable and currently
       supports Linux, FreeBSD and Mac OS X and runs on multiple CPU  architectures,  32-bit  and
       64-bit, including x86 and ARM.

COMMAND-LINE CONFIGURATION

       As  of  version 2.3.0, configuration file is the preferred mechanism for configuring PTPd,
       therefore the options available as short (-x) and long options  (--xxxxx)  mostly  provide
       basic  control  over  the  daemon  operation, and only provide the very basic PTP protocol
       settings. The rest of the settings (see ptpd2.conf(5)) can also be specified  as  command-
       line options, but they take the long --key:section="value" form.

BASIC DAEMON OPTIONS

       -c --config-file PATH
              Path to configuration file (see ptpd2.conf(5))

       -k --check-config
              Check configuration and exit - return 0 if configuration is correct.

       -v --version
              Print version string and exit

       -h --help
              Show help screen

       -H --long-help
              Show detailed help for all settings and behaviours

       -e --explain SETTING
              Show help for a single setting (section:key)

       -O --default-config
              Show default configuration and exit (output usable as a configuration file)

       -L --ignore-lock
              Skip lock file checks and locking (also global:ignore_lock)

       -A --auto-lock
              Use  preset  /  port  mode  specific lock file names - useful when running multiple
              instances

       -l --lockfile
              Specify lock file path (also global:lock_file)

       -p --print-lockfile
              Print path to lock file and exit (useful for init scripts in combination with  auto
              lock files)

       -R --lock-directory DIR
              Directory to store lock files (also global:lock_directory)

       -f --log-file PATH
              Path to log file (also global:logfile)

       -S --statistics-file PATH
              Path to statistics file (also global:statistics_file)

BASIC PTP PROTOCOL OPTIONS

       -i --interface DEV
              REQUIRED:Interface to use - eth0, etc (also ptpengine:interface)

       -d --domain NUMBER
              PTP domain number to become part of (also ptpengine:domain)

       -s --slaveonly
              Slave only mode (also ptpengine:preset=slaveonly)

       -m --masterslave
              Full   IEEE   1588   implementation:   master,   slave   when  not  best  GM  (also
              ptpengine:preset=masterslave)

       -M --masteronly
              Master only mode: passive when not best GM (also ptpengine:preset=masteronly)

       -y --hybrid
              Hybrid mode - mixed  multicast  and  unicast  operation  (multicast  for  sync  and
              announce, unicast for delay request and response (also ptpengine:ip_mode=hybrid)

       -U --unicast
              Unicast   operation   -   (also   ptpengine:ip_mode=unicast).  For  a  GM,  unicast
              destinations     must      be      specified      (-u,      --unicast-destinations,
              ptpengine:unicast_destinations)  unless  using  unicast negotiation (-g, --unicast-
              negotiation, ptpengine:unicast_negotiation=y) for delay request and response  (also
              ptpengine:ip_mode=hybrid).  For  a slave, unicast destinations must be specified if
              not using unicast negotiation.

       -g --unicast-negotiation
              Enable unicast message delivery and interval negotiation usin  signaling  messages,
              as used by the Telecom profile (also enables ptpengine:ip_mode=unicast)

       -u --unicast-destinations ip/host, ip/host, ...
              List  of  unicast  destinations  -  see --unicast (also ptpengine:ip_mode=unicast +
              ptpengine:unicast_destinations)  -E  --e2e  End  to  end  delay   mechanism   (also
              ptpengine:delay_mechanism=E2E)

       -E --p2p
              Peer to peer delay mechanism (also ptpengine:delay_mechanism=P2P)

       -a --delay-override
              In  slave  state,  override  delay  request  interval  announced  by  master  (also
              ptpengine:log_delayreq_override) - the value of ptpengine:log_delayreq_interval  is
              used

       -r --delay-interval NUMBER
              Specify     delay     request     message     interval     (log    2)    -    (also
              ptpengine:log_delayreq_interval)

       -n --clock:no_adjust
              Do not adjust the clock (also clock:no_adjust)

       -D<DD...> --debug
              Debug level (also global:debug_level) - only if compiled with RUNTIME_DEBUG

       -C --foreground
              Don't run in background (also global:foreground=Y)

       -V --verbose
              Run  in   foreground,   log   all   the   messages   to   standard   output   (also
              global:verbose_foreground=Y)

COMPATIBILITY OPTIONS

       PTPd supports the following options compatible with versions before 2.3.0:

               -b DEV  Network interface to use

               -i NUMBER
                       PTP domain number

               -g      Slave only mode

               -G      ´Master mode with NTP´ (master only mode)

               -W      ´Master mode without NTP´ (master / slave mode)

               -U      Hybrid mode (mixed unicast + multicast operation)

               -Y NUMBER
                       Delay request interval (log 2)

               -t      Do not adjust the clock

       NOTE:  the  above options are deprecated and will be removed in subsequent versions. Until
       then, their use will issue a warning.

PTPD PORT STATES

               init   INITIALIZING

               flt    FAULTY

               lstn_init
                      LISTENING (first time)

               lstn_reset
                      LISTENING (subsequent reset)

               pass   PASSIVE (not best master, not announcing)

               uncl   UNCALIBRATED

               slv    SLAVE

               pmst   PRE-MASTER

               mst    MASTER (active)

               dsbl   DISABLED

               ? (unk)
                      UNKNOWN state

STATISTICS LOG FILE FORMAT

       When the statistics log is enabled (ptpengine:log_statistics, verbose foreground  mode  or
       log  file  - ptpengine:statistics_file), a PTPd slave will log clock sync information upon
       the receipt of every Sync and Delay Response message.  When PTPd starts up or flushes  the
       log, a comment line (starting with #) will be logged, containing the names of all columns.
       The format of this log is a series of comma-separated  values  (CSV)  and  can  be  easily
       imported  into  statistics  tools  and most spreadsheet software packages for analysis and
       graphing.  This log can get very large when running PTPd for longer periods  of  time  and
       with  high  message  rates,  therefore  to  reduce  the  number  of  messages  logged, the
       global:statistics_log_interval setting can be used, to limit the log output to one message
       per  configured  interval only. The size and maximum number of the statistics log can also
       be controlled - (see ptpd2.conf(5)).

       The meaning of the columns is as follows:

               Timestamp
                       Time when message received. This can take the form of text date / time  or
                       Unix  timestamp  (with fractional seconds), or both (in which case an exra
                       field  is  added),  depending  on  the  global:statistics_timestamp_format
                       setting  (see  ptpd2.conf(5)).   When  importing  the  log  into  plotting
                       software, if the software can understand Unix time, it is best to set  the
                       timestamp  format to unix or both, as some software will not properly deal
                       with the fractional part of the second when converting the date  and  time
                       from text.

               State   Port state (see PTP PORT STATES).

               Clock ID
                       Port  identity  of  the current best master, as defined by IEEE 1588. This
                       will be the local clock's ID if  the  local  clock  is  the  best  master.
                       Displayed as clock_id/port(host) Port is the PTP clock port number, not to
                       be confused with UDP ports. The clock ID is an EUI-64 64-bit  ID,  usually
                       converted  from  the  48-bit  MAC address, by inserting 0xfffe between the
                       lower and upper half of the MAC address. PTPd will attempt to convert  the
                       clock  ID  back  to  MAC address and look up the hostname from /etc/ethers
                       (see ethers(5)). Populating the ethers file will  help  the  administrator
                       recognise the masters by familiar hostnames.

               One Way Delay
                       Current value of one-way delay (or mean path delay) in seconds, calculated
                       by PTPd in slave state from the Delay Request  -  Delay  Response  message
                       exchange.  Note: if this value remains at zero, this usually means that no
                       Delay Response messages are being received, likely due to a network issue.

               Offset From Master
                       Current value of offset from master in seconds - this is the  main  output
                       of  the  PTP  engine in slave state, which is the input of the clock servo
                       for  clock  corrections.  This  is  the  value  typically  observed   when
                       estimating the slave performance.

               Slave to Master
                       Intermediate  offset  value  (seconds)  extracted from the Delay Request -
                       Delay Response message exchange, used for computing one-way delay. If  the
                       last  value  was rejected by a filter, the previous value will be shown in
                       the log. This value will also be zero if no Delay  Response  messages  are
                       being received.

               Master to Slave
                       Intermediate offset value (seconds) extracted from the Sync messages, used
                       for computing the offset from master.  If the last value was rejected by a
                       filter, the previous value will be shown in the log.

               Observed Drift
                       The  integral  accumulator of the clock control PI servo model - frequency
                       difference between the slave clock and master clock.  This  value  becomes
                       stable  when  the clock offset has stabilised, and can be used (and is) to
                       detect clock stability.

               Last Packet Received
                       This field shows what message was received last - this will be S for  Sync
                       and  D  for  Delay Response. If a slave logs no D entries, this means it's
                       not receiving Delay Response messages, which could be a network issue.

               One Way Delay Mean
                       One-way delay mean computed over the last sampling window.

               One Way Delay Std Dev
                       One-way delay standard deviation computed over the last sampling window.

               Offset From Master Mean
                       Offset from master mean computed over the last sampling window.

               Offset From Master Std Dev
                       Offset from master standard deviation  computed  over  the  last  sampling
                       window.

               Observed Drift Mean
                       Observed  drift  / local clock frequency adjustment mean computed over the
                       last sampling window.

               Observed Drift Std Dev
                       Observed drift /  local  clock  frequency  adjustment  standard  deviation
                       computed  over  the  last  sampling window.  The lower the value, the less
                       aggressively the clock is being controlled and therefore the  more  stable
                       it is.

               raw delayMS
                       Raw (unfiltered) delayMS value - useful for evaluating outliers and filter
                       performance.

               raw delaySM
                       Raw (unfiltered) delaySM value - useful for evaluating outliers and filter
                       performance.

       NOTE:  All the statistical measures (mean and std dev) will only be computed and displayed
       if PTPd was built without --disable-statistics. The duration of  the  sampling  period  is
       controlled with the global:statistics_update_interval setting - (see ptpd2.conf(5)).

HANDLED SIGNALS

       PTPd handles the following signals:

               SIGHUP  Reload configuration file (if used) and reopen log files

               SIGUSR1 When in slave state, force clock step to current Offset from Master value

               SIGUSR2 Dump  all  PTP  protocol  counters  to  current  log  target (and clear if
                       ptpengine:sigusr2_clears_counters set)

               SIGINT|SIGTERM
                       Clean exit - close logs and other open files, clean up lock file and exit.

               SIGKILL Force an unclean exit.

EXIT CODES

       Upon exit, ptpd2 returns 0 on success - either successfully started  in  daemon  mode,  or
       otherwise exited cleanly.  0 is  also returned when the -k (--check-config) option is used
       and the configuration was correct. A non-zero exit code  is  returned  on  errors.   3  is
       returned on lock file errors and when ptpd2 could not be started as daemon.  2 is returned
       on memory allocation errors during  startup.  For  all  other  error  conditions  such  as
       configuration  errors, running ptpd2 in help mode or with no parameters, on self shutdown,
       network startup errors and when attempting to run ptpd2 as non-root -  1 is returned.

SUPPORTED PLATFORMS AND ARCHITECTURES

       PTPd is fully supported on Linux and FreeBSD as this is what the core developers focus on.
       OpenBSD  and  NetBSD are also supported, but get less developers' attention.  So is Max OS
       X, and as of PTPd 2.3.1 also OpenSolaris (11) derivatives (tested  on  OmniOS).   Sun's  /
       Oracle's  Solaris  11  has  not  been  tested  but in essence, it should work as intended.
       Solaris 10 is NOT supported because it does not provide the  SO_TIMESTAMP  socket  option.
       It  should  theoretically  be  possible to use Solaris 10 using the pf facility as used by
       snoop, but there is currently no ongoing effort to achieve this. Patches for  QNX/Neutrino
       have  been provided, but cannot yet officially be merged because of no availability of QNX
       to the developers. Some users have ported PTPd to other RTOS, but this has not been merged
       either.

       As  of  2.3.1,  PTPd  runs  entirely in software and only relies on kernel and OS APIs, so
       there are no hardware  dependencies.  Any  little-endian  or  big-endian  port  of  modern
       versions  of the supported OSes should work, but only x86 and ARM are actively tested. The
       only dependencies close to hardware can be NIC drivers and how and if they impact software
       timestamping.

HARDWARE TIMESTAMPING SUPPORT

       As  of  2.3.1,  PTPd still does not support hardware timestamping. This functionality will
       appear in the upcoming version 2.4 - potentially  an  interim  version  of  2.3.x  may  be
       delivered  that  will support hardware clocks and timestamping on Linux. This is very much
       OS-specific and to a large extent, hardware-specific. Linux has a PTP kernel API  but  not
       all  hardware  supports  it.   Because PTPd supports multiple OS platforms, where hardware
       timestamping may use different mechanisms on every platform, it has to be re-written in  a
       modular  way to allow this without unnecessarily increasing code complexity, which already
       is a problem.

BUGS

       As of ptpd 2.3.1, the (Open)Solaris (11) OS family is supported, but libpcap functionality
       is  currently  broken - IPv4/pcap and Ethernet transports cannot be used on those systems.
       PTPd will compile and run,
        but will not receive any data.

       Please  report   any   bugs   using   the   bug   tracker   on   the   SourceForge   page:
       http://sourceforge.net/projects/ptpd/

SEE ALSO

       ptpd2.conf(5)

AUTHORS

       Gael Mace <gael_mace@users.sourceforge.net>

       Alexandre Van Kempen

       Steven Kreuzer <skreuzer@freebsd.org>

       George Neville-Neil <gnn@freebsd.org>

       Wojciech Owczarek <wojciech@owczarek.co.uk>

       ptpd2(8) man page was written by Wojciech Owczarek for ptpd 2.3.0 in November 2013