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

docs: improve troubleshooting guide for rclone

Browse source
This commit is contained in:
Nicolas Meienberger 2026-02-01 11:58:54 +01:00
parent 37861089ba
commit 4563cd3a99
4 changed files with 273 additions and 39 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
.github/ISSUE_TEMPLATE/2_bug_report.yml vendored
View file

@ -12,6 +12,16 @@ body:
options:
- label: I have read the [troubleshooting guide](https://github.com/nicotsx/zerobyte/blob/main/TROUBLESHOOTING.md)
required: true
- type: checkboxes
id: rclone_preflight
attributes:
label: Rclone Pre-flight Checklist (if applicable)
description: If your issue involves rclone, confirm you've tested on the host first as described in the troubleshooting guide
options:
- label: This issue is NOT related to rclone (skip if not using rclone)
- label: I have tested `rclone listremotes` and `rclone lsd remote:` on the **host** and they work
- label: I have verified the rclone config is mounted into the container
- label: I have restarted the container after config changes
- type: textarea
id: description
attributes:

10
README.md
View file

@ -40,7 +40,7 @@ In order to run Zerobyte, you need to have Docker and Docker Compose installed o
```yaml
services:
zerobyte:
image: ghcr.io/nicotsx/zerobyte:v0.24
image: ghcr.io/nicotsx/zerobyte:v0.25
container_name: zerobyte
restart: unless-stopped
cap_add:
@ -118,7 +118,7 @@ If you only need to back up locally mounted folders and don't require remote sha
```yaml
services:
zerobyte:
image: ghcr.io/nicotsx/zerobyte:v0.24
image: ghcr.io/nicotsx/zerobyte:v0.25
container_name: zerobyte
restart: unless-stopped
ports:
@ -157,7 +157,7 @@ If you want to track a local directory on the same server where Zerobyte is runn
```diff
services:
zerobyte:
image: ghcr.io/nicotsx/zerobyte:v0.24
image: ghcr.io/nicotsx/zerobyte:v0.25
container_name: zerobyte
restart: unless-stopped
cap_add:
@ -232,7 +232,7 @@ Zerobyte can use [rclone](https://rclone.org/) to support 40+ cloud storage prov
```diff
services:
zerobyte:
image: ghcr.io/nicotsx/zerobyte:v0.24
image: ghcr.io/nicotsx/zerobyte:v0.25
container_name: zerobyte
restart: unless-stopped
cap_add:
@ -247,7 +247,7 @@ Zerobyte can use [rclone](https://rclone.org/) to support 40+ cloud storage prov
volumes:
- /etc/localtime:/etc/localtime:ro
- /var/lib/zerobyte:/var/lib/zerobyte
+ - ~/.config/rclone:/root/.config/rclone
+ - ~/.config/rclone:/root/.config/rclone:ro
```
> **Note for non-root users:** If your container runs as a different user (e.g., TrueNAS apps), mount your config to the appropriate location and set `RCLONE_CONF_DIR`:

288
TROUBLESHOOTING.md
View file

@ -16,48 +16,91 @@ docker logs -f zerobyte
---
## Common issues
## Table of Contents
### Permission denied errors when mounting remote shares
- [Common Issues](#common-issues)
- [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)
- [Secure (Recommended)](#secure-recommended)
- [Advanced](#advanced)
- [AppArmor-Enabled Systems (Ubuntu/Debian)](#apparmor-enabled-systems-ubuntudebian)
- [Seccomp-Restricted Environments](#seccomp-restricted-environments)
- [SELinux-Enabled Systems (CentOS/Fedora)](#selinux-enabled-systems-centosfedora)
- [Privileged Mode (Not Recommended)](#privileged-mode-not-recommended)
- [FUSE-Based Backends](#fuse-based-backends)
- [Rclone Issues](#rclone-issues)
- [Test on Host First](#critical-test-on-host-first)
- [Pre-flight Checklist](#pre-flight-checklist)
- [Common Rclone Errors](#common-rclone-errors)
- ["No Remotes Available" in Dropdown](#no-remotes-available-in-dropdown)
- ["Failed to Create File System" Error](#failed-to-create-file-system-error)
- [EACCES Errors](#eacces-errors)
- [Rclone Volume Mount Issues](#rclone-volume-mount-issues)
- [Requirements](#rclone-volume-requirements)
- [Common Mount Errors](#rclone-common-mount-errors)
- [Still Having Issues?](#still-having-issues)
---
## Common Issues
### 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.
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)
- 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
### Security Levels for Mounting Remote Shares {#security-levels-for-mounting-remote-shares}
Zerobyte supports multiple deployment models depending on your security requirements and environment.
---
#### **Secure** (recommended)
#### Permission Errors with Remote Shares {#secure-recommended}
Mount remote shares **outside of Zerobyte** (on the host) and point Zerobyte to an already mounted local path.
**Problem:** You're getting permission errors when Zerobyte tries to mount remote shares (SMB/CIFS, NFS, etc.).
This approach avoids granting additional privileges to the container and is the most portable and secure option.
**Solution:** Mount remote shares **outside of Zerobyte** (on the host) and point Zerobyte to an already-mounted local path. This avoids container permission issues entirely.
```yaml
services:
zerobyte:
volumes:
- /mnt/your-remote-share:/data
```
**How to fix:**
Remote mounts can be managed via `systemd`, `autofs`, or manual host mounts.
1. Mount your remote share on the host first using `systemd`, `autofs`, or manual mount:
```bash
sudo mount -t cifs //server/share /mnt/your-remote-share -o credentials=/path/to/creds
```
2. Then mount that local path into Zerobyte:
```yaml
services:
zerobyte:
volumes:
- /mnt/your-remote-share:/data
```
3. Restart the container:
```bash
docker compose down && docker compose up -d
```
---
#### **Advanced** (Zerobyte performs mounts)
#### Container Cannot Perform Mounts {#advanced}
If Zerobyte must perform filesystem mounts itself, the container requires the `SYS_ADMIN` capability.
**Problem:** Zerobyte shows "Operation not permitted" errors when trying to mount remote shares directly.
**Solution:** Grant the `SYS_ADMIN` capability to allow the container to perform mount operations.
**Warning:** This grants significant privileges to the container and should only be used when necessary.
```yaml
services:
@ -70,7 +113,7 @@ services:
---
#### AppArmor-enabled systems (Ubuntu/Debian)
#### AppArmor-Enabled Systems (Ubuntu/Debian) {#apparmor-enabled-systems-ubuntudebian}
On hosts using AppArmor, the default Docker profile (`docker-default`) may block mount operations even when `SYS_ADMIN` is present.
@ -96,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.
@ -113,7 +156,7 @@ services:
---
#### SELinux-enabled systems (CentOS/Fedora)
#### SELinux-Enabled Systems (CentOS/Fedora) {#selinux-enabled-systems-centosfedora}
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:
@ -140,11 +183,13 @@ services:
---
#### **Not recommended** (When all else fails)
#### Still Getting Permission Errors After SYS_ADMIN {#privileged-mode-not-recommended}
Running the container in privileged mode disables most container isolation mechanisms and significantly increases the attack surface.
**Problem:** Mount operations still fail even with `SYS_ADMIN` capability.
This option should be used only as a last resort for troubleshooting.
**Solution (Last Resort):** Run the container in privileged mode. This disables most container isolation mechanisms and significantly increases the attack surface.
**Warning:** Only use this as a last resort for troubleshooting. Remove and switch to a more secure solution once you identify the actual issue.
```yaml
services:
@ -154,19 +199,198 @@ services:
---
### Notes on FUSE-based backends
### FUSE Mount Failures {#fuse-based-backends}
Access to `/dev/fuse` is required **only for FUSE-based filesystems** (such as `sshfs` or `rclone mount`).
**Problem:** FUSE-based mounts (sshfs, rclone mount) are failing with device access errors.
It is **not required** for SMB/CIFS mounts.
**Cause:** Access to `/dev/fuse` is required for FUSE-based filesystems.
### Rclone mount issues
**Solution:** Ensure `/dev/fuse` is mounted into the container. This is **not required** for SMB/CIFS mounts.
When using `rclone`, you may get errors like:
````yaml
services:
zerobyte:
devices:
- /dev/fuse:/dev/fuse
---
## Rclone Issues
### ⚠️ 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.**
Most rclone issues are due to misconfigured remotes, not Zerobyte bugs. Follow this checklist on your host machine:
```bash
bun: Failed to spawn process: EACCES
error > Failed to list rclone remotes: bun: Failed to spawn process: EACCES
# 1. List all configured remotes
rclone listremotes
# 2. Test listing a remote (replace 'myremote' with your remote name)
rclone lsd myremote:
# 3. Test reading from a remote
rclone ls myremote:path/to/test
# 4. For volume mounts: Test mounting on host first
mkdir -p /tmp/rclone-test
rclone mount myremote:path /tmp/rclone-test --daemon --vfs-cache-mode writes
ls /tmp/rclone-test
fusermount -u /tmp/rclone-test # Unmount when done
````
**If these commands fail on your host, fix your rclone configuration before using Zerobyte.**
Common issues include:
- Expired OAuth tokens (run `rclone config` to re-authenticate)
- Incorrect credentials
- Missing permissions on cloud provider side
- Network/firewall issues
---
### Pre-flight Checklist {#pre-flight-checklist}
If you're experiencing rclone issues, verify all of the following:
- [ ] Rclone is installed and configured on the Docker **host**
- [ ] `rclone listremotes` shows your remote
- [ ] `rclone lsd remote:` successfully lists directories
- [ ] The rclone config directory is mounted into the container
---
### Common Rclone Errors {#common-rclone-errors}
#### "No Remotes Available" in Dropdown {#no-remotes-available-in-dropdown}
**Cause:** Zerobyte cannot find your rclone configuration file.
**Diagnosis:**
```bash
# Check if config is accessible inside container
docker exec zerobyte ls -la /root/.config/rclone/
docker exec zerobyte cat /root/.config/rclone/rclone.conf
```
Try to disable the AppArmor confinement for the container as described in the [AppArmor-enabled systems](#apparmor-enabled-systems-ubuntudebian) section above or [Seccomp-restricted environments](#seccomp-restricted-environments) section.
**Solutions:**
1. Ensure you've mounted your host's rclone config:
```yaml
volumes:
- ~/.config/rclone:/root/.config/rclone:ro
```
2. For non-root containers (e.g., TrueNAS), set the correct path:
```yaml
environment:
- RCLONE_CONFIG_DIR=/home/appuser/.config/rclone
volumes:
- ~/.config/rclone:/home/appuser/.config/rclone:ro
```
3. **Restart the container** after mounting the config:
```bash
docker compose down
docker compose up -d
```
#### "Failed to Create File System" Error {#failed-to-create-file-system-error}
**Cause:** Authentication failure with the cloud provider.
**Solution:**
1. On your host, run: `rclone config`
2. Re-authenticate the remote (especially for OAuth providers like Google Drive, Dropbox, OneDrive)
3. Verify with: `rclone lsd remote:`
4. Restart the Zerobyte container
#### EACCES Errors {#eacces-errors}
**Cause:** AppArmor or seccomp is blocking rclone execution.
**Solution:** Disable security profiles as described in:
- [AppArmor-enabled systems](#apparmor-enabled-systems-ubuntudebian)
- [Seccomp-restricted environments](#seccomp-restricted-environments)
---
### 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:
#### Prerequisites Check {#rclone-volume-requirements}
If rclone volume mounting isn't working, verify these prerequisites on your system:
- **Linux host required:** Windows/macOS hosts cannot use rclone volumes. If you're on these platforms, you'll need to use a different volume backend.
- **`/dev/fuse` device:** Check if FUSE is available and properly passed to the container
- **`SYS_ADMIN` capability:** Required for mount operations inside containers
- **FUSE support on host:** Verify FUSE is installed and working on your Docker host
#### Common Mount Errors {#rclone-common-mount-errors}
**"mount helper error: fusermount3: failed to open /dev/fuse: Permission denied"**
Solutions in order of preference:
1. **Verify FUSE works on host first:**
```bash
# On host
rclone mount remote:path /tmp/test --daemon
ls /tmp/test
fusermount -u /tmp/test
```
2. **Ensure /dev/fuse is mounted in container:**
```yaml
devices:
- /dev/fuse:/dev/fuse
```
3. **Check user permissions inside container:**
```bash
docker exec zerobyte ls -la /dev/fuse
```
**"mount helper error: fusermount3: mount failed: Operation not permitted"**
This indicates the container lacks `SYS_ADMIN` capability:
```yaml
cap_add:
- SYS_ADMIN
```
---
### 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:
```bash
# Host verification
rclone version
rclone listremotes
rclone lsd remote: 2>&1
# Container verification
docker exec zerobyte ls -la /root/.config/rclone/
docker exec zerobyte env | grep RCLONE
docker logs zerobyte 2>&1 | tail -50
# Check container capabilities
docker inspect zerobyte --format='{{.HostConfig.CapAdd}}'
docker inspect zerobyte --format='{{.HostConfig.Devices}}'
```
Include the output (with sensitive data redacted) in your GitHub issue.

4
docker-compose.yml
View file

@ -22,7 +22,7 @@ services:
- /etc/localtime:/etc/localtime:ro
- /var/lib/zerobyte:/var/lib/zerobyte
- ./app:/app/app
- ~/.config/rclone:/root/.config/rclone
- ~/.config/rclone:/root/.config/rclone:ro
- ./tmp/:/test-data
zerobyte-prod:
@ -47,7 +47,7 @@ services:
volumes:
- /etc/localtime:/etc/localtime:ro
- /var/lib/zerobyte:/var/lib/zerobyte
- ~/.config/rclone:/root/.config/rclone
- ~/.config/rclone:/root/.config/rclone:ro
zerobyte-e2e:
build: