diff --git a/.github/ISSUE_TEMPLATE/2_bug_report.yml b/.github/ISSUE_TEMPLATE/2_bug_report.yml index 49eabec3..d7ac6ac4 100644 --- a/.github/ISSUE_TEMPLATE/2_bug_report.yml +++ b/.github/ISSUE_TEMPLATE/2_bug_report.yml @@ -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: diff --git a/README.md b/README.md index 55f7b759..53e2f42f 100644 --- a/README.md +++ b/README.md @@ -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`: diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index ad99d74e..612937bd 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -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. diff --git a/docker-compose.yml b/docker-compose.yml index fa68efa0..49f2b361 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -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: