Skip to main content

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:

  1. Compressing the selected data,
  2. Encrypting — with client-side end-to-end encryption enabled, only ciphertext leaves your system,
  3. 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.
Open source

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_error in lionbackup.yaml: warn (default) or abort to 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-VM reads 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: abort aborts 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
StageWhenIf the command fails
pre_backupbefore anything else, even before the sources are checkedThe run backs up nothing.
post_snapshotas soon as the shadow copy exists, otherwise after readingThe backup continues but ends with an error.
post_backupalways at the end, even after errorsThe 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.

Commands run with the client's rights

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.