de-DE/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>Fragt einen oder mehrere NTP-Server ab und liefert Diagnoseinformationen zur Netzwerkzeit zurück.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Get-NTPTime implementiert einen NTPv3-/NTPv4-Client (RFC 2030 / RFC 5905) über UDP. Für jeden über -NTPServer übergebenen Servernamen oder jede literale IP-Adresse wird der Name zu einer oder mehreren IPv4-/IPv6-Adressen aufgelöst. Das zurückgegebene Objekt enthält den vollständigen Satz an Feldern aus der Serverantwort (Leap Indicator, Stratum, Root Delay/Dispersion, Reference Identifier sowie alle vier NTP-Zeitstempel) zusammen mit der lokal gemessenen Roundtrip-Verzögerung und der Zeitabweichung (Offset).</maml:para> <maml:para>Löst ein Servername zu mehreren Adressen auf, steuert -AddressSelectionMode, wie diese verwendet werden: nur die erste Adresse abfragen, bei Fehler auf die nächste Adresse ausweichen, alle Adressen abfragen und pro Adresse ein eigenes Ergebnisobjekt zurückgeben, oder (in einer späteren Version) automatisch die Adresse mit der kleinsten Synchronisationsdistanz auswählen.</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>Ein oder mehrere NTP-Servernamen oder literale IP-Adressen (IPv4 oder IPv6). Jeder Eintrag wird unabhängig abgefragt und erzeugt ein oder mehrere eigene Ergebnisobjekte.</maml:para> </maml:description> <command:parameterValue required="true">String[]</command:parameterValue> <dev:type><maml:name>String[]</maml:name></dev:type> <dev:defaultValue>Keiner</dev:defaultValue> </command:parameter> <command:parameter required="false" position="named" pipelineInput="false" globalScope="false"> <maml:name>NTPVersion</maml:name> <maml:description> <maml:para>Im Anfragepaket zu verwendende NTP-Protokollversion. Gültige Werte sind 3 (NTPv3) und 4 (NTPv4). Standardwert ist 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>Löst der Servername sowohl zu IPv4- als auch IPv6-Adressen auf, werden IPv6-Adressen zuerst versucht. Hat keine Auswirkung, wenn nur eine Adressfamilie verfügbar ist. Kann nicht zusammen mit -OnlyIPv6 oder -OnlyIPv4 verwendet werden.</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>Beschränkt die Namensauflösung auf IPv6-Adressen. Besitzt der Server keinen AAAA-Eintrag, wird eine Warnung ausgegeben und für diesen Server kein Ergebnis geliefert.</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>Beschränkt die Namensauflösung auf IPv4-Adressen. Besitzt der Server keinen A-Eintrag, wird eine Warnung ausgegeben und für diesen Server kein Ergebnis geliefert.</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>Steuert, wie die aufgelösten Adressen eines Servers verwendet werden, wenn es mehr als eine gibt:</maml:para> <maml:para>- First: Es wird nur die erste aufgelöste Adresse abgefragt (am schnellsten, kein Failover).</maml:para> <maml:para>- Failover (Standard): Adressen werden der Reihe nach versucht, bis eine erfolgreich ist; das erste erfolgreiche Ergebnis wird zurückgegeben, verbleibende Adressen werden übersprungen.</maml:para> <maml:para>- All: Jede aufgelöste Adresse wird parallel abgefragt und liefert ein eigenes Ergebnisobjekt, einschließlich fehlgeschlagener Versuche (siehe isValid).</maml:para> <maml:para>- BestSyncDistance: Jede aufgelöste Adresse wird parallel abgefragt, zurückgegeben wird nur das einzelne Ergebnis mit der kleinsten Synchronisationsdistanz (RFC 5905: RootDispersion + RootDelay/2 + lokaler Roundtrip/2) unter den gültigen Antworten. Fehlgeschlagene Adressen werden ignoriert; antwortet keine, wird eine Warnung ausgegeben und nichts zurückgegeben.</maml:para> <maml:para>All und BestSyncDistance fragen Adressen über einen Runspace-Pool nebenläufig ab (bis zu 8 gleichzeitig), sodass die Gesamtlaufzeit von der am langsamsten antwortenden Adresse dominiert wird statt von der Summe aller.</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>Gibt anstelle des vollständigen Diagnoseobjekts nur den Transmit Timestamp des Servers als [DateTime]-Wert zurück.</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>Dieses Cmdlet akzeptiert keine Pipeline-Eingabe.</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>Bei Verwendung von -AsDateTime: der Transmit Timestamp des Servers, umgewandelt in einen lokalen [DateTime]-Wert (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>Andernfalls: ein Objekt pro abgefragter Adresse mit folgenden Eigenschaften:</maml:para> <maml:para>LeapIndicator, Version, Mode, Stratum, Poll, Precision, RootDelay, RootDispersion, ReferenceIdentifier - direkt aus dem NTP-Header übernommene Felder, siehe RFC 5905 Abschnitt 7.3.</maml:para> <maml:para>ReferenceTimestamp, OriginateTimestamp, ReceiveTimestamp, TransmitTimestamp - die vier NTP-Zeitstempel, umgewandelt in lokale [DateTime]-Werte.</maml:para> <maml:para>UsedNTPServer, UsedNTPServerIP - der übergebene Servername sowie die konkret abgefragte IP-Adresse.</maml:para> <maml:para>LocalReciveTime, RoundtripDelay, Offset - lokal gemessener Empfangszeitpunkt, Roundtrip-Verzögerung und Zeitabweichung, jeweils in Sekunden.</maml:para> <maml:para>SyncDistance - Synchronisationsdistanz nach RFC 5905 (RootDispersion + RootDelay/2 + RoundtripDelay/2, in Sekunden); der Wert, anhand dessen im Modus BestSyncDistance der Gewinner ermittelt wird. Nur aussagekräftig, wenn isValid True ist.</maml:para> <maml:para>connectError, sendReciveError - boolesche Werte, die anzeigen, ob die UDP-Verbindung oder der Sende-/Empfangsvorgang für diese Adresse fehlgeschlagen ist.</maml:para> <maml:para>isValid - True nur dann, wenn für diese Adresse eine vollständige, auswertbare Antwort empfangen wurde. Bei False sind alle obigen Felder Platzhalter-/Sentinel-Werte (MinValue-Zeitstempel, LeapIndicator 3 / Stratum 15 als Kennzeichen für "nicht synchronisiert") und sollten ignoriert werden.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>Diese Funktion öffnet der Reihe nach eine ausgehende UDP-Verbindung auf Port 123 zu jeder aufgelösten Adresse. Es sind keine erhöhten Rechte erforderlich.</maml:para> <maml:para>Aus diesem Modul wird ausschließlich Get-NTPTime exportiert; die intern verwendeten Hilfsfunktionen (Adressauflösung, Paket-Parsing, Endianness-Behandlung) sind Implementierungsdetails und nicht Teil der öffentlichen Schnittstelle.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- BEISPIEL 1 --------------------------</maml:title> <dev:code>Get-NTPTime -NTPServer pool.ntp.org</dev:code> <dev:remarks> <maml:para>Fragt pool.ntp.org ab und liefert das vollständige Diagnoseobjekt der ersten erfolgreich antwortenden Adresse (Standardmodus Failover).</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- BEISPIEL 2 --------------------------</maml:title> <dev:code>Get-NTPTime -NTPServer pool.ntp.org -AsDateTime</dev:code> <dev:remarks> <maml:para>Gibt nur die aktuelle Netzwerkzeit als [DateTime]-Wert zurück.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- BEISPIEL 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>Fragt jede IPv6-Adresse hinter beiden Servernamen ab und liefert pro Adresse ein eigenes Ergebnisobjekt, sodass sich Offset und Roundtrip-Verzögerung über alle Adressen vergleichen lassen.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- BEISPIEL 4 --------------------------</maml:title> <dev:code>Get-NTPTime -NTPServer '129.6.15.28' -NTPVersion 3</dev:code> <dev:remarks> <maml:para>Fragt direkt eine literale IPv4-Adresse ab (ohne DNS-Auflösung) unter Verwendung der älteren Protokollversion NTPv3.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- BEISPIEL 5 --------------------------</maml:title> <dev:code>Get-NTPTime -NTPServer pool.ntp.org -AddressSelectionMode BestSyncDistance</dev:code> <dev:remarks> <maml:para>Fragt alle Adressen hinter pool.ntp.org parallel ab und liefert nur das einzelne Ergebnis mit der kleinsten Synchronisationsdistanz.</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> |