danvics/zerobyte
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs(troubleshooting): fix anchors

Browse source
This commit is contained in:
Nicolas Meienberger 2026-02-01 12:01:58 +01:00
parent 4563cd3a99
commit ebdca8870b
1 changed files with 25 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

50
TROUBLESHOOTING.md
View file

@ -21,13 +21,13 @@ docker logs -f zerobyte
- [Common Issues](#common-issues) - [Common Issues](#common-issues)
- [Permission Denied Errors When Mounting Remote Shares](#permission-denied-errors-when-mounting-remote-shares) - [Permission Denied Errors When Mounting Remote Shares](#permission-denied-errors-when-mounting-remote-shares)
- [Security Levels for Mounting Remote Shares](#security-levels-for-mounting-remote-shares) - [Security Levels for Mounting Remote Shares](#security-levels-for-mounting-remote-shares)
- [Secure (Recommended)](#secure-recommended) - [Permission Errors with Remote Shares](#permission-errors-with-remote-shares)
- [Advanced](#advanced) - [Container Cannot Perform Mounts](#container-cannot-perform-mounts)
- [AppArmor-Enabled Systems (Ubuntu/Debian)](#apparmor-enabled-systems-ubuntudebian) - [AppArmor-Enabled Systems (Ubuntu/Debian)](#apparmor-enabled-systems-ubuntudebian)
- [Seccomp-Restricted Environments](#seccomp-restricted-environments) - [Seccomp-Restricted Environments](#seccomp-restricted-environments)
- [SELinux-Enabled Systems (CentOS/Fedora)](#selinux-enabled-systems-centosfedora) - [SELinux-Enabled Systems (CentOS/Fedora)](#selinux-enabled-systems-centosfedora)
- [Privileged Mode (Not Recommended)](#privileged-mode-not-recommended) - [Still Getting Permission Errors After SYS_ADMIN](#still-getting-permission-errors-after-sys_admin)
- [FUSE-Based Backends](#fuse-based-backends) - [FUSE Mount Failures](#fuse-mount-failures)
- [Rclone Issues](#rclone-issues) - [Rclone Issues](#rclone-issues)
- [Test on Host First](#critical-test-on-host-first) - [Test on Host First](#critical-test-on-host-first)
- [Pre-flight Checklist](#pre-flight-checklist) - [Pre-flight Checklist](#pre-flight-checklist)
@ -36,15 +36,15 @@ docker logs -f zerobyte
- ["Failed to Create File System" Error](#failed-to-create-file-system-error) - ["Failed to Create File System" Error](#failed-to-create-file-system-error)
- [EACCES Errors](#eacces-errors) - [EACCES Errors](#eacces-errors)
- [Rclone Volume Mount Issues](#rclone-volume-mount-issues) - [Rclone Volume Mount Issues](#rclone-volume-mount-issues)
- [Requirements](#rclone-volume-requirements) - [Prerequisites Check](#prerequisites-check)
- [Common Mount Errors](#rclone-common-mount-errors) - [Common Mount Errors](#common-mount-errors)
- [Still Having Issues?](#still-having-issues) - [Still Having Issues?](#still-having-issues)
--- ---
## Common Issues ## Common Issues
### Permission Denied Errors When Mounting Remote Shares {#permission-denied-errors-when-mounting-remote-shares} ### 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. 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.
@ -58,13 +58,13 @@ In some environments, Linux security mechanisms such as AppArmor or seccomp may
--- ---
### Security Levels for Mounting Remote Shares {#security-levels-for-mounting-remote-shares} ### Security Levels for Mounting Remote Shares
Zerobyte supports multiple deployment models depending on your security requirements and environment. Zerobyte supports multiple deployment models depending on your security requirements and environment.
--- ---
#### Permission Errors with Remote Shares {#secure-recommended} #### Permission Errors with Remote Shares
**Problem:** You're getting permission errors when Zerobyte tries to mount remote shares (SMB/CIFS, NFS, etc.). **Problem:** You're getting permission errors when Zerobyte tries to mount remote shares (SMB/CIFS, NFS, etc.).
@ -94,7 +94,7 @@ Zerobyte supports multiple deployment models depending on your security requirem
--- ---
#### Container Cannot Perform Mounts {#advanced} #### Container Cannot Perform Mounts
**Problem:** Zerobyte shows "Operation not permitted" errors when trying to mount remote shares directly. **Problem:** Zerobyte shows "Operation not permitted" errors when trying to mount remote shares directly.
@ -113,7 +113,7 @@ services:
--- ---
#### AppArmor-Enabled Systems (Ubuntu/Debian) {#apparmor-enabled-systems-ubuntudebian} #### 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. On hosts using AppArmor, the default Docker profile (`docker-default`) may block mount operations even when `SYS_ADMIN` is present.
@ -139,7 +139,7 @@ services:
--- ---
#### Seccomp-Restricted Environments {#seccomp-restricted-environments} #### Seccomp-Restricted Environments
Docker's default seccomp profile may block mount-related syscalls required by filesystem operations. Docker's default seccomp profile may block mount-related syscalls required by filesystem operations.
@ -156,7 +156,7 @@ services:
--- ---
#### SELinux-Enabled Systems (CentOS/Fedora) {#selinux-enabled-systems-centosfedora} #### SELinux-Enabled Systems (CentOS/Fedora)
On hosts using SELinux, you may need to adjust the security context to allow mount operations. 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: If mount operations fail with permission errors, you can try adding the following label:
@ -183,7 +183,7 @@ services:
--- ---
#### Still Getting Permission Errors After SYS_ADMIN {#privileged-mode-not-recommended} #### Still Getting Permission Errors After SYS_ADMIN
**Problem:** Mount operations still fail even with `SYS_ADMIN` capability. **Problem:** Mount operations still fail even with `SYS_ADMIN` capability.
@ -199,7 +199,7 @@ services:
--- ---
### FUSE Mount Failures {#fuse-based-backends} ### FUSE Mount Failures
**Problem:** FUSE-based mounts (sshfs, rclone mount) are failing with device access errors. **Problem:** FUSE-based mounts (sshfs, rclone mount) are failing with device access errors.
@ -217,7 +217,7 @@ services:
## Rclone Issues ## Rclone Issues
### ⚠️ Critical: Test on Host First {#critical-test-on-host-first} ### ⚠️ Critical: Test on Host First
**Before reporting any rclone-related issue, you MUST verify that rclone works correctly on your Docker host.** **Before reporting any rclone-related issue, you MUST verify that rclone works correctly on your Docker host.**
@ -251,7 +251,7 @@ Common issues include:
--- ---
### Pre-flight Checklist {#pre-flight-checklist} ### Pre-flight Checklist
If you're experiencing rclone issues, verify all of the following: If you're experiencing rclone issues, verify all of the following:
@ -262,9 +262,9 @@ If you're experiencing rclone issues, verify all of the following:
--- ---
### Common Rclone Errors {#common-rclone-errors} ### Common Rclone Errors
#### "No Remotes Available" in Dropdown {#no-remotes-available-in-dropdown} #### "No Remotes Available" in Dropdown
**Cause:** Zerobyte cannot find your rclone configuration file. **Cause:** Zerobyte cannot find your rclone configuration file.
@ -300,7 +300,7 @@ docker exec zerobyte cat /root/.config/rclone/rclone.conf
docker compose up -d docker compose up -d
``` ```
#### "Failed to Create File System" Error {#failed-to-create-file-system-error} #### "Failed to Create File System" Error
**Cause:** Authentication failure with the cloud provider. **Cause:** Authentication failure with the cloud provider.
@ -311,7 +311,7 @@ docker exec zerobyte cat /root/.config/rclone/rclone.conf
3. Verify with: `rclone lsd remote:` 3. Verify with: `rclone lsd remote:`
4. Restart the Zerobyte container 4. Restart the Zerobyte container
#### EACCES Errors {#eacces-errors} #### EACCES Errors
**Cause:** AppArmor or seccomp is blocking rclone execution. **Cause:** AppArmor or seccomp is blocking rclone execution.
@ -322,11 +322,11 @@ docker exec zerobyte cat /root/.config/rclone/rclone.conf
--- ---
### Rclone Volume Mount Issues {#rclone-volume-mount-issues} ### Rclone Volume Mount Issues
When using rclone as a **volume backend** (mounting cloud storage to back up from), additional requirements apply: When using rclone as a **volume backend** (mounting cloud storage to back up from), additional requirements apply:
#### Prerequisites Check {#rclone-volume-requirements} #### Prerequisites Check
If rclone volume mounting isn't working, verify these prerequisites on your system: If rclone volume mounting isn't working, verify these prerequisites on your system:
@ -335,7 +335,7 @@ If rclone volume mounting isn't working, verify these prerequisites on your syst
- **`SYS_ADMIN` capability:** Required for mount operations inside containers - **`SYS_ADMIN` capability:** Required for mount operations inside containers
- **FUSE support on host:** Verify FUSE is installed and working on your Docker host - **FUSE support on host:** Verify FUSE is installed and working on your Docker host
#### Common Mount Errors {#rclone-common-mount-errors} #### Common Mount Errors
**"mount helper error: fusermount3: failed to open /dev/fuse: Permission denied"** **"mount helper error: fusermount3: failed to open /dev/fuse: Permission denied"**
@ -373,7 +373,7 @@ cap_add:
--- ---
### Still having issues? {#still-having-issues} ### Still having issues?
If you've verified rclone works on the host and followed all troubleshooting steps above, gather this information for your issue report: If you've verified rclone works on the host and followed all troubleshooting steps above, gather this information for your issue report: