nixpkgs/doc/configuration.xml

248 lines
7.3 KiB
XML
Raw Normal View History

<chapter xmlns="http://docbook.org/ns/docbook"
2015-12-07 12:41:18 -07:00
xmlns:xlink="http://www.w3.org/1999/xlink"
xml:id="chap-packageconfig">
<title>Global configuration</title>
2017-02-16 19:02:13 -07:00
<para>Nix comes with certain defaults about what packages can and
cannot be installed, based on a package's metadata. By default, Nix
will prevent installation if any of the following criteria are
true:</para>
2015-12-07 12:41:18 -07:00
2017-02-16 19:02:13 -07:00
<itemizedlist>
<listitem><para>The package is thought to be broken, and has had
2017-02-16 19:02:13 -07:00
its <literal>meta.broken</literal> set to
<literal>true</literal>.</para></listitem>
<listitem><para>The package's <literal>meta.license</literal> is set
to a license which is considered to be unfree.</para></listitem>
<listitem><para>The package has known security vulnerabilities but
has not or can not be updated for some reason, and a list of issues
has been entered in to the package's
<literal>meta.knownVulnerabilities</literal>.</para></listitem>
</itemizedlist>
<para>Note that all this is checked during evaluation already,
and the check includes any package that is evaluated.
In particular, all build-time dependencies are checked.
<literal>nix-env -qa</literal> will (attempt to) hide any packages
that would be refused.
</para>
<para>Each of these criteria can be altered in the nixpkgs
2017-02-16 19:02:13 -07:00
configuration.</para>
<para>The nixpkgs configuration for a NixOS system is set in the
<literal>configuration.nix</literal>, as in the following example:
<programlisting>
{
nixpkgs.config = {
allowUnfree = true;
};
}
</programlisting>
However, this does not allow unfree software for individual users.
Their configurations are managed separately.</para>
<para>A user's of nixpkgs configuration is stored in a user-specific
configuration file located at
<filename>~/.config/nixpkgs/config.nix</filename>. For example:
2015-12-07 12:41:18 -07:00
<programlisting>
{
2015-02-15 10:29:52 -07:00
allowUnfree = true;
2015-12-07 12:41:18 -07:00
}
</programlisting>
2017-02-16 19:02:13 -07:00
</para>
2015-12-07 12:41:18 -07:00
2017-02-16 19:02:13 -07:00
<section xml:id="sec-allow-broken">
<title>Installing broken packages</title>
2015-12-07 12:41:18 -07:00
2017-02-16 19:02:13 -07:00
<para>There are two ways to try compiling a package which has been
marked as broken.</para>
2015-12-07 12:41:18 -07:00
2017-02-16 19:02:13 -07:00
<itemizedlist>
<listitem><para>
For allowing the build of a broken package once, you can use an
environment variable for a single invocation of the nix tools:
2015-12-07 12:41:18 -07:00
2017-02-16 19:02:13 -07:00
<programlisting>$ export NIXPKGS_ALLOW_BROKEN=1</programlisting>
</para></listitem>
2015-12-07 12:41:18 -07:00
2017-02-16 19:02:13 -07:00
<listitem><para>
For permanently allowing broken packages to be built, you may
add <literal>allowBroken = true;</literal> to your user's
configuration file, like this:
<programlisting>
2017-02-16 19:02:13 -07:00
{
allowBroken = true;
}
</programlisting>
2017-02-16 19:02:13 -07:00
</para></listitem>
</itemizedlist>
</section>
<section xml:id="sec-allow-unfree">
<title>Installing unfree packages</title>
2015-12-07 12:41:18 -07:00
2017-02-16 19:02:13 -07:00
<para>There are several ways to tweak how Nix handles a package
which has been marked as unfree.</para>
2015-12-07 12:41:18 -07:00
2017-02-16 19:02:13 -07:00
<itemizedlist>
<listitem><para>
To temporarily allow all unfree packages, you can use an
environment variable for a single invocation of the nix tools:
2015-12-07 12:41:18 -07:00
2017-02-16 19:02:13 -07:00
<programlisting>$ export NIXPKGS_ALLOW_UNFREE=1</programlisting>
</para></listitem>
<listitem><para>
It is possible to permanently allow individual unfree packages,
while still blocking unfree packages by default using the
<literal>allowUnfreePredicate</literal> configuration
option in the user configuration file.</para>
<para>This option is a function which accepts a package as a
parameter, and returns a boolean. The following example
configuration accepts a package and always returns false:
2015-12-07 12:41:18 -07:00
<programlisting>
2017-02-16 19:02:13 -07:00
{
allowUnfreePredicate = (pkg: false);
}
2015-12-07 12:41:18 -07:00
</programlisting>
2017-02-16 19:02:13 -07:00
</para>
2015-12-07 12:41:18 -07:00
2017-02-16 19:02:13 -07:00
<para>A more useful example, the following configuration allows
only allows flash player and visual studio code:
2015-12-07 12:41:18 -07:00
<programlisting>
2017-02-16 19:02:13 -07:00
{
allowUnfreePredicate = (pkg: elem (builtins.parseDrvName pkg.name).name [ "flashplayer" "vscode" ]);
}
2015-12-07 12:41:18 -07:00
</programlisting>
2017-02-16 19:02:13 -07:00
</para></listitem>
2017-02-16 19:02:13 -07:00
<listitem>
<para>It is also possible to whitelist and blacklist licenses
that are specifically acceptable or not acceptable, using
<literal>whitelistedLicenses</literal> and
<literal>blacklistedLicenses</literal>, respectively.
</para>
2015-12-07 12:41:18 -07:00
2017-02-16 19:02:13 -07:00
<para>The following example configuration whitelists the
licenses <literal>amd</literal> and <literal>wtfpl</literal>:
2015-12-07 12:41:18 -07:00
<programlisting>
2017-02-16 19:02:13 -07:00
{
whitelistedLicenses = with stdenv.lib.licenses; [ amd wtfpl ];
}
2015-12-07 12:41:18 -07:00
</programlisting>
2017-02-16 19:02:13 -07:00
</para>
2015-12-07 12:41:18 -07:00
2017-02-16 19:02:13 -07:00
<para>The following example configuration blacklists the
<literal>gpl3</literal> and <literal>agpl3</literal> licenses:
2015-12-07 12:41:18 -07:00
<programlisting>
2017-02-16 19:02:13 -07:00
{
blacklistedLicenses = with stdenv.lib.licenses; [ agpl3 gpl3 ];
}
2015-12-07 12:41:18 -07:00
</programlisting>
2017-02-16 19:02:13 -07:00
</para>
</listitem>
</itemizedlist>
<para>A complete list of licenses can be found in the file
<filename>lib/licenses.nix</filename> of the nixpkgs tree.</para>
</section>
2015-12-07 12:41:18 -07:00
2017-02-16 19:02:13 -07:00
<section xml:id="sec-allow-insecure">
<title>
Installing insecure packages
</title>
2015-12-07 12:41:18 -07:00
2017-02-16 19:02:13 -07:00
<para>There are several ways to tweak how Nix handles a package
which has been marked as insecure.</para>
2017-02-16 19:02:13 -07:00
<itemizedlist>
<listitem><para>
To temporarily allow all insecure packages, you can use an
environment variable for a single invocation of the nix tools:
<programlisting>$ export NIXPKGS_ALLOW_INSECURE=1</programlisting>
</para></listitem>
<listitem><para>
It is possible to permanently allow individual insecure
packages, while still blocking other insecure packages by
default using the <literal>permittedInsecurePackages</literal>
configuration option in the user configuration file.</para>
<para>The following example configuration permits the
installation of the hypothetically insecure package
<literal>hello</literal>, version <literal>1.2.3</literal>:
<programlisting>
{
permittedInsecurePackages = [
"hello-1.2.3"
];
}
</programlisting>
</para>
</listitem>
<listitem><para>
It is also possible to create a custom policy around which
insecure packages to allow and deny, by overriding the
<literal>allowInsecurePredicate</literal> configuration
option.</para>
<para>The <literal>allowInsecurePredicate</literal> option is a
function which accepts a package and returns a boolean, much
like <literal>allowUnfreePredicate</literal>.</para>
<para>The following configuration example only allows insecure
packages with very short names:
<programlisting>
{
allowInsecurePredicate = (pkg: (builtins.stringLength (builtins.parseDrvName pkg.name).name) &lt;= 5);
}
</programlisting>
</para>
<para>Note that <literal>permittedInsecurePackages</literal> is
only checked if <literal>allowInsecurePredicate</literal> is not
specified.
</para></listitem>
</itemizedlist>
</section>
2015-12-07 12:41:18 -07:00
<!--============================================================-->
2015-04-20 09:54:39 -06:00
<section xml:id="sec-modify-via-packageOverrides"><title>Modify
packages via <literal>packageOverrides</literal></title>
2015-04-20 09:54:39 -06:00
2015-12-07 12:41:18 -07:00
<para>You can define a function called
<varname>packageOverrides</varname> in your local
<filename>~/.config/nixpkgs/config.nix</filename> to overide nix packages. It
2015-12-07 12:41:18 -07:00
must be a function that takes pkgs as an argument and return modified
set of packages.
2015-12-07 12:41:18 -07:00
<programlisting>
{
packageOverrides = pkgs: rec {
foo = pkgs.foo.override { ... };
};
2015-12-07 12:41:18 -07:00
}
</programlisting>
2015-04-20 09:54:39 -06:00
</para>
2015-12-07 12:41:18 -07:00
2015-04-20 09:54:39 -06:00
</section>
2015-12-07 12:41:18 -07:00
2015-04-20 09:54:39 -06:00
</chapter>