extern/nixos-and-flakes-book
1
0
Fork 0
mirror of https://github.com/ryan4yin/nixos-and-flakes-book.git synced 2024-11-21 23:53:12 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #87 from kourtni/fix-substituers-typo

Browse Source 
Fixes typo: substituers -> substituters
This commit is contained in:
Ryan Yin 2024-02-15 10:41:19 +08:00 committed by GitHub
commit 34e31f7bfd
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 42 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
docs/nixos-with-flakes/add-custom-cache-servers.md
View File

@ -23,23 +23,23 @@ In Nix, you can configure cache servers using the following options:
1. cache mirror's data are directly synchronized from the official cache server. Therefore, their public keys are the same as those of the official cache server, and you can use the public key of the official cache server without additional configuration.
2. This entirely trust-based public key verification mechanism transfers the security responsibility to users. If users want to use a third-party cache server to speed up the build process of a certain library, they must take on the corresponding security risks and decide whether to add the public key of that cache server to `trusted-public-keys`. To completely solve this trust issue, Nix has introduced the experimental feature [ca-derivations](https://nixos.wiki/wiki/Ca-derivations), which does not depend on `trusted-public-keys` for signature verification. Interested users can explore it further.
You can configure the `substituers` and `trusted-public-keys` parameters in the following ways:
You can configure the `substituters` and `trusted-public-keys` parameters in the following ways:
1. Configure in `/etc/nix/nix.conf`, a global configuration that affects all users.
1. You can use `nix.settings.substituers` and `nix.settings.trusted-public-keys` in any NixOS Module to declaratively generate `/etc/nix/nix.conf`.
2. Configure in the `flake.nix` of a flake project using `nixConfig.substituers`. This configuration only affects the current flake.
1. You can use `nix.settings.substituters` and `nix.settings.trusted-public-keys` in any NixOS Module to declaratively generate `/etc/nix/nix.conf`.
2. Configure in the `flake.nix` of a flake project using `nixConfig.substituters`. This configuration only affects the current flake.
3. Temporarily set through the `--option` parameter of the `nix` command, and this configuration only applies to the current command.
Among these three methods, except for the first global configuration, the other two are temporary configurations. If multiple methods are used simultaneously, later configurations will directly override earlier ones.
However, there are security risks in temporarily setting `substituers`, as explained earlier regarding the deficiencies of the security verification mechanism based on `trusted-public-keys`. To set `substituers` through the second and third methods, you need to meet one of the following conditions:
However, there are security risks in temporarily setting `substituters`, as explained earlier regarding the deficiencies of the security verification mechanism based on `trusted-public-keys`. To set `substituters` through the second and third methods, you need to meet one of the following conditions:
1. The current user is included in the [`trusted-users`](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-trusted-users) parameter list in `/etc/nix/nix.conf`.
2. The `substituers` specified temporarily via `--option substituers "http://xxx"` are included in the [`trusted-substituters`](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-trusted-substituters) parameter list in `/etc/nix/nix.conf`.
2. The `substituters` specified temporarily via `--option substituters "http://xxx"` are included in the [`trusted-substituters`](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-trusted-substituters) parameter list in `/etc/nix/nix.conf`.
Based on the above information, the following are examples of the three configuration methods mentioned earlier.
Firstly, declaratively configure system-level `substituers` and `trusted-public-keys` using `nix.settings` in `/etc/nixos/configuration.nix` or any NixOS Module:
Firstly, declaratively configure system-level `substituters` and `trusted-public-keys` using `nix.settings` in `/etc/nixos/configuration.nix` or any NixOS Module:
```nix{7-27}
{
@ -50,8 +50,8 @@ Firstly, declaratively configure system-level `substituers` and `trusted-public-
# ...
nix.settings = {
# given the users in this list the right to specify additional substituters via:
# 1. `nixConfig.substituers` in `flake.nix`
# 2. command line args `--options substituers http://xxx`
# 1. `nixConfig.substituters` in `flake.nix`
# 2. command line args `--options substituters http://xxx`
trusted-users = ["ryan"];
substituters = [
@ -73,9 +73,9 @@ Firstly, declaratively configure system-level `substituers` and `trusted-public-
}
```
The second method is to configure `substituers` and `trusted-public-keys` using `nixConfig` in `flake.nix`:
The second method is to configure `substituters` and `trusted-public-keys` using `nixConfig` in `flake.nix`:
> As mentioned earlier, it is essential to configure `nix.settings.trusted-users` in this configuration. Otherwise, the `substituers` we set here will not take effect.
> As mentioned earlier, it is essential to configure `nix.settings.trusted-users` in this configuration. Otherwise, the `substituters` we set here will not take effect.
```nix{5-23,43-47}
{
@ -122,7 +122,7 @@ The second method is to configure `substituers` and `trusted-public-keys` using
{
# given the users in this list the right to specify additional substituters via:
# 1. `nixConfig.substituers` in `flake.nix`
# 1. `nixConfig.substituters` in `flake.nix`
nix.settings.trusted-users = [ "ryan" ];
}
# omitting several configurations...
@ -133,10 +133,10 @@ The second method is to configure `substituers` and `trusted-public-keys` using
}
```
Finally, the third method involves using the following command to temporarily specify `substituers` and `trusted-public-keys` during deployment:
Finally, the third method involves using the following command to temporarily specify `substituters` and `trusted-public-keys` during deployment:
```bash
sudo nixos-rebuild switch --option substituers "https://nix-community.cachix.org" --option trusted-public-keys "nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs="
sudo nixos-rebuild switch --option substituters "https://nix-community.cachix.org" --option trusted-public-keys "nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs="
```
Choose one of the above three methods for configuration and deployment. After a successful deployment, all subsequent packages will preferentially search for caches from domestic mirror sources.
@ -145,11 +145,11 @@ Choose one of the above three methods for configuration and deployment. After a
### The `extra-` Prefix for Nix Options Parameters
As mentioned earlier, the `substituers` configured by the three methods will override each other, but the ideal situation should be:
As mentioned earlier, the `substituters` configured by the three methods will override each other, but the ideal situation should be:
1. At the system level in `/etc/nix/nix.conf`, configure only the most generic `substituers` and `trusted-public-keys`, such as official cache servers and domestic mirror sources.
2. In each flake project's `flake.nix`, configure the `substituers` and `trusted-public-keys` specific to that project, such as non-official cache servers like nix-community.
3. When building a flake project, nix should **merge** the `substituers` and `trusted-public-keys` configured in `flake.nix` and `/etc/nix/nix.conf`.
1. At the system level in `/etc/nix/nix.conf`, configure only the most generic `substituters` and `trusted-public-keys`, such as official cache servers and domestic mirror sources.
2. In each flake project's `flake.nix`, configure the `substituters` and `trusted-public-keys` specific to that project, such as non-official cache servers like nix-community.
3. When building a flake project, nix should **merge** the `substituters` and `trusted-public-keys` configured in `flake.nix` and `/etc/nix/nix.conf`.
Nix provides the [`extra-` prefix](https://nixos.org/manual/nix/stable/command-ref/conf-file.html?highlight=extra#file-format) to achieve this **merging** functionality.
@ -196,10 +196,10 @@ In other words, you can use it like this:
{
# given the users in this list the right to specify additional substituters via:
# 1. `nixConfig.substituers` in `flake.nix`
# 1. `nixConfig.substituters` in `flake.nix`
nix.settings.trusted-users = [ "ryan" ];
# the system-level substituers & trusted-public-keys
# the system-level substituters & trusted-public-keys
nix.settings = {
substituters = [
# cache mirror located in China

46
docs/zh/nixos-with-flakes/add-custom-cache-servers.md
View File

@ -19,30 +19,30 @@ Nix 提供了官方缓存服务器 <https://cache.nixos.org>，它缓存了 nixp
Nix 中通过如下几个 options 来配置缓存服务器：
1. [substituers](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-substituters): 它是一个字符串数组，每个字符串都是一个缓存服务器的地址，Nix 会按照数组中的顺序依次尝试从这些服务器中查找缓存。
2. [trusted-public-keys](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-trusted-public-keys): 为了防范恶意攻击，Nix 默认启用 [require-sigs](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-require-sigs) 功能，只有附带了签名、且签名能被 `trusted-public-keys` 中的任意一个公钥验证通过的缓存，才会被 Nix 使用。因此我们需要将 `substituers` 对应的公钥添加到 `trusted-public-keys` 中。
1. [substituters](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-substituters): 它是一个字符串数组，每个字符串都是一个缓存服务器的地址，Nix 会按照数组中的顺序依次尝试从这些服务器中查找缓存。
2. [trusted-public-keys](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-trusted-public-keys): 为了防范恶意攻击，Nix 默认启用 [require-sigs](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-require-sigs) 功能，只有附带了签名、且签名能被 `trusted-public-keys` 中的任意一个公钥验证通过的缓存，才会被 Nix 使用。因此我们需要将 `substituters` 对应的公钥添加到 `trusted-public-keys` 中。
1. 国内的镜像源都是直接从官方缓存服务器中同步的，因此它们的公钥与官方缓存服务器的公钥是一致的，我们可以直接使用官方缓存服务器的公钥，无需额外配置。
2. 这种完全依赖公钥机制的验证方式，实际是将安全责任转嫁给了用户。用户如果希望使用某个第三方库，但又希望使用它的第三方缓存服务器加快构建速度，那就必须自己承担对应的安全风险，自行决策是否将该缓存服务器的公钥添加进 `trusted-public-keys`。为了完全解决这个信任问题，Nix 推出了实验特性 [ca-derivations](https://nixos.wiki/wiki/Ca-derivations)，它不依赖 `trusted-public-keys` 进行签名校验，有兴趣的可以自行了解。
可通过如下几种方式来配置 `substituers` `trusted-public-keys` 两个参数：
可通过如下几种方式来配置 `substituters` `trusted-public-keys` 两个参数：
1. 在 `/etc/nix/nix.conf` 中配置，这是全局配置，对所有用户生效。
1. 可在任一 NixOS Module 中通过 `nix.settings.substituers` 与 `nix.settings.trusted-public-keys` 来声明式地生成 `/etc/nix/nix.conf`.
2. 在 flake 项目的 `flake.nix` 中通过 `nixConfig.substituers` 来配置，此配置仅对当前 flake 生效。
3. 可通过 `nix` 指令的 `--option substituers="http://xxx"` 参数来临时设定，此配置仅对当前指令生效。
1. 可在任一 NixOS Module 中通过 `nix.settings.substituters` 与 `nix.settings.trusted-public-keys` 来声明式地生成 `/etc/nix/nix.conf`.
2. 在 flake 项目的 `flake.nix` 中通过 `nixConfig.substituters` 来配置，此配置仅对当前 flake 生效。
3. 可通过 `nix` 指令的 `--option substituters="http://xxx"` 参数来临时设定，此配置仅对当前指令生效。
上面三种方式中，除了第一种全局配置外，其他两种都是临时配置。如果同时使用了多种方式，那么后面的配置会直接覆盖前面的配置。
但临时设置 `substituers` 存在安全风险，前面我们也解释了基于 `trusted-public-keys` 的安全验证机制存在缺陷。
将一个不可信的缓存服务器添加到 substituers 中，可能会导致包含恶意内容的缓存被复制到 Nix Store 中。
因此 Nix 对 substituers 的临时设置做出了限制，要想通过第二三种方式设定 substituers，前提是满足如下任意一个条件：
但临时设置 `substituters` 存在安全风险，前面我们也解释了基于 `trusted-public-keys` 的安全验证机制存在缺陷。
将一个不可信的缓存服务器添加到 substituters 中，可能会导致包含恶意内容的缓存被复制到 Nix Store 中。
因此 Nix 对 substituters 的临时设置做出了限制，要想通过第二三种方式设定 substituers，前提是满足如下任意一个条件：
1. [`/etc/nix/nix.conf` 中的 `trusted-users`](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-trusted-users) 参数列表中包含当前用户。
2. [`/etc/nix/nix.conf` 中的 `trusted-substituters`](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-trusted-substituters) 参数列表中包含我们临时指定的 substituers.
2. [`/etc/nix/nix.conf` 中的 `trusted-substituters`](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-trusted-substituters) 参数列表中包含我们临时指定的 substituters.
基于上述信息，如下是上述三种配置方式的示例。
首先是通过 `nix.settings` 声明式地配置系统层面的 substituers 与 trusted-public-keys, 将如下配置添加到 `/etc/nixos/configuration.nix` 或其他任一 NixOS Module 中即可：
首先是通过 `nix.settings` 声明式地配置系统层面的 substituters 与 trusted-public-keys, 将如下配置添加到 `/etc/nixos/configuration.nix` 或其他任一 NixOS Module 中即可：
```nix{7-27}
{
@ -53,8 +53,8 @@ Nix 中通过如下几个 options 来配置缓存服务器：
# ...
nix.settings = {
# given the users in this list the right to specify additional substituters via:
# 1. `nixConfig.substituers` in `flake.nix`
# 2. command line args `--options substituers http://xxx`
# 1. `nixConfig.substituters` in `flake.nix`
# 2. command line args `--options substituters http://xxx`
trusted-users = ["ryan"];
substituters = [
@ -76,7 +76,7 @@ Nix 中通过如下几个 options 来配置缓存服务器：
}
```
第二种方案是通过 `flake.nix` 配置 substituers 与 trusted-public-keys，将如下配置添加到 `flake.nix` 中即可：
第二种方案是通过 `flake.nix` 配置 substituters 与 trusted-public-keys，将如下配置添加到 `flake.nix` 中即可：
> 如前所述，此配置中的 `nix.settings.trusted-users` 也是必须配置的，否则我们在这里设置的 `substituters` 将无法生效。
@ -125,7 +125,7 @@ Nix 中通过如下几个 options 来配置缓存服务器：
{
# given the users in this list the right to specify additional substituters via:
# 1. `nixConfig.substituers` in `flake.nix`
# 1. `nixConfig.substituters` in `flake.nix`
nix.settings.trusted-users = [ "ryan" ];
}
# 省略若干配置...
@ -136,10 +136,10 @@ Nix 中通过如下几个 options 来配置缓存服务器：
}
```
以及第三种方案，使用如下命令在部署时临时指定 substituers 与 trusted-public-keys:
以及第三种方案，使用如下命令在部署时临时指定 substituters 与 trusted-public-keys:
```bash
sudo nixos-rebuild switch --option substituers "https://nix-community.cachix.org" --option trusted-public-keys "nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs="
sudo nixos-rebuild switch --option substituters "https://nix-community.cachix.org" --option trusted-public-keys "nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs="
```
选择上述三种方案的任一一种进行配置并部署，部署成功之后，后续所有的包都会优先从国内镜像源查找缓存。
@ -148,11 +148,11 @@ sudo nixos-rebuild switch --option substituers "https://nix-community.cachix.org
### Nix options 参数的 `extra-` 前缀
前面提到的三种方式配置的 `substituers` 会相互覆盖，但比较理想的情况应该是：
前面提到的三种方式配置的 `substituters` 会相互覆盖，但比较理想的情况应该是：
1. 在系统层面的 `/etc/nix/nix.conf` 中仅配置最通用的 substituers 与 trusted-public-keys，例如官方缓存服务器与国内镜像源。
2. 在每个 flake 项目的 `flake.nix` 中配置该项目特有的 substituers 与 trusted-public-keys，例如 nix-community 等非官方的缓存服务器。
3. 在构建 flake 项目时，应该将 `flake.nix` 与 `/etx/nix/nix.conf` 中配置的 substituers 与 trusted-public-keys **合并**使用。
1. 在系统层面的 `/etc/nix/nix.conf` 中仅配置最通用的 substituters 与 trusted-public-keys，例如官方缓存服务器与国内镜像源。
2. 在每个 flake 项目的 `flake.nix` 中配置该项目特有的 substituters 与 trusted-public-keys，例如 nix-community 等非官方的缓存服务器。
3. 在构建 flake 项目时，应该将 `flake.nix` 与 `/etx/nix/nix.conf` 中配置的 substituters 与 trusted-public-keys **合并**使用。
Nix 提供了 [`extra-` 前缀](https://nixos.org/manual/nix/stable/command-ref/conf-file.html?highlight=extra#file-format) 实现了这个**合并**功能。
@ -199,10 +199,10 @@ Nix 提供了 [`extra-` 前缀](https://nixos.org/manual/nix/stable/command-ref/
{
# given the users in this list the right to specify additional substituters via:
# 1. `nixConfig.substituers` in `flake.nix`
# 1. `nixConfig.substituters` in `flake.nix`
nix.settings.trusted-users = [ "ryan" ];
# the system-level substituers & trusted-public-keys
# the system-level substituters & trusted-public-keys
nix.settings = {
substituters = [
# cache mirror located in China