From c90f096af8df264f73b57dc2c9c0f37ecea5a2bf Mon Sep 17 00:00:00 2001 From: Ruben Nijveld Date: Fri, 18 Aug 2023 19:39:41 +0200 Subject: [PATCH] More formatting of files --- CHANGELOG.md | 30 +++-- README.md | 120 ++++++++++++------ SECURITY.md | 12 +- docs/development/audits.md | 6 + .../development/flowdiagram.svg | 0 docs/development/threat-model.md | 60 ++++++--- docs/manual/management-client.md | 47 +++++-- docs/manual/operational-considerations.md | 103 +++++++++++---- mkdocs.yml | 1 + 9 files changed, 272 insertions(+), 107 deletions(-) create mode 100644 docs/development/audits.md rename flowdiagram.svg => docs/development/flowdiagram.svg (100%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4d9beeacb..ca6efac1a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,13 +3,15 @@ Version 0.3.7 Major Changes ----- -- Reworked configuration options for peers (see [documentation](CONFIGURATION.md) for new instructions on how to configure peers). +- Reworked configuration options for peers (see the documentation for new + instructions on how to configure peers). - Removed support for rfc5905 algorithm. Minor Changes ----- - Send software timestamping is now enabled by default -- Hardware timestamping can now only be configured if ntpd-rs is built with the `hardware-timestamping` feature (off by default). +- Hardware timestamping can now only be configured if ntpd-rs is built with the + `hardware-timestamping` feature (off by default). - Upgraded dependencies. Bug fixes @@ -32,24 +34,29 @@ Minor Changes Bug fixes ----- -- Fixed bug that caused ntp-ctl validate to not print warnings on the configuration, only parsing errors. +- Fixed bug that caused ntp-ctl validate to not print warnings on the + configuration, only parsing errors. - Fixed bug in nts parsing that caused NTS to be entirely inoperable. Version 0.3.5 ====== -No changes compared with 0.3.4, needed due to technical difficulties in release process. +No changes compared with 0.3.4, needed due to technical difficulties in release +process. Version 0.3.4 ====== Minor Changes ----- -- Fixed bug that caused nts-providing servers to fail after key rotation (which by default happens daily). +- Fixed bug that caused nts-providing servers to fail after key rotation (which + by default happens daily). - Upgraded dependencies. -- Fix bug in package installers that caused us to overwrite configuration on update. +- Fix bug in package installers that caused us to overwrite configuration on + update. - Removed dependency on Axum in prometheus exporter. -- Improved measurement code to deal better with external programs changing the clock. +- Improved measurement code to deal better with external programs changing the + clock. - Removed some spurious warnings around server strata. Version 0.3.3 @@ -87,7 +94,8 @@ Major Changes - Implemented NTS Key Exchange - Implemented NTS client functionality and configuration - Implemented NTS server functionality and configuration -- Changed format of timedata reported for peers to ensure compatibility with different algorithms. +- Changed format of timedata reported for peers to ensure compatibility with + different algorithms. Minor Changes ----- @@ -123,10 +131,12 @@ Minor Changes ----- - Made poll interval range and initial value configurable. - Minor improvements to timestamping of received and sent packets. -- Minor improvements to log output, particularly around attribution of events to specific peers. +- Minor improvements to log output, particularly around attribution of events to + specific peers. - Upgraded dependencies Bugfixes ----- - Fixed a number of bugs around poll interval adjustment. -- Fixed a bug in peer dispersion calculation which resulted in overly pessimistic dispersion estimates. +- Fixed a bug in peer dispersion calculation which resulted in overly + pessimistic dispersion estimates. diff --git a/README.md b/README.md index f35cc4177..420395dbf 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,54 @@ -![checks](https://github.com/pendulum-project/ntpd-rs/actions/workflows/build.yaml/badge.svg?branch=main)[![codecov](https://codecov.io/gh/pendulum-project/ntpd-rs/branch/main/graph/badge.svg?token=WES1JIYUJH)](https://codecov.io/gh/pendulum-project/ntpd-rs)[![Crates.io](https://img.shields.io/crates/v/ntpd.svg)](https://crates.io/crates/ntpd) +![checks](https://github.com/pendulum-project/ntpd-rs/actions/workflows/build.yaml/badge.svg?branch=main) +[![codecov](https://codecov.io/gh/pendulum-project/ntpd-rs/branch/main/graph/badge.svg?token=WES1JIYUJH)](https://codecov.io/gh/pendulum-project/ntpd-rs) +[![Crates.io](https://img.shields.io/crates/v/ntpd.svg)](https://crates.io/crates/ntpd) # ntpd-rs -ntpd-rs is an NTP implementation written in Rust, with a focus on security and stability. It includes client and server functionality and supports NTS. +ntpd-rs is an NTP implementation written in Rust, with a focus on security and +stability. It includes client and server functionality and supports NTS. If a feature you need is missing please let us know by opening an issue. ## Installation -The recommended way of installing ntpd-rs is with the pre-built packages from the [releases](https://github.com/pendulum-project/ntpd-rs/releases) page. The installers automatically handle setting up users, permissions and configuration. - -Alternatively, you can use `cargo install ntpd` or build from source. +The recommended way of installing ntpd-rs is with the pre-built packages from +the [releases page]. The installers automatically handle setting up users, +permissions and configuration. Alternatively, you can use `cargo install ntpd` +or build from source by cloning the repository yourself. ### Build from source -Currently, ntpd-rs only supports Linux-based operating systems. Our current testing only targets Linux kernels after version 5.0.0, older kernels may work but this is not guaranteed. +Currently, ntpd-rs only supports Linux-based operating systems. Our current +testing only targets Linux kernels after version 5.0.0, older kernels may work +but this is not guaranteed. -ntpd-rs is written in rust. We strongly recommend using [rustup](https://rustup.rs) to install a rust toolchain, because the version provided by system package managers tends to be out of date. Be sure to use a recent version of the rust compiler. +ntpd-rs is written in rust. We strongly recommend using [rustup] to install a +rust toolchain, because the version provided by system package managers tends to +be out of date. Be sure to use a recent version of the rust compiler. To build +ntpd-rs run -To build ntpd-rs run ```sh cargo build --release ``` -This produces a `ntp-daemon` binary at `target/release/ntp-daemon`, which is the main NTP daemon. -Before running the ntpd-rs daemon, make sure that no other NTP daemons are running. E.g. when chrony is running +This produces a `ntp-daemon` binary at `target/release/ntp-daemon`, which is the +main NTP daemon. Before running the ntpd-rs daemon, make sure that no other NTP +daemons are running. E.g. when chrony is running + ```sh systemctl stop chronyd ``` -The ntpd-rs daemon requires elevated permissions to change the system clock. It can be tested against servers in the [NTP pool](https://ntppool.org): +The ntpd-rs daemon requires elevated permissions to change the system clock. + ```sh -sudo ./target/release/ntp-daemon -p pool.ntp.org -p pool.ntp.org -p pool.ntp.org -p pool.ntp.org +sudo ./target/release/ntp-daemon ``` -By default, at least 3 peer servers are needed for the algorithm to change the time. After a few minutes you should start to see messages indicating the offset of your machine from the server. +By default, at least 3 peer servers are needed for the algorithm to change the +time. After a few minutes you should start to see messages indicating the offset +of your machine from the server. ``` 2023-04-11T10:06:24.847375Z INFO ntp_proto::algorithm::kalman: Offset: 1.7506740305607742+-12.951528666965439ms, frequency: 8.525844072881435+-5.089483351832892ppm @@ -43,63 +56,98 @@ By default, at least 3 peer servers are needed for the algorithm to change the t 2023-04-11T10:06:25.443979Z INFO ntp_proto::algorithm::kalman: Changed frequency, current steer 4.26346751414286ppm, desired freq 0ppm ``` -A complete description of how the daemon can be configured can be found in the [configuration documentation](CONFIGURATION.md) +A complete description of how the daemon can be configured can be found in the +documentation found in the [documentation](./docs/). ## Minimum supported rust version -We make no guarantees about supporting older versions of rust. When building from source (either manually or with `cargo install`) use the latest rust version to prevent issues. +We make no guarantees about supporting older versions of rust. When building +from source (either manually or with `cargo install`) use the latest rust +version to prevent issues. -We are committed to keep ntpd-rs working on at least the latest stable, beta and nightly rust compiler. Beyond this, we keep track of the current minimum rust version needed to compile our code for purposes of documentation. However, right now we do not have a policy guaranteeing a minimum amount of time we will support a stable rust release beyond the 6 weeks during which it is the latest stable version. +We are committed to keep ntpd-rs working on at least the latest stable and beta +compilers. Beyond this, we keep track of the current minimum rust version needed +to compile our code for purposes of documentation. However, right now we do not +have a policy guaranteeing a minimum amount of time we will support a stable +rust release beyond the 6 weeks during which it is the latest stable version. -Please note that the Rust project only supports the latest stable rust release. As this is the only release that will receive any security updates, we STRONGLY recommend using the latest stable rust version for compiling ntpd-rs for daily use. +Please note that the Rust project only supports the latest stable rust release. +As this is the only release that will receive any security updates, we STRONGLY +recommend using the latest stable rust version for compiling ntpd-rs for daily +use. ## Package substructure Currently, the code is split up into several separate crates: - - `ntp-proto` contains the packet parsing and the algorithms needed for clock selection, filtering and steering. - - `ntp-daemon` contains the main NTP daemon, and deals with orchestrating the networking and configuration. - - `ntp-ctl` contains a control interface for the NTP daemon, allowing readout of current synchronisation state and dynamic configuration changes. - - `ntp-metrics-exporter` contains a HTTP interface for exporting the prometheus metrics. - - `test-binaries` contains a number of simple NTP servers that can be used for testing (see below). - - `ntp-os-clock` contains the unsafe code needed to interface with system clocks. - - `ntp-udp` contains the unsafe code needed to deal with timestamping on the network layer. - - `ntpd` contains the entrypoints for all our binaries -All unsafe code is contained within the `ntp-os-clock` and `ntp-udp` packages, which are kept as small as possible. All interfaces exposed by these crates should be safe. For a more detailed description of how ntpd-rs is structured, see the [development documentation](DEVELOPMENT.md). +* `ntp-proto` contains the packet parsing and the algorithms needed for clock + selection, filtering and steering. +* `test-binaries` contains a number of simple NTP servers that can be used for + testing (see below). +* `ntp-os-clock` contains the unsafe code needed to interface with system + clocks. +* `ntp-udp` contains the unsafe code needed to deal with timestamping on the + network layer. +* `ntpd` contains the entrypoints for all our binaries and the code for the + daemon (`ntp-daemon`), control client (`ntp-ctl`) and OpenMetrics/prometheus + exporter (`ntp-metrics-exporter`). + + +All unsafe code is contained within the `ntp-os-clock` and `ntp-udp` packages, +which are kept as small as possible. All interfaces exposed by these crates +should be safe. For a more detailed description of how ntpd-rs is structured, +see the [development documentation](./docs/development/). ## Test Binaries This crate contains extremely limited NTP servers for testing purposes -* `demobilize-server` always sends the DENY kiss code, the client must demobilize this association +* `demobilize-server` always sends the DENY kiss code, the client must + demobilize this association * `rate-limit-server` forces an increase of the poll interval to 32 seconds ## Roadmap -In Q1 2023 we completed our work on NTS. Our implementation is now full-featured, it supports NTP client and server with NTS. +In Q1 2023 we completed our work on NTS. Our implementation is now +full-featured, it supports NTP client and server with NTS. Our roadmap for 2023: -- Q2 2023: Adoption work, improved packaging, FreeBSD support -- Q3 2023: Stable release (pending funding) -- Q4 2023: Development work on experimental features, NTS pool, NTPv5 (pending funding) +* Q2 2023: Adoption work, improved packaging, FreeBSD support +* Q3 2023: Stable release (pending funding) +* Q4 2023: Development work on experimental features, NTS pool, NTPv5 (pending + funding) -We seek sponsorship for features and maintenance to continue our work. Contact us via pendulum@tweedegolf.com if you are interested! +We seek sponsorship for features and maintenance to continue our work. Contact +us via pendulum@tweedegolf.com if you are interested! ## History ### 2022 -The project originates from ISRG's project [Prossimo](https://www.memorysafety.org), as part of their mission to achieve memory safety for the Internet's most critical infrastructure. +The project originates from ISRG's project [Prossimo], as part of their mission +to achieve memory safety for the Internet's most critical infrastructure. Prossimo -Prossimo funded the initial development of the NTP client and server, and NTS support. The [NTP initiative page](https://www.memorysafety.org/initiative/ntp) on Prossimo's website tells the story. +Prossimo funded the initial development of the NTP client and server, and NTS +support. The [NTP initiative page] on Prossimo's website tells the story. ### 2023 -After completion of the initial development, the project's ownership moved from Prossimo to Tweede golf in April 2023. See the announcement [here](https://www.memorysafety.org/blog/ntp-and-nts-have-arrived/). +After completion of the initial development, the project's ownership moved from +Prossimo to Tweede golf in April 2023. See the [NTP announcement] for more +information. -Tweede golf is the long-term maintainer of ntpd-rs, that is now part of Tweede golf's [Project Pendulum](https://github.com/pendulum-project). Pendulum is building modern, open-source implementations of the Network Time Protocol and the Precision Time Protocol. In August of 2023, Sovereign Tech Fund invested in Pendulum. Read more on [their website](https://sovereigntechfund.de/en/projects/pendulum/). +Tweede golf is the long-term maintainer of ntpd-rs, that is now part of Tweede +golf's [Project Pendulum]. Pendulum is building modern, open-source +implementations of the Network Time Protocol and the Precision Time Protocol. ![STF](https://tweedegolf.nl/images/logo-stf-blank.png) + +[releases page]: https://github.com/pendulum-project/ntpd-rs/releases +[rustup]: https://rustup.rs +[Prossimo]: https://www.memorysafety.org +[NTP initiative page]: https://www.memorysafety.org/initiative/ntp +[NTP announcement]: https://www.memorysafety.org/blog/ntp-and-nts-have-arrived/ +[Project Pendulum]: https://github.com/pendulum-project diff --git a/SECURITY.md b/SECURITY.md index 8f6b2af96..b686af58b 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,7 +2,7 @@ Security policy =============== **Do not report security vulnerabilities through public GitHub issues.** -Instead, you can report security vulnerabilities using [our security page](https://github.com/pendulum-project/ntpd-rs/security), +Instead, you can report security vulnerabilities using [our security page], or send them by email to security+ntpdrs@tweedegolf.com. Please include as much of the following information as possible: @@ -20,9 +20,13 @@ We prefer to receive reports in English. If necessary, we also understand Dutch. ## Disclosure Policy -We adhere to the principle of [responsible disclosure](https://vuls.cert.org/confluence/display/CVD/Executive+Summary). +We adhere to the principle of [coordinated vulnerability disclosure]. Security Advisories =================== -Security advisories will be published [on GitHub](https://github.com/pendulum-project/ntpd-rs/security/advisories) -and possibly through other channels. +Security advisories will be published on our [github advisories page] and +possibly through other channels. + +[our security page]: https://github.com/pendulum-project/ntpd-rs/security +[coordinated vulnerability disclosure]: https://vuls.cert.org/confluence/display/CVD/Executive+Summary +[github advisories page]: https://github.com/pendulum-project/ntpd-rs/security/advisories diff --git a/docs/development/audits.md b/docs/development/audits.md new file mode 100644 index 000000000..5e7945220 --- /dev/null +++ b/docs/development/audits.md @@ -0,0 +1,6 @@ +# Audits + +## NLnet NGI Review Security Evaluation by Radically Open Security + +Date: 2023-04 \ +Report: [download](../audits/report-ntpd-rs-v11-final.pdf) diff --git a/flowdiagram.svg b/docs/development/flowdiagram.svg similarity index 100% rename from flowdiagram.svg rename to docs/development/flowdiagram.svg diff --git a/docs/development/threat-model.md b/docs/development/threat-model.md index ab6bad57b..5f200bf20 100644 --- a/docs/development/threat-model.md +++ b/docs/development/threat-model.md @@ -1,24 +1,33 @@ # Threat model -This document a threat model, based on the methodology presented by Eleanor Saitta, that we as developers use as a guide in our development process. It may not contain all the context needed to fully understand it, if clarifications are needed please ask us. +This document a threat model, based on the methodology presented by Eleanor +Saitta, that we as developers use as a guide in our development process. It may +not contain all the context needed to fully understand it, if clarifications are +needed please ask us. ## Actors, Assets & Actions ### Actors We model the following actors: - - System Admin: Administrator of the system running ntpd-rs - - System User: Non-administrator user of the system running ntpd-rs - - Reference Source: A remote time server we use as a source for our time. - - External Client: A remote user that is allowed to use this instance of ntpd-rs to receive time. - - Anonymous: Any other party + +- System Admin: Administrator of the system running ntpd-rs +- System User: Non-administrator user of the system running ntpd-rs +- Reference Source: A remote time server we use as a source for our time. +- External Client: A remote user that is allowed to use this instance of + ntpd-rs to receive time. +- Anonymous: Any other party ### Assets We model the following assets: - - Clock: The system clock - - Source configuration: The configuration on which sources to use, including some metadata on the current status of those sources - - Server configuration: The configuration on which interfaces to provide an NTP server on, and who can use those, including some metadata on the current server status. + +- Clock: The system clock +- Source configuration: The configuration on which sources to use, including + some metadata on the current status of those sources +- Server configuration: The configuration on which interfaces to provide an + NTP server on, and who can use those, including some metadata on the current + server status. ### Actions @@ -116,8 +125,10 @@ We model the following assets: - - Reference sources may update the Clock only when sufficiently many agree and don't exceed configured adjustment limits. - - System users may read configuration (both types) only when allowed by system admin. +- Reference sources may update the Clock only when sufficiently many agree and + don't exceed configured adjustment limits. +- System users may read configuration (both types) only when allowed by system + admin. ## Failure cases @@ -170,17 +181,26 @@ We model the following assets: ## Security strategy - - If any actor tries to read the clock, the system will not respond with a valid time if the IP address is not on the configured allowlist - - If any actor tries to update the clock, the system tries to verify consensus among multiple reference sources - - If any actor tries to update the clock, the system refuses updates beyond a configured limit - - If the configuration file (used to create the configuration) is world-writable, the system will emit a warning - - If the configuration socket (used to update the configuration) is world-writable, the system will emit a warning - - The observability socket (used to read the configuration/status) is a unix socket, which is unreachable over the network by default - - If any actor tries to read the clock too often, the system will stop responding a valid time to them +- If any actor tries to read the clock, the system will not respond with a + valid time if the IP address is not on the configured allowlist +- If any actor tries to update the clock, the system tries to verify consensus + among multiple reference sources +- If any actor tries to update the clock, the system refuses updates beyond a + configured limit +- If the configuration file (used to create the configuration) is + world-writable, the system will emit a warning +- If the configuration socket (used to update the configuration) is + world-writable, the system will emit a warning +- The observability socket (used to read the configuration/status) is a unix + socket, which is unreachable over the network by default +- If any actor tries to read the clock too often, the system will stop + responding a valid time to them ## Data flow diagram ![](flowdiagram.svg) - - The security boundaries between the admin and system users and ntpd-rs run through the unix sockets used for communication. - - The security boundaries for reference sources and external clients run through the network sockets used for communication. +- The security boundaries between the admin and system users and ntpd-rs run + through the unix sockets used for communication. +- The security boundaries for reference sources and external clients run + through the network sockets used for communication. diff --git a/docs/manual/management-client.md b/docs/manual/management-client.md index 5923c3862..60e9f4c2d 100644 --- a/docs/manual/management-client.md +++ b/docs/manual/management-client.md @@ -1,35 +1,56 @@ # Management client -**The management client interface format is unstable! Do you have suggestion for additional values to expose? let us know in an issue!** +**The management client interface format is unstable! Do you have suggestion +for additional values to expose? let us know in an issue!** -ntpd-rs comes with a management client for the daemon. This client can show the current state of the daemon, as well as change the log level and panic thresholds of the daemon. +ntpd-rs comes with a management client for the daemon. This client can show the +current state of the daemon, as well as change the log level and panic +thresholds of the daemon. ## Enabling the management client -In order to communicate with the daemon, the management client relies on two sockets, an observation socket and a configuration socket, which are disabled by default. To enable use of the client, these sockets should be enabled in [the configuration](CONFIGURATION.md). On Linux, it is common to place these sockets in a subdirectory of `/run` specific to the daemon. +In order to communicate with the daemon, the management client relies on two +sockets, an observation socket and a configuration socket, which are disabled +by default. To enable use of the client, these sockets should be enabled in +the configuration. On Linux, it is common to place these sockets in a +subdirectory of `/run` specific to the daemon. -The client can run with only one of the sockets enabled. In that situation, not all functionality is available. The same holds when the currently running user has insufficient permissions for one of the sockets. +The client can run with only one of the sockets enabled. In that situation, not +all functionality is available. The same holds when the currently running user +has insufficient permissions for one of the sockets. -For the configuration socket, default permissions restrict access to the group under which the server is running. Users should be added to this group when they need to be able to change configuration settings of the daemon dynamically. +For the configuration socket, default permissions restrict access to the group +under which the server is running. Users should be added to this group when +they need to be able to change configuration settings of the daemon dynamically. ## Using the management client The current client exposes 3 different commands: - - `ntp-ctl peers` displays information on the currently active peer connections - - `ntp-ctl system` displays information on the current synchronization state of the system. - - `ntp-ctl prometheus` combines output of `ntp-ctl peers` and `ntp-ctl system` in the - prometheus export format - - `ntp-ctl config` allows changing of some configuration parameters +- `ntp-ctl peers` displays information on the currently active peer connections +- `ntp-ctl system` displays information on the current synchronization state of + the system. +- `ntp-ctl prometheus` combines output of `ntp-ctl peers` and `ntp-ctl system` + in the prometheus export format +- `ntp-ctl config` allows changing of some configuration parameters ## Available configuration parameters -Currently, only the `log-level` configuration parameter can be set dynamically, through the `--log-level` command line parameter. For information on the allowed values, see [the configuration documentation](CONFIGURATION.md). +Currently, only the `log-level` configuration parameter can be set dynamically, +through the `--log-level` command line parameter. For information on the +allowed values, see the configuration documentation. ## Specifying socket locations -By default, the management client looks for the daemon's configuration in `/etc/ntpd-rs/ntp.toml` in order to extract the paths of the socket. If this file is not present, or when the socket paths are not configured in these, it defaults to `/run/ntpd-rs/observe` for the observation socket and `/run/ntpd-rs/configure` for the configuration sockets. +By default, the management client looks for the daemon's configuration in +`/etc/ntpd-rs/ntp.toml` in order to extract the paths of the socket. If this +file is not present, or when the socket paths are not configured in these, it +defaults to `/run/ntpd-rs/observe` for the observation socket and +`/run/ntpd-rs/configure` for the configuration sockets. -If the client fails to find the correct socket paths using the above process, it can be manually configured to look elsewhere. Most advisable is to point the management client to the configuration file of the server via the `--config` command line flag. +If the client fails to find the correct socket paths using the above process, +it can be manually configured to look elsewhere. Most advisable is to point +the management client to the configuration file of the server via the +`--config` command line flag. ## Output format diff --git a/docs/manual/operational-considerations.md b/docs/manual/operational-considerations.md index 15560f883..4382c8ccd 100644 --- a/docs/manual/operational-considerations.md +++ b/docs/manual/operational-considerations.md @@ -1,44 +1,99 @@ # Operational considerations -In this document, we provide a basic overview of the operational considerations that need to be carefully considered when configuring ntpd-rs as the system NTP client, along with our current recommendations. +In this document, we provide a basic overview of the operational considerations +that need to be carefully considered when configuring ntpd-rs as the system NTP +client, along with our current recommendations. ## Required number of available servers -In its operation, NTP requires that a majority of the used servers agree (up to the precision of the measurements) on the current time. However, in this mechanism, any servers that are currently unavailable because of connection issues and the like are completely ignored. As a consequences, the required quorum of agreeing servers may be lower than expected. +In its operation, NTP requires that a majority of the used servers agree (up to +the precision of the measurements) on the current time. However, in this +mechanism, any servers that are currently unavailable because of connection +issues and the like are completely ignored. As a consequences, the required +quorum of agreeing servers may be lower than expected. -To combat this, ntpd-rs provides the `minimum-agreeing-peers` setting to set a minimum number of servers that need to agree on the best time. The NTPv4 standard recommends using a value of at least `3` for `minimum-agreeing-peers`. When using this recommendation, it is important to configure enough remote servers to ensure the probability of dipping below `3` available servers is low enough. - -Increasing the `minimum-agreeing-peers` value beyond the default of 3 can help reduce the risk of a bad server affecting the system time. However, keep in mind that larger values may require more servers to be available before the clock can be synchronized, which can reduce availability. +To combat this, ntpd-rs provides the `minimum-agreeing-peers` setting to set a +minimum number of servers that need to agree on the best time. The NTPv4 +standard recommends using a value of at least `3` for `minimum-agreeing-peers`. +When using this recommendation, it is important to configure enough remote +servers to ensure the probability of dipping below `3` available servers is low +enough. +Increasing the `minimum-agreeing-peers` value beyond the default of 3 can help +reduce the risk of a bad server affecting the system time. However, keep in +mind that larger values may require more servers to be available before the +clock can be synchronized, which can reduce availability. ## Maximum clock adjustment boundaries -Although no clock is perfect, a normally functioning wall-time clock in a computer will typically require only relatively small adjustments to stay synchronized to an external clock. As such, it may be desirable to limit the maximum allowed adjustment to the system clock in order to limit the impact of malicious or erroneous servers. ntpd-rs has two options available for this, `single-step-panic-threshold` and `startup-step-panic-threshold`. - -The `single-step-panic-threshold` indicates the maximum amount ntpd-rs will adjust the system clock in a single step during normal operations. By default, this is limited to 30 minutes, but this may be lowered in the configuration. If an adjustment larger than `single-step-panic-threshold` is needed, ntpd-rs will throw an error (panic). We advise human intervention in this case: automatically restarting ntpd-rs may cause a panic loop. - -The `startup-step-panic-threshold` indicates the maximum amount ntpd-rs will adjust the system clock whilst starting up. Because the system may or may not have a hardware backup to use to keep time when shut down, the initial error of the system clock can be significantly larger than what can reasonably occur during normal operations. Therefore, this setting by default imposes no limit. Like `single-step-panic-threshold`, if `startup-step-panic-threshold` is set and exceeded, ntpd-rs will throw an error (panic). We advise human intervention in this case: automatically restarting ntpd-rs may cause a panic loop. - -Both the `single-step-panic-threshold` and `startup-step-panic-threshold` should be adjusted to achieve the desired mix of availability (avoiding false alarms) and resilience against erroneous servers. +Although no clock is perfect, a normally functioning wall-time clock in a +computer will typically require only relatively small adjustments to stay +synchronized to an external clock. As such, it may be desirable to limit the +maximum allowed adjustment to the system clock in order to limit the impact of +malicious or erroneous servers. ntpd-rs has two options available for this, +`single-step-panic-threshold` and `startup-step-panic-threshold`. + +The `single-step-panic-threshold` indicates the maximum amount ntpd-rs will +adjust the system clock in a single step during normal operations. By default, +this is limited to 30 minutes, but this may be lowered in the configuration. If +an adjustment larger than `single-step-panic-threshold` is needed, ntpd-rs will +throw an error (panic). We advise human intervention in this case: +automatically restarting ntpd-rs may cause a panic loop. + +The `startup-step-panic-threshold` indicates the maximum amount ntpd-rs will +adjust the system clock whilst starting up. Because the system may or may not +have a hardware backup to use to keep time when shut down, the initial error of +the system clock can be significantly larger than what can reasonably occur +during normal operations. Therefore, this setting by default imposes no limit. +Like `single-step-panic-threshold`, if `startup-step-panic-threshold` is set +and exceeded, ntpd-rs will throw an error (panic). We advise human intervention +in this case: automatically restarting ntpd-rs may cause a panic loop. + +Both the `single-step-panic-threshold` and `startup-step-panic-threshold` +should be adjusted to achieve the desired mix of availability (avoiding false +alarms) and resilience against erroneous servers. ## Automatic rebooting of the daemon -When ntpd-rs detects abnormal conditions during operation, it will automatically shut down. This is done to avoid poorly steering the clock and potentially inducing large clock errors, as once synchronized, an unsteered clock will keep time better than an actively incorrectly steered clock. +When ntpd-rs detects abnormal conditions during operation, it will +automatically shut down. This is done to avoid poorly steering the clock and +potentially inducing large clock errors, as once synchronized, an unsteered +clock will keep time better than an actively incorrectly steered clock. The abnormal conditions resulting in a shutdown include: - - Detection of an abnormally large (exceeds the panic thresholds) change in system time being required. - - Detection of an inconsistent internal state. - - Errors whilst trying to adjust the system clock (e.g. insufficient permissions). - -We strongly recommend against automatically restarting the daemon when it exits, as doing so may cause additional incorrect steering of the system clock, resulting in a larger error against UTC than intended. Instead, a human operator should determine the root cause of the shutdown and decide on the proper corrective action to take. - -Should it really be desirable to restart the daemon under certain circumstances (such as when killed by the Linux out-of-memory killer), this automatic restart should be configured as restrictive as possible, so as not to trigger outside the intended circumstance. For reboot upon activation of the out-of-memory killer, this could for example be achieved by checking that the exit code is 137 (which is guaranteed never to be used by the daemon itself). Furthermore, it is strongly recommended to reduce the `startup-step-panic-threshold` to match `single-step-panic-threshold`, in order to ensure that automatic restarting of the daemon does not unintentionally induce large corrections to the system clock. +- Detection of an abnormally large (exceeds the panic thresholds) change in + system time being required. +- Detection of an inconsistent internal state. +- Errors whilst trying to adjust the system clock (e.g. insufficient + permissions). + +We strongly recommend against automatically restarting the daemon when it +exits, as doing so may cause additional incorrect steering of the system clock, +resulting in a larger error against UTC than intended. Instead, a human +operator should determine the root cause of the shutdown and decide on the +proper corrective action to take. + +Should it really be desirable to restart the daemon under certain circumstances +(such as when killed by the Linux out-of-memory killer), this automatic restart +should be configured as restrictive as possible, so as not to trigger outside +the intended circumstance. For reboot upon activation of the out-of-memory +killer, this could for example be achieved by checking that the exit code is +137 (which is guaranteed never to be used by the daemon itself). Furthermore, +it is strongly recommended to reduce the `startup-step-panic-threshold` to +match `single-step-panic-threshold`, in order to ensure that automatic +restarting of the daemon does not unintentionally induce large corrections to +the system clock. ## Observability and configuration sockets The ntpd-rs daemon can expose two sockets: - - The observe socket is read-only and exposes some of the peer and clock algorithm state. - - The configuration socket accepts commands and allows changing of some of the configuration settings. - -When enabled, these sockets are by default exposed with quite generous permissions (`0o666` for observation and `0o660` for configuration). You should consider restricting access to these sockets, depending on the other software running on the system, and the techniques used for managing it. +- The observe socket is read-only and exposes some of the peer and clock + algorithm state. +- The configuration socket accepts commands and allows changing of some of the + configuration settings. + +When enabled, these sockets are by default exposed with quite generous +permissions (`0o666` for observation and `0o660` for configuration). You should +consider restricting access to these sockets, depending on the other software +running on the system, and the techniques used for managing it. diff --git a/mkdocs.yml b/mkdocs.yml index 002019536..e79ed390a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -23,3 +23,4 @@ nav: - Development: - development/code-structure.md - development/threat-model.md + - development/audits.md