On-premise backup

🏦

On-premise backup is an optional feature only available in the heylogin Enterprise Plan. Please contact our sales team at sales@heylogin.com.

The on-premise backup feature can be used to keep a full backup of all login data on site in an automated fashion.

Summary

The on-premise backup feature can be used to keep a full backup of all login data in a heylogin organization on a server of your own.

You configure a sever to perform a scheduled backup of heylogin data. This server must be capable of running docker containers. There are no hardware requirements.

The backup application logs in to your organization as a special Service User.

To revoke access of a service user, you can delete or disconnect it at any time like a normal user.

Backups are stored in an encrypted CSV format as .csv.age files.

The CSV format is the same as the export at heylogin.app. It contains login data in a format that can be imported in heylogin, or easily processed by other tools.
Files are encrypted using the age format.

Setup

Note that a full backup of all logins in your organization is, of course, highly sensitive data. The below commands should only be run on a server with good security!

To set up an on-premise backup, follow these steps:

Create a service user in your organization

Open heylogin.app, go to Management

Click “Create service user”

This feature must be enabled for your organization. If you do not see the button, contact sales to upgrade your plan.

Click on the newly created service user to find its Service User ID and Start Code

Create an age key using age-keygen.

The age recipient (also called “public key”) should look similar to this: age1z835qassa65nemmz70n6dgu7meyhl6e887z7tfm57ckmmu3p99qsqgx7w9

The resulting file (usually key.txt) is needed later to decrypt the backup

On your docker-capable server, run the following command:

shell
docker run -it --rm -v /your/config/directory:/state heylogin/backup setup

Replace /your/config/directory with a directory where the application may keep configuration and an internal cache. This data is typically a few megabytes in size at most.

You will be guided through a setup process

Enter Service User ID, Start Code, and your age public key when asked

Performing a backup

You can perform a full backup by running the following command:

shell
docker run --rm --pull=always -v /your/config/directory:/state -v /your/output/directory:/output heylogin/backup backup

Replace /your/config/directory with the same path as above

Replace /your/output/directory with the path where you would like encrypted backup files to be written

Note: The --pull=always option must be used here, otherwise the command might stop working when the locally cached docker image is too old!

Files will be written to the output directory as follows:

${vaultId}_${teamName}.csv.age for teams

${vaultId}_${email}.csv.age for personal logins

Decrypting backups

You can decrypt backup files with your age key.txt file:

shell
age --decrypt -i key.txt -o file.csv file.csv.age

Schedule backups

You can use a systemd timer to perform this backup on a scheduled time.

Use a .service file with a “oneshot” service:

toml
# /etc/systemd/system/heylogin-backup.service
[Unit]
Description=perform heylogin backup
Wants=network-online.target

[Service]
Type=oneshot
ExecStart=docker run --rm --pull=always -v /var/lib/heylogin/state:/state -v /var/lib/heylogin/output:/output registry.heylogin.app/backup backup
# You can start another script here after the backup was successfully placed in /var/lib/heylogin/output, e.g. to upload the data somewhere else
#ExecStartPost=/your/script/for/other/stuff

And add .timer file to call the service on a schedule:

toml
# /etc/systemd/system/heylogin-backup.timer
[Unit]
Description=perform daily heylogin backup
Requires=network-online.target

[Timer]
# Run once a day, at 05:00
OnCalendar=*-*-* 05:00:00

[Install]
WantedBy=timers.target