Creating Backups

Back up your server’s data to a physical drive or a network folder.

Important

Creating backups is an essential responsibility of self-hosting. If you do not make backups, you will eventually lose your data.

Important Info

You can create backups to a physical drive plugged directly into your server, or over-the-air to another device on the same LAN (a network folder).
Backups are encrypted using your master password. If you change your password prior backups retain the original password.
Services may choose to exclude certain files or folders from the backup. For example, Bitcoin excludes the blockchain, since it can be recovered by re-syncing.
Backups can take minutes or hours to complete, depending on your hardware and quantity of data.
To back up a service, StartOS first stops it (if it was running), performs the backup, then restarts it — but only if it was running beforehand. A service that was already stopped stays stopped. Consequently a service cannot be used while it is backing up, though you may continue to use your server and other services in the meantime.
Upon completion, StartOS issues a backup report, indicating which services were backed up, as well as any errors.
Wait for the Backup Complete notification before unplugging a backup drive. StartOS writes out the last of the backup and unmounts the drive before raising that notification, so the drive is safe to remove once it appears. The Backup Progress card reads Complete first, while StartOS is still finishing — the notification is the one to wait for.
Each backup updates the current state on its target. Keep backups on multiple targets for protection against loss of a drive or network share.
The backup targets list shows the free space available on each drive and network folder, so you can confirm your backup will fit before you start.
A backup keeps each service image for the server’s architecture (x86, ARM, or RISC-V). On another architecture, StartOS restores that image under emulation. Reinstall or update the service from the marketplace after the restore so StartOS can select its package for the new server architecture, including a native image where available.
The backup format changed. New backups are written to a StartOSBackupsV2 folder on the target, replacing the older StartOSBackups (V1) format written by StartOS 0.4 betas. A backup made on StartOS 0.3.5.1 is a different, older backup: it is not removed by the Delete old backup button, and StartOS 0.4 never touches it. To free that space, delete it yourself from the drive. StartOS helps you clean up the obsolete V1 data:
- When you select a target that still holds a V1 backup for this server, StartOS warns you before backing up and shows how much free space remains on the target (see below).
- After a backup completes, if the target still contains this server’s V1 backup, StartOS raises a notification reminding you it is no longer needed.
- On the Create Backup page, any target holding this server’s V1 backup shows a Delete old backup button — whether or not a new (V2) backup exists yet. After you confirm, StartOS removes this server’s old V1 backup from the target immediately and reclaims the space it occupied in the background, raising a notification once the space has been fully freed (on a large backup this can take a while); your current StartOSBackupsV2 backup — and any backups belonging to other servers that share the target — are untouched. If this server has no current (V2) backup on that target, StartOS asks for an extra confirmation first, since deleting the old backup would leave this server with no backup there.
Warning

Before backing up, check the free space remaining on the target and make sure your selected services will fit. If space is tight, use the Delete old backup button to reclaim the space this server’s old backup occupies, or choose another drive. A backup started while that space is still being reclaimed in the background waits for the reclamation to finish first, shown as an initial Reclaiming Space phase in the backup’s progress.

Existing backups remain usable for backups and restores with their original filesystem encryption/checksum format until explicitly converted. Normal mounts do not start conversion. The folder remains StartOSBackupsV2; this is separate from the older StartOSBackups folder cleanup described above.

In System → Create Backup, select Update format beside a target to convert this server’s backup. Review the downtime and compatibility warning and enter the selected backup’s master password. Selecting a target to create a backup also offers Update format or Skip when this server’s backup uses the older format. Skipping continues backup creation using the existing format.

Conversion runs in the background. Reopen the target’s conversion control to view weighted overall progress, all conversion phases, and byte/object counts. The completion notification names the target and reports success or the failure’s error message. A failed attempt offers Retry conversion, or Resume conversion when discovery reports it interrupted. An interrupted backup remains unavailable until resumption finishes. Resume conversion revalidates the password and continues from durable migration state. Closing the dialog does not cancel the operation. This control is separate from Delete old backup, which removes the pre-V2 backup folder.

Conversion upgrades encryption authentication and current-version references by rewriting encrypted data. It moves content in batches rather than keeping a second complete copy; free space is still needed for one batch of rewritten data and new index metadata. On a large or remote backup, this can take substantially longer than an ordinary incremental backup. Conversion requires exclusive offline access. Leave the target connected until it finishes; after interruption, explicitly resume conversion before using that store again.

An unreadable encrypted object or log frame does not block the upgrade of healthy data. Damaged data stays unreadable; filesystem I/O failures leave the upgrade resumable.

Without its saved key metadata, StartOS cannot decrypt a managed store. A retry moves such keyless encrypted data to the target’s trash for reclamation before starting over. This includes failed first backups from older releases. Partially populated key metadata is rejected instead.

Warning

Older StartOS releases cannot read an upgraded backup. Upgraded backups reject substitutions of individual stored records against their authenticated current references. An upgrade cannot establish the provenance of older data, prevent rollback to an entire genuine older backup view, or revoke previously copied backup data and key-wrapping metadata.

The discovery date shown before unlocking a backup is editable plaintext. After unlocking a converted backup, the date inside encrypted backup metadata belongs to the authenticated backup view. A genuine older view retains its older protected date; that date does not establish that no newer backup exists.

Command-Line Passwords

start-cli backup target mount, start-cli backup target info, and start-cli package backup restore prompt for the backup password instead of accepting it as a positional argument. Automation can supply it through BACKUP_PASSWORD. CIFS target add/update commands similarly prompt for the share password or read CIFS_PASSWORD; an empty password selects passwordless access. The PASSWORD variable used for CLI authentication remains separate.

Avoid typing secret values into shell commands, where shell history can retain them. The standalone startos-backup-fs utility reads its filesystem credential from standard input or --password-file; password changes read the replacement credential from --new-password-file. It does not accept plaintext password arguments. For StartOS-managed backups, this utility uses the filesystem key managed by StartOS, not the master password accepted by start-cli.

Read-only Snapshots

The low-level startos-backup-fs utility can retain named recovery points without duplicating unchanged file content. Upgraded stores never overwrite stored data in place; a snapshot retains a selected view while the current backup continues to update normally. Retention is manual: delete points when they are no longer needed.

Snapshots require a new-format or explicitly converted store. The low-level conversion command is startos-backup-fs convert /path/to/crypt --password-file /protected/filesystem-key.

Snapshot operations require exclusive offline access. Finish backups and unmount the decrypted filesystem before creating, listing, deleting, or mounting a recovery point. Use the filesystem credential described above, not the StartOS master password:

startos-backup-fs snapshot create /path/to/crypt before-update --password-file /protected/filesystem-key
startos-backup-fs snapshot list /path/to/crypt --password-file /protected/filesystem-key
startos-backup-fs mount /path/to/crypt /mnt/recovery --snapshot before-update --password-file /protected/filesystem-key
fusermount3 -u /mnt/recovery
startos-backup-fs snapshot delete /path/to/crypt before-update --password-file /protected/filesystem-key

The backing directory is StartOSBackupsV2/<server-id>/crypt on the mounted target. Protect the credential file with owner-only permissions. A recovery mount is read-only. Snapshot names use letters, digits, -, _, or ., up to 128 characters; . and .. are reserved.

Snapshot indices are stored in bounded, shared chunks. Metadata and retained changed data require space; the catalog of snapshot descriptors has a 64 MiB limit. After a point is deleted, storage it alone used is reclaimed once the files holding it are mostly unused by the current backup and other retained points. Snapshots share the target’s hardware and do not replace backups on separate devices.

Best Practices

Even with proper backups the risk of data corruption is always non-zero. Therefore it is recommended to take additional care when backing up highly valuable or irreplaceable data like a lightning node:

High quality SSDs should be favored over HDDs as a backup target.
Backup to multiple targets.
If backing up to multiple targets make sure all backups are up to date.
Set up continuous backups where a service offers them. A StartOS backup holds LND’s channel backup only as of the moment it was taken, and leaves Bark Wallet’s database out entirely; a continuous backup keeps a current, encrypted copy on storage you choose.

Physical Drive

Btrfs is the recommended format of your backup drive. Existing EXT4 backup drives remain supported. fat32 and exFAT are not recommended and may not work.

A new drive, or one formatted for another system, can be prepared from StartOS: in System > Create Backup, click “Format a drive”, choose the drive, and confirm. This erases everything on the drive and leaves a single Btrfs partition. The drive must be at least 1 GiB.

Warning

Backing up to USB thumb drives or SD card media is not recommended unless you are using high-endurance, high-quality storage. Low-quality flash memory is prone to corruption and failure over time.

If you are using a Raspberry Pi, backup drive must be self-powered, or be connected via a powered USB hub, to prevent possible data corruption.

Plug the drive into your server.
In StartOS, go to System > Create Backup. The drive appears under Physical Drives; if it doesn’t, click “Refresh”.
Click the drive.
Select the services to back up, or click “Toggle all”, then click “Done”.
Enter your master password.

Network Folder

A network folder backup sends your encrypted backup over the LAN to a shared folder on another device. First, create a shared folder on the target device, then connect to it from StartOS.

Step 1. Create a Shared Folder

Identify or create a folder to store your server backups.

Tip

This folder can be located on an external drive connected to your Mac.
Go to System Settings > General > Sharing and click the “info” icon.
Click the toggle to enable file sharing, then click the “plus” icon and select your backups folder.
Click “Options” and ensure “Share files and folders using SMB” is checked.
Check the box next to the user who owns the folder, then click “Done”.

Warning

If the user you want to share the folder with is tied to an Apple ID, StartOS cannot log in as that user. Create a separate user for the share instead: open System Settings > Users & Groups and click “Add User”. Set “New Account” to Sharing Only, then give it a short name such as start9 and a simple local password. Back in the sharing window, give that user “Read & Write” access to your backups folder, and check the box next to it under “Options”.

Tip

You can find the hostname at the top of the sharing window. The hostname will be an address beginning with smb://. To use as hostname, disregard the smb:// and simply enter the IP address that follows it. Alternatively, you can use the computer hostname (open Terminal and type hostname). Either method will work.

Install Samba if not already:

sudo apt install samba && sudo systemctl enable smbd

Add your user to samba, replacing $USER with your Linux username.
```
sudo smbpasswd -a $USER
```
You will be prompted for your linux password. Then, you must create a new SMB password for the user with permission to write to your new backup share. Keep the password somewhere safe, such as Vaultwarden.
Identify or create a folder to store your server backups. For example:
```
mkdir -p /home/$USER/start9-backup
```
replacing $USER with your Linux username and “start9-backup” with whatever you want the folder to be named.

Tip

This folder can be located on an external drive connected to your Linux machine.
Configure Samba by adding the following to the end of your /etc/samba/smb.conf file:
```
[start9-backup]
    path = /home/$USER/start9-backup
    create mask = 0600
    directory mask = 0700
    read only = no
    guest ok = no
```
Where:
- [start9-backup] is the share name — you can change it, but remember the name, you will need it later.
- path is the full directory path to the folder you created above.
Restart Samba to apply the changes:
```
sudo systemctl restart smbd
```
If your installation of Ubuntu is running a firewall by default or due to your own custom configuration, enter this command to allow connections to Samba. If it generates an error, you can safely ignore it:
```
sudo ufw allow Samba
```

Install Samba if not already:

sudo apt install samba && sudo systemctl enable smbd

Add your user to samba, replacing $USER with your Linux username.
```
sudo usermod -a -G sambashare $USER
sudo smbpasswd -a $USER
```
You will be prompted for your linux password. Then, you must create a new SMB password for the user with permission to write to your new backup share. Keep the password somewhere safe, such as Vaultwarden.
Identify or create a folder to store your server backups.

Tip

This folder can be located on an external drive connected to your Linux machine.
Right click the folder and click “Sharing Options”.
Select “Share this folder” and give the folder a Share name. Remember the name, you will need it later. Click “Create Share”.
If your installation of Mint is running a firewall by default or due to your own custom configuration, enter this command to allow connections to Samba. If it generates an error, you can safely ignore it:
```
sudo ufw allow Samba
```

Install Samba if it is not already installed.

Arch:
```
sudo pacman -S samba
```
Debian and Debian-based:
```
sudo apt install samba
```
CentOS/Redhat
```
sudo yum install samba
```
Fedora
```
sudo dnf install samba
```

Identify or create a folder to store your server backups. Make a note of the directory path. For example:
```
mkdir -p /home/$USER/start9-backup
```
replacing $USER with your Linux username and “start9-backup” with whatever you want the folder to be named.

Tip

This folder can be located on an external drive connected to your Linux machine.
Warning

If you are on Fedora 38+, you need to do an extra step to allow the Samba share in SELinux:
```
sudo semanage fcontext --add --type "samba_share_t" "/home/$USER/start9-backup(/.*)?"
sudo restorecon -R /home/$USER/start9-backup
```
Configure Samba by adding the following to the end of your /etc/samba/smb.conf file:
```
[backup-share]
    path = /home/$USER/start9-backup
    create mask = 0600
    directory mask = 0700
    read only = no
    guest ok = no
```
Where:
- [backup-share] can be replaced with whatever you want (must remain inside brackets). This is your Share Name. Remember the name, you will need it later.
- path is the directory path to the share folder from above.
Open a terminal and enter the following command, replacing $USER with your Linux username:
```
sudo smbpasswd -a $USER
```
This creates a password for the Local Network Share. Keep it somewhere safe, such as Vaultwarden.

Enable and restart Samba to apply the changes:

sudo systemctl enable smbd
sudo systemctl restart smbd

If your Linux system has a firewall enabled by default or due to custom configuration, you may need to allow connections to Samba. The command varies depending on the firewall in use:
- For systems using UFW (commonly found on Debian-based distros):
```
sudo ufw allow Samba
```
- For systems using firewalld (common on RHEL-based distros):
```
sudo firewall-cmd --permanent --add-service=samba
sudo firewall-cmd --reload
```

Ensure you have already created a ZFS pool in Storage > Pools. If you need help, see the TrueNAS CORE documentation.
Create a user for writing backups. Go to Accounts > Users > ADD. Enter a Full Name, Username, and Password. Near the bottom, set “Shell” to nologin and enable “Samba Authentication”. Click “SUBMIT”.
Go to Services > SMB. Enable SMB and check the box “Start Automatically”.
Open a shell and create your backups directory. For example:
```
mkdir /mnt/zpooldisk1/start9backupshare
```
Under Sharing > Windows Shares (SMB), click “ADD”. Set the path to the directory you created. Give the share a name and click “SUBMIT”.
A “Configure ACL” dialog will appear. Click “CONFIGURE NOW”.
On the “Edit ACL” screen, click “Apply User” and select the user you created. Set Permissions Type to “Basic” and Permissions to “Full Control”. Click SAVE.

Step 2. Connect from StartOS

The Hostname field accepts an IP address, a DNS name containing a dot (such as nas.home.arpa), a .local mDNS name, or a bare NetBIOS computer name. For DNS, enter the full name rather than a bare name such as nas.

In StartOS, go to System > Create Backup.
Under Network Folders, click “New”.
Complete the form:

Hostname: The hostname or IP address of your Mac (see the tip in the section above).
Path: The name of your shared folder, not the full directory path.
Username: The Mac user you gave access to the shared folder.
Password: Your password for the above user.

Warning

If you receive Filesystem I/O Error mount error(13): Permission denied and the username belongs to an account tied to an Apple ID, go back to Step 1 and create a Sharing Only user for the share.

Warning

If you receive Filesystem I/O Error mount error(13): Permission denied, ensure you have entered the correct values in the Username and Password fields.

Step 3. Back Up

Click the folder under Network Folders.
Select the services to back up, or click “Toggle all”, then click “Done”.
Enter your master password.

StartOS