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: options:
- label: I have read the [troubleshooting guide](https://github.com/nicotsx/zerobyte/blob/main/TROUBLESHOOTING.md) - label: I have read the [troubleshooting guide](https://github.com/nicotsx/zerobyte/blob/main/TROUBLESHOOTING.md)
required: true 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 - type: textarea
id: description id: description
attributes: 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 ```yaml
services: services:
zerobyte: zerobyte:
image: ghcr.io/nicotsx/zerobyte:v0.24 image: ghcr.io/nicotsx/zerobyte:v0.25
container_name: zerobyte container_name: zerobyte
restart: unless-stopped restart: unless-stopped
cap_add: cap_add:
@ -118,7 +118,7 @@ If you only need to back up locally mounted folders and don't require remote sha
```yaml ```yaml
services: services:
zerobyte: zerobyte:
image: ghcr.io/nicotsx/zerobyte:v0.24 image: ghcr.io/nicotsx/zerobyte:v0.25
container_name: zerobyte container_name: zerobyte
restart: unless-stopped restart: unless-stopped
ports: ports:
@ -157,7 +157,7 @@ If you want to track a local directory on the same server where Zerobyte is runn
```diff ```diff
services: services:
zerobyte: zerobyte:
image: ghcr.io/nicotsx/zerobyte:v0.24 image: ghcr.io/nicotsx/zerobyte:v0.25
container_name: zerobyte container_name: zerobyte
restart: unless-stopped restart: unless-stopped
cap_add: cap_add:
@ -232,7 +232,7 @@ Zerobyte can use [rclone](https://rclone.org/) to support 40+ cloud storage prov
```diff ```diff
services: services:
zerobyte: zerobyte:
image: ghcr.io/nicotsx/zerobyte:v0.24 image: ghcr.io/nicotsx/zerobyte:v0.25
container_name: zerobyte container_name: zerobyte
restart: unless-stopped restart: unless-stopped
cap_add: cap_add:
@ -247,7 +247,7 @@ Zerobyte can use [rclone](https://rclone.org/) to support 40+ cloud storage prov
volumes: volumes:
- /etc/localtime:/etc/localtime:ro - /etc/localtime:/etc/localtime:ro
- /var/lib/zerobyte:/var/lib/zerobyte - /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`: > **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. 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: Ensure that:
* Remote share credentials are correct - Remote share credentials are correct
* The host kernel supports the target filesystem (e.g. CIFS module is available) - 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) - 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. 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. 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 **How to fix:**
services:
zerobyte:
volumes:
- /mnt/your-remote-share:/data
```
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 ```yaml
services: 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. 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. 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. 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:
@ -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 ```yaml
services: 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 ```bash
bun: Failed to spawn process: EACCES # 1. List all configured remotes
error > Failed to list rclone remotes: bun: Failed to spawn process: EACCES 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 - /etc/localtime:/etc/localtime:ro
- /var/lib/zerobyte:/var/lib/zerobyte - /var/lib/zerobyte:/var/lib/zerobyte
- ./app:/app/app - ./app:/app/app
- ~/.config/rclone:/root/.config/rclone - ~/.config/rclone:/root/.config/rclone:ro
- ./tmp/:/test-data - ./tmp/:/test-data
zerobyte-prod: zerobyte-prod:
@ -47,7 +47,7 @@ services:
volumes: volumes:
- /etc/localtime:/etc/localtime:ro - /etc/localtime:/etc/localtime:ro
- /var/lib/zerobyte:/var/lib/zerobyte - /var/lib/zerobyte:/var/lib/zerobyte
- ~/.config/rclone:/root/.config/rclone - ~/.config/rclone:/root/.config/rclone:ro
zerobyte-e2e: zerobyte-e2e:
build: build: