Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ptpd2(8)		Precision Time Protocol	daemon		      ptpd2(8)

NAME
       ptpd2 - Precision Time Protocol daemon (1588-2008)

SYNOPSIS
       ptpd2 [ -?hH ] [	-e SETTING ] [ -kvOLAl ] [ -smMyEPanCV ] [ -c FILE ] [
       -R DIR ]	[ -f FILE ] [ -S FILE ]	[ -d DOMAIN ] [	-u ADDRESS ] [ -r NUM-
       BER ] -i	INTERFACE

DESCRIPTION
       PTPd is a daemon	that implements	the Precision Time Protocol (PTP) Ver-
       sion 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	Ether-
       net mode. Even without hardware assistance, PTPd	is able	to achieve and
       maintain	sub-microsecond	level timing precision and is  able  to	 with-
       stand  PTP Grandmaster failovers, link failures and restarts with mini-
       mal 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 op-
       eration,	 and  only  provide  the very basic PTP	protocol settings. The
       rest of the settings (see ptpd2.conf(5))	can also be specified as  com-
       mand-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 cor-
	      rect.

       -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 configu-
	      ration 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:pre-
	      set=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-destina-
	      tions,  ptpengine:unicast_destinations) unless using unicast ne-
	      gotiation	(-g, --unicast-negotiation, ptpengine:unicast_negotia-
	      tion=y)	 for	delay	request	  and	response   (also   pt-
	      pengine: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  pt-
	      pengine:ip_mode=unicast  +  ptpengine:unicast_destinations)   -E
	      --e2e  End  to  end delay	mechanism (also	ptpengine:delay_mecha-
	      nism=E2E)

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

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

       -r --delay-interval NUMBER
	      Specify  delay  request  message	interval  (log	2) - (also pt-
	      pengine: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	subse-
       quent 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  De-
       lay  Response  message.	When PTPd starts up or flushes the log,	a com-
       ment 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 spread-
       sheet  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 maxi-
       mum 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    onthe    global:statistics_time-
		       stamp_format setting (see ptpd2.conf(5)).  When import-
		       ing 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 prop-
		       erly  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 lo-
		       cal  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  up-
		       per  half of the	MAC address. PTPd will attempt to con-
		       vert 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 De-
		       lay 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 correc-
		       tions.  This is the value typically observed when esti-
		       mating 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  re-
		       jected by a filter, the previous	value will be shown in
		       the log.	This value will	also be	zero if	no  Delay  Re-
		       sponse messages are being received.

	       Master to Slave
		       Intermediate  offset value (seconds) extracted from the
		       Sync messages, used for computing the offset from  mas-
		       ter.   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 win-
		       dow.

	       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 stan-
		       dard  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 com-
       puted and displayed if PTPd was built without --disable-statistics. The
       duration	 of  the sampling period is controlled with the	global:statis-
       tics_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 pa-
       rameters,  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 So-
       laris 11	has not	been tested but	in essence,  it	 should	 work  as  in-
       tended.	 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 cur-
       rently no ongoing effort	to acheive this. Patches for QNX/Neutrino have
       been provided, but cannot yet officially	be merged because of no	avail-
       ability 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 soft-
       ware 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 plat-
       form,  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

version	2.3.1			  June,	2015			      ptpd2(8)

NAME | SYNOPSIS | DESCRIPTION | COMMAND-LINE CONFIGURATION | BASIC DAEMON OPTIONS | BASIC PTP PROTOCOL OPTIONS | COMPATIBILITY OPTIONS | PTPD PORT STATES | STATISTICS LOG FILE FORMAT | HANDLED SIGNALS | EXIT CODES | SUPPORTED PLATFORMS AND ARCHITECTURES | HARDWARE TIMESTAMPING SUPPORT | BUGS | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ptpd2&sektion=8&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help