The lionbackup client
Backups run through a lightweight client written in Go that is provided as an open-source client.
What the client does
The client handles the entire local part of a backup run:
- Compressing the selected data,
- Encrypting — with client-side end-to-end encryption enabled, only ciphertext leaves your system,
- Transferring to an available Citadel of the chosen Storage Zone.
If an endpoint fails during the transfer, the client automatically switches to another available Citadel.
Platforms
The client supports Linux, Windows and macOS (beta). Prebuilt binaries are available for download; the source code is publicly available.
Configuration
For operation you store in the local configuration:
- the project-scoped access token,
- with client-side encryption, the key material,
- the paths or data sources to be backed up.
Because the client is open source, it is possible to trace how compression, encryption and transfer work — transparency that fits lionbackup's sovereign orientation.
A complete walkthrough from login to first run is available under Getting started.
Multiple backup jobs on one machine
A project can have several configurations, for example a daily run for
documents and a weekly one for the database. Each configuration names its job
with name::
lionbackup:
name: daily-docs
The name appears in the output and in the name of the log file
(lionbackup-<name>-YYYYMMDD.log). Several configurations can therefore share
one log_directory without their lines getting mixed up in one file. If
name: is missing, the client derives it from the configuration's file name
(daily-docs.yaml → daily-docs). It is best to keep the file name and
name: the same.
Read errors, Windows special folders and run transparency
As of client v0.1.2:
- Windows legacy junctions (hidden compatibility links such as "My Pictures" inside the profile folder) are always skipped – they are unreadable by design and contain no data.
- Read errors below a source (access denied, file removed during the run) default to a warning + skip; the client reports the total of skipped entries at the end. A missing or unreadable source itself still aborts.
- The behaviour is configurable via
on_read_errorinlionbackup.yaml:warn(default) orabortto fail hard on the first error.
on_read_error: warn # or: abort
The client narrates its steps ("Step 1/3: checking sources …", "Source 2/5: …", scan progress every second), so even with very large directories you can see immediately what is happening.
Windows: open files via shadow copy
On Windows, the client reads files that a program currently holds open
exclusively from a shadow copy (VSS) of the drive. This is enabled by
default (use_vss: true) and requires administrator rights. Without them, the
client skips locked files, backs up the rest and lists them in the log. For
backups through the Task Scheduler, therefore choose "Run with highest
privileges".
The shadow copy does read the files of a running database, but without
involving the database. What is reliable is a backup the database writes
itself, for example via a pre_backup command (see below) into a folder the
client backs up.
Hyper-V VMs
From client 0.2.0 on, the client backs up entire VMs on a Windows Server
with the Hyper-V role. The configuration lists only their names, as Get-VM
shows them; on every run the client asks Hyper-V which files belong to them.
lionbackup:
hyperv:
vms:
- FILESRV01
- DC01 # or "*" for all VMs on the host
files: # optional, may be omitted
- D:\Shares
- Application-consistent, without shutting down. The shadow copy is created through DiskShadow with the Hyper-V writer. With the "Backup (volume shadow copy)" integration service in the guest this is an online backup, in which applications such as SQL Server are made consistent as well; without it, Hyper-V briefly puts the VM into a saved state.
- One backup per VM, structured like a Hyper-V export. After restoring,
Import-VMreads it in as a copy with a new ID. - Full backup. Every run backs up the whole VM. We raise the default limit of 100 GB per backup (see Limits) on request.
- Requirements. Windows Server 2025 or 2022, client running as
administrator, VM files on local volumes of a standalone host. The client
rejects VMs on Cluster Shared Volumes or SMB shares, pass-through disks and
VHD Sets with a message. Without DiskShadow (Windows 10/11), or if the
Hyper-V writer fails, it backs up only crash-consistent and warns;
on_writer_error: abortaborts instead. - Older checkpoints after the import. A checkpoint that already existed
before the backup only boots with Secure Boot in the imported VM once the
Secure Boot template has been set again
(
Set-VMFirmware -VM $vm -EnableSecureBoot On -SecureBootTemplate MicrosoftWindows). An import from Hyper-V's own export behaves the same.
A step-by-step guide including a restore test is on the blog: Back up Hyper-V VMs without shutting them down and Restoring a Hyper-V VM from the cloud.
Commands before and after the backup
From client 0.2.0 on, the client runs your own commands listed under
hooks:, for example a database dump before the backup:
lionbackup:
hooks:
pre_backup:
- 'C:\Scripts\backup-database.cmd'
post_backup:
- 'C:\Scripts\after-backup.cmd'
timeout_sec: 3600 # per command, default 3600
| Stage | When | If the command fails |
|---|---|---|
pre_backup | before anything else, even before the sources are checked | The run backs up nothing. |
post_snapshot | as soon as the shadow copy exists, otherwise after reading | The backup continues but ends with an error. |
post_backup | always at the end, even after errors | The run ends with an error. |
Put commands in single quotes: otherwise a colon followed by a space or a #
in the command breaks the YAML. On Windows they run through cmd.exe /C, on
Linux and macOS through /bin/sh -c.
Anyone who can change the configuration can use it to run commands, on a
server often as administrator. Store the configuration so that only
administrators can change it. On Linux and macOS the client refuses hooks: in
a configuration that the group or others may write to.