zerobyte/TROUBLESHOOTING.md

Troubleshooting

If you encounter any issues while using Zerobyte, you can check the application logs for more information. These logs can help you identify and resolve common problems; you should also check existing and closed issues on GitHub. In case you need further assistance, feel free to open a new issue with detailed information about the problem you are facing and any relevant log entries.

Warning

Make sure to never share sensitive information such as passwords, access keys, or personal data in public issues so remove them from logs before posting.

To view the logs, run the command below:

# replace 'zerobyte' with your container name if different
docker logs -f zerobyte

---

Common issues

Permission denied errors when mounting remote shares

Mounting remote filesystems (such as SMB/CIFS) requires kernel-level privileges. When Zerobyte attempts to perform mounts from inside a container, additional permissions may be required.

Ensure that:

• Remote share credentials are correct
• The host kernel supports the target filesystem (e.g. CIFS module is available)
• Docker is running in rootful mode (rootless Docker cannot perform kernel mounts)

In some environments, Linux security mechanisms such as AppArmor or seccomp may block mount-related operations even when the required capabilities are present.

---

Security levels for mounting remote shares

Zerobyte supports multiple deployment models depending on your security requirements and environment.

---

Secure (recommended)

Mount remote shares outside of Zerobyte (on the host) and point Zerobyte to an already mounted local path.

This approach avoids granting additional privileges to the container and is the most portable and secure option.

services:
  zerobyte:
    volumes:
      - /mnt/your-remote-share:/data

Remote mounts can be managed via systemd, autofs, or manual host mounts.

---

Advanced (Zerobyte performs mounts)

If Zerobyte must perform filesystem mounts itself, the container requires the SYS_ADMIN capability.

services:
  zerobyte:
    cap_add:
      - SYS_ADMIN

⚠️ Granting SYS_ADMIN allows the container to perform mount operations and should be used only when strictly necessary.

---

AppArmor-enabled systems (Ubuntu/Debian)

On hosts using AppArmor, the default Docker profile (docker-default) may block mount operations even when SYS_ADMIN is present.

If mount operations fail with permission errors, you may need to disable AppArmor confinement for the container. Check first if AppArmor is enabled on your system and the profile of the container:

# check if AppArmor is enabled
sudo aa-status
# if next command returns 'docker-default', AppArmor is enabled on the container
docker inspect --format='{{.AppArmorProfile}}' zerobyte

If AppArmor is enabled, you can disable it for the Zerobyte container by adding the following to your docker-compose.yml:

services:
  zerobyte:
    cap_add:
      - SYS_ADMIN
    security_opt:
      - apparmor:unconfined

---

Seccomp-restricted environments

Docker's default seccomp profile may block mount-related syscalls required by filesystem operations.

If mount operations continue to fail, you may need to disable seccomp filtering for the container:

services:
  zerobyte:
    cap_add:
      - SYS_ADMIN
    security_opt:
      - seccomp:unconfined

---

SELinux-enabled systems (CentOS/Fedora)

On hosts using SELinux, you may need to adjust the security context to allow mount operations. If mount operations fail with permission errors, you can try adding the following label:

services:
  zerobyte:
    cap_add:
      - SYS_ADMIN
    security_opt:
      - label:type:container_runtime_t

or disable SELinux enforcement for the container:

services:
  zerobyte:
    cap_add:
      - SYS_ADMIN
    security_opt:
      - label:disable

---

Not recommended (When all else fails)

Running the container in privileged mode disables most container isolation mechanisms and significantly increases the attack surface.

This option should be used only as a last resort for troubleshooting.

services:
  zerobyte:
    privileged: true

---

Notes on FUSE-based backends

Access to /dev/fuse is required only for FUSE-based filesystems (such as sshfs or rclone mount).

It is not required for SMB/CIFS mounts.

Rclone mount issues

When using rclone, you may get errors like:

bun: Failed to spawn process: EACCES
error > Failed to list rclone remotes: bun: Failed to spawn process: EACCES

Try to disable the AppArmor confinement for the container as described in the AppArmor-enabled systems section above or Seccomp-restricted environments section.