uboot: (firmwareOdroidC2/C4) don't invoke patch tool, use patches = [] instead
https://github.com/NixOS/nixpkgs/blob/master/pkgs/stdenv/generic/setup.sh#L948 this can do it nicely. Signed-off-by: Anton Arapov <anton@deadbeef.mx>
This commit is contained in:
Anton Arapov
Alan Daniels
commit
56de2bcd43
30691 changed files with 3076956 additions and 0 deletions
|
|
@ -0,0 +1,144 @@
|
|||
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-boot-problems">
|
||||
<title>Boot Problems</title>
|
||||
<para>
|
||||
If NixOS fails to boot, there are a number of kernel command line
|
||||
parameters that may help you to identify or fix the issue. You can
|
||||
add these parameters in the GRUB boot menu by pressing “e” to modify
|
||||
the selected boot entry and editing the line starting with
|
||||
<literal>linux</literal>. The following are some useful kernel
|
||||
command line parameters that are recognised by the NixOS boot
|
||||
scripts or by systemd:
|
||||
</para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>boot.shell_on_fail</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Allows the user to start a root shell if something goes wrong
|
||||
in stage 1 of the boot process (the initial ramdisk). This is
|
||||
disabled by default because there is no authentication for the
|
||||
root shell.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>boot.debug1</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Start an interactive shell in stage 1 before anything useful
|
||||
has been done. That is, no modules have been loaded and no
|
||||
file systems have been mounted, except for
|
||||
<literal>/proc</literal> and <literal>/sys</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>boot.debug1devices</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Like <literal>boot.debug1</literal>, but runs stage1 until
|
||||
kernel modules are loaded and device nodes are created. This
|
||||
may help with e.g. making the keyboard work.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>boot.debug1mounts</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Like <literal>boot.debug1</literal> or
|
||||
<literal>boot.debug1devices</literal>, but runs stage1 until
|
||||
all filesystems that are mounted during initrd are mounted
|
||||
(see
|
||||
<link linkend="opt-fileSystems._name_.neededForBoot">neededForBoot</link>).
|
||||
As a motivating example, this could be useful if you’ve
|
||||
forgotten to set
|
||||
<link linkend="opt-fileSystems._name_.neededForBoot">neededForBoot</link>
|
||||
on a file system.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>boot.trace</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Print every shell command executed by the stage 1 and 2 boot
|
||||
scripts.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>single</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Boot into rescue mode (a.k.a. single user mode). This will
|
||||
cause systemd to start nothing but the unit
|
||||
<literal>rescue.target</literal>, which runs
|
||||
<literal>sulogin</literal> to prompt for the root password and
|
||||
start a root login shell. Exiting the shell causes the system
|
||||
to continue with the normal boot process.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>systemd.log_level=debug</literal>
|
||||
<literal>systemd.log_target=console</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Make systemd very verbose and send log messages to the console
|
||||
instead of the journal. For more parameters recognised by
|
||||
systemd, see systemd(1).
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
<para>
|
||||
In addition, these arguments are recognised by the live image only:
|
||||
</para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>live.nixos.passwd=password</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Set the password for the <literal>nixos</literal> live user.
|
||||
This can be used for SSH access if there are issues using the
|
||||
terminal.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
<para>
|
||||
Notice that for <literal>boot.shell_on_fail</literal>,
|
||||
<literal>boot.debug1</literal>,
|
||||
<literal>boot.debug1devices</literal>, and
|
||||
<literal>boot.debug1mounts</literal>, if you did
|
||||
<emphasis role="strong">not</emphasis> select <quote>start the new
|
||||
shell as pid 1</quote>, and you <literal>exit</literal> from the new
|
||||
shell, boot will proceed normally from the point where it failed, as
|
||||
if you’d chosen <quote>ignore the error and continue</quote>.
|
||||
</para>
|
||||
<para>
|
||||
If no login prompts or X11 login screens appear (e.g. due to hanging
|
||||
dependencies), you can press Alt+ArrowUp. If you’re lucky, this will
|
||||
start rescue mode (described above). (Also note that since most
|
||||
units have a 90-second timeout before systemd gives up on them, the
|
||||
<literal>agetty</literal> login prompts should appear eventually
|
||||
unless something is very wrong.)
|
||||
</para>
|
||||
</section>
|
||||
|
|
@ -0,0 +1,72 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-nix-gc">
|
||||
<title>Cleaning the Nix Store</title>
|
||||
<para>
|
||||
Nix has a purely functional model, meaning that packages are never
|
||||
upgraded in place. Instead new versions of packages end up in a
|
||||
different location in the Nix store (<literal>/nix/store</literal>).
|
||||
You should periodically run Nix’s <emphasis>garbage
|
||||
collector</emphasis> to remove old, unreferenced packages. This is
|
||||
easy:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ nix-collect-garbage
|
||||
</programlisting>
|
||||
<para>
|
||||
Alternatively, you can use a systemd unit that does the same in the
|
||||
background:
|
||||
</para>
|
||||
<programlisting>
|
||||
# systemctl start nix-gc.service
|
||||
</programlisting>
|
||||
<para>
|
||||
You can tell NixOS in <literal>configuration.nix</literal> to run
|
||||
this unit automatically at certain points in time, for instance,
|
||||
every night at 03:15:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
nix.gc.automatic = true;
|
||||
nix.gc.dates = "03:15";
|
||||
</programlisting>
|
||||
<para>
|
||||
The commands above do not remove garbage collector roots, such as
|
||||
old system configurations. Thus they do not remove the ability to
|
||||
roll back to previous configurations. The following command deletes
|
||||
old roots, removing the ability to roll back to them:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ nix-collect-garbage -d
|
||||
</programlisting>
|
||||
<para>
|
||||
You can also do this for specific profiles, e.g.
|
||||
</para>
|
||||
<programlisting>
|
||||
$ nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old
|
||||
</programlisting>
|
||||
<para>
|
||||
Note that NixOS system configurations are stored in the profile
|
||||
<literal>/nix/var/nix/profiles/system</literal>.
|
||||
</para>
|
||||
<para>
|
||||
Another way to reclaim disk space (often as much as 40% of the size
|
||||
of the Nix store) is to run Nix’s store optimiser, which seeks out
|
||||
identical files in the store and replaces them with hard links to a
|
||||
single copy.
|
||||
</para>
|
||||
<programlisting>
|
||||
$ nix-store --optimise
|
||||
</programlisting>
|
||||
<para>
|
||||
Since this command needs to read the entire Nix store, it can take
|
||||
quite a while to finish.
|
||||
</para>
|
||||
<section xml:id="sect-nixos-gc-boot-entries">
|
||||
<title>NixOS Boot Entries</title>
|
||||
<para>
|
||||
If your <literal>/boot</literal> partition runs out of space,
|
||||
after clearing old profiles you must rebuild your system with
|
||||
<literal>nixos-rebuild boot</literal> or
|
||||
<literal>nixos-rebuild switch</literal> to update the
|
||||
<literal>/boot</literal> partition and clear space.
|
||||
</para>
|
||||
</section>
|
||||
</chapter>
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-container-networking">
|
||||
<title>Container Networking</title>
|
||||
<para>
|
||||
When you create a container using
|
||||
<literal>nixos-container create</literal>, it gets it own private
|
||||
IPv4 address in the range <literal>10.233.0.0/16</literal>. You can
|
||||
get the container’s IPv4 address as follows:
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-container show-ip foo
|
||||
10.233.4.2
|
||||
|
||||
$ ping -c1 10.233.4.2
|
||||
64 bytes from 10.233.4.2: icmp_seq=1 ttl=64 time=0.106 ms
|
||||
</programlisting>
|
||||
<para>
|
||||
Networking is implemented using a pair of virtual Ethernet devices.
|
||||
The network interface in the container is called
|
||||
<literal>eth0</literal>, while the matching interface in the host is
|
||||
called <literal>ve-container-name</literal> (e.g.,
|
||||
<literal>ve-foo</literal>). The container has its own network
|
||||
namespace and the <literal>CAP_NET_ADMIN</literal> capability, so it
|
||||
can perform arbitrary network configuration such as setting up
|
||||
firewall rules, without affecting or having access to the host’s
|
||||
network.
|
||||
</para>
|
||||
<para>
|
||||
By default, containers cannot talk to the outside network. If you
|
||||
want that, you should set up Network Address Translation (NAT) rules
|
||||
on the host to rewrite container traffic to use your external IP
|
||||
address. This can be accomplished using the following configuration
|
||||
on the host:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
networking.nat.enable = true;
|
||||
networking.nat.internalInterfaces = ["ve-+"];
|
||||
networking.nat.externalInterface = "eth0";
|
||||
</programlisting>
|
||||
<para>
|
||||
where <literal>eth0</literal> should be replaced with the desired
|
||||
external interface. Note that <literal>ve-+</literal> is a wildcard
|
||||
that matches all container interfaces.
|
||||
</para>
|
||||
<para>
|
||||
If you are using Network Manager, you need to explicitly prevent it
|
||||
from managing container interfaces:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
networking.networkmanager.unmanaged = [ "interface-name:ve-*" ];
|
||||
</programlisting>
|
||||
<para>
|
||||
You may need to restart your system for the changes to take effect.
|
||||
</para>
|
||||
</section>
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="ch-containers">
|
||||
<title>Container Management</title>
|
||||
<para>
|
||||
NixOS allows you to easily run other NixOS instances as
|
||||
<emphasis>containers</emphasis>. Containers are a light-weight
|
||||
approach to virtualisation that runs software in the container at
|
||||
the same speed as in the host system. NixOS containers share the Nix
|
||||
store of the host, making container creation very efficient.
|
||||
</para>
|
||||
<warning>
|
||||
<para>
|
||||
Currently, NixOS containers are not perfectly isolated from the
|
||||
host system. This means that a user with root access to the
|
||||
container can do things that affect the host. So you should not
|
||||
give container root access to untrusted users.
|
||||
</para>
|
||||
</warning>
|
||||
<para>
|
||||
NixOS containers can be created in two ways: imperatively, using the
|
||||
command <literal>nixos-container</literal>, and declaratively, by
|
||||
specifying them in your <literal>configuration.nix</literal>. The
|
||||
declarative approach implies that containers get upgraded along with
|
||||
your host system when you run <literal>nixos-rebuild</literal>,
|
||||
which is often not what you want. By contrast, in the imperative
|
||||
approach, containers are configured and updated independently from
|
||||
the host system.
|
||||
</para>
|
||||
<xi:include href="imperative-containers.section.xml" />
|
||||
<xi:include href="declarative-containers.section.xml" />
|
||||
<xi:include href="container-networking.section.xml" />
|
||||
</chapter>
|
||||
|
|
@ -0,0 +1,67 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-cgroups">
|
||||
<title>Control Groups</title>
|
||||
<para>
|
||||
To keep track of the processes in a running system, systemd uses
|
||||
<emphasis>control groups</emphasis> (cgroups). A control group is a
|
||||
set of processes used to allocate resources such as CPU, memory or
|
||||
I/O bandwidth. There can be multiple control group hierarchies,
|
||||
allowing each kind of resource to be managed independently.
|
||||
</para>
|
||||
<para>
|
||||
The command <literal>systemd-cgls</literal> lists all control groups
|
||||
in the <literal>systemd</literal> hierarchy, which is what systemd
|
||||
uses to keep track of the processes belonging to each service or
|
||||
user session:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ systemd-cgls
|
||||
├─user
|
||||
│ └─eelco
|
||||
│ └─c1
|
||||
│ ├─ 2567 -:0
|
||||
│ ├─ 2682 kdeinit4: kdeinit4 Running...
|
||||
│ ├─ ...
|
||||
│ └─10851 sh -c less -R
|
||||
└─system
|
||||
├─httpd.service
|
||||
│ ├─2444 httpd -f /nix/store/3pyacby5cpr55a03qwbnndizpciwq161-httpd.conf -DNO_DETACH
|
||||
│ └─...
|
||||
├─dhcpcd.service
|
||||
│ └─2376 dhcpcd --config /nix/store/f8dif8dsi2yaa70n03xir8r653776ka6-dhcpcd.conf
|
||||
└─ ...
|
||||
</programlisting>
|
||||
<para>
|
||||
Similarly, <literal>systemd-cgls cpu</literal> shows the cgroups in
|
||||
the CPU hierarchy, which allows per-cgroup CPU scheduling
|
||||
priorities. By default, every systemd service gets its own CPU
|
||||
cgroup, while all user sessions are in the top-level CPU cgroup.
|
||||
This ensures, for instance, that a thousand run-away processes in
|
||||
the <literal>httpd.service</literal> cgroup cannot starve the CPU
|
||||
for one process in the <literal>postgresql.service</literal> cgroup.
|
||||
(By contrast, it they were in the same cgroup, then the PostgreSQL
|
||||
process would get 1/1001 of the cgroup’s CPU time.) You can limit a
|
||||
service’s CPU share in <literal>configuration.nix</literal>:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
systemd.services.httpd.serviceConfig.CPUShares = 512;
|
||||
</programlisting>
|
||||
<para>
|
||||
By default, every cgroup has 1024 CPU shares, so this will halve the
|
||||
CPU allocation of the <literal>httpd.service</literal> cgroup.
|
||||
</para>
|
||||
<para>
|
||||
There also is a <literal>memory</literal> hierarchy that controls
|
||||
memory allocation limits; by default, all processes are in the
|
||||
top-level cgroup, so any service or session can exhaust all
|
||||
available memory. Per-cgroup memory limits can be specified in
|
||||
<literal>configuration.nix</literal>; for instance, to limit
|
||||
<literal>httpd.service</literal> to 512 MiB of RAM (excluding swap):
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
systemd.services.httpd.serviceConfig.MemoryLimit = "512M";
|
||||
</programlisting>
|
||||
<para>
|
||||
The command <literal>systemd-cgtop</literal> shows a continuously
|
||||
updated list of all cgroups with their CPU and memory usage.
|
||||
</para>
|
||||
</chapter>
|
||||
|
|
@ -0,0 +1,60 @@
|
|||
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-declarative-containers">
|
||||
<title>Declarative Container Specification</title>
|
||||
<para>
|
||||
You can also specify containers and their configuration in the
|
||||
host’s <literal>configuration.nix</literal>. For example, the
|
||||
following specifies that there shall be a container named
|
||||
<literal>database</literal> running PostgreSQL:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
containers.database =
|
||||
{ config =
|
||||
{ config, pkgs, ... }:
|
||||
{ services.postgresql.enable = true;
|
||||
services.postgresql.package = pkgs.postgresql_10;
|
||||
};
|
||||
};
|
||||
</programlisting>
|
||||
<para>
|
||||
If you run <literal>nixos-rebuild switch</literal>, the container
|
||||
will be built. If the container was already running, it will be
|
||||
updated in place, without rebooting. The container can be configured
|
||||
to start automatically by setting
|
||||
<literal>containers.database.autoStart = true</literal> in its
|
||||
configuration.
|
||||
</para>
|
||||
<para>
|
||||
By default, declarative containers share the network namespace of
|
||||
the host, meaning that they can listen on (privileged) ports.
|
||||
However, they cannot change the network configuration. You can give
|
||||
a container its own network as follows:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
containers.database = {
|
||||
privateNetwork = true;
|
||||
hostAddress = "192.168.100.10";
|
||||
localAddress = "192.168.100.11";
|
||||
};
|
||||
</programlisting>
|
||||
<para>
|
||||
This gives the container a private virtual Ethernet interface with
|
||||
IP address <literal>192.168.100.11</literal>, which is hooked up to
|
||||
a virtual Ethernet interface on the host with IP address
|
||||
<literal>192.168.100.10</literal>. (See the next section for details
|
||||
on container networking.)
|
||||
</para>
|
||||
<para>
|
||||
To disable the container, just remove it from
|
||||
<literal>configuration.nix</literal> and run
|
||||
<literal>nixos-rebuild switch</literal>. Note that this will not
|
||||
delete the root directory of the container in
|
||||
<literal>/var/lib/nixos-containers</literal>. Containers can be
|
||||
destroyed using the imperative method:
|
||||
<literal>nixos-container destroy foo</literal>.
|
||||
</para>
|
||||
<para>
|
||||
Declarative containers can be started and stopped using the
|
||||
corresponding systemd service, e.g.
|
||||
<literal>systemctl start container@database</literal>.
|
||||
</para>
|
||||
</section>
|
||||
|
|
@ -0,0 +1,132 @@
|
|||
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-imperative-containers">
|
||||
<title>Imperative Container Management</title>
|
||||
<para>
|
||||
We’ll cover imperative container management using
|
||||
<literal>nixos-container</literal> first. Be aware that container
|
||||
management is currently only possible as <literal>root</literal>.
|
||||
</para>
|
||||
<para>
|
||||
You create a container with identifier <literal>foo</literal> as
|
||||
follows:
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-container create foo
|
||||
</programlisting>
|
||||
<para>
|
||||
This creates the container’s root directory in
|
||||
<literal>/var/lib/nixos-containers/foo</literal> and a small
|
||||
configuration file in
|
||||
<literal>/etc/nixos-containers/foo.conf</literal>. It also builds
|
||||
the container’s initial system configuration and stores it in
|
||||
<literal>/nix/var/nix/profiles/per-container/foo/system</literal>.
|
||||
You can modify the initial configuration of the container on the
|
||||
command line. For instance, to create a container that has
|
||||
<literal>sshd</literal> running, with the given public key for
|
||||
<literal>root</literal>:
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-container create foo --config '
|
||||
services.openssh.enable = true;
|
||||
users.users.root.openssh.authorizedKeys.keys = ["ssh-dss AAAAB3N…"];
|
||||
'
|
||||
</programlisting>
|
||||
<para>
|
||||
By default the next free address in the
|
||||
<literal>10.233.0.0/16</literal> subnet will be chosen as container
|
||||
IP. This behavior can be altered by setting
|
||||
<literal>--host-address</literal> and
|
||||
<literal>--local-address</literal>:
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-container create test --config-file test-container.nix \
|
||||
--local-address 10.235.1.2 --host-address 10.235.1.1
|
||||
</programlisting>
|
||||
<para>
|
||||
Creating a container does not start it. To start the container, run:
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-container start foo
|
||||
</programlisting>
|
||||
<para>
|
||||
This command will return as soon as the container has booted and has
|
||||
reached <literal>multi-user.target</literal>. On the host, the
|
||||
container runs within a systemd unit called
|
||||
<literal>container@container-name.service</literal>. Thus, if
|
||||
something went wrong, you can get status info using
|
||||
<literal>systemctl</literal>:
|
||||
</para>
|
||||
<programlisting>
|
||||
# systemctl status container@foo
|
||||
</programlisting>
|
||||
<para>
|
||||
If the container has started successfully, you can log in as root
|
||||
using the <literal>root-login</literal> operation:
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-container root-login foo
|
||||
[root@foo:~]#
|
||||
</programlisting>
|
||||
<para>
|
||||
Note that only root on the host can do this (since there is no
|
||||
authentication). You can also get a regular login prompt using the
|
||||
<literal>login</literal> operation, which is available to all users
|
||||
on the host:
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-container login foo
|
||||
foo login: alice
|
||||
Password: ***
|
||||
</programlisting>
|
||||
<para>
|
||||
With <literal>nixos-container run</literal>, you can execute
|
||||
arbitrary commands in the container:
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-container run foo -- uname -a
|
||||
Linux foo 3.4.82 #1-NixOS SMP Thu Mar 20 14:44:05 UTC 2014 x86_64 GNU/Linux
|
||||
</programlisting>
|
||||
<para>
|
||||
There are several ways to change the configuration of the container.
|
||||
First, on the host, you can edit
|
||||
<literal>/var/lib/container/name/etc/nixos/configuration.nix</literal>,
|
||||
and run
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-container update foo
|
||||
</programlisting>
|
||||
<para>
|
||||
This will build and activate the new configuration. You can also
|
||||
specify a new configuration on the command line:
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-container update foo --config '
|
||||
services.httpd.enable = true;
|
||||
services.httpd.adminAddr = "foo@example.org";
|
||||
networking.firewall.allowedTCPPorts = [ 80 ];
|
||||
'
|
||||
|
||||
# curl http://$(nixos-container show-ip foo)/
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">…
|
||||
</programlisting>
|
||||
<para>
|
||||
However, note that this will overwrite the container’s
|
||||
<literal>/etc/nixos/configuration.nix</literal>.
|
||||
</para>
|
||||
<para>
|
||||
Alternatively, you can change the configuration from within the
|
||||
container itself by running <literal>nixos-rebuild switch</literal>
|
||||
inside the container. Note that the container by default does not
|
||||
have a copy of the NixOS channel, so you should run
|
||||
<literal>nix-channel --update</literal> first.
|
||||
</para>
|
||||
<para>
|
||||
Containers can be stopped and started using
|
||||
<literal>nixos-container stop</literal> and
|
||||
<literal>nixos-container start</literal>, respectively, or by using
|
||||
<literal>systemctl</literal> on the container’s service unit. To
|
||||
destroy a container, including its file system, do
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-container destroy foo
|
||||
</programlisting>
|
||||
</section>
|
||||
45
nixos/doc/manual/from_md/administration/logging.chapter.xml
Normal file
45
nixos/doc/manual/from_md/administration/logging.chapter.xml
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-logging">
|
||||
<title>Logging</title>
|
||||
<para>
|
||||
System-wide logging is provided by systemd’s
|
||||
<emphasis>journal</emphasis>, which subsumes traditional logging
|
||||
daemons such as syslogd and klogd. Log entries are kept in binary
|
||||
files in <literal>/var/log/journal/</literal>. The command
|
||||
<literal>journalctl</literal> allows you to see the contents of the
|
||||
journal. For example,
|
||||
</para>
|
||||
<programlisting>
|
||||
$ journalctl -b
|
||||
</programlisting>
|
||||
<para>
|
||||
shows all journal entries since the last reboot. (The output of
|
||||
<literal>journalctl</literal> is piped into <literal>less</literal>
|
||||
by default.) You can use various options and match operators to
|
||||
restrict output to messages of interest. For instance, to get all
|
||||
messages from PostgreSQL:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ journalctl -u postgresql.service
|
||||
-- Logs begin at Mon, 2013-01-07 13:28:01 CET, end at Tue, 2013-01-08 01:09:57 CET. --
|
||||
...
|
||||
Jan 07 15:44:14 hagbard postgres[2681]: [2-1] LOG: database system is shut down
|
||||
-- Reboot --
|
||||
Jan 07 15:45:10 hagbard postgres[2532]: [1-1] LOG: database system was shut down at 2013-01-07 15:44:14 CET
|
||||
Jan 07 15:45:13 hagbard postgres[2500]: [1-1] LOG: database system is ready to accept connections
|
||||
</programlisting>
|
||||
<para>
|
||||
Or to get all messages since the last reboot that have at least a
|
||||
<quote>critical</quote> severity level:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ journalctl -b -p crit
|
||||
Dec 17 21:08:06 mandark sudo[3673]: pam_unix(sudo:auth): auth could not identify password for [alice]
|
||||
Dec 29 01:30:22 mandark kernel[6131]: [1053513.909444] CPU6: Core temperature above threshold, cpu clock throttled (total events = 1)
|
||||
</programlisting>
|
||||
<para>
|
||||
The system journal is readable by root and by users in the
|
||||
<literal>wheel</literal> and <literal>systemd-journal</literal>
|
||||
groups. All users have a private journal that can be read using
|
||||
<literal>journalctl</literal>.
|
||||
</para>
|
||||
</chapter>
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-maintenance-mode">
|
||||
<title>Maintenance Mode</title>
|
||||
<para>
|
||||
You can enter rescue mode by running:
|
||||
</para>
|
||||
<programlisting>
|
||||
# systemctl rescue
|
||||
</programlisting>
|
||||
<para>
|
||||
This will eventually give you a single-user root shell. Systemd will
|
||||
stop (almost) all system services. To get out of maintenance mode,
|
||||
just exit from the rescue shell.
|
||||
</para>
|
||||
</section>
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-nix-network-issues">
|
||||
<title>Network Problems</title>
|
||||
<para>
|
||||
Nix uses a so-called <emphasis>binary cache</emphasis> to optimise
|
||||
building a package from source into downloading it as a pre-built
|
||||
binary. That is, whenever a command like
|
||||
<literal>nixos-rebuild</literal> needs a path in the Nix store, Nix
|
||||
will try to download that path from the Internet rather than build
|
||||
it from source. The default binary cache is
|
||||
<literal>https://cache.nixos.org/</literal>. If this cache is
|
||||
unreachable, Nix operations may take a long time due to HTTP
|
||||
connection timeouts. You can disable the use of the binary cache by
|
||||
adding <literal>--option use-binary-caches false</literal>, e.g.
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-rebuild switch --option use-binary-caches false
|
||||
</programlisting>
|
||||
<para>
|
||||
If you have an alternative binary cache at your disposal, you can
|
||||
use it instead:
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-rebuild switch --option binary-caches http://my-cache.example.org/
|
||||
</programlisting>
|
||||
</section>
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-rebooting">
|
||||
<title>Rebooting and Shutting Down</title>
|
||||
<para>
|
||||
The system can be shut down (and automatically powered off) by
|
||||
doing:
|
||||
</para>
|
||||
<programlisting>
|
||||
# shutdown
|
||||
</programlisting>
|
||||
<para>
|
||||
This is equivalent to running <literal>systemctl poweroff</literal>.
|
||||
</para>
|
||||
<para>
|
||||
To reboot the system, run
|
||||
</para>
|
||||
<programlisting>
|
||||
# reboot
|
||||
</programlisting>
|
||||
<para>
|
||||
which is equivalent to <literal>systemctl reboot</literal>.
|
||||
Alternatively, you can quickly reboot the system using
|
||||
<literal>kexec</literal>, which bypasses the BIOS by directly
|
||||
loading the new kernel into memory:
|
||||
</para>
|
||||
<programlisting>
|
||||
# systemctl kexec
|
||||
</programlisting>
|
||||
<para>
|
||||
The machine can be suspended to RAM (if supported) using
|
||||
<literal>systemctl suspend</literal>, and suspended to disk using
|
||||
<literal>systemctl hibernate</literal>.
|
||||
</para>
|
||||
<para>
|
||||
These commands can be run by any user who is logged in locally, i.e.
|
||||
on a virtual console or in X11; otherwise, the user is asked for
|
||||
authentication.
|
||||
</para>
|
||||
</chapter>
|
||||
42
nixos/doc/manual/from_md/administration/rollback.section.xml
Normal file
42
nixos/doc/manual/from_md/administration/rollback.section.xml
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-rollback">
|
||||
<title>Rolling Back Configuration Changes</title>
|
||||
<para>
|
||||
After running <literal>nixos-rebuild</literal> to switch to a new
|
||||
configuration, you may find that the new configuration doesn’t work
|
||||
very well. In that case, there are several ways to return to a
|
||||
previous configuration.
|
||||
</para>
|
||||
<para>
|
||||
First, the GRUB boot manager allows you to boot into any previous
|
||||
configuration that hasn’t been garbage-collected. These
|
||||
configurations can be found under the GRUB submenu <quote>NixOS -
|
||||
All configurations</quote>. This is especially useful if the new
|
||||
configuration fails to boot. After the system has booted, you can
|
||||
make the selected configuration the default for subsequent boots:
|
||||
</para>
|
||||
<programlisting>
|
||||
# /run/current-system/bin/switch-to-configuration boot
|
||||
</programlisting>
|
||||
<para>
|
||||
Second, you can switch to the previous configuration in a running
|
||||
system:
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-rebuild switch --rollback
|
||||
</programlisting>
|
||||
<para>
|
||||
This is equivalent to running:
|
||||
</para>
|
||||
<programlisting>
|
||||
# /nix/var/nix/profiles/system-N-link/bin/switch-to-configuration switch
|
||||
</programlisting>
|
||||
<para>
|
||||
where <literal>N</literal> is the number of the NixOS system
|
||||
configuration. To get a list of the available configurations, do:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ ls -l /nix/var/nix/profiles/system-*-link
|
||||
...
|
||||
lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -> /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055
|
||||
</programlisting>
|
||||
</section>
|
||||
141
nixos/doc/manual/from_md/administration/service-mgmt.chapter.xml
Normal file
141
nixos/doc/manual/from_md/administration/service-mgmt.chapter.xml
Normal file
|
|
@ -0,0 +1,141 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-systemctl">
|
||||
<title>Service Management</title>
|
||||
<para>
|
||||
In NixOS, all system services are started and monitored using the
|
||||
systemd program. systemd is the <quote>init</quote> process of the
|
||||
system (i.e. PID 1), the parent of all other processes. It manages a
|
||||
set of so-called <quote>units</quote>, which can be things like
|
||||
system services (programs), but also mount points, swap files,
|
||||
devices, targets (groups of units) and more. Units can have complex
|
||||
dependencies; for instance, one unit can require that another unit
|
||||
must be successfully started before the first unit can be started.
|
||||
When the system boots, it starts a unit named
|
||||
<literal>default.target</literal>; the dependencies of this unit
|
||||
cause all system services to be started, file systems to be mounted,
|
||||
swap files to be activated, and so on.
|
||||
</para>
|
||||
<section xml:id="sect-nixos-systemd-general">
|
||||
<title>Interacting with a running systemd</title>
|
||||
<para>
|
||||
The command <literal>systemctl</literal> is the main way to
|
||||
interact with <literal>systemd</literal>. The following paragraphs
|
||||
demonstrate ways to interact with any OS running systemd as init
|
||||
system. NixOS is of no exception. The
|
||||
<link linkend="sect-nixos-systemd-nixos">next section </link>
|
||||
explains NixOS specific things worth knowing.
|
||||
</para>
|
||||
<para>
|
||||
Without any arguments, <literal>systemctl</literal> the status of
|
||||
active units:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ systemctl
|
||||
-.mount loaded active mounted /
|
||||
swapfile.swap loaded active active /swapfile
|
||||
sshd.service loaded active running SSH Daemon
|
||||
graphical.target loaded active active Graphical Interface
|
||||
...
|
||||
</programlisting>
|
||||
<para>
|
||||
You can ask for detailed status information about a unit, for
|
||||
instance, the PostgreSQL database service:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ systemctl status postgresql.service
|
||||
postgresql.service - PostgreSQL Server
|
||||
Loaded: loaded (/nix/store/pn3q73mvh75gsrl8w7fdlfk3fq5qm5mw-unit/postgresql.service)
|
||||
Active: active (running) since Mon, 2013-01-07 15:55:57 CET; 9h ago
|
||||
Main PID: 2390 (postgres)
|
||||
CGroup: name=systemd:/system/postgresql.service
|
||||
├─2390 postgres
|
||||
├─2418 postgres: writer process
|
||||
├─2419 postgres: wal writer process
|
||||
├─2420 postgres: autovacuum launcher process
|
||||
├─2421 postgres: stats collector process
|
||||
└─2498 postgres: zabbix zabbix [local] idle
|
||||
|
||||
Jan 07 15:55:55 hagbard postgres[2394]: [1-1] LOG: database system was shut down at 2013-01-07 15:55:05 CET
|
||||
Jan 07 15:55:57 hagbard postgres[2390]: [1-1] LOG: database system is ready to accept connections
|
||||
Jan 07 15:55:57 hagbard postgres[2420]: [1-1] LOG: autovacuum launcher started
|
||||
Jan 07 15:55:57 hagbard systemd[1]: Started PostgreSQL Server.
|
||||
</programlisting>
|
||||
<para>
|
||||
Note that this shows the status of the unit (active and running),
|
||||
all the processes belonging to the service, as well as the most
|
||||
recent log messages from the service.
|
||||
</para>
|
||||
<para>
|
||||
Units can be stopped, started or restarted:
|
||||
</para>
|
||||
<programlisting>
|
||||
# systemctl stop postgresql.service
|
||||
# systemctl start postgresql.service
|
||||
# systemctl restart postgresql.service
|
||||
</programlisting>
|
||||
<para>
|
||||
These operations are synchronous: they wait until the service has
|
||||
finished starting or stopping (or has failed). Starting a unit
|
||||
will cause the dependencies of that unit to be started as well (if
|
||||
necessary).
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="sect-nixos-systemd-nixos">
|
||||
<title>systemd in NixOS</title>
|
||||
<para>
|
||||
Packages in Nixpkgs sometimes provide systemd units with them,
|
||||
usually in e.g <literal>#pkg-out#/lib/systemd/</literal>. Putting
|
||||
such a package in <literal>environment.systemPackages</literal>
|
||||
doesn't make the service available to users or the system.
|
||||
</para>
|
||||
<para>
|
||||
In order to enable a systemd <emphasis>system</emphasis> service
|
||||
with provided upstream package, use (e.g):
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
systemd.packages = [ pkgs.packagekit ];
|
||||
</programlisting>
|
||||
<para>
|
||||
Usually NixOS modules written by the community do the above, plus
|
||||
take care of other details. If a module was written for a service
|
||||
you are interested in, you'd probably need only to use
|
||||
<literal>services.#name#.enable = true;</literal>. These services
|
||||
are defined in Nixpkgs'
|
||||
<link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules">
|
||||
<literal>nixos/modules/</literal> directory </link>. In case the
|
||||
service is simple enough, the above method should work, and start
|
||||
the service on boot.
|
||||
</para>
|
||||
<para>
|
||||
<emphasis>User</emphasis> systemd services on the other hand,
|
||||
should be treated differently. Given a package that has a systemd
|
||||
unit file at <literal>#pkg-out#/lib/systemd/user/</literal>, using
|
||||
<xref linkend="opt-systemd.packages" /> will make you able to
|
||||
start the service via <literal>systemctl --user start</literal>,
|
||||
but it won't start automatically on login. However, You can
|
||||
imperatively enable it by adding the package's attribute to
|
||||
<xref linkend="opt-systemd.packages" /> and then do this (e.g):
|
||||
</para>
|
||||
<programlisting>
|
||||
$ mkdir -p ~/.config/systemd/user/default.target.wants
|
||||
$ ln -s /run/current-system/sw/lib/systemd/user/syncthing.service ~/.config/systemd/user/default.target.wants/
|
||||
$ systemctl --user daemon-reload
|
||||
$ systemctl --user enable syncthing.service
|
||||
</programlisting>
|
||||
<para>
|
||||
If you are interested in a timer file, use
|
||||
<literal>timers.target.wants</literal> instead of
|
||||
<literal>default.target.wants</literal> in the 1st and 2nd
|
||||
command.
|
||||
</para>
|
||||
<para>
|
||||
Using <literal>systemctl --user enable syncthing.service</literal>
|
||||
instead of the above, will work, but it'll use the absolute path
|
||||
of <literal>syncthing.service</literal> for the symlink, and this
|
||||
path is in <literal>/nix/store/.../lib/systemd/user/</literal>.
|
||||
Hence <link linkend="sec-nix-gc">garbage collection</link> will
|
||||
remove that file and you will wind up with a broken symlink in
|
||||
your systemd configuration, which in turn will not make the
|
||||
service / timer start on login.
|
||||
</para>
|
||||
</section>
|
||||
</chapter>
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-nix-store-corruption">
|
||||
<title>Nix Store Corruption</title>
|
||||
<para>
|
||||
After a system crash, it’s possible for files in the Nix store to
|
||||
become corrupted. (For instance, the Ext4 file system has the
|
||||
tendency to replace un-synced files with zero bytes.) NixOS tries
|
||||
hard to prevent this from happening: it performs a
|
||||
<literal>sync</literal> before switching to a new configuration, and
|
||||
Nix’s database is fully transactional. If corruption still occurs,
|
||||
you may be able to fix it automatically.
|
||||
</para>
|
||||
<para>
|
||||
If the corruption is in a path in the closure of the NixOS system
|
||||
configuration, you can fix it by doing
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-rebuild switch --repair
|
||||
</programlisting>
|
||||
<para>
|
||||
This will cause Nix to check every path in the closure, and if its
|
||||
cryptographic hash differs from the hash recorded in Nix’s database,
|
||||
the path is rebuilt or redownloaded.
|
||||
</para>
|
||||
<para>
|
||||
You can also scan the entire Nix store for corrupt paths:
|
||||
</para>
|
||||
<programlisting>
|
||||
# nix-store --verify --check-contents --repair
|
||||
</programlisting>
|
||||
<para>
|
||||
Any corrupt paths will be redownloaded if they’re available in a
|
||||
binary cache; otherwise, they cannot be repaired.
|
||||
</para>
|
||||
</section>
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="ch-troubleshooting">
|
||||
<title>Troubleshooting</title>
|
||||
<para>
|
||||
This chapter describes solutions to common problems you might
|
||||
encounter when you manage your NixOS system.
|
||||
</para>
|
||||
<xi:include href="boot-problems.section.xml" />
|
||||
<xi:include href="maintenance-mode.section.xml" />
|
||||
<xi:include href="rollback.section.xml" />
|
||||
<xi:include href="store-corruption.section.xml" />
|
||||
<xi:include href="network-problems.section.xml" />
|
||||
</chapter>
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-user-sessions">
|
||||
<title>User Sessions</title>
|
||||
<para>
|
||||
Systemd keeps track of all users who are logged into the system
|
||||
(e.g. on a virtual console or remotely via SSH). The command
|
||||
<literal>loginctl</literal> allows querying and manipulating user
|
||||
sessions. For instance, to list all user sessions:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ loginctl
|
||||
SESSION UID USER SEAT
|
||||
c1 500 eelco seat0
|
||||
c3 0 root seat0
|
||||
c4 500 alice
|
||||
</programlisting>
|
||||
<para>
|
||||
This shows that two users are logged in locally, while another is
|
||||
logged in remotely. (<quote>Seats</quote> are essentially the
|
||||
combinations of displays and input devices attached to the system;
|
||||
usually, there is only one seat.) To get information about a
|
||||
session:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ loginctl session-status c3
|
||||
c3 - root (0)
|
||||
Since: Tue, 2013-01-08 01:17:56 CET; 4min 42s ago
|
||||
Leader: 2536 (login)
|
||||
Seat: seat0; vc3
|
||||
TTY: /dev/tty3
|
||||
Service: login; type tty; class user
|
||||
State: online
|
||||
CGroup: name=systemd:/user/root/c3
|
||||
├─ 2536 /nix/store/10mn4xip9n7y9bxqwnsx7xwx2v2g34xn-shadow-4.1.5.1/bin/login --
|
||||
├─10339 -bash
|
||||
└─10355 w3m nixos.org
|
||||
</programlisting>
|
||||
<para>
|
||||
This shows that the user is logged in on virtual console 3. It also
|
||||
lists the processes belonging to this session. Since systemd keeps
|
||||
track of this, you can terminate a session in a way that ensures
|
||||
that all the session’s processes are gone:
|
||||
</para>
|
||||
<programlisting>
|
||||
# loginctl terminate-session c3
|
||||
</programlisting>
|
||||
</chapter>
|
||||
Loading…
Add table
Add a link
Reference in a new issue