OpenHAB
/
openhab-docs
mirror of https://github.com/openhab/openhab-docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Automated openhabian Docs fetch (#2468) 

Co-authored-by: openHAB Bot <info@openhab.org>
pull/2494/head
github-actions[bot] 2025-03-01 19:04:53 +01:00 committed by GitHub
parent b58eb38371
commit 4b85bb3772
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 820 additions and 683 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
installation/images/openHABian-SSH-MotD.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 95 KiB

BIN
installation/images/openHABian-config.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 71 KiB

After

Width:  |  Height:  |  Size: 202 KiB

BIN
installation/images/openHABian-install-failed.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 52 KiB

After

Width:  |  Height:  |  Size: 147 KiB

BIN
installation/images/openHABian-install-log.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 151 KiB

147
installation/openhabian-DEBUG.md
View File

@ -1,147 +0,0 @@
---
layout: documentation
title: openHABian
source: https://github.com/openhab/openhabian/blob/main/docs/openhabian-DEBUG.md
---
<!-- Attention authors: Do not edit directly. Please add your changes to the appropriate source repository -->
This document is meant to give a guiding hand to users when their openHABian install fails either on initial image installation or later on when running menu options that install or configure optional components.
::: tip
[TLDR](https://www.howtogeek.com/435266/what-does-tldr-mean-and-how-do-you-use-it/)
Set `debugmode=maximum`in `/etc/openhabian.conf` and see `/boot/first-boot.log` for image installation else record the terminal output.
:::
**Please do not ask for help on the forum unless you have read this guide.**
::: tip
**Attention:**
If you do not use the image but use `openhabian-config` manually - either to run `openhabian-config unattended` or interactive use -, **there is no logfile**.
To record output in this case, you need to configure your terminal client to record and save the command line output.
In PuTTy there's a field called 'Lines of scrollback' under the 'Window' option in settings that you should increase to at least some thousand lines else you might not capture everything you need to. Configure any other terminal client likewise.
:::
Keep in mind that parts of the following information such as for example Wi-Fi and IPv6 setup don't apply to manually installed systems because they happen at or before boot time.
## Prerequisites
First, please make sure you use the proper host hardware that is supported as per [README](https://github.com/openhab/openhabian/blob/main/README.md).
openHABian requires a minimum of 1GB of RAM to run well. While you can get away with 512MB when your box has enough CPU power like a RPi0W2, you must not run anything other than openHAB itself, in particular do **not** run memory hogs such as InfluxDB or Grafana.
openHABian requires you to provide direct Internet access for the duration of the installation.
Using private IP addresses is fine as long as your router properly provides NAT (Network Address Translation) services.
Either Ethernet or WiFi is supported at install time. WiFi requires either user configuration prior to the first boot of openHABian or to use the [hotspot](openhabian.md#wi-fi-hotspot) which will be launched whenever there's no Internet connectivity.
To configure WiFi, edit the `wifi_password=`, `wifi_ssid=` and `wifi_country=`fields in the `boot/openhabian.conf` file on your new SD card.
Your router (or a separate device) needs to provide properly configured DHCP services so your openHABian box gets an IP address assigned when you boot it for the first time.
The DHCP server also has to announce which DNS resolver to use so the box we install knows how to translate DNS names into IP addresses.
It also needs to announce which IP address to use as the default gateway to the internet - a typical access router is also the DHCP server and will announce it's own address here.
Finally, the DHCP server should also announce the NTP server(s) to use for proper time services.
Lack thereof will not break the installation procedure but can lead to all sorts of long term issues so we recommend to setup DHCP to announce a reachable and working NTP server.
A note on fixed IP addressing: openHABian does NOT support setting fixed IP address. That'll interfere with the other methods to configure networking. Don't mess with the Linux config files even if you are proficient in Linux. If you want to have a static IP, instead get the MAC address of your box and configure your DHCP server to map that MAC to the very specific IP you would like to obtain.
A note on IPv6: openHABian was reported failing to boot in some environments that make use of IPv6.
If basic IP initialization fails (you cannot `ping` your box) or installation gets stuck trying to download software packages, you might want to try disabling IPv6.
You can also do that before the very first install attempt if you're sure you don't need any IPv6 connectivity on your openHABian box.
See [this section of openhabian.md](https://github.com/openhab/openhabian/blob/main/docs/openhabian.md#ipv6-notes) how to disable IPv6 on your system.
Note that this is just a summary to cover the most commonly encountered cases.
The full boot procedure and how to obtain IP addresses, DNS resolver, default route and NTP server addresses are highly complex and widely customizable and a comprehensive description on how to properly configure your Internet access and router are out of scope of openHABian docs.
Please use an internet search to find more on your own.
## Install
Proceed to installation: Flash-whatever the image to an SD card. Use the Raspi Imager or Etcher.
NOW, read [openhabian.md](https://github.com/openhab/openhabian/blob/main/docs/openhabian.md#openhabianconf) how to access your SD card and how to modify the openHABian config file on there.
Some parameters are self-explanatory but some are not so please nonetheless read their full explanation in the linked document.
Given that you're already reading the debug guide, the most important parameter to set is likely `debugmode=maximum`.
Once you have passed the first time boot initialization phase and you can login to the system, `/etc/openhabian.conf` will be used from there on.
You can change it at any time to get output on future boot runs or if you use `openhabian-config` interactively.
_At this stage, read the first paragraph on the logfile and interactive use again._
To see debug output during the image installation process, you need to use the procedure from your PC **before** you power your box on.
If you have a console available (monitor and keyboard), you may attach it to follow the install process **but** be aware that attaching a keyboard may cause the installation to fail.
Now insert the SD card and turn on your system.
If you don't have any console, access the web console at `http://<yourhostip>:81/`.
It will display the contents of `/boot/first-log.boot` at intervals of some seconds while installing.
Mind you that if installation fails, network access may or may not be possible so you might need to access the box via console anyway in order to find out what went wrong.
Login to your box via network using `ssh openhabian@<hostname>`.
The default hostname is `openhabian`, and the default username and password both are `openhabian` unless you changed either of these in `openhabian.conf` before you started the installation run.
If that step fails, try to `ping openhabian`.
If that's failing, find out the system's IP address (usually by looking at your router's running configuration or using the command `arp -a` which is available on either Windows or Linux).
If you can login, there probably is an issue with your DHCP server.
If you cannot ping the system's IP address, try to login on the console.
In this case you will have to resort to debug the network setup which is beyond the scope of this document.
There's nothing specific about networking though - openHABian just uses the setup of the underlying OS, Raspi OS for RPis that is or whatever OS you chose to manually install upon.
So again, use an internet search to find more on your own.
Once logged in, enter `sudo bash` to become the root user.
Check if your install fails at some stage (also if it seems to hang forever): there will exist a file either `/opt/openHABian-install-failed` or `/opt/openHABian-install-inprogress` to reflect these states (to check, `ls -l /opt/openHABian-install*`).
As a first troubleshooting step, you should reboot your box to see if the same problems occurs on a second attempt.
## Debug
If the problem persists after booting succeeded at least in principle, login and check `/boot/first-boot.log` to get an indication what went wrong in the install process.
You can avoid openHABian to start reinstalling on future reboots by removing the status file, i.e. `rm -f /opt/openHABian-install*`, **but** be aware that your installation is incomplete and that you should not run openHAB on a box in that state.
You can use this state to debug, you can also use the menu options in `openhabian-config` to manually install everything that failed or is missing.
See `/opt/openhabian/openhabian-setup.sh` and the corresponding code in `/opt/openhabian/functions/*.bash` what usually gets installed on an unattended installation.
Note that if you keep or recreate the status file (just `touch /opt/openhabian-install-failed`), you can reboot at any time to continue unattended installation.
So if say Java install fails (Java being a prerequisite to installation of openHAB), you can use `openhabian-config` or manual install, then continue installation by rebooting.
Should you succeed at some point in time - great! Let us know what you did to make it work please through a Github issue (see below).
As we cannot be sure everything on your box is 100% the same what an unattended install gets you, please also do a complete reinstall before you start operating openHAB.
If possible start with the flash step.
If that does not work, at least delete all the packages that openhabian-setup had installed before you reboot.
Use `apt purge` (and not just `apt remove`).
### Create a debug log
You can put openHABian into a more verbose debug level **at any time** after the very first installation run: edit the config file `/etc/openhabian.conf` using the editor of your choice (use `nano` if you have no idea) and change the `debugmode` parameter to either `on` or `maximum` right away (default is `off`).
Specifying `maximum` is usually your best choice as it will have `openhabian-config` show every single command it executes so you might spot the problem right away.
If you open an issue, always provide the maintainers with a logfile at `maximum` detail level.
Your next boot run will also exhibit much more verbose logging.
Remember boot time output will be appended to `/boot/first-boot.log`.
If installation still fails to finish, please retrieve that file from your box, open a GitHub issue (see next paragraph), thoroughly describe the environment conditions and your findings so far and upload the log.
### How to open a Github issue
While written for openHAB, the guideline at <https://community.openhab.org/t/how-to-file-an-issue/68464> also applies to openHABian issues.
Please proceed as told there.
openHABian has its own repository at <https://github.com/openhab/openhabian>.
Search the issues listed there first if 'your' problem has already been seen and eventually opened as an issue by someone else (you should remove the `is:open` filter from the search bar to let you see closed issues).
If so, you may leave a "me too" comment there but please do not open another issue to avoid duplicates.
You can reference other issues (eventually also request to reopen closed ones) and Pull Requests by their number (just type #XXX along with your text, GitHub will insert the proper link).
If you open an issue, we kindly ask you to deliver as much information as possible.
It is awkward and annoying if we need to spend time asking and asking what the real problem is about.
Please avoid that situation, be proactive and tell us in the first place.
Once you opened the issue, copy `/boot/first-boot.log` from your openHABian box over to your desktop and upload it to GitHub.
If you succeed logging on and get to see a banner with system information, please also copy that as part of your issue.
If you're able to help in producing a fix to problems, we happily take any Pull Request.
Explaining git and Github unfortunately is out of our scope (the internet is your friend).
See the guidelines outlined in [CONTRIBUTING.md](https://github.com/openhab/openhabian/blob/main/CONTRIBUTING.md) as well.
For simple fixes to a single file only, you can click through the source starting at <https://github.com/openhab/openhabian> and edit the file online, GitHub will then offer to create the PR.
You can also clone the openHABian repository, make your changes locally and use git to check in your changes and upload them to a repo copy of yours, then follow the git-offered link to create the PR.
## Checkpoint
Remember to always let `openhabian-config` update itself on start.
If you want to change anything to work around some not yet fixed bug, you can directly edit the files in and below `/opt/openhabian` on your box.
Just do not let `openhabian-config` update itself on start as that would overwrite your changes.
You can also clone (download) a different openHABian version than the most current one, e.g. if a maintainer or contributor to openHABian offers or asks you to test-drive a development version.
Set the `clonebranch` parameter in `/etc/openhabian.conf` to the branch name to load, then update `openhabian-config` on start.
**Note**: You must not modify `repositoryurl` to point elsewhere than the official repo.
openHABian will only ever update from there so you can only test drive a test branch that a developer has provided you on the official site.
The main program is in `openhabian-setup.sh`.
If the initial unattended install fails again and again at the same step (say Java installation), you may try to comment that step out.
But mind the code in `build-image/first-boot.bash` towards the end starting with `git clone`.
This is where openHABian updates itself.
If you don't comment that out as well, it'll overwrite your changes on the next install run.
## Disclaimer
For obvious reasons, changing openHABian code is not a supported procedure.
We just want to give you a hint what you _could_ try doing if your install fails and you're sitting there, desperately looking for a fix.
Search the internet and learn for yourself how to edit a file, learn to understand shell programming basics, you're on your own here.
If you change openHABian code on your box, remember for the time it takes to get openHABian officially fixed, you must not let `openhabian-config` update itself on start as that would overwrite your changes.

295
installation/openhabian-amanda.md → installation/openhabian-backup.md
View File

@ -1,141 +1,169 @@
# How to backup your openHABian server using Amanda
---
layout: documentation
title: openHABian Backup
source: https://github.com/openhab/openhabian/blob/main/docs/openhabian-backup.md
---
## The need for recovery
# Backing up openHABian
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.
Accidents happen, electronics wear out, SD cards die, but you don't need to wait until then to prepare for it.
In fact you should not ever do that!
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.
Reconfiguring openHAB and openHABian from scratch can be incredibly painful (trust me, I speak from experience).
If you take a couple of basic precautions and implement some basic backup features when you setup openHABian, you can greatly reduce the chance that you would need to restart from scratch.
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.
We will provide some basic guidance below, please take the time to implement it, we promise you will regret it if you don't!
**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.
## What to Prepare For
**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.**
In an ideal world, you should have a spare for *every* component that you use in your smart home system.
This means having a backup SD card, RPi, router, switch, and any external addons (e.g. ZWave stick).
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.
Since you probably won't actually do that (but you should) here are some simple things that can reduce the headache if it is simply a part of your openHABian instance fails.
But in all reality, we **strongly** recommend getting a ZWave or Zigbee stick of the same model if you use those devices.
### SD card issues
### SD Card Failure
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.
One of the most common points of failure in a Raspberry Pi is an SD card failing.
This is why we *strongly* recommend using SD cards that are labelled "Endurance" as they are made for applications like this.
**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.
#### SD Mirroring
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.
We have a bultin option to mirror SD cards so that you can always have a backup ready.
## Some Amanda background
If you plan to mirror you SD card using the auto-backup features in openHAB, you should purchase 2 of the same model of SD card when you setup your system.
A different model of SD card may work, but sometimes models differ slightly in size causing issues.
If you can't find the same model, play it safe and buy a model larger than what you currently have to use for your backup.
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.
We also provide a couple of different options to allow you to backup your system to a local NAS, cloud storage, or a second SD card.
For more information on these options, please see [Storage Preparation](#storage-preparation).
* 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.
##### Moving the Root Filesystem
# Installation
Moving your system root to a USB stick or SSD is unsupported and dangerous.
It may seem appealing but it cannot be supported by the openHABian maintainers and will not provide a significant amount of additional reliability.
These notes were written for an interactive installation run.
Note openHABian provides the new ["auto backup" feature](https://github.com/openhab/openhabian/blob/main/docs/openhabian.md#auto-backup).
Besides USB sticks and SSD devices still suffer from the same issues as SD cards in the long run.
Overall don't try to do this unless you are confident in what you are doing.
::: danger Moving the Root Filesystem
If you choose to proceed and move your root filesystem, you are on your own!
It is very easy to break your system so proceed with **extreme** caution.
:::
## Builtin Protections
We have included a couple of things with openHABian to reduce the chance of system failure.
### ZRAM
On Raspberry Pi systems with 1+ GB of RAM we install ZRAM by default.
ZRAM helps to reduce wear on the SD card by preventing constant writes to the SD card.
It keeps select logs and persistence data in a compressed RAM disk and then syncs it back to the SD card before shutdown.
The major downside of this is that in the event of sudden power loss you may lose some persistence and logging data.
You can reduce the chance of sudden power loss by putting your openHABian system on a Uninterruptable Power Supply (UPS).
If you would rather not use ZRAM you can use menu option 38 to remove it.
For more information on ZRAM see [zram-config](https://github.com/ecdye/zram-config)
### Auto Backup
We provide a feature that can be setup on first boot to combine SD card mirroring with [Amanda](#amanda) to attempt to automatically configure some sensible backup settings for you as part of the inital install.
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
To configure this you should purchase a second SD card that is *at least* twice the size of your main SD card.
You will also need an SD to USB adapter to use when plugging in your backup card to your system.
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.
To configure these settings before first boot see [Backup Settings](./openhabian.md#backup-settings) for more information.
***
HEADS UP: You need to provide your storage BEFORE you install Amanda.
***
These settings can be configured using menu option 50 following first boot as well.
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](http://web.archive.org/web/20210128074026/https://linoxide.com/linux-how-to/how-to-mount-drive-in-linux/).
The Internet is your friend, but make sure you search for specific terms 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.
## Amanda
*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.
Amanda is a backup solution that is builtin to openHABian to provide rotating backups.
The best way to understand it is to read up on and understand some of the basic Amanda concepts over at [amanda.org](https://www.amanda.org).
Reading more not a mandatory step but it will probably help you understand the basic concepts better.
The world of UNIX and backups *is* complex and in the end, there's no way to fully hide that from you as the user.
Here's a couple of those concepts, but this is not a comprehensive list and if you are having trouble understanding, you will need to read the offical Amanda documentation.
#### History
It's helpful to know that Amanda was originally built to use magnetic tape changer libraries as backup storage in professional data center installations.
These tape changer libraries can operate multiple tape drives in parallel, and a tape commonly stored in what is called a 'slot'.
The ability to backup to a directory was added later, but the 'slot', 'drive' and 'tape' concepts were kept.
That's why in openHABian we will have *virtual* tapes and slots which are implemented as subdirectories (one for each 'tape') and filesystem links (two for the default configuration: `drive0` and `drive1`) which point to a virtual tape.
This means that if you have the `drive1` point to the slot3 directory, it effectively means that tape 3 is currently inserted in drive 1.
#### Amanda on openHABian
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 levels 1 or 2 of others, aiming to have the more or less same amount of data to be backed up every run.
See the Amanda [FAQ](https://wiki.zmanda.com/index.php/FAQ:How_do_I_make_Amanda_do_full_backups_on_weekends_and_incrementals_during_the_week%3F) on full backups for more information.
#### Raw Device Backups
Backing up *raw* devices such as `/dev/mmcblk0` (which is the internal SD card reader of a RPi) can only use a level 0 dump.
So if you include `/dev/mmcblk0` in your disklist, it'll be backed up on *every* 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 less often (e.g. monthly).
#### Storage for Amanda
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).
#### Amanda Filesystem Permissions
Amanda was built on top of UNIX and makes use of its user and rights system, so it is very useful to 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 administrative functions.
Use your personal user instead (i.e `openhabian` by default).
Installation tasks including edits of the Amanda config files, require the 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.
### Storage Preparation
Now once you have read up on all of this and feel you have understood this stuff, the next step will be to prepare your storage.
::: important
You need to provide your storage *before* you install Amanda.
:::
You have to mount the USB stick or disk from your NAS to a directory on your openHABian box.
If you don't know what this means in UNIX terms, please do some internet searches now to learn more.
Your mountpoint should be a directory on your Raspberry Pi with the USB device or NAS mounted to.
#### Networked Storage Warnings
If you have a NAS, you should typically export the storage shares using the NFS protocol.
::: warning
If you are a Windows user, please note that CIFS shares are not supported and will not work.
You should use a properly formatted UNIX shares if you are mounting from a NAS.
:::
Amanda does not work with CIFS because of issues with symlinks.
Additionally it doesn't make sense to use a Windows protocol to share a disk from a UNIX server (which is any NAS) to a UNIX client (openHABian) at all.
If you don't have a NAS, **do not** use your Windows box as the storage server.
Attach a USB stick to your Pi instead for storage.
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.
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
#### NAS Mount Example
```
----- EXAMPLE ONLY ----- Don't use unless you understand what these commands do! ----- EXAMPLE ONLY -----
@ -155,11 +183,12 @@ root@pi:/home/pi#
----- EXAMPLE ONLY ----- Don't use unless you understand what these commands do! ----- EXAMPLE ONLY -----
```
### USB storage mount example
#### USB Mount Example
You cannot use Windows FAT formatting (which is the standard on USB sticks).
You must use the ext4 native Linux filesystem on your stick or USB-attached hard drive.
Remember that the storage area has to be physically (plugged in) and logically (mounted) available anytime Amanda runs.
That's why we do not recommend to use removable media, but if you nonetheless do, the non-Windows filesystem will actually also help you in not accidentially unplugging the storage stick.
That's why we do not recommend using removable media, but if you nonetheless do, the non-Windows filesystem will actually also help you in not accidentially unplugging the storage stick.
```
root@pi:/home/pi# fdisk -l /dev/sda
@ -192,53 +221,59 @@ Writing inode tables: done
Creating journal (8192 blocks): done
Writing superblocks and filesystem accounting information: done
root@pi:/home/pi# mkdir -p /storage/usbstick-linux
root@pi:/home/pi# mkdir -p /storage/usbstick-linux
root@pi:/home/pi# echo "/dev/sda8 /storage/usbstick-linux ext4 defaults,noatime 0 1" >> /etc/fstab
root@pi:/home/pi# mount /storage/usbstick-linux
root@pi:/home/pi# df -k /storage/usbstick-linux
root@pi:/home/pi# df -k /storage/usbstick-linux
Filesystem 1K-blocks Used Available Use% Mounted on
/dev/sda8 13403236 8204144 4495196 65% /storage/usbstick-linux
root@pi:/home/pi#
```
## Software installation
### Amanda Installation
First, mount/prepare your storage (see examples).
Next, double check that your `backup` user has write access to all of the storage area (preferrably, he **owns** the directory): _Create_ a file there (`touch /path/to/storage/file`), check its ownership (`ls -l /path/to/storage/file`), then delete it
(`rm /path/to/storage/file`).
If that does not work as expected (to produce a file that is owned by the `backup` user), you need to change export options on your NAS/NFS server.
See also [paragraph on `no_root_squash`](#storage-preparation) above.
Next, double check that your `backup` user has write access to all of the storage area (preferrably `backup` should **own** the directory).
Now finally, install Amanda using the openHABian menu.
When you start the Amanda installation from the openHABian menu, the install routine will create a directory/link structure in the directory you tell it.
Your local user named "backup" will need to have write access there.
Amanda install routine should do that for you, but it only CAN do it for you if you created/mounted it before you ran the installation.
You can do this by creating a file there: `touch /path/to/storage/test_file`.
Then check its ownership by running: `ls -l /path/to/storage/test_file`.
Finally you can then delete it: `rm /path/to/storage/test_file`.
If that does not produce a file that is owned by the `backup` user, you need to change export options on your NAS/NFS server.
Also ensure you have [no_root_squash`](#storage-preparation) set correctly.
Now finally, install Amanda using the openHABian menu using option 50.
The installation procedure should create the appropriate directory structure in the directory you point it to (which should be the directory your storage is mounted on).
Your local user named `backup` will need to have write access there.
Amanda install routine should do that for you, but it can only do it for you if you created/mounted it before you ran the installation.
Installation will ask you a couple of questions.
* "What's the directory to store backups into?"
Here you need to enter the _local_ directory of your openHABian box, also known as _the mount point_.
- "What's the directory to store backups into?"
Here you need to enter the *local* directory of your openHABian box, also known as the *mount point*.
This is where you have mounted your USB storage or NAS disk share (which in above example for the NAS is `/storage/server` and for the USB stick is `/storage/usbstick-linux`).
* "How much storage do you want to dedicate to your backup in megabytes?"
- "How much storage do you want to dedicate to your backup in megabytes?"
Amanda will use at most this number of megabytes in total as its storage for backup.
If you choose to include the raw device in the backup cycle (next question), that means you should enter 3 times the size of your SD disk NOW.
If you choose not to include it (or selected the AWS S3 variant which omits raw SD backups per default), it's a lot less data and you need to estimate it by adding up the size of the config directories that are listed in the `disklist` file.
If you don't have any idea and chose to NOT backup your SD card, enter 1024 (= 1 GByte).
If you chose to backup it, the number should be larger than the SD capacity in megabytes plus 1024.
You can change it in the Amanda config file at any later time (the entry below the line reading `define tapetype DIRECTORY {`).
* "Backup raw SD card?" (not asked if you selected AWS S3 storage)
- "Backup raw SD card?" (not asked if you selected AWS S3 storage)
Answer "yes" if you want to create raw disk backups of your SD card.
This is only recommended if your SD card is 8GB or less in size, otherwise the backup can take too long.
You can always add/remove this by editing `${confdir}/disklist` at a later time.
All of your input will be used to create the initial Amanda config files, but you are free to change them later on.
HEADS UP: if you re-run the install routine, it will OVERWRITE the config files at any time so if you make changes there, remember these changes and store them elsewhere, too.
Once you're done installing openHABian and Amanda, proceed to the usage guide chapter below.
Finally, another HEADS UP: The first thing you should do after your first backup run ended successfully is to create a clone of your active server SD card by restoring the backup to a blank SD card as shown below as an `amfetchdump` example for recovery of a raw device's contents.
::: tip
If you re-run the install routine, it will **overwrite** the config files at any time so if you make changes manually, make sure to save them.
:::
The first thing you should do after your first backup run ended successfully is to create a clone of your active server SD card by restoring the backup to a blank SD card as shown below as an `amfetchdump` example for recovery of a raw device's contents.
`/dev/mmcblk0` is the RPi's internal SD reader device, and from an Amanda perspective, this is a raw device to be backed up to have that same name.
You will have two Amanda config directories (located in `/etc/amanda`) called `openhab-dir` and `openhab-AWS` if you choose to setup both of them.
If any of your Amanda backup or recovery runs fail (particularly if you try to use the S3 backup), you should try getting it to work following the guides and knowledge base available on the web at <http://www.amanda.org/>.
There's online documentation including tutorials and FAQs at <http://wiki.zmanda.com/index.php/User_documentation>.
If any of your Amanda backup or recovery runs fail (particularly if you try to use the S3 backup), you should try getting it to work following the guides and knowledge base available on the web at [amanda.org](https://www.amanda.org).
There's online documentation including tutorials and FAQs at <https://wiki.zmanda.com/index.php/User_documentation>.
In case you come across inherent problems or improvements, please let us (openHABian authors) know through a GitHub issue, but please don't expect us to guide you through Amanda, which is a rather complex system, and we're basically just users only, too.
@ -351,7 +386,7 @@ backup@pi:~$ amcheck openhab-dir
DUMPER STATS TAPER STATS
HOSTNAME DISK L ORIG-kB OUT-kB COMP% MMM:SS KB/s MMM:SS KB/s
-------------------------------------------- ----------------------- -------------- -------------
pi /dev/mmcblk0 0 15645696 7831974 50.1 78:01 1673.2 77:59 1673.9
pi /dev/mmcblk0 0 15645696 7831974 50.1 78:01 1673.2 77:59 1673.9
pi /etc/openhab 0 259820 259820 -- 0:32 8077.0 0:34 7641.8
pi /var/lib/openhab/persistence 0 48720 48720 -- 0:11 4501.6 0:13 3747.7
pi /var/lib/openhab/zwave 0 1370 1370 -- 0:01 1156.1 0:01 1370.0

131
installation/openhabian-troubleshooting.md Normal file
View File

@ -0,0 +1,131 @@
---
layout: documentation
title: openHABian Troubleshooting
source: https://github.com/openhab/openhabian/blob/main/docs/openhabian-troubleshooting.md
---
# openHABian Troubleshooting
::: important
**Please do not ask for help on the forum unless you have read this guide.**
:::
First off sorry that you had to come here, ideally this would never happen but technology and openHABian are both imperfect so here we are.
Hopefully the information in this guide will help and your system will be up and running in no time.
## Quick Checks
First things first, do a sanity check on a couple of simple things.
### Hardware
openHABian may not always perform as expected if running on unsupported or insufficient hardware.
Make sure that your system follows the current guidance given in the main documentation [here](./openhabian.md#hardware).
After checking your hardware, a couple of things to be aware of:
#### Less than 1 GB of RAM
If you are running on a system with less than 1 GB of RAM you will likely experience issues.
You may think you can get away with less than 1 GB of RAM but you won't have enough memory to run much other than openHAB.
If you experience issues then be aware it is unlikely that there will be much we can do to help.
There can be many different problems that having a minimal amount of RAM will cause (slowness, exceptions, unforced reboots, etc.).
There is not one thing you can check so be aware of that.
#### 1 GB of RAM
For systems with 1 GB of RAM then you will probably be fine with most things and even be able to run a couple of extra components.
Your system still has limits and they will be easily reached if you get a bunch of things going to be conservative.
Additionally, running a 64 bit image on only 1 GB of RAM tends to result in the same situation as running on a system with [less than 1 GB of RAM](#less-than-1-gb-of-ram) so probably don't try to do that either.
If you are running an older 32 bit system on 1 GB of RAM is typically fine.
Be aware that when openHAB 5 releases, 32 bit support will be dropped so you won't be able to upgrade to openHAB 5 without switching over to a 64 bit system.
#### 2+ GB of RAM
You probably have enough RAM to run all the packages you want unless you are going crazy so you should probably keep reading to see what else could be going wrong.
### Network Access
openHABian requires direct Internet access for the duration of the installation.
Ensure that your openHABian box has access to the internet and is not being blocked by any settings configured in your router.
Both Ethernet and Wi-Fi are supported at install time.
openHABian will use Ethernet if connected.
If neither Ethernet nor [static Wi-Fi configuration](#Wi-Fi) work and the Internet cannot be reached, the installer will fire up a hotspot with a wireless LAN named `openhabian-<n>`.
Use a mobile device to connect to it, select your home Wi-Fi or enter its name and password and openHABian will connect there permanently, i.e. safe across reboots.
If none of the things listed below work you are going to need to do more research on your own.
Networking is highly complex and there are many different things that could be the issue.
#### Wi-Fi
A non-interactive installation with static use of your home Wi-Fi requires user configuration action prior to the first boot of openHABian.
For more information on how to configure Wi-Fi before first boot see [Wi-Fi Settings](./openhabian.md#wi-fi-settings)
If you would rather not try to do any additional configuration before first boot you can try to make use of the [hotspot](./openhabian.md#wi-fi-hotspot) feature.
Note that if you observe issues after configuring Wi-Fi with hotspot you should attempt to configure it manually as mentioned above just to be safe.
#### DHCP
If you don't know what DHCP is and your network is working fine for everything else you probably have the correct setup and don't need to do any more.
If you do know what it is and have done any configuration of it in the past, go make sure that none of the settings are not blocking anything.
If you think this might be your issue but don't know what it is you should probably do some research about how to change the settings on your router.
::: tip Note
If you want to set a static IP address you need to do it through your router.
Configuring a static IP through openHABian is not supported.
:::
#### IPv6
There have been reports of occasional issues when IPv6 support is enabled in openHABian.
If you observe issues you may try disabling support see IPv6 settings [here](./openhabian.md#ipv6).
## Preparing Debug Logs / Reporting Issues
If you've tried the advice up to this point and it has still failed to install, it is time to dive deeper and enable debug logging.
### Enabling Debug Logs
Before your first boot, you will need to edit `/boot/openhabian.conf` and `debugmode` to `maximum` (or optionally `on` if you think you only need minimal debugging).
If you want even more logging you could also use `maximum` to increase the output (it will show the output of every command run by `openhabian-config`).
See [`debugmode`](./openhabian.md#debugmode) for more information.
After setting `debugmode` boot your system for the first time (yeah again).
Wait for it to complete the setup process, then login and check `/boot/first-boot.log` for the detailed logs.
If you are impatient, you can try and follow along with the installation logs in the web browser at [http://openhabian:81](http://openhabian:81).
If you want to try and salvage a failed install, you will be on your own.
The only option that we can support is a complete reinstall, sorry, there are just too many potential issues to support anything more than that.
### Opening Github Issues
Some helpful general guidance on opening issues for anything openHAB related is given [here](https://community.openhab.org/t/how-to-file-an-issue/68464).
Please take a moment to read through this thread to get a good background on what will come next first.
When you have read the thread above, please be sure to use the openHABian repository located at [openhab/openhabian](https://github.com/openhab/openhabian).
Make sure to search current and closed issues to check if others may have had a similar problem that may offer a solution to you as well.
If you find an issue that matches yours please share your experience and any relevant logs on that issue rather than opening a new issue.
If you are having a hard time seeing closed issues, be sure to remove the `is:open` filter at the start of the search bar.
If you need to open a new issue, please provide as much information as possible.
We have created an issue template that you can fill out when opening a new issue, please follow it and provide all that it asks for.
If possible, please attach a copy of `/boot/first-boot.log` when opening a new issue so that maintainers can look over it.
If you feel like you know the solution to your issue and would like to contribute it, please open a Pull Request.
Explaining `git` and GitHub unfortunately is out of our scope but the internet is your friend.
Double check the guidelines in [CONTRIBUTING.md](https://github.com/openhab/openhabian/blob/main/CONTRIBUTING.md) as well.
## Final Notes
Hopefully something in this guide was helpful and resolved your issue.
Some final things to note:
We cannot support any personal changes you have made to openHABian, so if you encounter an issue because of personal modifications, you will be on your own.
Remember that openHAB and openHABian are both maintained by volunteers, please be patient, we are doing our best and really want to make this a system that you love.
If you discover something that you find useful and want to contribute it back to openHABian, please open an issue and we would be happy to discuss its inclusion (no promises though).

930
installation/openhabian.md
View File

File diff suppressed because it is too large Load Diff