Manual: Explicitly mark commands that require to be run as root (#15589)

* manual: Mark commands that require root

Mark every command that requires to be run as root by prefixing them
with '#' instead of '$'.

* manual: Add note about commands that require root
This commit is contained in:
Wilhelm Schuster 2016-06-01 16:23:32 +02:00 committed by Domen Kožar
parent f547137425
commit 5f8d14546b
28 changed files with 101 additions and 98 deletions

View file

@ -21,7 +21,7 @@ Alternatively, you can use a systemd unit that does the same in the
background:
<screen>
$ systemctl start nix-gc.service
# systemctl start nix-gc.service
</screen>
You can tell NixOS in <filename>configuration.nix</filename> to run
@ -59,4 +59,4 @@ $ nix-store --optimise
Since this command needs to read the entire Nix store, it can take
quite a while to finish.</para>
</chapter>
</chapter>

View file

@ -13,7 +13,7 @@ create</literal>, it gets it own private IPv4 address in the range
address as follows:
<screen>
$ nixos-container show-ip foo
# nixos-container show-ip foo
10.233.4.2
$ ping -c1 10.233.4.2
@ -47,4 +47,4 @@ 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>
</section>
</section>

View file

@ -11,7 +11,7 @@
identifier <literal>foo</literal> as follows:
<screen>
$ nixos-container create foo
# nixos-container create foo
</screen>
This creates the containers root directory in
@ -25,7 +25,7 @@ line. For instance, to create a container that has
<literal>root</literal>:
<screen>
$ nixos-container create foo --config 'services.openssh.enable = true; \
# nixos-container create foo --config 'services.openssh.enable = true; \
users.extraUsers.root.openssh.authorizedKeys.keys = ["ssh-dss AAAAB3N…"];'
</screen>
@ -35,7 +35,7 @@ $ nixos-container create foo --config 'services.openssh.enable = true; \
run:
<screen>
$ nixos-container start foo
# nixos-container start foo
</screen>
This command will return as soon as the container has booted and has
@ -46,7 +46,7 @@ Thus, if something went wrong, you can get status info using
<command>systemctl</command>:
<screen>
$ systemctl status container@foo
# systemctl status container@foo
</screen>
</para>
@ -55,7 +55,7 @@ $ systemctl status container@foo
root using the <command>root-login</command> operation:
<screen>
$ nixos-container root-login foo
# nixos-container root-login foo
[root@foo:~]#
</screen>
@ -65,7 +65,7 @@ authentication). You can also get a regular login prompt using the
the host:
<screen>
$ nixos-container login foo
# nixos-container login foo
foo login: alice
Password: ***
</screen>
@ -74,7 +74,7 @@ With <command>nixos-container run</command>, you can execute arbitrary
commands in the container:
<screen>
$ nixos-container run foo -- uname -a
# 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
</screen>
@ -86,17 +86,17 @@ container. First, on the host, you can edit
and run
<screen>
$ nixos-container update foo
# nixos-container update foo
</screen>
This will build and activate the new configuration. You can also
specify a new configuration on the command line:
<screen>
$ nixos-container update foo --config 'services.httpd.enable = true; \
# nixos-container update foo --config 'services.httpd.enable = true; \
services.httpd.adminAddr = "foo@example.org";'
$ curl http://$(nixos-container show-ip foo)/
# curl http://$(nixos-container show-ip foo)/
&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">…
</screen>
@ -116,9 +116,9 @@ start</literal>, respectively, or by using
destroy a container, including its file system, do
<screen>
$ nixos-container destroy foo
# nixos-container destroy foo
</screen>
</para>
</section>
</section>

View file

@ -9,10 +9,10 @@
<para>You can enter rescue mode by running:
<screen>
$ systemctl rescue</screen>
# systemctl rescue</screen>
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>
</section>

View file

@ -18,14 +18,14 @@ You can disable the use of the binary cache by adding <option>--option
use-binary-caches false</option>, e.g.
<screen>
$ nixos-rebuild switch --option use-binary-caches false
# nixos-rebuild switch --option use-binary-caches false
</screen>
If you have an alternative binary cache at your disposal, you can use
it instead:
<screen>
$ nixos-rebuild switch --option binary-caches http://my-cache.example.org/
# nixos-rebuild switch --option binary-caches http://my-cache.example.org/
</screen>
</para>

View file

@ -10,7 +10,7 @@
doing:
<screen>
$ shutdown
# shutdown
</screen>
This is equivalent to running <command>systemctl
@ -19,7 +19,7 @@ poweroff</command>.</para>
<para>To reboot the system, run
<screen>
$ reboot
# reboot
</screen>
which is equivalent to <command>systemctl reboot</command>.
@ -28,7 +28,7 @@ Alternatively, you can quickly reboot the system using
the new kernel into memory:
<screen>
$ systemctl kexec
# systemctl kexec
</screen>
</para>
@ -41,4 +41,4 @@ $ systemctl kexec
i.e. on a virtual console or in X11; otherwise, the user is asked for
authentication.</para>
</chapter>
</chapter>

View file

@ -19,7 +19,7 @@ fails to boot. After the system has booted, you can make the selected
configuration the default for subsequent boots:
<screen>
$ /run/current-system/bin/switch-to-configuration boot</screen>
# /run/current-system/bin/switch-to-configuration boot</screen>
</para>
@ -27,12 +27,12 @@ $ /run/current-system/bin/switch-to-configuration boot</screen>
system:
<screen>
$ nixos-rebuild switch --rollback</screen>
# nixos-rebuild switch --rollback</screen>
This is equivalent to running:
<screen>
$ /nix/var/nix/profiles/system-<replaceable>N</replaceable>-link/bin/switch-to-configuration switch</screen>
# /nix/var/nix/profiles/system-<replaceable>N</replaceable>-link/bin/switch-to-configuration switch</screen>
where <replaceable>N</replaceable> is the number of the NixOS system
configuration. To get a list of the available configurations, do:
@ -45,4 +45,4 @@ lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link ->
</para>
</section>
</section>

View file

@ -66,9 +66,9 @@ messages from the service.
<para>Units can be stopped, started or restarted:
<screen>
$ systemctl stop postgresql.service
$ systemctl start postgresql.service
$ systemctl restart postgresql.service
# systemctl stop postgresql.service
# systemctl start postgresql.service
# systemctl restart postgresql.service
</screen>
These operations are synchronous: they wait until the service has

View file

@ -18,7 +18,7 @@ you may be able to fix it automatically.</para>
system configuration, you can fix it by doing
<screen>
$ nixos-rebuild switch --repair
# nixos-rebuild switch --repair
</screen>
This will cause Nix to check every path in the closure, and if its
@ -28,10 +28,10 @@ the path is rebuilt or redownloaded.</para>
<para>You can also scan the entire Nix store for corrupt paths:
<screen>
$ nix-store --verify --check-contents --repair
# nix-store --verify --check-contents --repair
</screen>
Any corrupt paths will be redownloaded if theyre available in a
binary cache; otherwise, they cannot be repaired.</para>
</section>
</section>

View file

@ -45,9 +45,9 @@ track of this, you can terminate a session in a way that ensures that
all the sessions processes are gone:
<screen>
$ loginctl terminate-session c3
# loginctl terminate-session c3
</screen>
</para>
</chapter>
</chapter>

View file

@ -31,7 +31,7 @@ and you run <command>nixos-rebuild</command>, specifying your own
Nixpkgs tree:
<screen>
$ nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs</screen>
# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs</screen>
</para>

View file

@ -82,7 +82,7 @@ $ nix-shell '<nixpkgs>' -A linuxPackages.kernel
$ unpackPhase
$ cd linux-*
$ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules
$ sudo insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko
# insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko
]]></screen>
</section>

View file

@ -12,7 +12,7 @@ here is how you create an encrypted Ext4 file system on the device
<filename>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</filename>:
<screen>
$ cryptsetup luksFormat /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d
# cryptsetup luksFormat /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d
WARNING!
========
@ -22,10 +22,10 @@ Are you sure? (Type uppercase yes): YES
Enter LUKS passphrase: ***
Verify passphrase: ***
$ cryptsetup luksOpen /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d crypted
# cryptsetup luksOpen /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d crypted
Enter passphrase for /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d: ***
$ mkfs.ext4 /dev/mapper/crypted
# mkfs.ext4 /dev/mapper/crypted
</screen>
To ensure that this file system is automatically mounted at boot time

View file

@ -63,14 +63,14 @@ commands such as <command>useradd</command>,
account named <literal>alice</literal>:
<screen>
$ useradd -m alice</screen>
# useradd -m alice</screen>
To make all nix tools available to this new user use `su - USER` which
opens a login shell (==shell that loads the profile) for given user.
This will create the ~/.nix-defexpr symlink. So run:
<screen>
$ su - alice -c "true"</screen>
# su - alice -c "true"</screen>
The flag <option>-m</option> causes the creation of a home directory
@ -79,7 +79,7 @@ have an initial password and therefore cannot log in. A password can
be set using the <command>passwd</command> utility:
<screen>
$ passwd alice
# passwd alice
Enter new UNIX password: ***
Retype new UNIX password: ***
</screen>
@ -87,7 +87,7 @@ Retype new UNIX password: ***
A user can be deleted using <command>userdel</command>:
<screen>
$ userdel -r alice</screen>
# userdel -r alice</screen>
The flag <option>-r</option> deletes the users home directory.
Accounts can be modified using <command>usermod</command>. Unix

View file

@ -41,13 +41,13 @@ If you are using WPA2 the <command>wpa_passphrase</command> tool might be useful
to generate the <literal>wpa_supplicant.conf</literal>.
<screen>
$ wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf</screen>
# wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf</screen>
After you have edited the <literal>wpa_supplicant.conf</literal>,
you need to restart the wpa_supplicant service.
<screen>
$ systemctl restart wpa_supplicant.service</screen>
# systemctl restart wpa_supplicant.service</screen>
</para>
</section>

View file

@ -5,7 +5,7 @@
xml:id="sec-x11">
<title>X Window System</title>
<para>The X Window System (X11) provides the basis of NixOS graphical
user interface. It can be enabled as follows:
<programlisting>
@ -48,7 +48,7 @@ services.xserver.autorun = false;
</programlisting>
The X server can then be started manually:
<screen>
$ systemctl start display-manager.service
# systemctl start display-manager.service
</screen>
</para>

View file

@ -25,8 +25,8 @@ $ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd
suggested by the following command:
<screen>
$ mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso</screen>
# mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso</screen>
</para>
</chapter>
</chapter>

View file

@ -94,8 +94,8 @@ $ nix-build -A 'config.systemd.units."httpd.service".unit'
<screen>
$ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \
/run/systemd/system/tmp-httpd.service
$ systemctl daemon-reload
$ systemctl start tmp-httpd.service
# systemctl daemon-reload
# systemctl start tmp-httpd.service
</screen>
Note that the unit must not have the same name as any unit in
@ -110,4 +110,4 @@ $ systemctl start tmp-httpd.service
</para>
</chapter>
</chapter>

View file

@ -70,7 +70,7 @@ sources, you need to tell <command>nixos-rebuild</command> about them
using the <option>-I</option> flag:
<screen>
$ nixos-rebuild switch -I nixpkgs=<replaceable>/my/sources</replaceable>/nixpkgs
# nixos-rebuild switch -I nixpkgs=<replaceable>/my/sources</replaceable>/nixpkgs
</screen>
</para>

View file

@ -12,16 +12,16 @@ properly:
<screen>
$ nix-build -A config.system.build.nixos-install
$ mount -t tmpfs none /mnt
$ ./result/bin/nixos-install</screen>
# mount -t tmpfs none /mnt
# ./result/bin/nixos-install</screen>
To start a login shell in the new NixOS installation in
<filename>/mnt</filename>:
<screen>
$ ./result/bin/nixos-install --chroot
# ./result/bin/nixos-install --chroot
</screen>
</para>
</chapter>
</chapter>

View file

@ -10,7 +10,7 @@ contains the current configuration of your machine. Whenever youve
changed something to that file, you should do
<screen>
$ nixos-rebuild switch</screen>
# nixos-rebuild switch</screen>
to build the new configuration, make it the default configuration for
booting, and try to realise the configuration in the running system
@ -23,7 +23,7 @@ either run them from a root shell or by prefixing them with
<para>You can also do
<screen>
$ nixos-rebuild test</screen>
# nixos-rebuild test</screen>
to build the configuration and switch the running system to it, but
without making it the boot default. So if (say) the configuration
@ -33,7 +33,7 @@ configuration.</para>
<para>There is also
<screen>
$ nixos-rebuild boot</screen>
# nixos-rebuild boot</screen>
to build the configuration and make it the boot default, but not
switch to it now (so it will only take effect after the next
@ -44,7 +44,7 @@ of the GRUB 2 boot screen by giving it a different <emphasis>profile
name</emphasis>, e.g.
<screen>
$ nixos-rebuild switch -p test </screen>
# nixos-rebuild switch -p test </screen>
which causes the new configuration (and previous ones created using
<literal>-p test</literal>) to show up in the GRUB submenu “NixOS -

View file

@ -5,7 +5,7 @@
xml:id="sec-uefi-installation">
<title>UEFI Installation</title>
<para>NixOS can also be installed on UEFI systems. The procedure
is by and large the same as a BIOS installation, with the following
changes:

View file

@ -54,7 +54,7 @@
changes. For example:
<screen>
$ mkfs.ext4 -L nixos /dev/sda1</screen>
# mkfs.ext4 -L nixos /dev/sda1</screen>
</para></listitem>
@ -66,10 +66,10 @@ $ mkfs.ext4 -L nixos /dev/sda1</screen>
<listitem><para>For creating LVM volumes, the LVM commands, e.g.,
<screen>
$ pvcreate /dev/sda1 /dev/sdb1
$ vgcreate MyVolGroup /dev/sda1 /dev/sdb1
$ lvcreate --size 2G --name bigdisk MyVolGroup
$ lvcreate --size 1G --name smalldisk MyVolGroup</screen>
# pvcreate /dev/sda1 /dev/sdb1
# vgcreate MyVolGroup /dev/sda1 /dev/sdb1
# lvcreate --size 2G --name bigdisk MyVolGroup
# lvcreate --size 1G --name smalldisk MyVolGroup</screen>
</para></listitem>
@ -84,7 +84,7 @@ $ lvcreate --size 1G --name smalldisk MyVolGroup</screen>
be installed on <filename>/mnt</filename>, e.g.
<screen>
$ mount /dev/disk/by-label/nixos /mnt
# mount /dev/disk/by-label/nixos /mnt
</screen>
</para></listitem>
@ -113,14 +113,14 @@ $ mount /dev/disk/by-label/nixos /mnt
generate an initial configuration file for you:
<screen>
$ nixos-generate-config --root /mnt</screen>
# nixos-generate-config --root /mnt</screen>
You should then edit
<filename>/mnt/etc/nixos/configuration.nix</filename> to suit your
needs:
<screen>
$ nano /mnt/etc/nixos/configuration.nix
# nano /mnt/etc/nixos/configuration.nix
</screen>
If youre using the graphical ISO image, other editors may be
@ -162,7 +162,7 @@ $ nano /mnt/etc/nixos/configuration.nix
<listitem><para>Do the installation:
<screen>
$ nixos-install</screen>
# nixos-install</screen>
Cross fingers. If this fails due to a temporary problem (such as
a network issue while downloading binaries from the NixOS binary
@ -186,7 +186,7 @@ Retype new UNIX password: ***
<listitem><para>If everything went well:
<screen>
$ reboot</screen>
# reboot</screen>
</para></listitem>
@ -235,15 +235,15 @@ drive (here <filename>/dev/sda</filename>). <xref linkend="ex-config"
<example xml:id='ex-install-sequence'><title>Commands for Installing NixOS on <filename>/dev/sda</filename></title>
<screen>
$ fdisk /dev/sda # <lineannotation>(or whatever device you want to install on)</lineannotation>
$ mkfs.ext4 -L nixos /dev/sda1
$ mkswap -L swap /dev/sda2
$ swapon /dev/sda2
$ mount /dev/disk/by-label/nixos /mnt
$ nixos-generate-config --root /mnt
$ nano /mnt/etc/nixos/configuration.nix
$ nixos-install
$ reboot</screen>
# fdisk /dev/sda # <lineannotation>(or whatever device you want to install on)</lineannotation>
# mkfs.ext4 -L nixos /dev/sda1
# mkswap -L swap /dev/sda2
# swapon /dev/sda2
# mount /dev/disk/by-label/nixos /mnt
# nixos-generate-config --root /mnt
# nano /mnt/etc/nixos/configuration.nix
# nixos-install
# reboot</screen>
</example>
<example xml:id='ex-config'><title>NixOS Configuration</title>

View file

@ -60,33 +60,33 @@ the <literal>nixos-14.12</literal> channel. To see which NixOS
channel youre subscribed to, run the following as root:
<screen>
$ nix-channel --list | grep nixos
# nix-channel --list | grep nixos
nixos https://nixos.org/channels/nixos-unstable
</screen>
To switch to a different NixOS channel, do
<screen>
$ nix-channel --add https://nixos.org/channels/<replaceable>channel-name</replaceable> nixos
# nix-channel --add https://nixos.org/channels/<replaceable>channel-name</replaceable> nixos
</screen>
(Be sure to include the <literal>nixos</literal> parameter at the
end.) For instance, to use the NixOS 14.12 stable channel:
<screen>
$ nix-channel --add https://nixos.org/channels/nixos-14.12 nixos
# nix-channel --add https://nixos.org/channels/nixos-14.12 nixos
</screen>
If you have a server, you may want to use the “small” channel instead:
<screen>
$ nix-channel --add https://nixos.org/channels/nixos-14.12-small nixos
# nix-channel --add https://nixos.org/channels/nixos-14.12-small nixos
</screen>
And if you want to live on the bleeding edge:
<screen>
$ nix-channel --add https://nixos.org/channels/nixos-unstable nixos
# nix-channel --add https://nixos.org/channels/nixos-unstable nixos
</screen>
</para>
@ -95,7 +95,7 @@ $ nix-channel --add https://nixos.org/channels/nixos-unstable nixos
channel by running
<screen>
$ nixos-rebuild switch --upgrade
# nixos-rebuild switch --upgrade
</screen>
which is equivalent to the more verbose <literal>nix-channel --update

View file

@ -1,7 +1,7 @@
<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refmeta>
<refentrytitle><filename>configuration.nix</filename></refentrytitle>
<manvolnum>5</manvolnum>
@ -34,5 +34,5 @@ therein.</para>
<xi:include href="options-db.xml" />
</refsection>
</refentry>

View file

@ -1,7 +1,7 @@
<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refmeta>
<refentrytitle><command>nixos-build-vms</command></refentrytitle>
<manvolnum>8</manvolnum>
@ -42,10 +42,10 @@ points to the generated virtual network.
services.openssh.enable = true;
nixpkgs.system = "i686-linux";
deployment.targetHost = "test1.example.net";
# Other NixOS options
};
test2 = {pkgs, config, ...}:
{
services.openssh.enable = true;
@ -53,7 +53,7 @@ points to the generated virtual network.
environment.systemPackages = [ pkgs.lynx ];
nixpkgs.system = "x86_64-linux";
deployment.targetHost = "test2.example.net";
# Other NixOS options
};
}

View file

@ -1,7 +1,7 @@
<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refmeta>
<refentrytitle><command>nixos-option</command></refentrytitle>
<manvolnum>8</manvolnum>
@ -64,7 +64,7 @@ $ nixos-option boot.loader.grub.enable
Value:
true
Default:
Default:
true
Description:

View file

@ -3,7 +3,7 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="book-nixos-manual">
<info>
<title>NixOS Manual</title>
<subtitle>Version <xi:include href="version" parse="text" /></subtitle>
@ -26,6 +26,9 @@
xlink:href="https://github.com/NixOS/nixpkgs/issues">NixOS GitHub
issue tracker</link>.</para>
<note>Commands prefixed with <literal>#</literal> have to be run as
root, either requiring to login as root user or temporarily switching
to it using <literal>sudo</literal> for example.</note>
</preface>
<xi:include href="installation/installation.xml" />