en-US/FITS.NetUtils-help.xml
|
<?xml version="1.0" encoding="utf-8"?> <helpItems xmlns="http://msh" schema="maml"> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10"> <command:details> <command:name>Get-NTPTime</command:name> <command:verb>Get</command:verb> <command:noun>NTPTime</command:noun> <maml:description> <maml:para>Queries one or more NTP servers and returns diagnostic time information.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Get-NTPTime implements an NTPv3/NTPv4 client (RFC 2030 / RFC 5905) over UDP. For each server name or literal IP address passed via -NTPServer, the DNS name is resolved to one or more IPv4/IPv6 addresses, and the resulting object contains the full set of fields from the server reply (leap indicator, stratum, root delay/dispersion, reference identifier, and all four NTP timestamps), together with the locally measured round-trip delay and clock offset.</maml:para> <maml:para>When a host name resolves to several addresses, -AddressSelectionMode controls how they are used: query only the first address, fail over to the next address on error, query all addresses and return one result object per address, or (in a later version) automatically pick the address with the smallest synchronization distance.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-NTPTime</maml:name> <command:parameter required="true" position="named" pipelineInput="false" globalScope="false"> <maml:name>NTPServer</maml:name> <command:parameterValue required="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="false" globalScope="false"> <maml:name>NTPVersion</maml:name> <command:parameterValue required="true">Byte</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="false" globalScope="false"> <maml:name>PreferIPv6</maml:name> <command:parameterValue required="false">SwitchParameter</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="false" globalScope="false"> <maml:name>AddressSelectionMode</maml:name> <command:parameterValue required="true">String</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="false" globalScope="false"> <maml:name>AsDateTime</maml:name> <command:parameterValue required="false">SwitchParameter</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-NTPTime</maml:name> <command:parameter required="true" position="named" pipelineInput="false" globalScope="false"> <maml:name>NTPServer</maml:name> <command:parameterValue required="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="false" globalScope="false"> <maml:name>NTPVersion</maml:name> <command:parameterValue required="true">Byte</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="false" globalScope="false"> <maml:name>OnlyIPv6</maml:name> <command:parameterValue required="false">SwitchParameter</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="false" globalScope="false"> <maml:name>AddressSelectionMode</maml:name> <command:parameterValue required="true">String</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="false" globalScope="false"> <maml:name>AsDateTime</maml:name> <command:parameterValue required="false">SwitchParameter</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-NTPTime</maml:name> <command:parameter required="true" position="named" pipelineInput="false" globalScope="false"> <maml:name>NTPServer</maml:name> <command:parameterValue required="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="false" globalScope="false"> <maml:name>NTPVersion</maml:name> <command:parameterValue required="true">Byte</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="false" globalScope="false"> <maml:name>OnlyIPv4</maml:name> <command:parameterValue required="false">SwitchParameter</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="false" globalScope="false"> <maml:name>AddressSelectionMode</maml:name> <command:parameterValue required="true">String</command:parameterValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="false" globalScope="false"> <maml:name>AsDateTime</maml:name> <command:parameterValue required="false">SwitchParameter</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" position="named" pipelineInput="false" globalScope="false"> <maml:name>NTPServer</maml:name> <maml:description> <maml:para>One or more NTP server host names or literal IP addresses (IPv4 or IPv6). Each entry is queried independently and produces its own result object(s).</maml:para> </maml:description> <command:parameterValue required="true">String[]</command:parameterValue> <dev:type><maml:name>String[]</maml:name></dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="false" globalScope="false"> <maml:name>NTPVersion</maml:name> <maml:description> <maml:para>NTP protocol version to send in the request packet. Valid values are 3 (NTPv3) and 4 (NTPv4). Default is 4.</maml:para> </maml:description> <command:parameterValue required="true">Byte</command:parameterValue> <dev:type><maml:name>Byte</maml:name></dev:type> <dev:defaultValue>4</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="false" globalScope="false"> <maml:name>PreferIPv6</maml:name> <maml:description> <maml:para>If the server name resolves to both IPv4 and IPv6 addresses, IPv6 addresses are tried first. Has no effect if only one address family is available. Cannot be combined with -OnlyIPv6 or -OnlyIPv4.</maml:para> </maml:description> <command:parameterValue required="false">SwitchParameter</command:parameterValue> <dev:type><maml:name>SwitchParameter</maml:name></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="false" globalScope="false"> <maml:name>OnlyIPv6</maml:name> <maml:description> <maml:para>Restricts name resolution to IPv6 addresses. If the server has no AAAA record, a warning is written and no result is produced for that server.</maml:para> </maml:description> <command:parameterValue required="false">SwitchParameter</command:parameterValue> <dev:type><maml:name>SwitchParameter</maml:name></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="false" globalScope="false"> <maml:name>OnlyIPv4</maml:name> <maml:description> <maml:para>Restricts name resolution to IPv4 addresses. If the server has no A record, a warning is written and no result is produced for that server.</maml:para> </maml:description> <command:parameterValue required="false">SwitchParameter</command:parameterValue> <dev:type><maml:name>SwitchParameter</maml:name></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="false" globalScope="false"> <maml:name>AddressSelectionMode</maml:name> <maml:description> <maml:para>Controls how a server's resolved addresses are used when there is more than one:</maml:para> <maml:para>- First: only the first resolved address is queried (fastest, no failover).</maml:para> <maml:para>- Failover (default): addresses are tried in order until one succeeds; the first successful result is returned and remaining addresses are skipped.</maml:para> <maml:para>- All: every resolved address is queried in parallel and a separate result object is returned for each one, including failed attempts (see isValid).</maml:para> <maml:para>- BestSyncDistance: every resolved address is queried in parallel, and only the single result with the smallest Synchronization Distance (RFC 5905: RootDispersion + RootDelay/2 + local Roundtrip/2) among the valid responses is returned. Failed addresses are ignored; if none respond, a warning is written and nothing is returned.</maml:para> <maml:para>All and BestSyncDistance query addresses concurrently (up to 8 at a time) via a runspace pool, so total runtime is dominated by the slowest responding address rather than the sum of all of them.</maml:para> </maml:description> <command:parameterValue required="true">String</command:parameterValue> <dev:type><maml:name>String</maml:name></dev:type> <dev:defaultValue>Failover</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="false" globalScope="false"> <maml:name>AsDateTime</maml:name> <maml:description> <maml:para>Returns only the server's Transmit Timestamp as a [DateTime] value instead of the full diagnostic object.</maml:para> </maml:description> <command:parameterValue required="false">SwitchParameter</command:parameterValue> <dev:type><maml:name>SwitchParameter</maml:name></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type><maml:name>None</maml:name></dev:type> <maml:description><maml:para>This cmdlet does not accept pipeline input.</maml:para></maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type><maml:name>System.DateTime</maml:name></dev:type> <maml:description><maml:para>When -AsDateTime is used: the server's Transmit Timestamp, converted to a local [DateTime] value (UTC).</maml:para></maml:description> </command:returnValue> <command:returnValue> <dev:type><maml:name>System.Management.Automation.PSObject</maml:name></dev:type> <maml:description> <maml:para>Otherwise: one object per queried address, with the following properties:</maml:para> <maml:para>LeapIndicator, Version, Mode, Stratum, Poll, Precision, RootDelay, RootDispersion, ReferenceIdentifier - fields taken directly from the NTP header, see RFC 5905 section 7.3.</maml:para> <maml:para>ReferenceTimestamp, OriginateTimestamp, ReceiveTimestamp, TransmitTimestamp - the four NTP timestamps, converted to local [DateTime] values.</maml:para> <maml:para>UsedNTPServer, UsedNTPServerIP - the server name as passed in and the specific IP address that was actually queried.</maml:para> <maml:para>LocalReciveTime, RoundtripDelay, Offset - locally measured reply arrival time, round-trip delay, and clock offset, all in seconds.</maml:para> <maml:para>SyncDistance - Synchronization Distance per RFC 5905 (RootDispersion + RootDelay/2 + RoundtripDelay/2, in seconds); the value used to pick the winner in BestSyncDistance mode. Only meaningful when isValid is true.</maml:para> <maml:para>connectError, sendReciveError - booleans indicating whether the UDP connection or the send/receive exchange failed for this address.</maml:para> <maml:para>isValid - true only if a complete, parseable reply was received for this address. When false, all fields above are placeholder/sentinel values (MinValue timestamps, LeapIndicator 3 / Stratum 15 to mark "unsynchronized") and should be ignored.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>This function opens an outbound UDP connection on port 123 to each resolved address in turn. It does not require elevated privileges.</maml:para> <maml:para>Only Get-NTPTime is exported by this module; the helper functions it relies on (address resolution, packet parsing, endianness handling) are internal implementation details and are not part of the public interface.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Get-NTPTime -NTPServer pool.ntp.org</dev:code> <dev:remarks> <maml:para>Queries pool.ntp.org and returns the full diagnostic object for the first address that answers successfully (default Failover mode).</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Get-NTPTime -NTPServer pool.ntp.org -AsDateTime</dev:code> <dev:remarks> <maml:para>Returns just the current network time as a [DateTime] value.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>Get-NTPTime -NTPServer 'de.pool.ntp.org', '2.de.pool.ntp.org' -AddressSelectionMode All -OnlyIPv6</dev:code> <dev:remarks> <maml:para>Queries every IPv6 address behind both host names and returns one result object per address, so you can compare offset and round-trip delay across all of them.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 4 --------------------------</maml:title> <dev:code>Get-NTPTime -NTPServer '129.6.15.28' -NTPVersion 3</dev:code> <dev:remarks> <maml:para>Queries a literal IPv4 address directly (no DNS resolution) using the older NTPv3 protocol version.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 5 --------------------------</maml:title> <dev:code>Get-NTPTime -NTPServer pool.ntp.org -AddressSelectionMode BestSyncDistance</dev:code> <dev:remarks> <maml:para>Queries every address behind pool.ntp.org in parallel and returns only the single result with the smallest synchronization distance.</maml:para> </dev:remarks> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>RFC 5905 - Network Time Protocol Version 4</maml:linkText> <maml:uri>https://www.rfc-editor.org/rfc/rfc5905</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> </helpItems> |