Frequently asked questions

Language files for the Docker version have not been updated

When a new Docker version is downloaded, BmuS immediately checks whether language files exist in the /config folder. This is not the case during the initial installation. Bmus then copies the language files from the Docker container to the /config folder.'

However, if language files from a previous installation are already there, BmuS does not overwrite them. The reason for this is that the user may have made changes to them that should not be overwritten.

The problem: If new functions have been added, there will also be new language variables. These will not be found. Text gaps may then appear in the logs or the dashboard.

Tip: Back up the language files from the /config folder to another directory. Restart the container. BmuS will now copy the new language files to the /config folder. Use a suitable text editor to compare the old and new versions, copy the new variables to the old language files, and update the version number to the latest version. Then copy the old (but updated) language files back to the /config folder.

Can I run BmuS in pull mode (NAS to NAS)?

Yes.

"Pull" mode is excellent for security (ransomware protection). Since BmuS is designed to run locally on the backup device, the logic is quite simple:

If you enter an IP, BmuS might try to run connectivity checks (Ping) or attempt to mount the destination itself, which isn't needed here.

The Setup: You need to mount your Primary NAS's SMB share to your Backup NAS's filesystem first (e.g., via /etc/fstab or OS mount to /mnt/primary_nas).

The Config: In BmuS, you then treat this mount simply as a local folder.

BACKUP_SOURCES="/mnt/primary_nas" (The path to your mounted SMB share)

BACKUP_PATH="/mnt/local_storage" (The local disk on your backup NAS)

Important: Please leave NAS_IP=""empty in your bmus.conf.

Since the mount is handled by the OS, BmuS treats this as a "Local Backup".

After restarting the Docker container, my rclone.conf file is gone

The /root/ directory within the container is volatile. When you stop the container (or restart the machine on which the container is running), the container is "thrown away" and recreated from the image upon restart. Anything not located within a volume (like /config) is then permanently lost.

BmuS prevents this by checking if an rclone.conf file exists in the Docker container. If so, BmuS checks if an rclone.conf file is located in the /config folder on the host. If it is not, or if the file is empty (0 Bytes), BmuS copies the rclone.conf file from the Docker container to the /config folder.

However, this only happens if CLOUD_BACKUP=1 is set in the bmus.conf file. If this is not the case, and you restart the container without this process having been carried out at least once AND directly after you have configured rclone, the rclone.conf file in the Docker container will be lost the moment you restart Docker.

Unless you plan to use cloud backup but still want to configure rclone in the Docker container prior performing a cloud backup, it's best to manually copy the rclone.conf file from the container to the /config directory.

Reconfigure rclone (if necessary):

docker exec -it bmus_backup rclone config

Manually copy the rclone.conf file into the /config folder:

docker exec -it bmus_backup cp /root/.config/rclone/rclone.conf /config/rclone.conf

Docker: I have configured and authorized rclone. Will the authorization be lost if I rebuild the Docker container?

No. If the backup has already been run with Cloud Backup, BmuS copied rclone.conf automatically from the Docker container to /BmuS-Docker/config, if it was not already there. If the file is already there, BmuS will always use this one, even if the Docker container is rebuilt or updated. The condition is that the path in bmus.conf is correct:

RCLONE_CFG_PATH="/config/rclone.conf"

I configured BmuS to use NFS for performance. Why does the script automatically switch to SMB/CIFS when the Cloud Backup starts?

This is an intentional "Auto-Pilot" feature designed to ensure the stability of your cloud uploads.

While NFS is superior for the local backup phase (transferring files from your Client/Host to the NAS/Network drive), it often causes significant issues during the Cloud Backup phase. Here is the detailed explanation of why BmuS performs this switch:

1. The Right Tool for the Job

• NFS (Network File System): BmuS prefers NFS for the main backup because it is extremely fast and handles Linux file permissions and metadata very well. It is the "race car" engine for rsync.
• SMB/CIFS (Samba): SMB is slightly slower but much more robust when it comes to file locking and broad compatibility. It is the "heavy-duty truck."

2. The Problem with Rclone & NFS

To upload your data to the cloud (OneDrive, Google Drive, etc.), BmuS uses a tool called rclone. In practice, running rclone on a mounted NFS share often leads to sporadic and frustrating errors, such as:

• "Stale File Handles": The connection to the file drops suddenly while reading.
• File Locking Issues: NFS and rclone disagree on who is allowed to access a file, causing the upload to freeze or crash.
• Timeouts: Large files might fail halfway through because the NFS protocol is optimized for speed/caching, while rclone needs a stable, continuous read stream.

3. The BmuS Solution

To prevent your Cloud Backup from failing silently or crashing:

1. BmuS detects that you are using NFS.
2. Before the cloud upload begins, it automatically unmounts the NFS share.
3. It remounts the same share using the SMB/CIFS protocol.
4. It performs the cloud upload safely and stably.

Summary: BmuS prioritizes Speed for your local backup and Stability for your cloud upload. You do not need to intervene; the script handles this protocol negotiation automatically in the background.

I don’t have a NAS. Can I backup on a SD or HD?

Yes. BmuS is very cooperative here if you configure it correctly.

Technically speaking, BmuS doesn't care whether the destination folder (BACKUP_PATH) is a mounted NAS, a USB hard drive, or an internal folder. The main thing is that it can write there.

Here is the behavior and necessary configuration for Native and Docker if you want to use a local hard drive (e.g., USB).

The behavior of the script (code level)

BmuS differentiates based on the NAS_IP variable:

1. If NAS_IP is set: BmuS assumes that it needs to mount a network drive (mount -t cifs …). It performs ping tests and attempts the mount.
2. If NAS_IP is EMPTY (“”): BmuS skips the entire network mount logic. It simply assumes: “The path specified in BACKUP_PATH is already there and ready.”

Native Installation

Configuration for native installation (e.g., Linux or Raspberry Pi with USB disk).

Let's assume you have a USB disk that your Linux automatically mounted to /media/usbdisk (or you entered it in /etc/fstab). To do this, simply empty .bmus_credentials

NAS_USER=""
NAS_PASS=""

and empty bmus.conf

NAS_IP=""
NAS_SHARE=""

Then mount the medium and enter the path to it in bmus.conf under BACKUP_PATH.

BACKUP_PATH=“/media/usbdisk/BmuS_Backup”

Docker Installation

Here, it is slightly different. The container does not see your hardware directly. You must “pass through” the USB disk from the host to the container.

Scenario: USB disk is mounted on the NAS/host under /mnt/usb_backup.

Adjusting docker-compose.yml: You have to change the volume. Instead of using the config folder, you map the real disk.

YAML

volumes:
  - ./config:/config
  - /:/host_root:ro
  # We map the USB disk in the container to /target
  - /mnt/usb_backup:/target

bmus.conf:

No NAS connection required in the container.

NAS_IP=""

The path INSIDE the container (see docker-compose).

BACKUP_PATH="/target/MyBackup"

Is it possible to start BmuS with different configs?

Yes.

Native installation

sudo CONFIG_FILE=/home/user/bmus_alternative.conf /home/user/bmus.sh

You can also add several cronjobs that execute different configs.

Open crontab.

sudo crontab -e

Daily at 3:00 a.m. and 6:00 a.m. with alternative configs.

0 3 * * * CONFIG_FILE=/home/user/bmus.conf /home/user/bmus.sh
0 6 * * * CONFIG_FILE=/home/user/bmus_alternative.conf /home/user/bmus.sh

Docker installation

sudo docker exec -it -e CONFIG_FILE=/config/bmus_alternative.conf bmus_backup /app/bmus.sh [ARGUMENTS]

Make sure that bmus_alternative.conf is in the config/ folder.

Daily at 3:00 a.m. and 6:00 a.m. with alternative docker configs.

0 4 * * * sudo docker exec -e CONFIG_FILE=/config/bmus.conf bmus_backup /app/bmus.sh
0 18 * * * sudo docker exec -e CONFIG_FILE=/config/bmus_alternative.conf bmus_backup /app/bmus.sh

You could also tweak the docker-compose.yml.

But since the Docker container (more precisely, the entrypoint.sh script) is hard-coded to always load /config/bmus.conf, you nee to use a “mount trick” here:

For the second container (bmus_alternative), we mount the file bmus_alternative.conf (from the host) directly over bmus.conf (in the container). The container “thinks” it is loading the default configuration, but in reality it is reading your second configuration.

services:
  # ---------------------------------------------------------
  # 1. Standard container (uses bmus.conf)
  # ---------------------------------------------------------
  bmus:
    image: backmeupscotty/bmus:latest
    container_name: bmus_backup
    restart: unless-stopped
    privileged: true
    volumes:
      - ./config:/config
      - /:/host_root:ro
    environment:
      - TZ=Europe/Berlin

  # ----------------------------------- ----------------------
  # 2. Second container (uses bmus_alternative.conf)
  # ------------------------------------------------------ ---
  bmus_secondary:
    image: backmeupscotty/bmus:latest
    container_name: bmus_backup_secondary
    restart: unless-stopped
    privileged: true
    volumes:
      # First mount the entire folder (for credentials, etc.)
      - ./config:/config
      
      # TRICK: We overwrite the bmus.conf in the container with the bmus_alternative.conf from the host
      - ./config/bmus_alternative.conf:/config/bmus.conf
      
      # OPTIONAL: We also redirect the log file so that they don't get mixed up
      # (Host: bmus_alternative.log -> Container: bmus.log)
      # IMPORTANT: Create an empty ‘bmus_alternative.log’ on the host beforehand!
      - ./config/bmus_alternative.log:/config/bmus.log
      
      - /:/host_root:ro
    environment:
      - TZ=Europe/Berlin

Both containers now run completely independently of each other. This means you can define completely different schedules (CRON_SCHEDULE), backup destinations, or sources in bmus_alternative.conf than in the first file.

Can I backup Windows?

Sure. But only with the Docker version and “Docker Desktop.”

1. Download and install Docker Desktop for Windows:
https://docs.docker.com/desktop/setup/install/windows-install/
2. Give Docker Desktop full access rights on your Windows PC.
3. Download the ZIP file Bmus-Docker.zip and unzip it.
4. Go to the folder where you unzipped Bmus-Docker.zip.
5. Open the Yaml and replace it with this:

services:
  bmus:
    image: backmeupscotty/bmus:latest
    container_name: bmus_backup
    restart: unless-stopped
    privileged: true
    cap_add:
      - SYS_ADMIN
      - DAC_READ_SEARCH
    environment:
      - TZ=Europe/Berlin # change to your time zone
    volumes:
      - ./config:/config
      # MAP YOUR WINDOWS DRIVES HERE:
      # Format: Drive:/Path:/host_root/Path
      - C:/Users/YourName:/host_root/YourName:ro
      # External Drive D:
      #- D:/Photos:/host_root/D/Photos:ro

6. Change to the /config folder
7. Open bmus.conf and configure it according to your preferences.

IMPORTANT: The most important difference is how you mount the drives. Windows uses drive letters (C:), Linux does not. Linux runs in the container. This means that you cannot use C:\ paths or backslashes \ in your configuration. You must specify the paths as they appear in the container.

Incorrect (Windows thinking):

BACKUP_SOURCES=(“C:\Users\YourName\Documents”)

Correct (Linux/Docker thinking):

BACKUP_SOURCES=(“/host_root/YourName/Documents”)

8. Remember to edit msmtp.conf (smtp config for mail reports), bmus_credentials (credentials to your NAS), and bmus_geocryptfs (Password file for encrypted backups).
9. Switch back from the /config folder to the root folder of the Bmus-Docker directory.

cd C:\Users\YourName\Bmus-Docker

10. Now you need to start loading and building the Docker image.
11. Enter the following command (CMD or PowerShell):

docker compose up -d

12. Once the image has loaded and appears in Docker Desktop, you are ready to proceed.
13. Open Notepad, copy the following code and save it to the root folder of Bmus-Docker as bmus.bat:

@echo off
REM ==========================================
REM BmuS wrapper for Windows
REM Forward commands to the Docker container
REM ==========================================

docker exec -it bmus_backup env CONFIG_FILE="/config/bmus.conf" /app/bmus.sh %*

14. Run Bmus for your first backup.

Type

bmus.bat 

or send the command into the container

docker exec -it bmus_backup env CONFIG_FILE="/config/bmus.conf" /app/bmus.sh

Optional:

If you want to call BmuS from anywhere (without always having to navigate to the folder first), you must add the folder containing the .bat file to the Windows PATH variable.

1. Press the Windows key + R, type sysdm.cpl, and press Enter.
2. Go to the Advanced tab -> Environment Variables.
3. In the lower section (“System variables”), find the line Path and click Edit.
4. Click New and paste the path to your folder (e.g., C:\Users\YourName\Bmus-Docker).
5. Confirm everything with OK.

If you then restart your terminal, you can simply type bmus wherever you are, and Windows will find the script automatically.

Can I back up (my Mac) to an external HD?

Yes, this works great. On macOS, external drives usually mount under /Volumes/NameOfDrive. You just need to map this path into the Docker container in your docker-compose.yml.

Example: - /Volumes/MyBackupDrive:/mnt/backup_drive

Ensure that you grant Docker Desktop permission to access "Removable Volumes" in your Mac's System Settings -> Privacy & Security -> Files and Folders (or "Full Disk Access"), otherwise the container might not see the external drive."

File System Requirements (Crucial for Mac): Because BmuS uses Hardlinks for deduplication (to save massive amounts of space), the file system matters:

• Recommended: APFS (Apple File System) or Mac OS Extended (HFS+). These are the native Mac formats. They support hardlinks perfectly. Since Docker maps the drive from macOS to the Linux container, BmuS can utilize the Mac's native file system features to create space-saving backups.
• Not Recommended: exFAT or FAT32. Many external drives come pre-formatted as exFAT. Do not use this for BmuS. exFAT does not support hardlinks. BmuS would still work, but it would have to create a full copy every single time instead of just saving the changes. Your drive would fill up very quickly.

Can I backup my Mac?

Absolutely. But only with the Docker version and “Docker Desktop.”

1. Download and install Docker Desktop for Mac:
   https://docs.docker.com/desktop/setup/install/mac-install/
2. Give Docker Desktop full access rights on your Mac.
3. Download the ZIP file Bmus-Docker.zip and unzip it.
4. Go to the folder where you unzipped Bmus-Docker.zip.
5. Open the Yaml and replace it with this:

services:
  bmus:
    # ---------------------------------------------------------
    # backmeupscotty
    # ---------------------------------------------------------
    #build: .
    image: backmeupscotty/bmus:latest
    container_name: bmus_backup
    restart: unless-stopped
    privileged: true
    cap_add:
      - SYS_ADMIN
      - DAC_READ_SEARCH
    
    volumes:     
      
      - /Users/your_mac_user_here:/host_root/Users/your_mac_user_here:ro
      - ./config:/config

    environment:
    # change to your time zone
      - TZ=Europe/Berlin

5. Change to the /config folder
6. Open bmus.conf and configure it according to your preferences.
7. IMPORTANT: The backup path under BACKUP_SOURCES under Mac always starts with
   /host_root/Users/your_mac_user/
   Example: “/host_root/Users/your_mac_user/Documents/PDF”
8. Remember to edit msmtp.conf (smtp config for mail reports), bmus_credentials (credentials to your NAS), and bmus_geocryptfs (Password file for encrypted backups).
9. Switch back from the /config folder to the root folder of the Bmus-Docker directory.
10. Give the bmus file execution permissions:

sudo chmod +x bmus

11. Now you need to start loading and building the Docker image.
12. Enter the following command:
    sudo docker compose up -d
13. Once the image has loaded and appears in Docker Desktop, you are ready to proceed.
14. Run Bmus for your first backup:
    sudo bmus or send the command into the container sudo docker exec -it bmus_backup /app/bmus.sh

This is what the wrapper code looks like:

#!/bin/bash

# Container is running?
if [ ! "$(sudo docker ps -q -f name=bmus_backup)" ]; then
    echo "Error: BmuS container is not running!"
    echo "Please start it first: sudo docker compose up -d"
    exit 1
fi

# Pass the command to the container
# “$@” passes all arguments (such as --restore --list) 1:1
sudo docker exec -it -e CONFIG_FILE=/config/bmus.conf bmus_backup /app/bmus.sh "$@"

I purchased Dashboard Pro and am using the Docker version of BmuS. How do I add the dashboard to the Docker container?How

1. Place the file bmus_dashboard_pro.sh directly into the config folder.
   (Do not rename the file).
2. Open bmus.conf
3. Change DASHBOARD_MODE="simple" to DASHBOARD_MODE="advanced"
4. Change DASHBOARD_GENERATOR="$HOME_PI/bmus_dashboard.sh" to
   DASHBOARD_GENERATOR="/config/bmus_dashboard_pro.sh"
5. Restart the container to apply permissions:
   sudo docker compose restart bmus
6. The Pro Dashboard will now be generated automatically after every backup.

I bought Dashboard-Pro. Do I get updates?

Yes. When you purchased Dashboard-Pro, an account was automatically created for you. You can use this account to download the latest version.

It took too long backup a few files via SMB

It took too long backup a few files via SMB. The log shows:

[16.12.2025 23:44:31] - Error copying /home/user/folder/, retrying with root…
[16.12.2025 23:51:14] - Copying /home/user/folder/ with root successful

A: The cause: --copy-links and “ghost files”

find -type f counts only real files that physically exist. By default, it ignores symbolic links (symlinks) pointing to other folders.

However, BmuS has a special setting for CIFS mode that changes this behavior.

RSYNC_OPTIONS+=" ... --copy-links ..."

The --copy-links option forces rsync to follow symlinks and copy the contents of the target as if they were real files on the Desktop.

The scenario: There is likely a symlink to a location that:

• Contains a very large number of files (e.g., a symlink to the root /, /var/log, or even the home directory itself → recursion loop).
• Or points to a network target that is slow/unreachable.

What happens:

1. find sees the symlink, says “not a file,” and does not count it → result: 40 files.
2. rsync (as non root user) sees the symlink, follows it (because of --copy-links), and starts scanning thousands of files in the target.
3. After 8.5 minutes in this example, non root user pi (or whatever it is) hits a file in the target they cannot read → abort (error).
4. The script retries as root.
5. root can read everything, so it scans the linked folder successfully (but slowly, ~6.5 minutes), realizes “everything is already there” (or deduplicates it), and reports success.

Solution 1

We need to identify which symlink is causing the problem.

Step 1: Check for symlinks

Run this command to list all symlinks on the Desktop:

ls -la /home/user/folder | grep "^l"

(The l at the beginning of the line indicates a link/symlink.)

Look for symlinks pointing to system-critical folders (like /, /usr, /var) or to the backup drive itself (/mnt/...).

Step 2: Fix it

You have two options:

Option A (Clean): Delete the problematic symlink from the Desktop or move it to a folder that is not being backed up.

Option B (Configuration): Switch bmus.conf to NFS mode (NAS_MOUNT_MODE="nfs").

Why this helps: In NFS mode, your script (according to code analysis) does not use --copy-links. rsync would then simply copy the link itself (takes milliseconds) instead of following it.

Summary: Your backup is not really “stuck.” It is working hard to scan the contents of a folder that shouldn’t actually be on the Desktop but is “virtually” included through a symlink. Once you identify this symlink, the Desktop backup will complete in under 5 seconds.

Solution 2

If the cause are not symlinks and that there are only a few small files—which still take minutes—points to a deeper issue with the network protocol.

If we can rule out symlinks, the only logical explanation for this extreme delay (~10 seconds per file) is timeouts.

BmuS attempts to set or read certain file attributes (timestamps, permissions) on the NAS for each file. The NAS (or the protocol) does not respond quickly enough, causing rsync to wait for a timeout, retry, and then continue.

Steps to fix this:

1. Switch protocol (strongly recommended)

The currently used protocol cifs_simple is often a bottleneck for Linux-to-Linux backups (Linux / Pi to NAS) and prone to permission issues.

Change the mount mode in your bmus.conf.

Option A: NFS (Best solution)
If your NAS supports NFS (easily enabled on Synology/QNAP), use it. It is much faster and does not have these permission/timeout issues.

# In bmus.conf
NAS_MOUNT_MODE="nfs"

# If not set yet, specify the NFS path (example for Synology):
NAS_SHARE_NFS="/volume1/Backup"

(You can find the exact path on the NAS or with showmount -e 192.xxx.xxx.xxx on your Master (Linux/Pi).

Option B: CIFS Optimized (Fast alternative)
If you want to stay with SMB/CIFS, use the optimized mode. This disables certain checks (noserverino) that often slow down rsync.

# In bmus.conf
NAS_MOUNT_MODE="cifs_optimized"

2. Diagnosis (Optional)

To confirm that timeouts are the cause, you can run this once on your system after a backup:

dmesg | tail -n 20

If you see red messages like CIFS VFS: Server not responding or Send error in Setattr, this confirms the timeout theory.

Summary: Your folder is fine. The “bottleneck” is the cifs_simple connection. Switching to cifs_optimized or, better, nfs will allow this folder to be backed up in seconds.

Deduplication log displays different values

Let's say the text log shows:

[15.12.2025 01:16:35] - Hardlinks created: 5018 files
[15.12.2025 01:16:35] - Deduplication rate: 99.8% 
[15.12.2025 01:16:35] - Total number of files: 5030
[15.12.2025 01:16:35] - Deduplication rate calculated: 99.8%
[15.12.2025 01:16:35] - Generating detailed deduplication log...
[15.12.2025 01:17:34] - Detailed deduplication log generated.
[15.12.2025 01:17:34] - Deduplication performance: 3937 hardlinks in 59 seconds

At first glance, this looks inconsistent, confusing, and wrong. But it's correct. Let's take a closer look.

This is not an error, but rather due to the different ways in which the two numbers are counted.

The explanation

1. The number 5018 (“Hardlinks created”)

This number is based on the mathematical calculation from the rsync statistics in BmuS:

local hardlink_count=$((GLOBAL_RSYNC_TOTAL_FILES - GLOBAL_RSYNC_TRANSFERRED_FILES))
GLOBAL_RSYNC_TOTAL_FILES 
# Counts everything that rsync has touched. 
# This includes: files, directories (folders), 
# symlinks (shortcuts), device nodes, etc.

If rsync does not need to transfer a folder or file (because it already exists in the reference backup), the script counts this as “saved” or deduplicated.

Important: This also includes 1081 folders and symlinks.

2. The number 3937 (“Detailed deduplication log”)

This number is generated by the find command, which writes the log file:

find “$backup_dir” -type f -links +1 -printf “%n|%s|%P\n” > “${DEDUP_LOGFILE}.raw”

The parameter -type f is the key. It means: “Search ONLY for regular files.”

Directories are ignored here (technically speaking, directories are not “hardlinked” like files in Linux; they simply exist as a structure).

Symlinks are often ignored here as well (depending on the find implementation and -type f).

The calculation works out.

Statistics (everything): 5018 objects
Log (files only): 3937 files
Difference: 1081 objects

These 1081 missing entries are simply the folder structure and any symlinks (e.g., in /etc/ or /var/www/) that rsync has synchronized (hence in the statistics) but which are not “files with hard links” (hence not in the log).

Conclusion for you:

You don't need to worry. Your backup is complete. Deduplication works perfectly (99.8%).

The log file intentionally shows only “real files” to remain clear, while the statistics above show the total amount of work saved by the backup.

How can I test whether deduplication really works?

Simply compare two files with each other.

1. Both files must have the same inode number.
2. The link count (second column) should be ≥ 2.

If so, hard linking is working. For example:

ls -li backup1/file.txt backup2/file.txt

The output should look similar to this:

1234567 -rw-r--r-- 2 user user 10485760 Jan 1 12:00 backup1/file.txt
1234567 -rw-r--r-- 2 user user 10485760 Jan 1 12:00 backup2/file.txt

Real world example:

ls -li 2025-12-06/2025-12-06_23-30-12/check_pihole.sh 2025-12-05/2025-12-05_23-30-12/check_pihole.sh
220365 -rwxrwxrwx 33 root root 85 Oct 21 15:00 2025-12-05/2025-12-05_23-30-12/check_pihole.sh
220365 -rwxrwxrwx 33 root root 85 Oct 21 15:00 2025-12-06/2025-12-06_23-30-12/check_pihole.sh

Inode: 220365 – both files have the same inode number → they point to the same content.
Link count: 33 – this means that there are 33 hard links to this content, so this content is only stored physically once.
Size: 85 bytes – the content is small, but no matter how many hard links you create to it, it will not occupy 33×85 bytes, but only 85 bytes once + minimal directory entries.

Why does the Dashboard show the status “Error” in red?

Q: Why does the Dashboard show the status "Error" in red? 
A: The status turns red if either COPY_ERRORS or VERIFY_ERRORS are greater than zero.

• Copy Errors: Usually happens if rsync loses connection or lacks permission to read a source file.
• Verify Errors: Occur if you enabled BACKUP_VERIFICATION=1 and the checksum of the backup doesn't match the source. Check the bmus.log file for details on which specific file failed.

How does the deduplication feature save space on my NAS?

Q: How does the deduplication feature save space on my NAS? 

A: BmuS uses the rsync --link-dest feature. When a file hasn't changed since the last backup, BmuS creates a "hard link" to the existing file instead of copying it again. Hard links look and act like real files but point to the same data on the disk. This means you can have 10 full daily backups that only take up the storage space of one full backup plus the small daily changes.

What is the difference between “Flat Structure” and “Date Folders” mode?

Q: What is the difference between "Flat Structure" and "Date Folders" mode? 
A: BmuS automatically detects your backup style.

• Date Folders: If you enable BACKUP_USE_DATE_FOLDERS=1 or DEDUP_ENABLE=1, BmuS creates a new folder for every backup (e.g., 2025-11-28). Retention deletes the entire folder when it gets too old.
• Flat Structure: If disabled, files are copied directly into the backup root. BmuS will delete individual files based on their age (mtime) to save space.

Why is the “Deduplication Rate” in the history sometimes 0.0%?

Q: Why is the "Deduplication Rate" in the history sometimes 0.0%? 

A: The deduplication rate is calculated by comparing the number of hard links to the total number of files. If this is the very first backup to a new folder, there is no previous reference to link against, so the rate is 0%. It will increase with the second backup run as unchanged files are linked. It can also be 0% if DEDUP_ENABLE is turned off.

What happens if my NAS is not reachable when the backup starts?

Q: What happens if my NAS is not reachable when the backup starts? 

A: BmuS has a built-in retry mechanism. It will try to ping your NAS (configured via NAS_IP) multiple times. If it fails, it waits for a few seconds and tries again. You can configure the number of retries (PING_RETRIES) in bmus.conf. If it still fails, the script will abort to prevent errors, unless you have set IGNORE_FAILED_PING=1.

My backups are encrypted. How can I access them in an emergency without the script?

Q: My backups are encrypted. How can I access them in an emergency without the script? 

A: BmuS uses gocryptfs for encryption. In an emergency, you can install gocryptfs on any Linux machine and mount your encrypted backup folder manually using your password file: gocryptfs -passfile /path/to/password_file /mnt/nas/encrypted_backup /mnt/restore_point This will make your files visible in plain text in the restore point directory.

Old encrypted files and folders are not reliably deleted.

Q: Old encrypted files and folders are not reliably deleted.

A: If READABLE_NAMES=0, the file and folder names are encrypted. The problem is that BmuS deletes the files based on the folder name, which is composed of the backup date. BmuS does not delete based on the age of the file or the last modification date, as these timestamps may be younger than the original backup date.

If the folder names are encrypted, BmuS can no longer recognize the creation date of the folder. BmuS then falls back on checking the timestamp of the folder or file.

However, if this timestamp has been changed in the meantime by a third-party system (NAS), BmuS may not delete the file because the timestamp is not (yet) outside the interval defined in ENCRYPTED_BACKUP_AGE_DAYS.

Solution: (1) Either you wait until this is the case (which might be the day after) and hope that your NAS (or wherever these files are stored) no longer changes the timestamps, or (2) you have to manually delete the skipped folders and files.

In any case, the routine works reliably for encrypted and unencrypted folders and files that were created with READABLE_NAMES=1.

Can I backup the whole system with BmuS?

This is a very ambitious idea that sounds tempting at first glance (“One click, everything secure”), but involves massive technical pitfalls when you look at the details.

Short answer

BmuS is a file-based backup tool (rsync) . Backing up an entire running system actually requires an image-based tool (such as dd or partimage).

If you try to replicate this with rsync, you're opening Pandora's box.

The technical problems (why it's difficult)

1. The “open heart surgery” problem

You are backing up a system while it is running.

Inconsistency: While you are backing up /var/lib, an application is writing to a file. The backup is corrupt.

Stopping services: You would need to know which services are running. If you blindly stop them all, you might cut off your own SSH connection or the network stack that BmuS needs for the NAS mount.

2. The infinite loop trap (excludes)

You can't just do rsync -av / /mnt/backup.

You must exclude virtual file systems: /proc, /sys, /dev, /run, /tmp.

The killer: You must exclude /mnt and /media. If you don't, BmuS will back up the NAS to the NAS to the NAS… until the disk bursts.

3. The “restore nightmare” (the main argument against it)

Let's assume the backup works. The SD card breaks. You buy a new one, installs a fresh Raspberry Pi OS, and restores your “full backup.”

UUID conflicts: /etc/fstab and /boot/cmdline.txt contain the UUIDs of the old partitions. The new SD card has different ones. The system no longer boots.

Kernel mix: The fresh OS has kernel 6.1, your backup has kernel 5.10 (or vice versa). You overwrite modules in /lib/modules. Kernel panic is inevitable.

User IDs: If the UIDs/GIDs don't match, you'll have a mess of permissions.

So: No. The sexiness of BmuS lies precisely in the fact that it is a system for backing up files—at intervals that you choose. If you want a complete backup, say once a month, and want to write it to an SD card, you need an SD image backup tool.

I have a feature request

That's great. I would be very happy to see it. You can submit your feature request here.

https://www.back-me-up-scotty.com/docs/feature-requests/

I found an error …

Great! Please let me know.

Can I use the dashboard pro on multiple installations?

Yes! You pay this small one-time fee of 10 euros and can then use it with as many instances of BmuS as you like. You do not need to purchase Dashboard Pro separately for each BmuS instance.

How does the dashboard looks like?

See the following links for screenshots of both versions:

Standard dashboard: dashboard_simple
Pro dashboard: dashboard_pro

If you would like to have a detailed reporting, you can purchase the Pro version of the dashboard for a one-time fee of 10 euros.

What’s the difference between simple and pro dashboard?

Feature Category	Feature	🟢 Simple Edition (Standard)	🚀 Advanced Edition (Pro)
Core Technology	Architecture	❌ Static HTML & CSS only	✅ Dynamic HTML5 + Chart.js
	Data Depth	❌ Current Log only	✅ Log + History CSV (Trend Analysis)
Visualizations	Storage History	❌ No History (Current size only)	✅ Interactive Area Chart (30-Day Growth)
	Performance	❌ Current duration only	✅ Duration Line Graph (Speed Analysis)
	File Counts	❌ Text only	✅ Bar Chart (New vs. Total Files)
	Error Tracking	❌ Simple Status Banner	✅ Error Rate Trend (Visual Warning)
Deduplication	Efficiency Stats	❌ Not available	✅ Efficiency Gauge (Space Saved %)
	Detailed Log	❌ Not available	✅ Top 100 Deduplicated Files List
User Experience	Interactivity	❌ Static (Read-only)	✅ Interactive Hover Effects on Graphs
	Visuals	🟡 Functional / Minimalist	✅ Modern "Command Center" Design
Maintenance	Complexity	✅ Very Low (Single Script)	🟡 Moderate (Requires CSV maintenance)

Is the free version limited?

With BmuS (bmus.sh) you’ll get all core functions (backup & restore) without any limitation.

However, in the standard version, the report generator (bmus_dashboard.sh) only generates those statistics you would see if you set DASHBOARD_MODE to simple in bmus.conf. 

In other words: The standard version is limited to simple mode dashboard while you can switch from simple to pro dashboard and vice versa with the pro-version of the dashboard generator.

Why is there no change log until December 1, 2025?

Because I didn't keep track of it myself ( I am lazy) and published the program on December 1, 2025. However, the change log will be published from that date onwards.

Why doesn’t BmuS support Block-Level Deduplication (like Borg or Restic)?

A: This is a deliberate design choice based on Performance and Transparency.

1. The "No Black Box" Philosophy Tools with block-level deduplication chop your files into millions of tiny data chunks and store them in proprietary database/container formats. To read your data, you must use their specific software. If that tool breaks or becomes obsolete, your data is lost. BmuS takes a different approach: Your files are stored as normal, readable files on the disk. You can plug your backup drive into any computer and open your photos or documents without needing BmuS installed. We prioritize recoverability over maximum storage efficiency.

2. Technical Limitations of Bash Block-level deduplication requires calculating complex hashes (checksums) for millions of data blocks in real-time. Compiled languages like C, Go, or Python can do this efficiently. BmuS is written in Bash (shell script). Attempting to implement block-level logic in Bash would make the backup extremely slow and consume massive amounts of CPU/RAM, which goes against our goal of running smoothly on low-power devices like Raspberry Pis.

3. The Trade-off

• Block-Level (Others): Saves more space (especially for VMs), but locks your data into a specific format.
• File-Level (BmuS): Saves slightly less space, but your data remains in standard, human-readable formats (Zero Vendor Lock-in).

Can I restore a backup to a different folder structure?

Q: Can I restore a backup to a different folder structure?

A: Yes.

When restoring, BmuS recreates the relative structure. If you restore to /tmp/restore, the file originally located at /etc/pihole/setupVars.conf will appear at /tmp/restore/etc/pihole/setupVars.conf. This prevents BmuS from accidentally overwriting your live system files. You can verify the files in the restore folder before manually moving them to their live location.

I want to restore a single file. Do I have to download the whole backup?

Q: I want to restore a single file. Do I have to download the whole backup?

A: No.

Use the built-in restore mode. BmuS can mount the remote backup and extract just the single file you need directly to your Computer.

Example:

sudo bash bmus.sh --restore --date 2024-11-30 --target /tmp --file "my_important_doc.pdf"

My SQL/MariaDB backup is failing or empty.

Q: My SQL/MariaDB backup is failing or empty.

A: This is usually a permission issue.

BmuS uses mysqldump. Ensure that the user defined in .bmus_credentials has the necessary rights (LOCK TABLES, SELECT, SHOW VIEW) for the databases you are trying to back up. Also, check if the MariaDB service is actually running.

systemctl status mariadb

Why can’t I use Deduplication and Encryption at the same time?

Q: Why can't I use Deduplication and Encryption at the same time?

A: BmuS prevents this combination to protect you from inefficiency.

Deduplication relies on recognizing identical files to create hardlinks. Encryption scrambles the file content and filename with a unique "salt" every time. Therefore, the same file looks different every day after encryption. Enabling both would result in zero space savings while still creating the complex directory structure.

Can I simply copy the backup files from my NAS to a USB stick to take them with me?

Q: Can I simply copy the backup files from my NAS to a USB stick to take them with me?

A: Yes. Since BmuS uses file-based encryption (FUSE), every file on your NAS corresponds to one file on your source, just with a scrambled name and content. You can copy/move these encrypted folders just like normal files. To read them, you just need to mount them again with the correct key.

My computer died. How do I access my encrypted backups?

Q: F***. My computer died. How do I access my encrypted backups?

A: Because BmuS uses standard gocryptfs, you are not locked into this script. You can access your data on any Linux machine (or even Mac/Windows with compatible tools) that has gocryptfs installed.

CRITICAL: You absolutely need two things to restore your data on a new machine:

1. The Password File (or the password itself).
2. The gocryptfs.conf file located inside the encrypted backup folder on your NAS.

Pro Tip: Keep a copy of your encryption password and the gocryptfs.conf in a safe place (e.g., a password manager), separate from the Pi/Computer.

Mount Error

My dashboard shows a red "Mount Error". What should I do?

A: This usually means your NAS or backup target is unreachable.

1. Check if the IP address in bmus.conf is correct.
2. Check if your NAS is awake and connected to the network.

• 3. BmuS tries to ping the NAS before mounting. If the ping fails, it aborts to prevent freezing.

Rsync exit code 24

Q: I see "Rsync exit code 24" (Vanished Files) in the logs. Is my backup broken?

A: No, your backup is likely fine.

Error 24 means "File vanished during source-filter." This happens when a temporary file (like a browser cache file or a lock file) exists when rsync scans the directory but is deleted by the system before rsync can copy it. BmuS automatically detects this code and considers the backup "Successful" (Green status) because no important data was lost.

How do I automate BmuS to run every night?

BmuS is designed to be run via cron. You don't need to keep a terminal window open.

To run the backup every night at 03:00 AM, open your crontab (crontab -e or sudo crontab -e) and add:

Bash

0 3 * * * sudo /home/pi/bmus.sh > /dev/null 2>&1

Note: I recommend running it as sudo (root) to ensure it has permission to read all system files and mount drives.

Why is my deduplication rate low?

My dashboard shows low efficiency/deduplication rates, even though I haven't created many new files. Why is so much storage being used?

A: BmuS uses file-based deduplication (via hardlinks). This means: A file is only linked to save space if it is 100% identical to the version from the previous day. As soon as even a single bit changes, BmuS must copy the entire file again.

Here are the most common reasons for a low rate:

1. Large, Changing Files (VMs & Containers) This is the "arch-enemy" of hardlinks.

• Example: You have a 50 GB Virtual Machine image (or a VeraCrypt container).
• Problem: You start the VM and change only a small text file inside it. To the file system, the "timestamp" and checksum of the massive 50 GB file have changed.
• Result: BmuS must copy the full 50 GB again. No deduplication takes place.

2. Database Dumps (SQL) BmuS automatically creates SQL dumps (.sql).

• Problem: Almost every SQL dump contains the current date and time of creation in the header (e.g., -- Dump completed on 2025-11-30 14:00:00).
• Result: Even if not a single record in the database has changed, the text file is technically a "new file" due to the new timestamp in the header. It is saved anew every day.

3. Metadata Changes (Photos & Music) Did you re-tag your MP3 collection or edit photos in management software (like Lightroom)?

• Problem: Even if the image looks visually the same – as soon as a keyword (tag) or rating is written into the file, the file content changes.
• Result: All affected files are detected as "new" and fully copied.

4. Moving or Renaming Folders Did you move a large folder "Vacation 2023" from /Photos/New to /Photos/Archive?

• Problem: rsync (the engine behind BmuS) often does not recognize "moves" as such. It sees: "Oh, files in /Photos/New were deleted" and "Hey, lots of new files in /Photos/Archive".
• Result: The files are created anew at the new location (consuming storage space) instead of just being linked.

5. Encryption (Indirect Effect) If you use encryption (BACKUP_ENCRYPTION=1), this applies even more strictly.

• Problem: Since filenames and contents are encrypted, BmuS cannot "look inside" the file to compare it with previous plain versions.
• Result: If deduplication doesn't work well in plaintext (see points 1-4), it definitely won't work in an encrypted state. (Note: BmuS technically prevents enabling both simultaneously to avoid this inefficiency).

💡 Optimization Tip: If you have huge files that change minimally every day (e.g., VM images), consider excluding them via BACKUP_EXCLUDE or accept the higher storage requirement. For databases and normal documents, this behavior is normal and usually uncritical, as these files are often small.

Troubleshooting

NAS not accessible

# Ping-Test
ping -c 4 192.168.0.xxx # NAS IP

# Check firewall
sudo ufw status

Mount failed

Check SMB version (possibly vers=2.0 instead of vers=3.0)

Adjust the bmus.sh line with mount -o username=…

# Manual mount test
sudo mount -t cifs //192.168.0.xxx/Backup /mnt/workstation \
-o username=user,password=pass,vers=3.0

MySQL dump failed

# Test MySQL connection
mysql -u user -p -e "SHOW DATABASES;"

# Check permissions
mysql -u user -p -e "SHOW GRANTS;"

Email not sent

msmtp must be installed beforehand.

https://marlam.de/msmtp/
https://github.com/marlam/msmtp

# Test msmtp configuration
echo "Test" | msmtp --debug your@email.com

# Check msmtp config
cat ~/.msmtprc

Dashboard without charts

iOS/Apple Mail: Charts do not load in Preview
Solution: Use WebDAV link or save file
Chart.js missing: Check CDN connection:

curl -I https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js

Is BmuS Open Source?

No. It is a "Internal Use" or "Freeware for Business" license.

Here is the license:

BmuS COMMUNITY SOURCE - AVAILABLE LICENSE

Copyright (c) [2025] [Niels Gerhardt / BmuS - Back Me Up Scotty]

1. GRANT OF LICENSE
   Permission is hereby granted, free of charge, to any person or entity obtaining a copy of this software and associated documentation files (the "Software"), to use the Software for PERSONAL and INTERNAL BUSINESS purposes, subject to the following conditions: a) Internal Use: You may install and use the Software on an unlimited number of devices owned or controlled by you or your organization to perform backups of your own data or systems.
   b) Modification: You may modify the source code of the Software for your own internal needs or adaptation.
2. RESTRICTIONS
   The rights granted above are strictly limited by the following prohibitions: a) No Sale or Resale: You may NOT sell, rent, lease, license, or sub-license the Software or any parts thereof. The Software must remain free of charge.
   b) No Commercial Distribution: You may NOT include this Software as part of a paid product, service package, or commercial distribution.
   c) No "Backup-as-a-Service": You may NOT use the Software to offer a paid backup service to third parties where the Software itself is the primary value proposition.
   d) No Public Redistribution: You may NOT redistribute, upload to public repositories, or publish the source code or binaries (original or modified) to the general public.
3. OWNERSHIP
   The original Author retains all right, title, and interest in and to the Software. Modifications made by you remain your property but are subject to the distribution restrictions of this license (i.e., you cannot sell or share your modifications publicly).
4. DISCLAIMER OF WARRANTY
   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. THE AUTHORS OR COPYRIGHT HOLDERS SHALL NOT BE LIABLE FOR ANY DAMAGES, DATA LOSS, OR LIABILITY ARISING FROM THE USE OF THE SOFTWARE. USE AT YOUR OWN RISK.

Missing dependencies

Error: "numfmt: command not found"

sudo apt-get install coreutils

or

sudo apt-get upgrade coreutils

Error: "mount.cifs: command not found"

sudo apt-get install cifs-utils

Error: "msmtp: command not found"

sudo apt-get install msmtp msmtp-mta

Error: "mysqldump: command not found"

sudo apt-get install mysql-client

or

sudo apt-get install mysql-client