docs(updater): document --url option for offline/air-gapped installs

admin_manual/maintenance/update.rst

@@ -239,6 +239,86 @@ To execute this, run the command with the ``--no-interaction`` option. (i.e.
    :alt: Terminal showing Nextcloud command line updater running in non-interactive batch mode
    :class: terminal-image
 
+Using a custom download URL
+---------------------------
+
+The ``--url`` option lets you override the archive the updater downloads.
+Common use cases:
+
+* **Pinning a specific version** — install an exact patch release rather than
+  whatever the update check resolves to.
+* **Internal mirrors** — serve the archive from a company mirror or proxy.
+* **Offline / air-gapped environments** — stage the archive locally and
+  supply it via a ``file://`` URL.
+
+.. warning::
+   The normal update rules still apply when using ``--url``:
+
+   * **Downgrading is not supported**.
+   * **Skipping major versions is not supported.** You must update one major
+     version at a time (e.g. 28 → 29 → 30, not 28 → 30).
+
+   Passing ``--url`` does not bypass these constraints.
+
+Point the updater at any HTTP/HTTPS URL:
+
+.. code-block:: bash
+
+    sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar \
+        --url https://download.nextcloud.com/server/releases/nextcloud-33.0.0.zip
+
+
+.. versionadded:: 34
+
+For a locally staged archive, use a ``file://`` URL:
+
+.. code-block:: bash
+
+    sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar \
+        --url file:///tmp/nextcloud-33.0.0.zip
+
+Signature verification
+~~~~~~~~~~~~~~~~~~~~~~
+
+When ``--url`` is used the updater cannot look up the official signature
+automatically. You have two options:
+
+* **Provide the signature** — pass the base64-encoded signature with
+  ``--signature``. You can get the signature from
+  https://nextcloud.com/changelog/ or from the same mirror that hosts the
+  archive:
+
+  .. code-block:: bash
+
+      sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar \
+          --url file:///tmp/nextcloud-33.0.0.zip \
+          --signature "BASE64_SIGNATURE_HERE"
+
+* **Skip verification** — pass ``--no-verify`` to disable integrity checking
+  entirely. Only do this if you fully trust the source of the archive and the
+  transfer channel:
+
+  .. code-block:: bash
+
+      sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar \
+          --url file:///tmp/nextcloud-33.0.0.zip \
+          --no-verify
+
+.. warning::
+   Skipping signature verification (``--no-verify``) removes the integrity
+   check that protects against corrupted or tampered archives. Only use it
+   when the archive comes from a fully trusted, controlled source.
+
+These options can be combined with ``--no-interaction`` for fully automated
+runs:
+
+.. code-block:: bash
+
+    sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar \
+        --url file:///tmp/nextcloud-33.0.0.zip \
+        --signature "BASE64_SIGNATURE_HERE" \
+        --no-interaction
+
 Troubleshooting
 ---------------