Merge branch 'nginx:main' into patch-1

kedartal · web-flow · commit f1d8fc112acd · 2025-07-01T12:08:17.000-04:00
diff --git a/source/CHANGES.txt b/source/CHANGES.txt
@@ -1,3 +1,20 @@
+Changes with Unit 1.34.2                                         26 Feb 2025
+
+    *) Security: fix missing websocket payload length validation in the Java
+       language module which could lead to Java language module processes
+       consuming excess CPU. (CVE-2025-1695).
+
+    *) Bugfix: fix incorrect websocket payload length calculation in the
+       Java language module.
+
+
+Changes with Unit 1.34.1                                         10 Jan 2025
+
+    *) Bugfix: fix instability issues due to OpenTelemetry (OTEL) support.
+
+    *) Bugfix: fix issues with building OpenTelemetry (OTEL) support on
+       various platforms, including macOS.
+
 
 Changes with Unit 1.34.0                                         19 Dec 2024
 
diff --git a/source/certificates.rst b/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
 
diff --git a/source/community.rst b/source/community.rst
@@ -8,18 +8,28 @@
 Community
 #########
 
-************************
-Meetings and discussions
-************************
+**********************************
+Maintenance and support guidelines
+**********************************
 
-We hold semi-regular meetings on Zoom
-to discuss all things related to Unit
-with our tightly knit and vibrant community.
+Going forward, NGINX Unit will no longer receive new features or
+enhancements from the project maintainers. NGINX Unit is still open to
+community contributions.
 
-Recorded sessions:
+The team is focusing its limited capacity to keep NGINX Unit stable,
+secure and high-quality. Its focus will be on critical maintenance, such
+as for security issues, dependency upgrades, and resolving crashes or
+undefined behavior.
 
-- `NGINX Unit Community Call No.1
-  <https://www.youtube.com/watch?v=EZbcc6D03Io>`__
+************
+Discuss Unit
+************
+
+The `Discussions section <https://github.com/nginx/unit/discussions>`_ of the
+Unit repo is the main place for discussing any topics related to the NGINX Unit project.
+
+Here you can share your ideas, ask questions, and discuss any issues both about
+using Unit and contributing to Unit.
 
 *************************
 Reporting bugs and issues
@@ -60,6 +70,10 @@ You can also ask questions and discuss your suggestions for Unit by:
 - Subscribing to the `unit@nginx.org mailing list <https://mailman.nginx.org/mailman3/lists/unit.nginx.org/>`_
   and posting your ideas there.
 
+*************
+Documentation
+*************
+
 If you are interested in contributing to the **Unit documentation**,
 or find a typo or an error in the docs, you can submit a pull request on the
 `unit-docs repo <https://github.com/nginx/unit-docs/pulls>`_.
diff --git a/source/conf.py b/source/conf.py
@@ -5,8 +5,8 @@
 project = 'NGINX Unit'
 author = 'NGINX, Inc.'
 copyright = '2017-2025'
-version = '1.34.0'
-release_date = 'Dec 19, 2024'
+version = '1.34.2'
+release_date = 'Feb 26, 2025'
 release = version
 needs_sphinx = '6.2'
 
diff --git a/source/configuration/index.rst b/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
 #############
diff --git a/source/controlapi.rst b/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
 
diff --git a/source/howto/apollo.rst b/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
 
diff --git a/source/howto/certbot.rst b/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
 ***********************
diff --git a/source/howto/express.rst b/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
diff --git a/source/howto/grafana.rst b/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
 
diff --git a/source/howto/koa.rst b/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
diff --git a/source/howto/mailman.rst b/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
 
diff --git a/source/howto/mediawiki.rst b/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
 
diff --git a/source/howto/modules.rst b/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:
 
 *************************
diff --git a/source/howto/nextcloud.rst b/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
 
diff --git a/source/howto/roundcube.rst b/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
 
diff --git a/source/howto/samples.rst b/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:
 
 **
diff --git a/source/howto/security.rst b/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:
 
diff --git a/source/howto/source.rst b/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:
 
 ============================
diff --git a/source/include/howto_change_ownership.rst b/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>`:
 
diff --git a/source/include/howto_upload_config.rst b/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
 
diff --git a/source/installation.rst b/source/installation.rst
diff --git a/source/news.rst b/source/news.rst
diff --git a/source/news/2024/index.rst b/source/news/2024/index.rst
diff --git a/source/news/2025/index.rst b/source/news/2025/index.rst
diff --git a/source/news/2025/unit-1.34.1-released.rst b/source/news/2025/unit-1.34.1-released.rst
diff --git a/source/news/2025/unit-1.34.2-released.rst b/source/news/2025/unit-1.34.2-released.rst
diff --git a/source/scripting.rst b/source/scripting.rst
diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst
