Merge pull request #188 from nginx/issue-171

docs: add notes about root requirements for commands

Author: JTorreG

source/certificates.rst

@@ -39,7 +39,7 @@ order them leaf to root.
 
 Upload the resulting bundle file to Unit's certificate storage
 under a suitable name
-(in this case, **bundle**):
+(in this case, **bundle**), running the following command as root:
 
 .. code-block:: console
 
@@ -127,7 +127,7 @@ as **GET**-table JSON using **/certificates**:
 
    Access array items,
    such as individual certificates in a chain,
-   and their properties by indexing:
+   and their properties by indexing, running the following commands as root:
 
    .. code-block:: console
 
@@ -196,7 +196,7 @@ the application is now accessible via SSL/TLS:
 
 Finally, you can delete a certificate bundle
 that you don't need anymore
-from the storage:
+from the storage, running the following command as root:
 
 .. code-block:: console
 

source/configuration/index.rst

@@ -4,6 +4,10 @@
 
 .. include:: ../include/replace.rst
 
+.. note::
+   The commands in this document starting with a hash (#) must be run as root or
+   with superuser privileges.
+
 #############
 Configuration
 #############

source/controlapi.rst

@@ -130,7 +130,7 @@ may benefit from this
    Repeat these commands on the second machine
    to see where the target instance stores its state.
 
-   Stop both Unit instances, for example:
+   Stop both Unit instances, for example, running the following command as root:
 
    .. code-block:: console
 
@@ -147,7 +147,7 @@ may benefit from this
    Copy the reference state directory to the target state directory
    by arbitrary means;
    make sure to include subdirectories and hidden files.
-   Finally, restart both Unit instances:
+   Finally, restart both Unit instances running the following command as root:
 
    .. code-block:: console
 
@@ -205,6 +205,10 @@ OpenAPI specification
 Quick start
 ***********
 
+
+.. note::
+   Run the `curl` commands in this section as root.
+
 For a brief intro,
 we configure Unit to serve a static file.
 Suppose you saved this as **/www/data/index.html**:
@@ -264,7 +268,7 @@ To configure Unit,
 **PUT** this snippet to the **/config** section via the
 :ref:`control socket <source-startup>`.
 Working with JSON in the command line can be cumbersome;
-instead, save and upload it as **snippet.json**:
+instead, save and upload it as **snippet.json**.
 
 .. code-block:: console
 
@@ -362,7 +366,7 @@ connections are properly closed,
 processes end smoothly.
 
 Any type of update can be done with different URIs,
-provided you supply the right JSON:
+provided you supply the right JSON. Run the following commands as root:
 
 .. code-block:: console
 
@@ -400,7 +404,7 @@ For instance, save your application object as **wiki.json**:
        "path": "/www/wiki/"
    }
 
-Use it to set up an application called **wiki-prod**:
+Use it to set up an application called **wiki-prod**.
 
 .. code-block:: console
 

source/howto/apollo.rst

@@ -10,15 +10,16 @@ using Unit:
 
 #. Install :ref:`Unit <installation-precomp-pkgs>` with the
    **unit-dev/unit-devel** package.  Next, :ref:`install
-   <installation-nodejs-package>` Unit's **unit-http** package:
+   <installation-nodejs-package>` Unit's **unit-http** package. Run the following
+   command as root:
 
    .. code-block:: console
 
       # npm install -g --unsafe-perm unit-http
 
 #. Create your app directory, `install
    <https://expressjs.com/en/starter/installing.html>`_ |app|, and link
-   **unit-http**:
+   **unit-http**. Run the commands starting with a hash (#) as root:
 
    .. code-block:: console
 

source/howto/certbot.rst

@@ -9,6 +9,10 @@ advisable to obtain certificates for your website from a certificate authority
 <https://certbot.eff.org>`__ that issues free certificates signed by `Let's
 Encrypt <https://letsencrypt.org>`_, a non-profit CA.
 
+.. note::
+   The commands in this document starting with a hash (#) must be run as root or
+   with superuser privileges.
+
 ***********************
 Generating Certificates
 ***********************

source/howto/express.rst

@@ -10,7 +10,8 @@ using Unit:
 
 #. Install :ref:`Unit <installation-precomp-pkgs>` with the
    **unit-dev/unit-devel** package.  Next, :ref:`install
-   <installation-nodejs-package>` Unit's **unit-http** package:
+   <installation-nodejs-package>` Unit's **unit-http** package. Run the following
+   command as root:
 
    .. code-block:: console
 
@@ -32,6 +33,8 @@ using Unit:
 
       $ npm install express --save
 
+   Run the following command as root:
+
    .. code-block:: console
 
       # npm link unit-http

source/howto/grafana.rst

@@ -134,7 +134,7 @@ so we can :ref:`configure it <configuration-go>` to run on Unit.
    usually **$GOPATH/bin/**; it's used for the **executable** option in
    the Unit configuration.
 
-#. Run the following commands so Unit can access |app|'s files:
+#. Run the following commands (as root) so Unit can access |app|'s files:
 
    .. code-block:: console
 

source/howto/koa.rst

@@ -9,7 +9,8 @@ To run apps built with the `Koa <https://koajs.com>`_ web framework using Unit:
 
 #. Install :ref:`Unit <installation-precomp-pkgs>` with the
    **unit-dev/unit-devel** package.  Next, :ref:`install
-   <installation-nodejs-package>` Unit's **unit-http** package:
+   <installation-nodejs-package>` Unit's **unit-http** package. Run the following
+   command as root:
 
    .. code-block:: console
 
@@ -30,6 +31,8 @@ To run apps built with the `Koa <https://koajs.com>`_ web framework using Unit:
 
       $ npm install koa
 
+   Run the following command as root:
+
    .. code-block:: console
 
       # npm link unit-http

source/howto/mailman.rst

@@ -25,7 +25,7 @@ To install and run the web UI for the `Mailman 3
 
    These are needed to configure Unit.
 
-#. Run the following command so Unit can access |app|'s static files:
+#. Run the following command (as root) so Unit can access |app|'s static files:
 
    .. code-block:: console
 
@@ -39,7 +39,7 @@ To install and run the web UI for the `Mailman 3
       run the :program:`ps aux | grep unitd` command to be sure.
 
    Alternatively, add Unit's unprivileged user account to |app|'s group so Unit
-   can access the static files:
+   can access the static files. Run the following command as root:
 
    .. code-block:: console
 

source/howto/mediawiki.rst

@@ -138,6 +138,8 @@ documentation platform using Unit:
 
       $ chmod 600 LocalSettings.php
 
+   Run the following commands (as root) to set the correct ownership:
+
    .. code-block:: console
 
       # chown :nxt_ph:`unit:unit <Values from Step 3>` LocalSettings.php
@@ -147,7 +149,7 @@ documentation platform using Unit:
       # mv LocalSettings.php :nxt_ph:`/path/to/app/ <Path to the application directory; use a real path in your configuration>`
 
 #. After installation, add a match condition to the first step to disable
-   access to the **mw-config/** directory:
+   access to the **mw-config/** directory. Run the following command (as root):
 
    .. code-block:: console
 

source/howto/modules.rst

@@ -14,6 +14,10 @@ Languages supported by Unit fall into these two categories:
 
 For any specific language and its version, Unit needs a language module.
 
+.. note::
+   The commands in this document starting with a hash (#) must be run as root or
+   with superuser privileges.
+
 .. _modules-ext:
 
 *************************

source/howto/nextcloud.rst

@@ -180,7 +180,8 @@ platform using Unit:
 #. .. include:: ../include/howto_upload_config.rst
 
 #. Adjust Unit's **max_body_size** :ref:`option <configuration-stngs>` to
-   avoid potential issues with large file uploads, for example:
+   avoid potential issues with large file uploads, for example, runnig the
+   following command as root:
 
    .. code-block:: console
 

source/howto/roundcube.rst

@@ -71,7 +71,7 @@ To run the `Roundcube <https://roundcube.net>`_ webmail platform using Unit:
 #. After installation, switch **share** and **root** to the
    **public_html/** subdirectory to `protect
    <https://github.com/roundcube/roundcubemail/wiki/Installation#protect-your-installation>`__
-   sensitive data:
+   sensitive data, run the following command as root:
 
    .. code-block:: console
 

source/howto/samples.rst

@@ -7,6 +7,9 @@ App Samples
    These steps assume Unit was already :ref:`installed
    <installation-precomp-pkgs>` with the language module for each app.
 
+   The commands in this document starting with a hash (#) must be run as root or
+   with superuser privileges.
+
 .. _sample-go:
 
 **

source/howto/security.rst

@@ -9,6 +9,9 @@ configuration, and maintenance.
 This guide lists the steps to protect your Unit from installation to individual
 app configuration.
 
+.. note::
+   The commands in this document starting with a hash (#) must be run as root or
+   with superuser privileges.
 
 .. _security-update:
 

source/howto/source.rst

@@ -7,6 +7,10 @@ Building From Source
 After you've obtained Unit's :ref:`source code <source>`, configure
 and compile it to fine-tune and run a custom Unit build.
 
+.. note::
+   The commands in this document starting with a hash (#) must be run as root or
+   with superuser privileges.
+
 .. _source-prereq-build:
 
 ============================

source/include/howto_change_ownership.rst

@@ -1,4 +1,4 @@
-Run the following command so Unit can access :nxt_hint:`the application
+Run the following command (as root) so Unit can access :nxt_hint:`the application
 directory <If the application uses several directories, run the command for
 each one>`:
 

source/include/howto_upload_config.rst

@@ -1,5 +1,5 @@
 Upload the updated configuration.  Assuming the JSON above was added to
-:file:`config.json`:
+:file:`config.json`. Run the following command as root:
 
 .. code-block:: console
 

source/installation.rst

@@ -30,6 +30,10 @@ You can install NGINX Unit in four alternative ways:
   and :ref:`build <source-config-src>` a custom binary from scratch;
   just make sure you know what you're doing.
 
+.. note::
+   The commands in this document starting with a hash (#) must be run as root or
+   with superuser privileges.
+
 
 .. _source-prereqs:
 

source/scripting.rst

@@ -151,15 +151,16 @@ by their **Authorization** header field values:
    export default http
 
 To upload it to Unit's JavaScript module storage
-as **http**:
+as **http**, run the following command as root:
 
 .. code-block:: console
 
    # curl -X PUT --data-binary @http.js --unix-socket :nxt_ph:`/path/to/control.unit.sock <Path to the remote control socket>` \
          http://localhost/js_modules/:nxt_ph:`http <Module name in Unit's configuration>`
 
 Unit doesn't enable the uploaded modules by default,
-so add the module's name to **settings/js_module**:
+so add the module's name to **settings/js_module** running the following command
+as root:
 
 .. code-block:: console
 

source/troubleshooting.rst

@@ -9,6 +9,10 @@
 Troubleshooting
 ###############
 
+.. note::
+   The commands in this document starting with a hash (#) must be run as root or
+   with superuser privileges.
+
 .. _troubleshooting-log:
 
 *******