Alpine Linux - User contributions [en]

Alpine local backup

2025-11-27T04:22:02Z

Antonomy: grammar and formatting

Local backup utility ({{ic|lbu}}) is the Alpine Linux tool for managing [[Diskless Mode]] installations. For these installations, {{ic|lbu}} must be used to [[#Committing changes|commit the changes]] whenever [[Alpine Package Keeper]] is used.

When Alpine Linux boots in diskless mode, it initially only loads a few required packages from the boot device. However, local adjustments to what-gets-loaded-into-RAM are possible, e.g. installing a package or adjusting the configuration files in {{path|/etc}}. The modifications can be saved with {{ic|lbu}} to an overlay file i.e [[Diskless Mode#Apkovl|apkovl]] file, which can be automatically loaded when booting to restore the saved state.

By default, an {{ic|lbu commit}} only stores modifications below {{Path|/etc}}, with the exception of the {{Path|/etc/init.d/}} directory. If a user was created during the {{ic|setup-alpine}} script, that user's home directory is also added to the paths that {{ic|lbu}} will back up. However, {{ic|[[#Include_special_files.2Ffolders_to_the_apkovl|lbu include]]}} enables modifying that set of included files, and can be used to specify additional files or folders.

== Overview ==

The <code>lbu</code> tool has several subcommands to manage the .apkovl:
{|
|-
| lbu commit
| lbu ci
| Create a backup of config to writeable media
|-
| lbu package
| lbu pkg
| Create backup package
|-
| lbu status
| lbu st
| Check what files have been changed since last commit
|-
| lbu list
| lbu ls
| Lists files that would go to tar package. Same as: {{Codeline|lbu package -v /dev/null}}
|-
| lbu diff
|
| Run a diff against last commit
|-
| lbu include
| lbu inc or lbu add
| Add filename(s) to include list{{Path|/etc/apk/protected_paths.d/lbu.list}}
|-
| lbu exclude
| lbu ex or lbu delete
| Add filename(s) to exclude list {{Path|/etc/apk/protected_paths.d/lbu.list}}
|-
| lbu list-backup
| lbu lb
| Show old commits
|-
| lbu revert
|
|Revert to older commit
|-
|}

In the examples below, you will find some characters with special meaning:
* '''|''' = '''or''' ''('lbu commit|ci' means that you can type ether 'lbu commit' or 'lbu ci')''
* '''[ ]''' = '''optional''' ''(In 'lbu commit|ci [-nv]' you can skip the '-n', '-v' or '-nv' part if you don't want it)''

== Committing changes ==

When you "commit" or save changes you've made to your system, <code>lbu</code> will generate a file named something like {{Path|<var>myboxname</var>.apkovl.tar.gz}} ''('myboxname' will be the same as the hostname)''.
The file (which contains your modifications) is called your "apkovl".
You will need to save your apkovl on suitable media (floppy, usb, cf, etc.).
<pre>
Create a backup of config to writeable media.

usage: lbu commit|ci [-nv] [<media>]

Options:
-d Remove old apk overlay files.
-e Protect configuration with a password.
-n Don't commit, just show what would have been commited.
-p <password> Give encryption password on the command-line
-v Verbose mode.

The following values for <media> is supported: floppy usb
If <media> is not specified, the environment variable LBU_BACKUPDIR or
LBU_MEDIA will be used. If LBU_BACKUPDIR is set, nothing will be mounted.

Password protection will use aes-256-cbc encryption. Other ciphers can be
used by setting the DEFAULT_CIPHER or ENCRYPTION environment variables.
For possible ciphers, try: openssl -v

The password used to encrypt the file, can either be specified with the -p
option or using the PASSWORD environment variable.

The environment variables can also be set in /etc/lbu/lbu.conf
</pre>

== Creating an .apkovl "package" elsewhere than on the configured media ==

To "commit" changes, but override the destination of the generated apkovl file, use <code>lbu package</code> instead of <code>lbu commit</code>:

<pre>
usage: lbu package|pkg -v [<dirname>|<filename>]

Options:
-v Verbose mode.

If <dirname> is a directory, a package named <hostname>.apkovl.tar.gz will
be created in the specified directory.

If <filename> is specified, and is not a directory, a package with the
specified name will be created.

If neither <dirname> nor <filename> is specified, a package named
<hostname>.apkovl.tar.gz will be created in the current working directory.
</pre>

To create an apkovl from a client on a remote server, it's possible to use <code>lbu package</code> via SSH with {{Path|-}} as the apkovl name on the server:{{Cmd|ssh root@client "lbu package -" > client.apkovl.tar.gz}}

== Checking what will be added to your apkovl ==

<code>lbu status</code> lists what will be saved the next time you run <code>lbu commit</code>. Its default output is incremental, that is, it shows
only the files that have changed since the last commit. <br>
This can be overridden with the <code>-a</code> flag:

<pre>
usage: lbu status|st [-av]

Options:
-a Compare all files, not just since last commit.
-v show include and exclude lists.
</pre>

Another option is <code>lbu list</code>. This works like <code>lbu status -a</code> but the format of the output is a bit different. (It's strictly equivalent to <code>lbu package -v /dev/null</code>).

usage: lbu list|ls

A third option is <code>lbu diff</code>. This shows the same incremental changes that <code>lbu status</code> (without <code>-a</code>) does, but in a different format.

usage: lbu diff

== Include special files/folders to the apkovl ==

Assume you have some files you want to save permanently, but they are not located in {{Path|/etc}}.<BR>
e.g. {{Path|/root/.ssh/authorized_keys}} (used by <code>sshd</code> to authenticate ssh-users). Such files/folders can be added to lbu's ''include'' list with the following command:

<pre>
usage: lbu include|inc|add [-rv] <file> ...
lbu include|inc|add [-v] -l

Options:
-l List contents of include list.
-r Remove specified file(s) from include list.
-v Verbose mode.
</pre>

{{Note|This information used to be maintained in {{Path|/etc/lbu/include}}. Now it's maintained together with the ''exclude'' list in {{Path|/etc/apk/protected_paths.d/lbu.list}}. Either way, the command <code>lbu include</code> only modifies lbu's configuration. You will need to run <code>lbu commit</code> to actually create/modify your apkovl.}}

== Exclude specific files/folders from the apkovl ==

Assume you have some files located in {{Path|/etc}} or one of its subfolders you ''do not'' want to save.
It could be a log file or status file that for some reason isn't in {{Path|/var/log/}} but in a location that would otherwise be tracked by <code>lbu</code>.
Such files/folders can be added to lbu's ''exclude'' list by manually editing the file or using the following command:
<pre>
usage: lbu exclude|ex|delete [-rv] <file> ...
lbu exclude|ex|delete [-v] -l

Options:
-l List contents of exclude list.
-r Remove specified file(s) from exclude list.
-v Verbose mode.
</pre>
{{Note|As stated above, this information is now maintained in {{Path|/etc/apk/protected_paths.d/lbu.list}}. The command <code>lbu exclude</code> also only modifies lbu's configuration. You will need to run <code>lbu commit</code> to actually create/modify your apkovl.}}

== Multiple backup versions ==

Lbu can keep multiple backups so you can revert back to older configurations. Set BACKUP_LIMIT in {{Path|/etc/lbu/lbu.conf}} to the number of backups you want to keep. Based on BACKUP_LIMIT, the previously active .apkovl will be renamed before creating the new file.

You can list the currently available backups and revert to an older one with the following commands:{{Cmd|<nowiki># lbu list-backup [<media>]
# lbu revert <filename> [<media>]</nowiki>}}

Nothing is changed on your running system when "reverting", it only affects which apkovl is loaded at the next boot.

== Saving and loading ISO image customizations ==

ISO boot images can save running states to [[Diskless Mode#Using an internal disk for persistent storage|system partitions]] and automatically loaded when booting the ISO boot image.

== Execute a script as part of a backup ==

Sometimes it's necessary to run a script before or after a backup. Scripts in two optional directories enable that:

/etc/lbu/pre-package.d
/etc/lbu/post-package.d

Files in those directories are run using run-script rules (meaning they must have the executable bit set, they are run in alphabetical order, and cannot contain an extension. e.g. {{Path|runme}} works, but {{Path|runme.sh}} does not. Also the shebang line on the first line should be indicated, e.g. #!/bin/sh .)

The scripts in {{Path|pre-package.d}} are run before apkovl is created. Scripts in {{Path|post-package.d}} are run after apkovl is created.

=== Example ===

Rather than adding the raw database directories to {{Path|/etc/lbu/include}}, you can do a "database dump". e.g. {{Pkg|postgresql}}:

* Create {{Path|/etc/lbu/pre-package.d/sqldump}} with the following contents: <pre>pg_dumpall -U postgres | gzip -c >/root/pgdatabases.gz</pre>
* Mark the file executable: <code>chmod +x /etc/lbu/pre-package.d/sqldump</code>
* Create {{Path|/etc/lbu/post-package.d/sqldumpdelete}} with the following contents: <pre>rm -f /root/pgdatabases.gz</pre>
* Mark the file executable: <code>chmod +x /etc/lbu/post-package.d/sqldumpdelete</code>
* Finally, add the database dump file to the list of files to back up: <code>lbu include root/pgdatabases.gz</code>

Now when you do a <code>lbu commit</code>, the sql databases are dumped and gzipped to {{Path|/root/pgdatabases.gz}}.
The temporary file is deleted at the end of the lbu commit.

On a catastrophic restore, the databases are not automatically restored (that's not lbu's job), but you will find a complete database dump in the {{Path|/root}} directory, where it can be restored manually.

P.s. These scripts are also launched when starting the commands: diff, list-backup, package, revert, status.

== See also ==

* [[Diskless Mode]]
* [[Back Up a Flash Memory Installation]]
* [[Manually editing a existing apkovl]]

[[Category:Installation]]
[[Category:Booting]]
[[Category:Package Manager]]
[[category: Diskless]]

Alpine local backup

2025-11-27T04:11:48Z

Antonomy: fixes broken diskless mode link

Local backup utility ({{ic|lbu}}) is the Alpine Linux tool to manage [[Diskless Mode]] installations. For these installations, {{ic|lbu}} tool must be used to [[#Committing changes|commit the changes]] whenever [[Alpine Package Keeper]] is used.

When Alpine Linux boots in diskless mode, it initially only loads a few required packages from the boot device. However, local adjustments to what-gets-loaded-into-RAM are possible, e.g. installing a package or adjusting the configuration files in {{path|/etc}}. The modifications can be saved with {{ic|lbu}} tool to an overlay file i.e [[Diskless Mode#Apkovl|apkovl]] file that can be automatically loaded when booting, to restore the saved state.

By default, an {{ic|lbu commit}} only stores modifications below {{Path|/etc}}, with the exception of the {{Path|/etc/init.d/}} directory. If a user was created during the {{ic|setup-alpine}} script, that user's home directory is also added to the paths that <code>lbu</code> will backup up. However, [[#Include_special_files.2Ffolders_to_the_apkovl|lbu include]] enables modifying that set of included files, and can be used to specify additional files or folders.

== Overview ==

The <code>lbu</code> tool has several subcommands to manage the .apkovl:
{|
|-
| lbu commit
| lbu ci
| Create a backup of config to writeable media
|-
| lbu package
| lbu pkg
| Create backup package
|-
| lbu status
| lbu st
| Check what files have been changed since last commit
|-
| lbu list
| lbu ls
| Lists files that would go to tar package. Same as: {{Codeline|lbu package -v /dev/null}}
|-
| lbu diff
|
| Run a diff against last commit
|-
| lbu include
| lbu inc or lbu add
| Add filename(s) to include list{{Path|/etc/apk/protected_paths.d/lbu.list}}
|-
| lbu exclude
| lbu ex or lbu delete
| Add filename(s) to exclude list {{Path|/etc/apk/protected_paths.d/lbu.list}}
|-
| lbu list-backup
| lbu lb
| Show old commits
|-
| lbu revert
|
|Revert to older commit
|-
|}

In the examples below, you will find some characters with special meaning:
* '''|''' = '''or''' ''('lbu commit|ci' means that you can type ether 'lbu commit' or 'lbu ci')''
* '''[ ]''' = '''optional''' ''(In 'lbu commit|ci [-nv]' you can skip the '-n', '-v' or '-nv' part if you don't want it)''

== Committing changes ==

When you "commit" or save changes you've made to your system, <code>lbu</code> will generate a file named something like {{Path|<var>myboxname</var>.apkovl.tar.gz}} ''('myboxname' will be the same as the hostname)''.
The file (which contains your modifications) is called your "apkovl".
You will need to save your apkovl on suitable media (floppy, usb, cf, etc.).
<pre>
Create a backup of config to writeable media.

usage: lbu commit|ci [-nv] [<media>]

Options:
-d Remove old apk overlay files.
-e Protect configuration with a password.
-n Don't commit, just show what would have been commited.
-p <password> Give encryption password on the command-line
-v Verbose mode.

The following values for <media> is supported: floppy usb
If <media> is not specified, the environment variable LBU_BACKUPDIR or
LBU_MEDIA will be used. If LBU_BACKUPDIR is set, nothing will be mounted.

Password protection will use aes-256-cbc encryption. Other ciphers can be
used by setting the DEFAULT_CIPHER or ENCRYPTION environment variables.
For possible ciphers, try: openssl -v

The password used to encrypt the file, can either be specified with the -p
option or using the PASSWORD environment variable.

The environment variables can also be set in /etc/lbu/lbu.conf
</pre>

== Creating an .apkovl "package" elsewhere than on the configured media ==

To "commit" changes, but override the destination of the generated apkovl file, use <code>lbu package</code> instead of <code>lbu commit</code>:

<pre>
usage: lbu package|pkg -v [<dirname>|<filename>]

Options:
-v Verbose mode.

If <dirname> is a directory, a package named <hostname>.apkovl.tar.gz will
be created in the specified directory.

If <filename> is specified, and is not a directory, a package with the
specified name will be created.

If neither <dirname> nor <filename> is specified, a package named
<hostname>.apkovl.tar.gz will be created in the current working directory.
</pre>

To create an apkovl from a client on a remote server, it's possible to use <code>lbu package</code> via SSH with {{Path|-}} as the apkovl name on the server:{{Cmd|ssh root@client "lbu package -" > client.apkovl.tar.gz}}

== Checking what will be added to your apkovl ==

<code>lbu status</code> lists what will be saved the next time you run <code>lbu commit</code>. Its default output is incremental, that is, it shows
only the files that have changed since the last commit. <br>
This can be overridden with the <code>-a</code> flag:

<pre>
usage: lbu status|st [-av]

Options:
-a Compare all files, not just since last commit.
-v show include and exclude lists.
</pre>

Another option is <code>lbu list</code>. This works like <code>lbu status -a</code> but the format of the output is a bit different. (It's strictly equivalent to <code>lbu package -v /dev/null</code>).

usage: lbu list|ls

A third option is <code>lbu diff</code>. This shows the same incremental changes that <code>lbu status</code> (without <code>-a</code>) does, but in a different format.

usage: lbu diff

== Include special files/folders to the apkovl ==

Assume you have some files you want to save permanently, but they are not located in {{Path|/etc}}.<BR>
e.g. {{Path|/root/.ssh/authorized_keys}} (used by <code>sshd</code> to authenticate ssh-users). Such files/folders can be added to lbu's ''include'' list with the following command:

<pre>
usage: lbu include|inc|add [-rv] <file> ...
lbu include|inc|add [-v] -l

Options:
-l List contents of include list.
-r Remove specified file(s) from include list.
-v Verbose mode.
</pre>

{{Note|This information used to be maintained in {{Path|/etc/lbu/include}}. Now it's maintained together with the ''exclude'' list in {{Path|/etc/apk/protected_paths.d/lbu.list}}. Either way, the command <code>lbu include</code> only modifies lbu's configuration. You will need to run <code>lbu commit</code> to actually create/modify your apkovl.}}

== Exclude specific files/folders from the apkovl ==

Assume you have some files located in {{Path|/etc}} or one of its subfolders you ''do not'' want to save.
It could be a log file or status file that for some reason isn't in {{Path|/var/log/}} but in a location that would otherwise be tracked by <code>lbu</code>.
Such files/folders can be added to lbu's ''exclude'' list by manually editing the file or using the following command:
<pre>
usage: lbu exclude|ex|delete [-rv] <file> ...
lbu exclude|ex|delete [-v] -l

Options:
-l List contents of exclude list.
-r Remove specified file(s) from exclude list.
-v Verbose mode.
</pre>
{{Note|As stated above, this information is now maintained in {{Path|/etc/apk/protected_paths.d/lbu.list}}. The command <code>lbu exclude</code> also only modifies lbu's configuration. You will need to run <code>lbu commit</code> to actually create/modify your apkovl.}}

== Multiple backup versions ==

Lbu can keep multiple backups so you can revert back to older configurations. Set BACKUP_LIMIT in {{Path|/etc/lbu/lbu.conf}} to the number of backups you want to keep. Based on BACKUP_LIMIT, the previously active .apkovl will be renamed before creating the new file.

You can list the currently available backups and revert to an older one with the following commands:{{Cmd|<nowiki># lbu list-backup [<media>]
# lbu revert <filename> [<media>]</nowiki>}}

Nothing is changed on your running system when "reverting", it only affects which apkovl is loaded at the next boot.

== Saving and loading ISO image customizations ==

ISO boot images can save running states to [[Diskless Mode#Using an internal disk for persistent storage|system partitions]] and automatically loaded when booting the ISO boot image.

== Execute a script as part of a backup ==

Sometimes it's necessary to run a script before or after a backup. Scripts in two optional directories enable that:

/etc/lbu/pre-package.d
/etc/lbu/post-package.d

Files in those directories are run using run-script rules (meaning they must have the executable bit set, they are run in alphabetical order, and cannot contain an extension. e.g. {{Path|runme}} works, but {{Path|runme.sh}} does not. Also the shebang line on the first line should be indicated, e.g. #!/bin/sh .)

The scripts in {{Path|pre-package.d}} are run before apkovl is created. Scripts in {{Path|post-package.d}} are run after apkovl is created.

=== Example ===

Rather than adding the raw database directories to {{Path|/etc/lbu/include}}, you can do a "database dump". e.g. {{Pkg|postgresql}}:

* Create {{Path|/etc/lbu/pre-package.d/sqldump}} with the following contents: <pre>pg_dumpall -U postgres | gzip -c >/root/pgdatabases.gz</pre>
* Mark the file executable: <code>chmod +x /etc/lbu/pre-package.d/sqldump</code>
* Create {{Path|/etc/lbu/post-package.d/sqldumpdelete}} with the following contents: <pre>rm -f /root/pgdatabases.gz</pre>
* Mark the file executable: <code>chmod +x /etc/lbu/post-package.d/sqldumpdelete</code>
* Finally, add the database dump file to the list of files to back up: <code>lbu include root/pgdatabases.gz</code>

Now when you do a <code>lbu commit</code>, the sql databases are dumped and gzipped to {{Path|/root/pgdatabases.gz}}.
The temporary file is deleted at the end of the lbu commit.

On a catastrophic restore, the databases are not automatically restored (that's not lbu's job), but you will find a complete database dump in the {{Path|/root}} directory, where it can be restored manually.

P.s. These scripts are also launched when starting the commands: diff, list-backup, package, revert, status.

== See also ==

* [[Diskless Mode]]
* [[Back Up a Flash Memory Installation]]
* [[Manually editing a existing apkovl]]

[[Category:Installation]]
[[Category:Booting]]
[[Category:Package Manager]]
[[category: Diskless]]