Official NixOS Wiki

Binary Cache: Difference between revisions

← Older edit
VisualWikitext
imported>Heywoodlh
m MacOS/Nix-Darwin links
I think this https://discourse.nixos.org/t/garnix-blog-stop-trusting-nix-caches/70177 raises a valid point that should be added to the wiki to educate people about the implications.
 
(5 intermediate revisions by 5 users not shown)
Line 2: Line 2:


A binary cache builds Nix packages and caches the result for other machines. Any machine with Nix installed can be a binary cache for another one, no matter the operating system.
A binary cache builds Nix packages and caches the result for other machines. Any machine with Nix installed can be a binary cache for another one, no matter the operating system.
If you are facing problems with derivations not being in a cache, try switching to a release version. Most caches will have many derivations for a specific release.


== Setting up a binary cache ==
== Setting up a binary cache ==
Line 114: Line 112:
== Using a binary cache ==
== Using a binary cache ==


To configure Nix to use a certain binary cache, refer to the Nix manual.<ref group="cf.">[https://nixos.org/nix/manual/#ch-files Nix Manual, 21. Files]</ref> Add the binary cache as substituter (see the options {{ic|substituters}} and {{ic|extra-substituters}}) and the public key to the trusted keys (see {{ic|trusted-public-keys}}).
To configure Nix to use a certain binary cache, refer to the Nix manual.<ref group="cf.">[https://nixos.org/nix/manual/#ch-files Nix Manual, 21. Files]</ref> Add the binary cache as substituter (see the option {{ic|substituters}}) and the public key to the trusted keys (see {{ic|trusted-public-keys}}).
{{Warning|When adding a third-party binary cache you now trust all packages being served from that cache. Make sure this is a conscious decision. Trusting arbitrary caches can open you up to suppply chain attacks.
For more context: https://discourse.nixos.org/t/garnix-blog-stop-trusting-nix-caches/70177 (if source unavailable, https://web.archive.org/web/20251001172145/https://garnix.io/blog/stop-trusting-nix-caches)}}{{tip|If you are facing problems with derivations not being in a cache, try switching to a release version. Most caches will have many derivations for a specific release.}}


Permanent use of binary cache:
Permanent use of binary cache:
Line 134: Line 134:
     };
     };
   };
   };
</syntaxhighlight>
</syntaxhighlight>As described on [https://search.nixos.org/options?show=nix.settings.substituters&type=packages&query=substituters search.nixos.org] by default <nowiki>https://cache.nixos.org/</nowiki> is added to the substituters. You may need to use lib.mkForce to override this and ensure your substituter is the primary choice.<syntaxhighlight>
# /etc/nixos/configuration.nix
 
 
{ config, lib, pkgs, ... }:


{{Warning|Keys that are entered incorrectly or are otherwise invalid, aside from preventing you from benefiting from the cached derivations, may also prevent you from rebuilding your system. This is most likely to occur after garbage collection (e.g., via <code>nix-collect-garbage -d</code>). Consult [https://github.com/NixOS/nix/issues/8271 NixOS/nix#8271] for additional details and a workaround.}}
{
  nix = {
    settings = {
      substituters = lib.mkForce [
        "http://binarycache.example.com"
      ];
      trusted-public-keys = [
        "binarycache.example.com-1:dsafdafDFW123fdasfa123124FADSAD"
      ];
    };
  };
}
</syntaxhighlight>{{Warning|Keys that are entered incorrectly or are otherwise invalid, aside from preventing you from benefiting from the cached derivations, may also prevent you from rebuilding your system. This is most likely to occur after garbage collection (e.g., via <code>nix-collect-garbage -d</code>). Consult [https://github.com/NixOS/nix/issues/8271 NixOS/nix#8271] for additional details and a workaround.}}


Temporary use of binary cache:
Temporary use of binary cache:
Line 178: Line 194:
<syntaxHighlight lang=nix>
<syntaxHighlight lang=nix>
{
{
  nixConfig = {
    extra-substituters = [
      "https://colmena.cachix.org"
    ];
    extra-trusted-public-keys = [
      "colmena.cachix.org-1:7BzpDnjjH8ki2CT3f6GdOk7QAzPOl+1t3LvTLXqYcSg="
    ];
  };
   outputs = { ... }: {
   outputs = { ... }: {
     nixConfig = {
     ...
      extra-substituters = [
        "https://colmena.cachix.org"
      ];
      extra-trusted-public-keys = [
        "colmena.cachix.org-1:7BzpDnjjH8ki2CT3f6GdOk7QAzPOl+1t3LvTLXqYcSg="
      ];
    };
   };
   };
}
}
</syntaxHighlight>
</syntaxHighlight>
=== Binary cache priority ===
Each binary cache has a priority field. A lower number indicates a higher priority.<syntaxhighlight lang="shell-session">
$curl https://cache.nixos.org/nix-cache-info
StoreDir: /nix/store
WantMassQuery: 1
Priority: 40
</syntaxhighlight>You may want to override this value by appending <code>?priority=n</code> at the end of the cache url.<syntaxhighlight lang="nix">
substituters = https://nix-community.cachix.org?priority=1 https://cache.nixos.org?priority=2
</syntaxhighlight>


== Populating a binary cache ==
== Populating a binary cache ==
Line 200: Line 229:
</syntaxhighlight>
</syntaxhighlight>
For details see the [https://nixos.org/manual/nix/stable/package-management/sharing-packages.html Sharing Packages Between Machines] in the Nix manual.
For details see the [https://nixos.org/manual/nix/stable/package-management/sharing-packages.html Sharing Packages Between Machines] in the Nix manual.
== Signing Existing Packages ==
It is also possible to sign all the packages that already exist in the nix store of the machine serving the binary cache to make them immediately available.
<code>$ nix store sign --extra-experimental-features nix-command --all --key-file /var/cache-priv-key.pem</code>
Note : As of NixOS 24.11 {{ic|--extra-experimental-features nix-command}} is required for {{ic|store sign}} if this is not in your configuration.nix.


== Hosted binary cache ==
== Hosted binary cache ==
Line 244: Line 278:
curl https://cache.nixos.org/$(readlink -f $(which bash) | cut -c12-43).narinfo
curl https://cache.nixos.org/$(readlink -f $(which bash) | cut -c12-43).narinfo
</pre>
</pre>
== Command Line Options ==
It is also possible to pass {{ic|substituters}} and {{ic|trusted-public-keys}} on the command line if they are not in {{ic|configuration.nix}} or you want to use a particular binary cache server.
$ nix-build --option substituters "<nowiki>http://binarycache.example.com</nowiki>" --option trusted-public-keys "binarycache.example.com-1:dsafdafDFW123fdasfa123124FADSAD" '<nixpkgs>' -A pkgs.PACKAGE
$ nixos-rebuild --option substituters "<nowiki>http://binarycache.example.com</nowiki>" --option trusted-public-keys "binarycache.example.com-1:dsafdafDFW123fdasfa123124FADSAD" switch
To do an offline install (providing your binary cache contains all the packages required);
$ nixos-install --option substituters "<nowiki>http://binarycache.example.com</nowiki>" --option trusted-public-keys "binarycache.example.com-1:dsafdafDFW123fdasfa123124FADSAD"


== See also ==
== See also ==
<references group="cf."/>
<references group="cf."/>


Retrieved from "https://wiki.nixos.org/wiki/Binary_Cache"