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

nixos/doc/manual/administration/cleaning-store.xml

@@ -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

nixos/doc/manual/administration/container-networking.xml

@@ -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

nixos/doc/manual/administration/imperative-containers.xml

@@ -11,7 +11,7 @@
 identifier <literal>foo</literal> as follows:
 
 <screen>
-$ nixos-container create foo
+# nixos-container create foo
 </screen>
 
 This creates the container’s 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,7 +116,7 @@ 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>

nixos/doc/manual/administration/maintenance-mode.xml

@@ -9,7 +9,7 @@
 <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,

nixos/doc/manual/administration/network-problems.xml

@@ -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>

nixos/doc/manual/administration/rebooting.xml

@@ -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>

nixos/doc/manual/administration/rollback.xml

@@ -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:

nixos/doc/manual/administration/service-mgmt.xml

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

nixos/doc/manual/administration/store-corruption.xml

@@ -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,7 +28,7 @@ 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 they’re available in a

nixos/doc/manual/administration/user-sessions.xml

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

nixos/doc/manual/configuration/adding-custom-packages.xml

@@ -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>
 

nixos/doc/manual/configuration/linux-kernel.xml

@@ -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>

nixos/doc/manual/configuration/luks-file-systems.xml

@@ -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

nixos/doc/manual/configuration/user-mgmt.xml

@@ -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 user’s home directory.
 Accounts can be modified using <command>usermod</command>.  Unix

nixos/doc/manual/configuration/wireless.xml

@@ -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>

nixos/doc/manual/configuration/x-windows.xml

@@ -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>
 

nixos/doc/manual/development/building-nixos.xml

@@ -25,7 +25,7 @@ $ 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>
 

nixos/doc/manual/development/building-parts.xml

@@ -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 daemon-reload
-$ systemctl start tmp-httpd.service
+# systemctl start tmp-httpd.service
 </screen>
 
       Note that the unit must not have the same name as any unit in

nixos/doc/manual/development/sources.xml

@@ -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>

nixos/doc/manual/development/testing-installer.xml

@@ -12,14 +12,14 @@ properly:
 
 <screen>
 $ nix-build -A config.system.build.nixos-install
-$ mount -t tmpfs none /mnt
+# mount -t tmpfs none /mnt
-$ ./result/bin/nixos-install</screen>
+# ./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>

nixos/doc/manual/installation/changing-config.xml

@@ -10,7 +10,7 @@ contains the current configuration of your machine.  Whenever you’ve
 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 -

nixos/doc/manual/installation/installing.xml

@@ -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
+# pvcreate /dev/sda1 /dev/sdb1
-$ vgcreate MyVolGroup /dev/sda1 /dev/sdb1
+# vgcreate MyVolGroup /dev/sda1 /dev/sdb1
-$ lvcreate --size 2G --name bigdisk MyVolGroup
+# lvcreate --size 2G --name bigdisk MyVolGroup
-$ lvcreate --size 1G --name smalldisk MyVolGroup</screen>
+# 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 you’re 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>
+# fdisk /dev/sda # <lineannotation>(or whatever device you want to install on)</lineannotation>
-$ mkfs.ext4 -L nixos /dev/sda1
+# mkfs.ext4 -L nixos /dev/sda1
-$ mkswap -L swap /dev/sda2
+# mkswap -L swap /dev/sda2
-$ swapon /dev/sda2
+# swapon /dev/sda2
-$ mount /dev/disk/by-label/nixos /mnt
+# mount /dev/disk/by-label/nixos /mnt
-$ nixos-generate-config --root /mnt
+# nixos-generate-config --root /mnt
-$ nano /mnt/etc/nixos/configuration.nix
+# nano /mnt/etc/nixos/configuration.nix
-$ nixos-install
+# nixos-install
-$ reboot</screen>
+# reboot</screen>
 </example>
 
 <example xml:id='ex-config'><title>NixOS Configuration</title>

nixos/doc/manual/installation/upgrading.xml

@@ -60,33 +60,33 @@ the <literal>nixos-14.12</literal> channel.  To see which NixOS
 channel you’re 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

nixos/doc/manual/manual.xml

@@ -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" />