Skip to content

ntp command group

The ntp command group in the alpine-admin-cli manages the global administrator NTP (Network Time Protocol) configuration for {{ product_name }}: the trusted-time server endpoint and the validation policy that decides which NTP responses are accepted. Use it to inspect the active configuration, apply partial updates, and back up or restore the configuration as a binary protobuf file.

These are remote gRPC commands. Before running any command in this group you must:

  1. Create a host profile with profile hosts create.
  2. Authenticate with profile authn login.

The global -p/--profile option (default default-admin) selects which host profile to use for a single invocation and is placed before the command path. Host connection profiles — including their embedded OIDC logins (with PIN-sealed tokens) — are stored under ${HOME}/.config/alpinepki/hosts/. Shared flags are documented in Global options.

Commands in this group

Command Purpose
ntp view Display the current administrator NTP configuration
ntp update Apply a partial (merge) update to the configuration
ntp backup Back up the configuration to a binary .pb file
ntp restore Restore the configuration from a binary .pb backup

Typical workflow

  1. Inspect the active configuration with ntp view.
  2. Capture a known-good snapshot with ntp backup before making changes.
  3. Apply changes with ntp update; only the supplied options change.
  4. If a change must be reverted, reapply the snapshot with ntp restore.

Command group help

bin/admin.sh ntp --help

ntp view

Display the global administrator NTP configuration (validation policy and server).

Syntax

bin/admin.sh ntp view [options]

Required options

This command has no command-specific required options.

Optional options

Show optional options
Option Default Description
-f, --out-format YAML Output format: JSON or YAML

Example

bin/admin.sh ntp view -f json

ntp update

Update the global administrator NTP configuration. This command performs a partial merge: the current configuration is fetched, only the options you supply are applied on top, and the merged configuration is written back. Any option you omit leaves the corresponding field unchanged.

Syntax

bin/admin.sh ntp update [options]

Required options

This command has no required options. Supply only the fields you want to change.

Optional options

Show optional options
Option Default Description
--ntp-server-name unchanged NTP server name (non-blank)
--ntp-description unchanged NTP server description
--ntp-host unchanged NTP server host (validated host value)
--ntp-policy-name unchanged Validation policy name (non-blank)
--ntp-time-source-mode unchanged Time source mode: TIME_SOURCE_MODE_SERVER_ONLY, TIME_SOURCE_MODE_SERVER_IF_VALID_ELSE_CLIENT, or TIME_SOURCE_MODE_CLIENT_ONLY
--ntp-failure-mode unchanged Failure mode: NTP_FAILURE_MODE_INHERIT, NTP_FAILURE_MODE_NEVER, NTP_FAILURE_MODE_FAIL_ON_ANY_GATE, NTP_FAILURE_MODE_FAIL_ON_NO_USABLE_SERVER_TIME, or NTP_FAILURE_MODE_FAIL_ON_OFFSET_TOO_LARGE_TO_APPLY
--ntp-port unchanged NTP UDP port (1-65535)
--ntp-timeout unchanged Request timeout as an ISO-8601 duration (e.g. PT5S)
--ntp-request-version unchanged NTP request protocol version (1-4)
--ntp-acceptable-response-versions unchanged Comma-separated acceptable response versions (each 1-4); replaces the existing list
--ntp-samples unchanged Number of NTP samples (positive integer)
--ntp-sample-spacing unchanged Delay between samples as an ISO-8601 duration (e.g. PT0.250S)
--ntp-max-stratum unchanged Maximum accepted NTP stratum (1-16)
--ntp-max-round-trip-delay unchanged Maximum round-trip delay (ISO-8601 duration)
--ntp-max-root-delay unchanged Maximum root delay (ISO-8601 duration)
--ntp-max-root-dispersion unchanged Maximum root dispersion (ISO-8601 duration)
--ntp-max-measurement-error-bound unchanged Maximum measurement error bound (ISO-8601 duration)
--ntp-max-server-clock-age unchanged Maximum server clock age (ISO-8601 duration)
--ntp-max-absolute-offset unchanged Maximum absolute offset (ISO-8601 duration)
--ntp-max-offset-jitter unchanged Maximum offset jitter (ISO-8601 duration)
--ntp-max-applied-offset unchanged Maximum applied offset (ISO-8601 duration)
--[no-]ntp-require-server-mode unchanged Require NTP server response mode
--[no-]ntp-allow-broadcast-mode unchanged Allow NTP broadcast mode
--[no-]ntp-reject-kiss-of-death unchanged Reject kiss-of-death responses
--[no-]ntp-reject-unsynced-leap-alarm unchanged Reject unsynced leap-alarm responses
--[no-]ntp-require-non-zero-originate-time unchanged Require non-zero originate timestamp
--[no-]ntp-require-non-zero-receive-time unchanged Require non-zero receive timestamp
--[no-]ntp-require-non-zero-transmit-time unchanged Require non-zero transmit timestamp
--[no-]ntp-require-non-zero-reference-time unchanged Require non-zero reference timestamp
--[no-]ntp-require-client-time-not-backwards unchanged Require client time not moving backwards
--[no-]ntp-include-time-info-comments-in-warnings unchanged Include timing comments in warnings
-f, --out-format YAML Output format: JSON or YAML

Validation rules

  • ntp update is a read-modify-write merge: it first runs the equivalent of ntp view, applies only the supplied options, then writes the result back. Omitted options keep their current values.
  • --ntp-time-source-mode accepts only TIME_SOURCE_MODE_SERVER_ONLY, TIME_SOURCE_MODE_SERVER_IF_VALID_ELSE_CLIENT, or TIME_SOURCE_MODE_CLIENT_ONLY (case-insensitive).
  • --ntp-failure-mode accepts only NTP_FAILURE_MODE_INHERIT, NTP_FAILURE_MODE_NEVER, NTP_FAILURE_MODE_FAIL_ON_ANY_GATE, NTP_FAILURE_MODE_FAIL_ON_NO_USABLE_SERVER_TIME, or NTP_FAILURE_MODE_FAIL_ON_OFFSET_TOO_LARGE_TO_APPLY (case-insensitive).
  • --ntp-port must be in the range 1-65535.
  • --ntp-request-version and each value of --ntp-acceptable-response-versions must be in the range 1-4.
  • --ntp-max-stratum must be in the range 1-16.
  • --ntp-samples must be a positive integer.
  • Duration options use ISO-8601 day-time durations (for example PT5S for five seconds, PT0.250S for 250 milliseconds).
  • --ntp-acceptable-response-versions replaces the existing list rather than appending to it.

Example (point at a new NTP server)

bin/admin.sh ntp update \
  --ntp-server-name primary-time \
  --ntp-host time.example.com \
  --ntp-port 123 \
  --ntp-timeout PT5S \
  -f json

Example (tighten the validation policy)

bin/admin.sh ntp update \
  --ntp-time-source-mode TIME_SOURCE_MODE_SERVER_IF_VALID_ELSE_CLIENT \
  --ntp-failure-mode NTP_FAILURE_MODE_FAIL_ON_NO_USABLE_SERVER_TIME \
  --ntp-max-stratum 4 \
  --ntp-request-version 4 \
  --ntp-acceptable-response-versions 3,4 \
  --ntp-samples 8 \
  --ntp-sample-spacing PT0.250S \
  --ntp-reject-kiss-of-death \
  --no-ntp-allow-broadcast-mode \
  -f yaml

ntp backup

Back up the global administrator NTP configuration to a binary protobuf (.pb) file, or print it as Base64 to the console.

Syntax

bin/admin.sh ntp backup [options]

Required output mode options (choose exactly one)

Option Description Example
-o, --output-file Write the binary .pb backup to a file (creates or truncates the file) -o ./admin-ntp.pb
-s, --print-to-screen Print the backup to the console as Base64 -s

Validation rules

  • Provide exactly one of -o/--output-file or -s/--print-to-screen; this is an exclusive, required argument group.
  • File output is the raw binary .pb payload. Console output is Base64-encoded so the binary content can be captured from the terminal.

Optional options

Show optional options
Option Default Description
-f, --out-format YAML Output format for status and error messages: JSON or YAML

Example

bin/admin.sh ntp backup -o ./admin-ntp.pb

ntp restore

Restore the global administrator NTP configuration from a binary protobuf (.pb) backup produced by ntp backup.

Syntax

bin/admin.sh ntp restore [options]

Required options

Option Description Example
-i, --input-file Binary .pb backup file to restore -i ./admin-ntp.pb

Optional options

Show optional options
Option Default Description
-f, --out-format YAML Output format: JSON or YAML

Example

bin/admin.sh ntp restore -i ./admin-ntp.pb -f json

Standard CLI options are documented in Global options.

FAQ

Do ntp commands require a login first?

Yes. Every command in the ntp group is a remote gRPC call. Create a host profile with profile hosts create and authenticate with profile authn login before running them.

Does ntp update replace the whole configuration?

No. ntp update performs a partial merge. It fetches the current configuration, applies only the options you supply, and writes back the merged result. Options you omit keep their existing values.

What file format does ntp backup produce?

A binary protobuf (.pb) file when you use -o/--output-file, or the same payload Base64-encoded to the console when you use -s/--print-to-screen. Restore it with ntp restore -i <file>.