nextcloud / nextcloud/server

Add a dedicated DNS‐resolution health check and admin warning for DNS failures

Open
#53,668 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

0. Needs triage enhancement feature: settings
Dominant language
PHP
Stars
36.9k
Forks
5.2k
Avg merge
2d 3h
Merged PRs (30d)
713

Description

Description

Nextcloud currently assumes that the host’s DNS resolver is functional and only surfaces DNS‐related errors indirectly (e.g. “Could not check that your web server can connect to itself”). In environments where DNS is misconfigured or temporarily unreachable, this can lead to severe performance degradation—pages hang until DNS timeouts expire—without any clear indication in the admin UI that DNS is the root cause.

I propose adding a dedicated DNS‐resolution health check to the Administration → Overview → Security & setup warnings page that:

  1. Attempts to resolve and connect to at least one of the trusted_domains or overwrite.cli.url entries.
  2. Optionally performs a lightweight resolution test against a well-known host (e.g. updates.nextcloud.org) to detect broader external DNS issues.
  3. Surfaces a clear warning (“Your server’s DNS resolution appears broken: Nextcloud will be very slow or non-functional until this is resolved.”) with guidance on how to fix common DNS misconfigurations.

Steps to reproduce

  1. Configure host or Docker daemon with invalid or unreachable DNS servers.
  2. Restart server (or container).
  3. Log in to Nextcloud and navigate to any page (login screen, file list, dashboard).
  4. Observe that pages may take 10+ seconds to load or time out entirely, and no DNS‐specific warning appears under Overview → Security & setup warnings.

Expected behavior

  • Nextcloud detects that the host’s DNS resolver is not working (via a quick lookup) and displays a prominent warning in the admin overview, calling out “DNS resolution failure” as a root cause.
  • The warning should include actionable advice, e.g. “Please ensure your server’s /etc/resolv.conf or Docker DNS settings point to a working resolver.”

Actual behavior

  • Nextcloud proceeds with synchronous HTTP requests on every page load, blocking the PHP‐FPM worker until each DNS timeout completes.
  • The only warnings in Security & setup warnings relate to self‐checks (e.g. unable to connect to trusted_domains), but no explicit DNS failure message is shown.

Proposed solution

  1. New health check in lib/private/SetupChecks/ (or similar) that performs:

    • gethostbyname() or equivalent lookup on trusted_domains[0] (or configured overwrite.cli.url).
    • If that fails, mark this check as failed with severity warning or error.
  2. Admin UI: add entry under Administration → Overview → Security & setup warnings:

    DNS resolution failure
    Nextcloud was not able to resolve your server’s hostname or contact the update servers. This may cause extreme delays or failures when loading pages.
    Resolution: Please verify your server’s DNS settings (e.g. /etc/resolv.conf, Docker daemon dns entries, systemd-resolved configuration).

  3. (Optional) Config flag to disable external DNS tests if administrators purposely block outbound DNS (e.g. air-gapped installs).


Additional context

  • Running system-cron mode does prevent cron jobs on every page load, but Nextcloud still performs a number of external HTTP/DNS calls during normal page rendering (asset loading, external storage mounts, app metadata checks).
  • Administrators typically only discover DNS misconfiguration when performance degrades severely, and have little in-UI guidance on how to resolve it.

Thank you for considering this enhancement! I believe it will greatly improve clarity and reduce “mystery” performance issues caused by broken DNS.


PS: this whole issue text was written, or rather generated, by chatGPT after it helped me to resolve the issue that my nextcloud instance on cloudron was unbarable slow and i couldnt figgure out why, the reason was that the docker container had timeout for any dns request (after seconds) because the unbound dns service was broken...

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in lib/private/SetupChecks/ and trace how checks are surfaced under Administration → Overview → Security & setup warnings. Review the trusted_domains and overwrite.cli.url configuration paths, then determine the intended lookup scope, handling of external DNS tests, warning severity, and administrator guidance. Done means the agreed DNS failure cases produce a clear admin warning without disrupting supported installations.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
backend, networking
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.