From d3b654cde57c0f0615c7f316e79b552b54ea09d5 Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Wed, 13 May 2026 15:54:12 +0200 Subject: [PATCH 1/4] docs(updater): document --url option for offline/air-gapped installs Covers --url (HTTP/HTTPS and file://), --signature for providing a base64 archive signature, --no-verify as escape hatch, and combining all three with --no-interaction for automated runs. Signed-off-by: skjnldsv --- admin_manual/maintenance/update.rst | 62 +++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/admin_manual/maintenance/update.rst b/admin_manual/maintenance/update.rst index 01e233d0b28..f156b83a5b8 100644 --- a/admin_manual/maintenance/update.rst +++ b/admin_manual/maintenance/update.rst @@ -239,6 +239,68 @@ 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 (offline / air-gapped installs) +------------------------------------------------------------ + +By default the updater fetches the Nextcloud release archive from the official +download servers. In environments without internet access — or when you want to +serve the archive from an internal mirror — you can point the updater at any +HTTP/HTTPS URL with the ``--url`` option: + +.. code-block:: bash + + sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar \ + --url https://mirror.example.com/nextcloud-30.0.0.tar.bz2 + +For local file access you can use a ``file://`` URL: + +.. code-block:: bash + + sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar \ + --url file:///tmp/nextcloud-30.0.0.tar.bz2 + +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-30.0.0.tar.bz2 \ + --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-30.0.0.tar.bz2 \ + --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 +offline update runs: + +.. code-block:: bash + + sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar \ + --url file:///tmp/nextcloud-30.0.0.tar.bz2 \ + --signature "BASE64_SIGNATURE_HERE" \ + --no-interaction + Troubleshooting --------------- From e2e175373c06bc872f1a3e874e79594f80120b02 Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Wed, 13 May 2026 15:57:01 +0200 Subject: [PATCH 2/4] docs(updater): document --url option for custom download URL Covers pinning a specific version, internal mirrors, and offline/ air-gapped use via file://. Includes --signature and --no-verify options with appropriate warnings. Warns explicitly that downgrading and skipping major versions remain unsupported regardless of --url usage. Signed-off-by: skjnldsv --- admin_manual/maintenance/update.rst | 31 +++++++++++++++++++++-------- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/admin_manual/maintenance/update.rst b/admin_manual/maintenance/update.rst index f156b83a5b8..2f378c2c189 100644 --- a/admin_manual/maintenance/update.rst +++ b/admin_manual/maintenance/update.rst @@ -239,20 +239,35 @@ 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 (offline / air-gapped installs) ------------------------------------------------------------- +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** and risks data corruption. + * **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. -By default the updater fetches the Nextcloud release archive from the official -download servers. In environments without internet access — or when you want to -serve the archive from an internal mirror — you can point the updater at any -HTTP/HTTPS URL with the ``--url`` option: +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://mirror.example.com/nextcloud-30.0.0.tar.bz2 -For local file access you can use a ``file://`` URL: +For a locally staged archive, use a ``file://`` URL: .. code-block:: bash @@ -292,7 +307,7 @@ automatically. You have two options: when the archive comes from a fully trusted, controlled source. These options can be combined with ``--no-interaction`` for fully automated -offline update runs: +runs: .. code-block:: bash From 8eb1bd4d1b4b4cd64deaa9242d4b0eabb2023bc3 Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Wed, 13 May 2026 15:57:39 +0200 Subject: [PATCH 3/4] docs(updater): use real download URL in --url examples Signed-off-by: skjnldsv --- admin_manual/maintenance/update.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/admin_manual/maintenance/update.rst b/admin_manual/maintenance/update.rst index 2f378c2c189..f5104d118f7 100644 --- a/admin_manual/maintenance/update.rst +++ b/admin_manual/maintenance/update.rst @@ -265,14 +265,14 @@ 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://mirror.example.com/nextcloud-30.0.0.tar.bz2 + --url https://download.nextcloud.com/server/releases/nextcloud-33.0.0.zip 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-30.0.0.tar.bz2 + --url file:///tmp/nextcloud-33.0.0.zip Signature verification ~~~~~~~~~~~~~~~~~~~~~~ @@ -288,7 +288,7 @@ automatically. You have two options: .. code-block:: bash sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar \ - --url file:///tmp/nextcloud-30.0.0.tar.bz2 \ + --url file:///tmp/nextcloud-33.0.0.zip \ --signature "BASE64_SIGNATURE_HERE" * **Skip verification** — pass ``--no-verify`` to disable integrity checking @@ -298,7 +298,7 @@ automatically. You have two options: .. code-block:: bash sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar \ - --url file:///tmp/nextcloud-30.0.0.tar.bz2 \ + --url file:///tmp/nextcloud-33.0.0.zip \ --no-verify .. warning:: @@ -312,7 +312,7 @@ runs: .. code-block:: bash sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar \ - --url file:///tmp/nextcloud-30.0.0.tar.bz2 \ + --url file:///tmp/nextcloud-33.0.0.zip \ --signature "BASE64_SIGNATURE_HERE" \ --no-interaction From dc0413e438793c467a9c9196153adfc9ba17bc3e Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Wed, 13 May 2026 16:01:34 +0200 Subject: [PATCH 4/4] docs(updater): note file:// URL support requires Nextcloud 34 Signed-off-by: skjnldsv --- admin_manual/maintenance/update.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/admin_manual/maintenance/update.rst b/admin_manual/maintenance/update.rst index f5104d118f7..932ca85c131 100644 --- a/admin_manual/maintenance/update.rst +++ b/admin_manual/maintenance/update.rst @@ -254,7 +254,7 @@ Common use cases: .. warning:: The normal update rules still apply when using ``--url``: - * **Downgrading is not supported** and risks data corruption. + * **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). @@ -267,6 +267,9 @@ Point the updater at any HTTP/HTTPS URL: 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