<commit_before># How to backup your openHABian server using Amanda

## The need for recovery

First, make yourself aware how important a comprehensive backup and recovery concept is.
Yes, this text is the README on the backup software part for openHABian that you're reading, but take a couple of minutes to read and think about recovery in a generic sense first.
This might avoid a LOT of frustration.

So you have your smart home working thanks to openHAB(ian).... but what if a component of your system fails?
First thing is: you need spare hardware of EVERY component that needs to work for your smart home to work.
Think of EVERY relevant component and not just the obvious ones.
Think of your Internet router, switch, server, NAS and required addons such as a ZWave or 433MHz radio or WiFi USB stick, proper power supplies and the SD card writer.

Now think of a recovery concept for each of these components: what do you have to do if it fails?
If the SD card in your RPi fails because of SD corruption (a very common problem), you need to have a PREinstalled, at least somewhat current clone SD card that contains all your current OS packages, including all helper programs you might be using (such as say mosquitto or any scripts you might have installed yourself), and your matching CURRENT openHAB config, and more.
If you believe "in case of SD card crash, I'll simply reinstall my server from scratch", then think first!
How long will that take you?
Are you even capable of doing that?
Will the latest version of openHABian/Linux packages be guaranteed to work with each other and with your hardware?
Do you REALLY remember all the parts and places of your system where you configured something related to your server/home network and smart home?
If you're honest to yourself, the answer will often be **NO**.
Yes, you can get your smart home back up working somehow, but it will take several hours, and it will not be a complete restoration of all features and setups you used to have in operation before the crash.

**A specific word of WARNING:**
If you run a ZWave network like many openHAB users do, think what you need to do if the controller breaks and you need to replace it.
A new controller has a different Home ID, so all of your devices will not talk to it unless you re-include all of them (and to physically access devices in quite a number of cases means you need to open your walls!!).
Even if you have easy access, it can take many hours, even more so if it's dark and your ... no I'm **NOT** joking, and I'm not overdoing things.
This is what happened to several people, and it can happen to you, too.
We have seen people be so frustrated that they gave up on openHAB or smart home altogether because of this.
For RaZberry/zwave.me USB stick, you can run the Z-Way software to backup and restore the ZWave network data including the controller.
For the Aeon Gen5 stick, there's a Windows tool available for download.

**NOTE: you will face the same type of problem if you run a gateway unit to control commercial systems such as a HomeMatic CCU or Insteon controller.**

Remember Murphy's law: When your system fails and you need to restore your system for the first time, you'll notice your backup is broken.
So dive into and ensure you have a working restore procedure and don't just believe it'll work BUT TEST IT, and repeat every now and then.

### SD card issues

The most common setup for a openHAB smart home server is to run a Raspberry Pi off its internal SD card, so we provide a backup concept for that one.
But it will also work on most other SBCs (single board computers) and modified configurations (such as if you moved your OS or parts thereof).
Pay special attention to SD card size: different models slightly differ in size.
Any replacement gear must have _at least_ the size of the original card so best is to get two identical cards right in the first place.
If you don't, ensure at least you use the smaller one as your main and the larger one as the replacement card.

**Another word of WARNING:**
Moving your system off the internal SD card does NOT solve SD corruption problems or increase reliability in any other way.
SD cards and USB sticks use the same technology, and SSDs / HDDs still can get corrupted as well, and they can crash, too.
You may or may not want to use Internet / cloud services for various reasons (privacy, bandwidth, cost), so we provide you with one solution that is designed to run on local hardware only.
We provide a config to use a directory as the backup destination.
This can be a directory mounted from your NAS (if you have one), a USB-attached storage stick, hard drive, or other device.
We also provide a config to store your most important data on Amazon Web Services if you are not afraid of that.
We believe this will cover most openHAB backup use cases.
NOTE: don't use CIFS (Windows sharing).
If you have a NAS, use NFS instead.
It does not work with CIFS because of issues with symlinks, and it doesn't make sense to use a Windows protocol to share a disk from a UNIX server (all NAS) to a UNIX client (openHABian) at all.
If you don't have a NAS, DON'T use your Windows box as the storage server.
Attach a USB stick to your Pi instead for storage.
There's many more possible configurations, the software is very flexible and you can tailor it to your own needs if those offers do not match your needs.
You could even use it to backup all of your servers (if any) and desktop PCs, including Windows machines.
Either way, it's not one-or-the-other, you can run multiple configs in parallel.
But in any case, you will need to have a clone SD card with your CURRENT config.

Now all that being said, let's turn to what what you're here for: how to accomplish the software side of backup and restoration.

## Some Amanda background

Best is to read up on and understand some of the basic Amanda concepts over at <http://www.amanda.org>.
That's not a mandatory step but it will probably help you understand a couple of things better.
The world of UNIX and backup IS complex and in the end, there's no way to fully hide that from a user.
Here's a couple of those concepts, but this is not a comprehensive list.
I cannot understand the system for you, that's something you have to accomplish on your own.
Read and understand the Amanda docs.

*   It's helpful to know that Amanda was originally built to use magnetic tape changer libraries as backup storage in professional data center installations.
    It can operate multiple tape drives in parallel, and the tapes used to be commonly stored in what's called a 'slot' inside the tape library cabinet.
*   The default dumpcycle for an openHABian installation is 2 weeks.
    Amanda will run a 'level 0' dump (that means to backup EVERYTHING) once in a dumpcycle and will run 'level 1' dumps for the rest of the time (that means to only backup files that have CHANGED since the last level 0 dump was done, also called an 'incremental' backup).
    Amanda will combine level 0 of some devices with level 1 or 2 of others, aiming to have the more or less same amount of data to be backed up every day (every invocation, actually).
    No, you cannot have it do level 0 on weekends and level 1 else, [see FAQ](https://wiki.zmanda.com/index.php/FAQ:How_do_I_make_Amanda_do_full_backups_on_weekends_and_incrementals_during_the_week%3F).
*   Note for _raw_ devices to backup such as `/dev/mmcblk0` (which is the internal SD card reader of a RPi), nothing but a level 0 dump will work because there is no efficient way to determine what has been changed since the last full dump.
    So if you include `/dev/mmcblk0` in your disklist, it'll be backed up on EACH run.
    If you don't want that (as it'll likely consume the by far largest part of your backup run time and capacity) then remove it from the disklist.
    You can create a second Amanda configuration to only include that raw device and run it say just once every month.
    Essentially you need to create a copy of the /etc/amanda.conf/openhab-dir directory and contents, but a full explanation is out of scope for these docs.
*   Typically, for a backup system to use this methodology, you need the amount of storage to be 2-3 times as large as the amount of data to be backed up.
    The number of tapes and their capacity (both of which are sort of artificially set when you store to a filesystem) determines how long your storage capacity will last until Amanda starts to overwrite old backups.
    By asking you to enter the total size of the storage area, the Amanda installation routine will compute the maximum amount of data that Amanda will store into each tape subdirectory as (storage size) divided by (number of tapes, 15 by default).
    The ability to backup to a directory was added later, but the 'slot', 'drive' and 'tape' concepts were kept.
    That's why here, as a deployment inside openHABian, we will have 'virtual' tapes and slots which are implemented as subdirectories (one for each 'tape') and filesystem links (two by default config, drive0 and drive1) to point to a virtual tape.
    If you have the drive1 link point to the slot3 directory, it effectively means that tape 3 is currently inserted in drive 1).
*   Amanda was built on top of UNIX and makes use of its user and rights system, so it is very useful and you should familiarize yourself with that.
    As a general good UNIX practice, you shouldn’t use functional users such as “backup” (the OS uses functional users to execute tasks with specific access rights) for administration tasks.
    Use your personal user instead (that you have created that at the beginning of your openHABian installation or `openhabian` by default).
    Installation tasks including post-package-installation changes (edits) of the Amanda config files, require to use the `root` user.
    Any ordinary user (such as your personal one) can execute commands on behalf of root (and with root permission) by prepending `sudo` to the command.
    As yourself, prepend "sudo -u backup" to execute the following commands as the "backup" user.

# Installation

These notes were written for an interactive installation run.
Note openHABian comes with the new ["auto backup" feature](https://github.com/openhab/openhabian/blob/main/docs/openhabian.md#auto-backup).
It'll essentially mirror your internal SD card to another (bigger) card in an external card reader and uses the remaining space as your Amanda storage area.
We highly recommend you to make use of this feature on initial openHABian installation, but you can also setup Amanda later on as well.

## Storage preparation

Now once you read up on all of this and feel you have understood this stuff, the next step will be to prepare your storage.

***
HEADS UP: You need to provide your storage BEFORE you install Amanda.
***

That is, you have to mount the USB stick or disk from your NAS to a directory that is LOCAL to your openHABian box.
Specifically for Windows users: if you are not familiar with the UNIX filesystem concept and what it means 'to mount' storage, read up on it NOW.
Various tutorial can be found on the net such as <https://linoxide.com/linux-how-to/how-to-mount-drive-in-linux>.
The internet is your friend, but make sure you ask search for specific things such as “how to mount a NAS disk on a Raspberry Pi” to match your use case.
So NOW, prepare your storage by creating a directory somewhere and by then mounting the USB device or disk you've previously exported (= shared, i.e. made available for mounting) on that directory.
This is your mountpoint.

*For Windows fans: Let's be clear here.
This only works if client AND server side are UNIX machines.
And it only works to use NFS.
If you want to use Windows sharing (CIFS), you can try to use the `nounix` mount option in /etc/fstab of your openHAB machine, but this is known to not work in various cases and to cause trouble.
You are COMPLETELY on your own here.
Using CIFS is **NOT SUPPORTED**.
Let alone it also does not make sense as NFS can do the same but any Windows machine will not run 24x7 as a RPi or NAS will do.

Another specific thing to watch out for when configuring your export share on the NFS server is to add the `no_root_squash` option (that's the name on a generic Linux box, depending on your server OS or UI it might have a different name but it'll be available, too).
Its function is to NOT map accesses of userID 0 (root) to some other UID as your server will do by default.

Here's examples how to mount a NAS (to have the DNS name "nas" and IP address 192.168.1.100) and two partitions from an attached USB stick identified as `/dev/sda8` (Linux ext4) and `/dev/sda1` and Windows vfat(FAT-32) filesystems.

HEADS UP: These are just EXAMPLES.
Device and directory names will be different on your system.
Do not deploy these commands unless you are fully aware what they will do to your system, using a command with a wrong device name can destroy your system.

### NAS mount example

```<commit_msg>Update openhabian-amanda.md<commit_after># How to backup your openHABian server using Amanda

## The need for recovery

First, make yourself aware how important a comprehensive backup and recovery concept is.
Yes, this text is the README on the backup software part for openHABian that you're reading, but take a couple of minutes to read and think about recovery in a generic sense first.
This might avoid a LOT of frustration.

So you have your smart home working thanks to openHAB(ian).... but what if a component of your system fails?
First thing is: you need spare hardware of EVERY component that needs to work for your smart home to work.
Think of EVERY relevant component and not just the obvious ones.
Think of your Internet router, switch, server, NAS and required addons such as a ZWave or 433MHz radio or WiFi USB stick, proper power supplies and the SD card writer.

Now think of a recovery concept for each of these components: what do you have to do if it fails?
If the SD card in your RPi fails because of SD corruption (a very common problem), you need to have a PREinstalled, at least somewhat current clone SD card that contains all your current OS packages, including all helper programs you might be using (such as say mosquitto or any scripts you might have installed yourself), and your matching CURRENT openHAB config, and more.
If you believe "in case of SD card crash, I'll simply reinstall my server from scratch", then think first!
How long will that take you?
Are you even capable of doing that?
Will the latest version of openHABian/Linux packages be guaranteed to work with each other and with your hardware?
Do you REALLY remember all the parts and places of your system where you configured something related to your server/home network and smart home?
If you're honest to yourself, the answer will often be **NO**.
Yes, you can get your smart home back up working somehow, but it will take several hours, and it will not be a complete restoration of all features and setups you used to have in operation before the crash.

**A specific word of WARNING:**
If you run a ZWave network like many openHAB users do, think what you need to do if the controller breaks and you need to replace it.
A new controller has a different Home ID, so all of your devices will not talk to it unless you re-include all of them (and to physically access devices in quite a number of cases means you need to open your walls!!).
Even if you have easy access, it can take many hours, even more so if it's dark and your ... no I'm **NOT** joking, and I'm not overdoing things.
This is what happened to several people, and it can happen to you, too.
We have seen people be so frustrated that they gave up on openHAB or smart home altogether because of this.
For RaZberry/zwave.me USB stick, you can run the Z-Way software to backup and restore the ZWave network data including the controller.
For the Aeon Gen5 stick, there's a Windows tool available for download.

**NOTE: you will face the same type of problem if you run a gateway unit to control commercial systems such as a HomeMatic CCU or Insteon controller.**

Remember Murphy's law: When your system fails and you need to restore your system for the first time, you'll notice your backup is broken.
So dive into and ensure you have a working restore procedure and don't just believe it'll work BUT TEST IT, and repeat every now and then.

### SD card issues

The most common setup for a openHAB smart home server is to run a Raspberry Pi off its internal SD card, so we provide a backup concept for that one.
But it will also work on most other SBCs (single board computers) and modified configurations (such as if you moved your OS or parts thereof).
Pay special attention to SD card size: different models slightly differ in size.
Any replacement gear must have _at least_ the size of the original card so best is to get two identical cards right in the first place.
If you don't, ensure at least you use the smaller one as your main and the larger one as the replacement card.

**Another word of WARNING:**
Moving your system off the internal SD card does NOT solve SD corruption problems or increase reliability in any other way.
SD cards and USB sticks use the same technology, and SSDs / HDDs still can get corrupted as well, and they can crash, too.
You may or may not want to use Internet / cloud services for various reasons (privacy, bandwidth, cost), so we provide you with one solution that is designed to run on local hardware only.
We provide a config to use a directory as the backup destination.
This can be a directory mounted from your NAS (if you have one), a USB-attached storage stick, hard drive, or other device.
We also provide a config to store your most important data on Amazon Web Services if you are not afraid of that.
We believe this will cover most openHAB backup use cases.
NOTE: don't use CIFS (Windows sharing).
If you have a NAS, use NFS instead.
It does not work with CIFS because of issues with symlinks, and it doesn't make sense to use a Windows protocol to share a disk from a UNIX server (all NAS) to a UNIX client (openHABian) at all.
If you don't have a NAS, DON'T use your Windows box as the storage server.
Attach a USB stick to your Pi instead for storage.
There's many more possible configurations, the software is very flexible and you can tailor it to your own needs if those offers do not match your needs.
You could even use it to backup all of your servers (if any) and desktop PCs, including Windows machines.
Either way, it's not one-or-the-other, you can run multiple configs in parallel.
But in any case, you will need to have a clone SD card with your CURRENT config.

Now all that being said, let's turn to what what you're here for: how to accomplish the software side of backup and restoration.

## Some Amanda background

Best is to read up on and understand some of the basic Amanda concepts over at <http://www.amanda.org>.
That's not a mandatory step but it will probably help you understand a couple of things better.
The world of UNIX and backup IS complex and in the end, there's no way to fully hide that from a user.
Here's a couple of those concepts, but this is not a comprehensive list.
I cannot understand the system for you, that's something you have to accomplish on your own.
Read and understand the Amanda docs.

*   It's helpful to know that Amanda was originally built to use magnetic tape changer libraries as backup storage in professional data center installations.
    It can operate multiple tape drives in parallel, and the tapes used to be commonly stored in what's called a 'slot' inside the tape library cabinet.
*   The default dumpcycle for an openHABian installation is 2 weeks.
    Amanda will run a 'level 0' dump (that means to backup EVERYTHING) once in a dumpcycle and will run 'level 1' dumps for the rest of the time (that means to only backup files that have CHANGED since the last level 0 dump was done, also called an 'incremental' backup).
    Amanda will combine level 0 of some devices with level 1 or 2 of others, aiming to have the more or less same amount of data to be backed up every day (every invocation, actually).
    No, you cannot have it do level 0 on weekends and level 1 else, [see FAQ](https://wiki.zmanda.com/index.php/FAQ:How_do_I_make_Amanda_do_full_backups_on_weekends_and_incrementals_during_the_week%3F).
*   Note for _raw_ devices to backup such as `/dev/mmcblk0` (which is the internal SD card reader of a RPi), nothing but a level 0 dump will work because there is no efficient way to determine what has been changed since the last full dump.
    So if you include `/dev/mmcblk0` in your disklist, it'll be backed up on EACH run.
    If you don't want that (as it'll likely consume the by far largest part of your backup run time and capacity) then remove it from the disklist.
    You can create a second Amanda configuration to only include that raw device and run it say just once every month.
    Essentially you need to create a copy of the /etc/amanda.conf/openhab-dir directory and contents, but a full explanation is out of scope for these docs.
*   Typically, for a backup system to use this methodology, you need the amount of storage to be 2-3 times as large as the amount of data to be backed up.
    The number of tapes and their capacity (both of which are sort of artificially set when you store to a filesystem) determines how long your storage capacity will last until Amanda starts to overwrite old backups.
    By asking you to enter the total size of the storage area, the Amanda installation routine will compute the maximum amount of data that Amanda will store into each tape subdirectory as (storage size) divided by (number of tapes, 15 by default).
    The ability to backup to a directory was added later, but the 'slot', 'drive' and 'tape' concepts were kept.
    That's why here, as a deployment inside openHABian, we will have 'virtual' tapes and slots which are implemented as subdirectories (one for each 'tape') and filesystem links (two by default config, drive0 and drive1) to point to a virtual tape.
    If you have the drive1 link point to the slot3 directory, it effectively means that tape 3 is currently inserted in drive 1).
*   Amanda was built on top of UNIX and makes use of its user and rights system, so it is very useful and you should familiarize yourself with that.
    As a general good UNIX practice, you shouldn’t use functional users such as “backup” (the OS uses functional users to execute tasks with specific access rights) for administration tasks.
    Use your personal user instead (that you have created at the beginning of your openHABian installation or `openhabian` by default).
    Installation tasks including post-package-installation changes (edits) of the Amanda config files, require to use the `root` user.
    Any ordinary user (such as your personal one) can execute commands on behalf of root (and with root permission) by prepending `sudo` to the command.
    As yourself, prepend "sudo -u backup" to execute the following commands as the "backup" user.

# Installation

These notes were written for an interactive installation run.
Note openHABian comes with the new ["auto backup" feature](https://github.com/openhab/openhabian/blob/main/docs/openhabian.md#auto-backup).
It'll essentially mirror your internal SD card to another (bigger) card in an external card reader and uses the remaining space as your Amanda storage area.
We highly recommend you to make use of this feature on initial openHABian installation, but you can also setup Amanda later on as well.

## Storage preparation

Now once you read up on all of this and feel you have understood this stuff, the next step will be to prepare your storage.

***
HEADS UP: You need to provide your storage BEFORE you install Amanda.
***

That is, you have to mount the USB stick or disk from your NAS to a directory that is LOCAL to your openHABian box.
Specifically for Windows users: if you are not familiar with the UNIX filesystem concept and what it means 'to mount' storage, read up on it NOW.
Various tutorials can be found on the net such as <https://linoxide.com/linux-how-to/how-to-mount-drive-in-linux>.
The internet is your friend, but make sure you ask search for specific things such as “how to mount a NAS disk on a Raspberry Pi” to match your use case.
So NOW, prepare your storage by creating a directory somewhere and by then mounting the USB device or disk you've previously exported (= shared, i.e. made available for mounting) on that directory.
This is your mountpoint.

*For Windows fans: Let's be clear here.
This only works if client AND server side are UNIX machines.
And it only works to use NFS.
If you want to use Windows sharing (CIFS), you can try to use the `nounix` mount option in /etc/fstab of your openHAB machine, but this is known to not work in various cases and to cause trouble.
You are COMPLETELY on your own here.
Using CIFS is **NOT SUPPORTED**.
Let alone it also does not make sense as NFS can do the same but any Windows machine will not run 24x7 as a RPi or NAS will do.

Another specific thing to watch out for when configuring your export share on the NFS server is to add the `no_root_squash` option (that's the name on a generic Linux box, depending on your server OS or UI it might have a different name but it'll be available, too).
Its function is to NOT map accesses of userID 0 (root) to some other UID as your server will do by default.

Here's examples how to mount a NAS (to have the DNS name "nas" and IP address 192.168.1.100) and two partitions from an attached USB stick identified as `/dev/sda8` (Linux ext4) and `/dev/sda1` and Windows vfat(FAT-32) filesystems.

HEADS UP: These are just EXAMPLES.
Device and directory names will be different on your system.
Do not deploy these commands unless you are fully aware what they will do to your system, using a command with a wrong device name can destroy your system.

### NAS mount example

```
{'fraction_non_alphanumeric': 0.039828102217788354, 'fraction_numerical': 0.0035300437418463665, 'mean_word_length': 4.125467059980334, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 6, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6927217', 'n_tokens_mistral': 6599, 'n_tokens_neox': 6323, 'n_words': 4490}