FAQ & troubleshooting

Answers to the most common questions and quick fixes for typical stumbling blocks: ports already in use, ICMP without root, the Docker socket, certificate warnings and logs.

Your question isn't listed?

For any questions about Node64, use the official forum v64.tech. The community and the ipv64.net team will help you – and your question helps others later on.

Frequently asked questions

Yes, completely. Node64 is deliberately built to be fully functional without an account. Without one you get: local health checks with every check type, all your own notification channels, DNS64, PROXY64 in local mode (proxy hosts, streams, access lists), certificates via HTTP-01, through one of 26 other DNS providers, from your own CA or by upload, the local API and backups.

Only with an ipv64.net account: the DynDNS updater (it updates ipv64 domains), online and hybrid checks, the portal, ipv64 mail and SMS, CDN64 and DNS-01 certificates for ipv64 domains. A cluster of several nodes works without an account too. Details in Connect to ipv64.net.

Node64 itself is free and licensed under Apache 2.0. Local measurements and services on the node never count against any limits.

Limits only apply to what runs through ipv64.net – such as online monitoring locations, DynDNS updates, SMS or CDN domains. They depend on your account class; the “Free” class costs nothing. Current classes and prices are on the ipv64.net pricing page.

  • No telemetry. Node64 doesn't send usage data.
  • With an ipv64 API key the node registers for the node overview on ipv64.net – with name, location, version and modules, without secrets or measurements.
  • Version check only if you want it: when enabled, Node64 fetches a version file from ipv64.net once a day – no data is sent.
  • Secrets stay encrypted in your database (AES-256-GCM with /data/secret.key).
  • Once you link the health check sync, configuration and results are transferred to ipv64.net – including targets in your home network. The interface points this out before you link. You can unlink at any time.
  • Apart from that, only what your modules themselves need goes out – for example your checks reaching their targets, DNS64 querying the upstream servers you chose, or blocklist downloads.

For how ipv64.net processes data, see the ipv64.net privacy policy.

The ipv64.net health checks test from the outside – from locations in Nuremberg and Falkenstein. They see what the internet sees and can only check publicly reachable targets.

Node64 checks from the inside, right in your network: including private targets such as your NAS, router or .local names, Docker containers on the same host – and with no limits, because local measurements don't count against your account class.

The combination is where it shines: with the health check sync, a check measures locally and online (hybrid). By default it only counts as down when every location reports down; if only some do, it's “partially down”. That tells you whether the problem is in your home network, your internet connection or the service itself. More in Health checks.

Yes. The image is built for linux/amd64, linux/arm64 and linux/arm/v7, and Docker picks the right one automatically – on a Raspberry Pi with a 64-bit OS arm64, with a 32-bit OS armv7. See Installation → Platforms.

There isn't one. On first visit, the setup wizard has you create a user with a password of at least 10 characters. See First steps.

On the Docker host, in the running container:

docker exec node64 /node64 reset-password

The command sets a new random password, shows it once and ends all sessions. With -disable-2fa it also switches off two-factor login. All options under Forgot your password: emergency access.

When you turn on two-factor login, Node64 shows eight recovery codes once. Each one works exactly once in place of the app code. Log in with one, then set up the app again. If the codes are gone too, docker exec node64 /node64 reset-password -disable-2fa helps (see emergency access).

The node simply keeps measuring, stores the results locally and uploads them once the connection is back – nothing gets lost. Changes are buffered and delivered later. ipv64 runs two equivalent servers with automatic failover for this. If both are gone, the node carries on standalone and sends its notifications through its own channels.

Port 53 is already in use (DNS64)

On many Linux systems, systemd-resolved occupies port 53 with its stub listener (DNSStubListener=yes). DNS64 then shows the error on its page and retries every minute.

To see what's holding the port:

sudo ss -lunp 'sport = :53'

You have two options:

  1. Turn off the stub listener (the typical approach on Ubuntu and Debian with systemd-resolved). The host keeps using systemd-resolved, just without its own listener on port 53: 
    sudo mkdir -p /etc/systemd/resolved.conf.d
printf '[Resolve]\nDNSStubListener=no\n' | sudo tee /etc/systemd/resolved.conf.d/no-stub.conf
sudo ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf
sudo systemctl restart systemd-resolved
    Within a minute, DNS64 starts on its own.
  2. Use a different port: the port can be changed under DNS64 → Settings. Keep in mind that devices on your network normally expect DNS on port 53.

For an overview of all ports and conflicts, see Settings → Ports.

DNS64: names like example.com.home.local in the log

The device appends its search domain itself – usually after the actual query failed, for example with SERVFAIL because the upstreams briefly didn't answer. DNS64 appends nothing. The query log marks it “search domain appended by the device”.

Port 80 or 443 is already in use

Ports 80 and 443 belong to Node64's shared entry point – used by PROXY64, DNS over HTTPS, the interface under its own name and Let's Encrypt (HTTP-01). Node64 opens them only while a module needs them. If another web server or proxy already runs on the host, the conflict only appears at that point.

sudo ss -ltnp 'sport = :443'
  • Check for conflicts: Settings → Ports reports them, even when another program on the host holds the port. It also shows per port whether something is really listening and why a module could not open it (e.g. “address already in use”).
  • Use different ports: the entry point's ports are configurable. If your router forwards 443 to 8443, for example, let Node64 listen on 8443 and set “HTTPS port from outside” to 443.
  • Replace the old proxy: PROXY64 can take over as your reverse proxy – see PROXY64.
  • No open ports at all: with CDN64, services are reachable through a tunnel without any port forwarding.

ICMP (ping) checks fail

Node64 doesn't run as root. For ping checks to work anyway, the container needs one of two settings:

compose.yaml 
    sysctls:
      - net.ipv4.ping_group_range=0 65535   # unprivileged ping, also covers ICMPv6
    # or:
    # cap_add:
    #   - NET_RAW

With network_mode: host, Docker doesn't allow net.* sysctls in the container – use cap_add: NET_RAW there. If you removed capabilities with cap_drop, Node64 still starts, but ICMP won't work.

Only IPv6 pings failing? Then the container is probably missing IPv6 – see IPv6 in the container.

Docker checks: permission denied on the socket

Node64 runs as user 65532 and can only read the Docker socket if it's in the socket's group. Find the socket's group ID on the host:

stat -c %g /var/run/docker.sock

and put exactly that number under group_add:

compose.yaml 
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    group_add:
      - "996"   # output of stat -c %g /var/run/docker.sock

Then recreate the container with docker compose up -d. If you'd rather not pass the socket through directly, use a docker-socket-proxy – see Configuration → Docker host.

The browser warns about the certificate

When you open https://<host>:8080, Node64 initially uses a self-signed certificate, so the warning is expected. To fix it:

  • Request a proper certificate under Certificates (e.g. Let's Encrypt) and select it for the interface.
  • Or mount your own certificate via NODE64_TLS_CERT and NODE64_TLS_KEY (see Configuration).

The node doesn't come back after a restore or reset

After restoring a backup and after a factory reset, Node64 exits on its own so Docker can start it fresh. That only works with a restart policy:

docker update --restart unless-stopped node64
docker start node64

In Compose files, add restart: unless-stopped to the service.

Viewing logs

  • In the interface: the Logs menu entry shows the last 2000 lines, with download.
  • On the host: docker logs -f node64 (or docker compose logs -f).
  • More detail: under Settings → Logging, temporarily set an area to debug. With “Reset after” it falls back automatically.
  • As JSON: NODE64_LOG_FORMAT=json for log collectors.
  • Safe to share: passwords, tokens and keys are always masked in the log.
bash 
docker logs --tail 200 node64
docker exec node64 /node64 version
curl http://localhost:8080/api/health

Still stuck? Ask in the ipv64.net community or check the ipv64.net wiki.

← PreviousAI interface (MCP)

Something unclear, missing, or a question about Node64? Ask in the official forum v64.tech.

Questions about Node64?
For any questions about the product, use the official forum: setup, troubleshooting, ideas and exchange with the community and the ipv64.net team.
Go to the forum v64.tech