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

···
 background:
 
 <screen>
-$ systemctl start nix-gc.service
+# systemctl start nix-gc.service
 </screen>
 
 You can tell NixOS in <filename>configuration.nix</filename> to run
···
 Since this command needs to read the entire Nix store, it can take
 quite a while to finish.</para>
 
-</chapter>
+</chapter>

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

···
 address as follows:
 
 <screen>
-$ nixos-container show-ip foo
+# nixos-container show-ip foo
 10.233.4.2
 
 $ ping -c1 10.233.4.2
···
 external interface. Note that <literal>ve-+</literal> is a wildcard
 that matches all container interfaces.</para>
 
-</section>
+</section>

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

···
 identifier <literal>foo</literal> as follows:
 
 <screen>
-$ nixos-container create foo
+# nixos-container create foo
 </screen>
 
 This creates the container’s root directory in
···
 <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>
 
···
 run:
 
 <screen>
-$ nixos-container start foo
+# nixos-container start foo
 </screen>
 
 This command will return as soon as the container has booted and has
···
 <command>systemctl</command>:
 
 <screen>
-$ systemctl status container@foo
+# systemctl status container@foo
 </screen>
 
 </para>
···
 root using the <command>root-login</command> operation:
 
 <screen>
-$ nixos-container root-login foo
+# nixos-container root-login foo
 [root@foo:~]#
 </screen>
 
···
 the host:
 
 <screen>
-$ nixos-container login foo
+# nixos-container login foo
 foo login: alice
 Password: ***
 </screen>
···
 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>
 
···
 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 = "[e-mail]";'
 
-$ 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>
 
···
 destroy a container, including its file system, do
 
 <screen>
-$ nixos-container destroy foo
+# nixos-container destroy foo
 </screen>
 
 </para>
 
-</section>
+</section>

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

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

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

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

···
 doing:
 
 <screen>
-$ shutdown
+# shutdown
 </screen>
 
 This is equivalent to running <command>systemctl
···
 <para>To reboot the system, run
 
 <screen>
-$ reboot
+# reboot
 </screen>
 
 which is equivalent to <command>systemctl reboot</command>.
···
 the new kernel into memory:
 
 <screen>
-$ systemctl kexec
+# systemctl kexec
 </screen>
 
 </para>
···
 i.e. on a virtual console or in X11; otherwise, the user is asked for
 authentication.</para>
 
-</chapter>
+</chapter>

nixos/doc/manual/administration/rollback.xml

···
 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>
 
···
 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:
···
 
 </para>
 
-</section>
+</section>

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

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

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

···
 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
···
 <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
 binary cache; otherwise, they cannot be repaired.</para>
 
-</section>
+</section>

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

···
 all the session’s processes are gone:
 
 <screen>
-$ loginctl terminate-session c3
+# loginctl terminate-session c3
 </screen>
 
 </para>
 
-</chapter>
+</chapter>

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

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

···
 $ 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

···
 <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!
 ========
···
 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

···
 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
···
 be set using the <command>passwd</command> utility:
 
 <screen>
-$ passwd alice
+# passwd alice
 Enter new UNIX password: ***
 Retype new UNIX password: ***
 </screen>
···
 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

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

···
          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>
···
 </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

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

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

···
 <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
···
 
 </para>
 
-</chapter>
+</chapter>

nixos/doc/manual/development/sources.xml

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

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

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

···
 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
···
 <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
···
 <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
···
 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-uefi.xml

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

nixos/doc/manual/installation/installing.xml

···
     changes.  For example:
 
 <screen>
-$ mkfs.ext4 -L nixos /dev/sda1</screen>
+# mkfs.ext4 -L nixos /dev/sda1</screen>
 
     </para></listitem>
 
···
     <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>
 
···
   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>
···
     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
···
   <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
···
   <listitem><para>If everything went well:
 
 <screen>
-$ reboot</screen>
+# reboot</screen>
 
   </para></listitem>
 
···
 
 <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>

nixos/doc/manual/installation/upgrading.xml

···
 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>
···
 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/man-configuration.xml

···
 <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>
···
 <xi:include href="options-db.xml" />
 
 </refsection>
-  
+
 </refentry>

nixos/doc/manual/man-nixos-build-vms.xml

···
 <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>
···
       services.openssh.enable = true;
       nixpkgs.system = "i686-linux";
       deployment.targetHost = "test1.example.net";
-      
+
       # Other NixOS options
     };
-    
+
   test2 = {pkgs, config, ...}:
     {
       services.openssh.enable = true;
···
       environment.systemPackages = [ pkgs.lynx ];
       nixpkgs.system = "x86_64-linux";
       deployment.targetHost = "test2.example.net";
-      
+
       # Other NixOS options
     };
 }

nixos/doc/manual/man-nixos-option.xml

···
 <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>
···
 Value:
 true
 
-Default: 
+Default:
 true
 
 Description:

nixos/doc/manual/manual.xml

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