diff --git a/build-image/openhabian.conf b/build-image/openhabian.conf index 65720ab8a..4d5b9fd67 100644 --- a/build-image/openhabian.conf +++ b/build-image/openhabian.conf @@ -22,6 +22,13 @@ timezone=Europe/Berlin locales="en_US.UTF-8 de_DE.UTF-8" system_default_locale="en_US.UTF-8" +# Eventually disable all IPv6 e.g. on installation problems +# values: "enable", "disable" +ipv6=enable + +# the framebuffer on RPi is enabled by default +framebuffer=enable + # WiFi settings. An ethernet connection is recommended. # If you have a RPi3 or higher, RPi0W or a supported external WiFi dongle, the WiFi # interface can be setup and used for the initial installation. @@ -38,10 +45,6 @@ wifi_password="" # See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 or /usr/share/zoneinfo/zone.tab wifi_country="" -# Eventually disable all IPv6 e.g. on installation problems -# values: "enable", "disable" -ipv6=enable - # repo and branch to clone from repositoryurl=https://github.com/openhab/openhabian.git clonebranch=openHAB @@ -54,12 +57,13 @@ clonebranch=openHAB # off, on (verbose output in log) or maximum (show every command) debugmode=off -# the framebuffer on RPi is enabled by default -framebuffer=enable - # apt timeout to wait for lock with multiple install actions going on apttimeout=60 +# Java version to install +# Valid arguments: 11, 17, Zulu11-32, Zulu11-64, Zulu21-64, BellSoft21 +java_opt=17 + # fake hardware # force treating your box as if it was a ... # pi5, pi4, pi4_8gb, cm4, pi400, pi3, cm3, pi3+, cm3+, pi2, pi1, cm1, pi0, pi0w, pi0w2, x86 @@ -70,13 +74,9 @@ apttimeout=60 # hwarch= # OS distribution/release -# Valid arguments: raspios, raspbian, debian, ubuntu, stretch, buster, bullseye, bionic, focal +# Valid arguments: raspios, raspbian, debian, ubuntu, stretch, buster, bullseye, bookworm, bionic, focal # osrelease= -# Java version to install -# Valid arguments: 11, 17, Zulu11-32, Zulu11-64, Zulu21-64 -java_opt=17 - # install zram per default, set to "disable" to skip installation zraminstall=enable zram_reset=done # remove when zram is no longer needed to auto update diff --git a/docs/images/openHABian-SSH-MotD.png b/docs/images/openHABian-SSH-MotD.png deleted file mode 100644 index eb5137d40..000000000 Binary files a/docs/images/openHABian-SSH-MotD.png and /dev/null differ diff --git a/docs/images/openHABian-config.png b/docs/images/openHABian-config.png index c843f54c6..4e5aae867 100644 Binary files a/docs/images/openHABian-config.png and b/docs/images/openHABian-config.png differ diff --git a/docs/images/openHABian-install-failed.png b/docs/images/openHABian-install-failed.png index 2c9db9d72..7338c6090 100644 Binary files a/docs/images/openHABian-install-failed.png and b/docs/images/openHABian-install-failed.png differ diff --git a/docs/images/openHABian-install-log.png b/docs/images/openHABian-install-log.png deleted file mode 100644 index a3493ab77..000000000 Binary files a/docs/images/openHABian-install-log.png and /dev/null differ diff --git a/docs/openhabian-DEBUG.md b/docs/openhabian-DEBUG.md deleted file mode 100644 index 941c94d6c..000000000 --- a/docs/openhabian-DEBUG.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -layout: documentation -title: openHABian -source: https://github.com/openhab/openhabian/blob/main/docs/openhabian-DEBUG.md ---- - - - -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://: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@`. -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 also applies to openHABian issues. -Please proceed as told there. -openHABian has its own repository at . -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 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. diff --git a/docs/openhabian-amanda.md b/docs/openhabian-backup.md similarity index 63% rename from docs/openhabian-amanda.md rename to docs/openhabian-backup.md index 0829c39a7..279f67a44 100644 --- a/docs/openhabian-amanda.md +++ b/docs/openhabian-backup.md @@ -1,141 +1,169 @@ -# 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 . -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 provides the new ["auto backup" feature](https://github.com/openhab/openhabian/blob/main/docs/openhabian.md#auto-backup). +--- +layout: documentation +title: openHABian Backup +source: https://github.com/openhab/openhabian/blob/main/docs/openhabian-backup.md +--- + +# Backing up openHABian + +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! + +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. + +We will provide some basic guidance below, please take the time to implement it, we promise you will regret it if you don't! + +## What to Prepare For + +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). + +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 Failure + +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. + +#### SD Mirroring + +We have a bultin option to mirror SD cards so that you can always have a backup ready. + +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. + +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). + +##### Moving the Root Filesystem + +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. + +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 . -There's online documentation including tutorials and FAQs at . +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 . 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 diff --git a/docs/openhabian-troubleshooting.md b/docs/openhabian-troubleshooting.md new file mode 100644 index 000000000..c66d2c8fc --- /dev/null +++ b/docs/openhabian-troubleshooting.md @@ -0,0 +1,128 @@ +--- +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 both supported at install time. + +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 + +WiFi requires user configuration 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). diff --git a/docs/openhabian.md b/docs/openhabian.md index 805ad2de9..857310259 100644 --- a/docs/openhabian.md +++ b/docs/openhabian.md @@ -4,10 +4,6 @@ title: openHABian source: https://github.com/openhab/openhabian/blob/main/docs/openhabian.md --- -{% include base.html %} - - - # openHABian - Hassle-free openHAB Setup You just discovered openHAB and now you are eager to start but you're afraid of setting up a standalone system for it? @@ -19,198 +15,141 @@ openHABian is here to help. ## Features openHABian is a **self-configuring** Linux system setup to reliably operate your openHAB instance 24 hours a day. -It provides: + +A fresh install provides: - Complete **SD-card images pre-configured with openHAB** for the Raspberry Pi line of small single-board computers - The openHABian configuration tool to set up and configure openHAB and many related things on any Debian based system -- Fully automated hassle-free setup without a need for a display or keyboard, connected via Ethernet or [Wi-Fi](#wi-fi-based-setup-notes) -- [Comprehensive capabilities to ensure your system will keep working reliably 24/7](#availability-and-backup) including: - - ZRAM - - [SD card mirroring](#sd-mirroring) - - [Amanda backup system](openhabian-amanda.md) -- [Tailscale](https://tailscale.com/blog/how-tailscale-works/) VPN and [WireGuard](https://www.wireguard.com/) for remote VPN access -- Samba file sharing [pre-configured ready to use shares](https://www.openhab.org/docs/installation/linux.html#mounting-locally) -- Login information screen, powered by [FireMotD](https://github.com/OutsideIT/FireMotD) -- The [Mosquitto](https://mosquitto.org) MQTT broker -- The [InfluxDB](https://www.influxdata.com/) database to store home automation data and [Grafana](https://grafana.com/) to visualize it -- FIND, the [Framework for Internal Navigation and Discovery](https://www.internalpositioning.com/) -- Self-controlled remote access using a [reverse proxy](security.html##running-openhab-behind-a-reverse-proxy) with a [Let's Encrypt](https://letsencrypt.org) certificate +- Fully automated hassle-free setup without a need for a display or keyboard, connected via Ethernet or Wi-Fi (see [networking](#wi-fi-based-setup-notes)) +- Samba file sharing [pre-configured ready to use shares]({{base}}/installation/linux.html#mounting-locally) +- [ZRAM](https://www.github.com/ecdye/zram-config) to reduce wear on SD cards -![openHABian-config menu](images/openHABian-config.png) +With many more optional features available in the `openhabian-config` menu. -## openHABian basics - -openHABian installs the latest major version of **openHAB** (currently 4.x) by default. -Currently the default Java version that will be installed is Java 17. +![openHABian-config menu](images/openHABian-config.png) -### Who should use openHABian? +## Getting Started with openHABian openHABian is for starters *and* expert users. -We sometimes read about people deciding against use of openHABian because they want to install additional software and believe openHABian does not let them do this. -This is not true, however, the best way to ensure a stable system is to avoid installing packages unrelated to openHAB as they may cause issues. -Therefore our recommendation is and will always be to dedicate a single system to only your openHAB instance and avoid using it for other purposes. -Saving another 100 bucks is not worth putting the reliable day-to-day operations of your home at risk. - -With that being said, we can't and won't stop you from doing whatever you want, but don't say we didn't warn you. +openHABian provides a solid base for openHAB and can be configured in any number of ways after the initial install. +We suggest that users keep the packages on the system all openHAB related, this will help keep the system as stable as possible. -### Unsupported usecases +This advice works well with the idea of a single board computer (SBC) as they are meant to cheap and affordable to be used for a single purpose. +Therefore our recommendation is to dedicate a single system (typically a Raspberry Pi) to your openHAB instance and any related software. -We do have to make one thing clear, we cannot and will not provide support for changes made beyond the scope of the base system provided by openHABian. -This means any changes not made by `openhabian-config` to your system will not be supported by the maintainers. -We as the openHABian maintainers are really committed to providing you with a fine user experience. -This takes enormous efforts in testing and is only possible with a fixed set of hardware and software parameters. -If you feel like something is missing and should be supported, feel free to ask if you could contribute support for it to the project. +With that being said, we can't and won't stop you from doing whatever you want, but don't say we didn't warn you. -## Hardware +### Hardware -### Hardware recommendation +#### Hardware Recommendation -Our current recommendation is to get a RPi model 4/5 with 2/4 GB of RAM, whatever you can get hold of for a good price. +Our current recommendation is to get a Raspberry Pi model 4 or 5 with 2 or 4 GB of RAM, whatever you can get for a good price. Older RPi models (or models with less RAM) can be sufficient to run a smallish openHAB setup. -Be warned though, they will not be enough to run a full-blown system with many bindings and memory consuming openHABian features/components such as zram or InfluxDB. +Please note that running 64bit mode on RPi's with only 1 GB of RAM tends not to work super well. -We also recommend an "Endurance" SD card. +You will need an SD card to go along with your Raspberry Pi, SD cards labelled "Endurance" are best for openHABian. Cards labelled "Endurance" can handle more write cycles and will typically last longer for openHAB's use conditions. -We also recommend that you get a 2nd SD card right away and prepare to make use of the [SD mirroring](#sd-mirroring) feature. -Typically this means getting an SD card of the same model or at least the size of your primary one, plus a USB card reader. +Ideally you should purchase two SD cards, and a USB adapter for the second card so that you can make use of the [SD mirroring](./openhabian-backup.md#sd-mirroring) feature. +This will give you a ready to go drop in replacement in the case of any hardware issues later on. -If you want to be on the safe side, order the official 3A power supply, otherwise any old mobile charger will usually do fine. - -### Hardware support +#### Hardware Support All Raspberry Pi models are supported by openHABian. -::: tip Note + +::: info Note With the upcoming openHAB 5 release, we will drop support for anything older than an RPi 3 as openHAB 5 will require a 64 bit processor. ::: -openHABian can run on x86 based systems but you will need to install the OS yourself. +openHABian can run on x86 based systems but you will need to install debian yourself. +See [installation on other Linux systems](#installation-on-other-linux-systems) for directions on what to do. -Anything else ARM based such as ODroids, OrangePis and the like may or may not work. -NAS servers such as QNAP and Synology boxes are not supported. -We do not actively prohibit installation on any hardware, including unsupported systems, *but we probably will **not** offer support for any issues you encounter*. +All other system combinations do not have official support. +We do not actively prohibit installation on any hardware, including unsupported systems, *but we will **not** offer support for any issues you encounter*. We **strongly** suggest that you stay with a supported version. This will help you and those you will want to ask for help on the forum focus on a known set of issues and solutions. -For ARM hardware that we don't support, you can try any of the [fake hardware parameters](#fake-hardware-mode) to 'simulate' RPi hardware and Raspberry Pi OS. - -### Hardware modifications - -Plugging in HATs like an UPS or USB sticks or even SSDs for storage is fine. -Though please note that we cannot support attaching any hardware that requires additional software or configuration changes. -Also remember that any future changes to openHABian (i.e. by the `openhabian-config` tool) can interfere with any modifications of yours. -Beware that in the future changes you've made may break your box and openHAB experience at anytime. - -#### external boot medium - -We neither recommend nor support using an SSD or other external medium as your boot device. -If you know Linux well enough to manually apply all the required modifications, feel free to do so. -Be warned that this is completely untested and unsupported. -Please don't ask for help if you run into trouble. - -Anybody afraid of SD card issues should use ZRAM and the [SD mirroring feature](#sd-mirroring) to mitigate. -This will provide you with a secondary, up to date SD card, available for swapping in at any time. - -## OS support - -Going beyond RPi images, because openHABian is really just a set of scripts, we support running openHABian on x86 hardware using generic Debian. - -We provide code that is *reported* to run on Ubuntu but we do **not** support Ubuntu so please don't open issues for this (PRs adding support are welcome). -Several optional components such as WireGuard or Homegear are known to expose problems on Ubuntu. - -As of openHAB 4, `buster` and older distros are no longer supported. -You must be on `bookworm` or newer. -We do not recommend upgrading from an older distro without a fresh install. -Please save yourself the pain and re-install using the latest openHABian image and import your config manually instead. - -### 32/64 Bit support +##### 32/64 Bit Image Support Any RPi 3 or newer supports 64 bit operation. Unless you really know what you are doing and have a compelling reason to do so, stick with the 64 bit image. If you do install a 32 bit image, please note that you will be unable to upgrade to openHAB 5 in the future. +On systems with only 1 GB of RAM running the 64 bit image may cause issues as there may not be sufficient RAM. +If you observe issues please consider upgrading to a model with more that 1 GB of RAM. + ### Networking -A working DHCP server is a mandatory prerequisite to openHABian's networking setup. -We recommend you configure your DHCP server to always assign the same IP based based on your RPi's MAC address. -That'll effectively get you a fixed local IP address. +You need to connect your Raspberry Pi to the network by Ethernet or configure Wi-Fi settings before first boot. +If you plan on using Wi-Fi see [first boot configuration](#first-boot-configuration) for how to configure those settings. + +If we fail to connect to any networks on first boot, we will try to open a [Wi-Fi hotspot](#Wi-Fi-Hotspot) that will allow you to connect your Raspberry Pi to Wi-Fi from another device. +The hotspot is temporary and will close once the Wi-Fi connects successfully. +If connection fails the hotspot will return for you to try again. + +#### Wi-Fi Hotspot -Most DHCP servers are part of your router and have an option to allow for this type of mapping. -For example in AVM Fritz!boxes (popular in Germany), it's a simple checkbox you can tick - note it only appears after the address was assigned to a client (your openHABian box) for the first time. +When your openHABian box does not get Internet connectivity through either Ethernet or Wi-Fi (if configured), openHABian will launch a **hotspot**. +Use your mobile phone to scan for Wi-Fi networks, you should be seeing an new unprotected network called `openHABian-` with `` being a digit. +Once connected, most smartphones will transfer you to a web page. +If this does not happen on your mobile device, open your browser on the mobile and point it at [http://raspberrypi.local](http://raspberrypi.local). +If you cannot connect to this address, go to [http://10.41.0.1](http://10.41.0.1). -Please note that it is **not** supported to setup openHABian with a static IP address as described in the Raspberry Pi OS documentation. +On that page you can select the SSID of the network you want to connect your system to. +Provide the password and submit it be aware that as soon as you do, the system will immediately stop the hotspot and attempt to connect to the specified network. +As such your browser will be unable to provide any indication of if the operation succeeded. -When you boot a flashed image for the first time, openHABian will setup and use Ethernet if it is connected. -If not Ethernet is detected it'll also use the `wifi_ssid` and `wifi_password` parameters from `/boot/openhabian.conf` to determine if/how to setup the Wi-Fi interface. +Try to ping the new system's hostname (default is `openhabian`) or check DHCP on your router to see if your openHABian system appeared there. +You can use `sudo comitup-cli` inside openHABian to change networks and eventually remove network credentials. -After these stages it checks for connectivity to the Internet and if that fails, it'll try to open a [Wi-Fi hotspot](#Wi-Fi-Hotspot) that will let you manually connect your system Wi-Fi. -Remember that once the hotspot is started, it'll hide once you have successfully used it to connect your Wi-Fi. -If connection fails it'll return again. +Note that the hotspot will remain on standby and will show up again every time your `wlan0` interface is losing connectivity. +For more information on the hotspot functions see [comitup documentation](https://davesteele.github.io/comitup/). +Most behavior can be tweaked by setting parameters (such as a default password) in `/etc/comitup.conf`. +The hotspot feature is known to work on RPi3 and newer but can expose problems when used with USB Wi-Fi adapters. -## Raspberry Pi prepackaged SD card image +### Installation on Raspberry Pi Systems **Flash, plug, wait, enjoy:** -The provided image is based on the [Raspberry Pi OS Lite](https://www.raspberrypi.org/software/operating-systems/#raspberry-pi-os-32-bit) (previously called Raspbian) standard system. + +The provided image is based on [Raspberry Pi OS Lite](https://www.raspberrypi.org/software/operating-systems/#raspberry-pi-os-32-bit) (previously called Raspbian). openHABian is designed as a headless system, you will not need a display or a keyboard. On first boot, the system will set up openHAB, its tools and settings. -Packages will be downloaded in their *newest* version and configured. -The whole process will take some minutes, then openHAB and all other tools required to get started will be ready to use without further configuration steps. +Packages will be downloaded and configured in their *newest* version. +The whole process will take some time and if all goes well openHAB will be setup and ready to go without needing any additional configuration. **Installation:** - Make sure you meet the [hardware prerequisites](#hardware) first -- [Prepare your local router](#networking) -- Write the image to your SD card using the official [Raspberry Pi Imager](https://www.raspberrypi.org/software/). openHABian can be selected via 'Other specific purpose OS / Home assistants and home automation'. -- Alternatively, you can [download the card image file](https://github.com/openhab/openhabian/releases) and use any flash tool such as [Etcher](https://www.balena.io/etcher/). -- Optionally, you can change a number of parameters *now* to affect the installation. See this section (https://www.openhab.org/docs/installation/openhabian.html#openhabian-conf). As a beginner or if in doubt what an option does, don't change anything. -- Insert the SD card into your Raspberry Pi. Connect your Ethernet. If you want to use Wi-Fi instead, [configure Wi-Fi](#wi-fi-based-setup-notes) before booting or use the hotspot function later on. **Do not attach a keyboard**. Power on and wait approximately 10-30 minutes for openHABian to do its magic. The system will be accessible by its IP or via the local DNS name `openhabian` and you can watch the install progress in your browser at [http://openhabian:81](http://openhabian:81). If for whatever reason networking does not work, openHABian will launch a [hotspot](#Wi-Fi-Hotspot) so if you see that, something's up with your networking. -- Connect to the openHAB UI at [http://openhabian:8080](http://openhabian:8080) -- [Connect to the Samba network shares](https://www.openhab.org/docs/installation/linux.html#mounting-locally) -- **If you encounter any setup problem, [please continue here](#successful)** +- Write the image to your SD card + - Use the official [Raspberry Pi Imager](https://www.raspberrypi.org/software/) select: 'Other specific-purpose OS -> Home assistants and home automation -> openHAB' + - Alternatively download the latest release from [here](https://github.com/openhab/openhabian/releases/latest) and flash using a tool like [Etcher](https://etcher.balena.io) +- Change any settings you want (see [first boot configuration](#first-boot-configuration)) +- Insert the SD card into your Raspberry Pi +- Prepare whatever networking you need (see [networking](#networking)) +- Power on and wait approximately 10-30 minutes for openHABian to do its magic + - You can watch the install progress in your browser at [http://openhabian:81](http://openhabian:81) or whatever your IP address is if the hostname does not work + - If for whatever reason networking does not work, openHABian will launch a [hotspot](#Wi-Fi-Hotspot) +- Connect to the openHAB UI at [http://openhabian:8080](http://openhabian:8080) and make your home smart +- If you encounter any issues, see [troubleshooting](./openhabian-troubleshooting.md) When openHABian has installed and configured your openHAB system, you can start to use it right away. -[Connect to your Raspberry Pi SSH console](https://www.raspberrypi.org/documentation/remote-access/ssh/windows.md) using the username `openhabian` and password `openhabian`. -You should be seeing a welcome screen like the following: -![openHABian login screen](images/openHABian-SSH-MotD.png) +### Installation on Other Linux Systems -➜ Continue at the ["openHABian Configuration Tool"](#openhabian-configuration-tool) chapter below. +You can install openHABian on x86 hardware on top of an existing Debian installation. +Please note that the install process is tailored to work for RPi systems. +We cannot test systems outside of RPis upfront so there may be some issues we cannot anticipate that come up. -### Wi-Fi Hotspot -When your openHABian box does not get Internet connectivity through either Ethernet or Wi-Fi (if configured), openHABian will launch a **hotspot**. -Use your mobile phone to scan for Wi-Fi networks, you should be seeing a new network called `openHABian-` with `` being a digit. -Connecting will work without a password. Once connected, most smartphones will transfer you to a web page. -If this does not happen on your mobile device, open your browser on the mobile and point it at `http://raspberrypi.local` or `http://comitup-`. -This may or may not work for your mobile browser as it requires Bonjour/ZeroConf abilities. -If you cannot connect to this address, go to `http://10.41.0.1`. -On that page you can select the SSID of the network you want to connect your system to. -Provide the password and press the button. -Note that as soon as you do, the wlan0 IP address of your system changes so your mobile browser will not be able to provide you any feedback if that worked out. -Try to ping the new system's hostname (default is `openhabian`) or check DHCP on your router if your openHABian system appeared there. -You can use `sudo comitup-cli` inside openHABian to change networks and eventually remove network credentials. -Note the hotspot may not only become available during installation: it will remain on standby and will show up again every time your `wlan0` interface is losing connectivity. -For more information on hotspot functions see [comitup-cli](https://davesteele.github.io/comitup/). Most behavior can be tweaked by setting parameters (such as a default password) in `/etc/comitup.conf`. -The hotspot feature is known to work on RPi0W, RPi3 and newer but is known to often expose problems with Wi-Fi USB adapters. +Although the core parts of openHABian were reported to work on Ubuntu, it is not supported and untested. +If you try and fail, please help and drop us a note on GitHub with debug log enabled, see [troubleshooting](./openhabian-toubleshooting.md). - -### Other Linux Systems (add openHABian just like any other software) -Going beyond what the RPi image provides, you can also install openHABian on x86 hardware on top of any existing Debian installation. -Please note that the unattended install is tailored to work for Raspberries. -We cannot test HW/OS combos beyond RPis upfront so there is no promise for this work. -Note that although the core parts of openHABian were reported to work on Ubuntu, it is not supported and untested. -If you try and fail, please help and drop us a note on GitHub with debug log enabled, see [DEBUG guide](openhabian-DEBUG.md). - -Start with a fresh installation of your operating system, login and run +Start with a fresh installation of Debian, login and run: ``` bash # start shell as root user sudo bash -``` - -then start installation -``` bash # install git - you can skip this if it's already installed apt-get update apt-get install git @@ -221,20 +160,33 @@ ln -s /opt/openhabian/openhabian-setup.sh /usr/local/bin/openhabian-config cp /opt/openhabian/build-image/openhabian.conf /etc/openhabian.conf ``` -Edit `/etc/openhabian.conf` to match your needs, then finally use +Edit `/etc/openhabian.conf` to match your needs (see [first boot configuration](#first-boot-configuration)). +To start the openHABian setup process run: ``` bash openhabian-config unattended ``` -to install. +When openHABian has installed and configured your openHAB system, you can start to use it right away. + +### Failed Installs + +![openHABian install failed](./images/openHABian-install-failed.png) -## openHABian Configuration Tool +If you see something like this image when you try to log in, we're sorry! +We hoped this would never happen, please jump over to [openHABian Troubleshooting](./openhabian-troubleshooting.md) and start there for next steps. -The following instructions are written for a Raspberry Pi but should be applicable to all hardware / all openHABian environments. +## Going further with openHABian + +### openHABian Configuration Tool + +The following instructions are written for a Raspberry Pi but should be applicable to all openHABian environments. Once connected to the command line console of your system, please execute the openHABian configuration tool by typing the following command: -(Hint: sudo executes a command with elevated rights and will hence ask for your password. The default is `openhabian`). +::: tip Hint +`sudo` executes a command with elevated rights and will hence ask for your password. +The default password is `openhabian`. +::: ``` bash sudo openhabian-config @@ -243,310 +195,476 @@ sudo openhabian-config ![openHABian-config menu](images/openHABian-config.png) The configuration tool is the heart and center of openHABian. -It is not only a menu with a set of options but also used in a special unattended mode to automate the setup run, either as part of the RPi image or in a manual install run. -⌨ - A quick note on menu navigation. +A quick note on menu navigation: + Use the cursor keys to navigate, Enter to execute, Space to select and Tab to jump to the actions on the bottom of the screen. Press Esc twice to exit the configuration tool. -### First steps with openHAB +#### Settings to Adjust + +We try to setup everything for you so that you don't have to do any additional configuration if you don't want to, however there are a couple things that sometimes don't quite work so it is always good to double check them: + +- **Timezone**: Your timezone is typically set by your network, but if it appears to be the wrong time you can use menu option 33 to set it manually. +- **Language**: By default we set the `locale` setting to `en_US.UTF8` as this tends to be the best for error messages, it can be changed using menu option 32. +- **Passwords**: You should change the default password using menu option 34. + +##### Default Passwords + +For reference, the default username and passwords are as follows: + +- Main user (e.g. `ssh` or `sudo`): `openhabian:openhabian` +- Samba share: `openhabian:openhabian` +- openHAB remote console: `openhab:habopen` + +### Actually Using openHAB + +By this point, you should already have a fully functional openHAB setup running on your system. +See [Getting Started - First Steps]({{base}}/tutorial/first_steps.html) for what to do next with openHAB. + +### First Steps with Linux + +You may be thinking that this computer is a little different than your typical desktop machine. +That is because this machine runs on Linux, if you want more information on how to do things on a headless Linux system check out some of the resources linked below. + +- "Learn the ways of Linux-fu, for free." at [linuxjourney.com](https://linuxjourney.com) +- "Now what?" what to do with the terminal at [linuxcommand.org](https://linuxcommand.org) +- Raspberry Pi official documentation at [raspberrypi.org](https://raspberrypi.org) + +### Additional Optional Components + +There are a number of additional tools included with openHABian to enable additional functionality that can be installed. +Each of these are included as a part of `openhabian-config` menu option 20. -After your first setup of openHABian completed successfully, please access the openHAB dashboard to dig into its possibilites. -Check out the [openHAB primers tutorial](https://www.openhab.org/docs/tutorial/). -Be sure to read up on the [Configuration](https://www.openhab.org/docs/configuration/) section of the documentation pages to learn more. +- [InfluxDB and Grafana](https://community.openhab.org/t/influxdb-grafana-persistence-and-graphing/13761/1) - Persistence and Graphing at [http://openhabian:3000](http://openhabian:3000) +- [Eclipse Mosquitto](http://mosquitto.org) - Open Source MQTT v3.1/v3.1.1 Broker +- [Node-RED](https://nodered.org) - "Flow-based programming for the Internet of Things" at [http://openhabian:1880](http://openhabian:1880) +- [Homegear](https://www.homegear.eu/index.php/Main_Page) - Homematic control unit emulation +- [KNXd](http://michlstechblog.info/blog/raspberry-pi-eibknx-ip-gateway-and-router-with-knxd) - KNX daemon running at `224.0.23.12:3671/UDP` +- [OWServer](https://owfs.org) - 1-Wire system of Dallas/Maxim +- [FIND](https://www.internalpositioning.com/) - Framework for Internal Navigation and Discovery +- Mi Flora MQTT daemon + +## First boot configuration -### Linux Hints +Many settings are configurable prior to the first boot of openHABian by changing the key value pairs in the `/boot/openhabian.conf` file on the SD card once you have flashed the initial image onto it. -If you're a newbie to Linux, you sooner or later will have to know some Linux if you want to copy some files or are on the search for a solution to a problem. -Take some time at this stage to study tutorials and get to know the most basic commands and tools to be able to navigate on your Linux system, edit configurations, check the system state or look at log files. +The openHABian configuration file uses key value pairs, essentially a list of `option=value` settings in a plain text file. +All supported options are already in the file but unused options and optional components are commented out by default. +Comments are defined by a `#` followed by a space, so any line you want to be ignored needs to start with a `# ` (yes the space is important). -- "Learn the ways of Linux-fu, for free" interactively with exercises at [linuxjourney.com](https://linuxjourney.com). -- The official Raspberry Pi help articles over at [raspberrypi.org](https://www.raspberrypi.org/help) -- "Now what?", Tutorial on the Command line console at [LinuxCommand.org](http://linuxcommand.org/index.php) +If you don't know what an option does, probably don't change it as the default options are usually best. -### more openHABian configuration +The available options combined with examples are listed below for convenience: -openHABian is supposed to provide a ready-to-use openHAB base system. -There are a few things, however, we need you to decide and act on right now at the beginning: +### System Configuration -- **Timezone:** The time zone of your openHABian system will be determined based on your internet connection. - In some cases you might have to adjust that setting. -- **Language:** The `locale` setting of the openHABian base system is set to "en_US.UTF-8". - While this setting will not do any harm, you might prefer e.g. console errors in German or Spanish. - Change the locale settings accordingly. - Be aware, that error solving might be easier when using the English error messages as search phrases. -- **Passwords:** Relying on default passwords is a security concern you should care about! - The openHABian system is preconfigured with a few passwords you should change to ensure the security of your system. - This is especially important if your system is accessible from outside your private subnet. +#### `hostname` -All of these settings can be changed via the openHABian configuration tool. +Set a custom hostname for the system. -Here are the passwords in question with their respective default "username:password" values. -They can be changed from openHABian menu. +::: details Example +``` +hostname="openhabian" +``` +::: -### Passwords +#### `username` -- User password needed for SSH or sudo (e.g. "openhabian:openhabian") -- Samba share password (e.g. "openhabian:openhabian") -- openHAB remote console (e.g. "openhab:habopen") -- Amanda backup password (no default, applied when installing) -- Nginx reverse proxy login (no default, applied when installing) _For manual configuration see [here](https://www.openhab.org/docs/installation/security.html#adding-or-removing-users)._ -- InfluxDB (No password set by default) -- Grafana visualization ("admin:admin") +Set a custom primary username for the system. -## Availability and Backup +::: details Example +``` +username="openhabian" +``` +::: -openHABian is designed to reliably run 24 hours a day, seven days a week. That's a complex challenge involving hardware, software and operational procedures. -This is the right time to prepare your system for disasters such as getting hit by hardware outages or the SD card wear-out/corruption problem. +#### `adminkeyurl` -Preparing for hardware breakage is the challenge that is the most easy one to overcome with common-off-the-shelf hardware that is known to work as a drop-in replacement the very moment you will be in need of (e.g. when your smart home server just died). +Download a public SSH key from a given URL and authorize the owner of the key to login as the admin user (i.e. the user configured by `username`). -::: tip get your spare hardware ready -Order **spare** pieces of *all* hardware components your home automation relies on to work. At a minimum, that's the computer itself and another storage medium. -Have it ready for use *on site*, unboxed, mounted and tested to be working. +::: details Example +``` +adminkeyurl="https://example.com/mysshkey.pub" +``` ::: -**HEADS UP:** that statement applies to EVERY hardware setup, even if you run openHAB in some virtualization environment on some $$$ x86 server rackmounted in your basement. -For our recommended hardware setup that means getting another Raspberry Pi (same model), 2 more SD cards and a power supply (in case of emergency, a smartphone charger will also do). +#### `timezone` -That being said, openHABian has a number of built in software features we borrowed from professional data center operations. +Timezone to set the system to. +Typically should be set to your current timezone following the "Region/City" general format, see the Debian documentation for more information. -1. SD cards are known they can 'wear out' after some time and crash your OS and openHAB setup and data when they do. See [this community forum post](https://community.openhab.org/t/corrupt-filesystems-every-2-3-month/13057/20) for more information. - The Zram feature moves write intensive parts of openHABian into RAM to mitigate the risk of SD card corruption. - WARNING: power failure will result in some data to get lost (albeit the system should continue to run) so we recommend to also get an UPS. - Zram is enabled by default for swap, logs and persistence data. - You can toggle use in \[menu option 38\]. +::: details Example +``` +timezone="America/Denver" +``` +::: + +#### `locales` -2. SD cards, SSDs and HDDs can break or crash just like any hardware. - Mirror your SD card to have a ready-to-use alternative boot medium ready on site at any time ! - Get an USB card writer and another SD card and set up SD mirroring using \[menu option 53\]. - This will ensure you have an always ready-to-use clone of your storage medium handy at all times. - In case of emergency, you can simply swap SD cards and get back online within just a few minutes. - See [auto backup](#sd-mirroring) documentation. +Set the locales to install for your machine in a space separated list (i.e. the languages to install on system). +See the Debian documentation for more information. -::: tip remote replacement -Disasters love to happen when you're not at home. -With an openHABian RPi mirror SD setup, you can instruct your partner, kid or your cottage neighbour to replace the SD card and/or computer from remote, by phone. No need for Internet or any sort of configuring to get your system back up running. +::: details Example +``` +locales="en_US.UTF-8 de_DE.UTF-8" +``` ::: -3. Use the integrated original openHAB [openhab-cli tool](https://community.openhab.org/t/recommended-way-to-backup-restore-oh2-configurations-and-things/7193/82) at regular intervals to interactively backup/restore your openHAB **config** \[menu option 50/51\]. +#### `system_default_locale` -4. Use [Amanda Network Backup](http://www.amanda.org/) to create full system backups. - HEADS UP: This is NOT meant to be a replacement for #1 or #3, it's a *complement* that will also enable you to restore your system to any point in time of the past. - The specific [Amanda documentation is here](openhabian-amanda.md). - Use \[menu option 52\] to set up. +Set the default locale for the system. +See the Debian documentation for more information. -5. For completeness, openHABian still provides the historic option to move the root filesystem to USB-attached devices. See \[menu option 37\]. - We don't recommend or support doing so but if you're convinced this is beneficial to your situation, feel free to go for it. +::: details Example +``` +system_default_locale="en_US.UTF-8" +``` +::: + +#### `ipv6` + +Enable or disable IPv6 support on your system. + +::: details Example +``` +ipv6="enable" +``` +::: - WARNING 1: openHABian maintainers do not support you in applying hardware modifications to have an effect on the system itself such as to add an SSD drive to boot from. - We clearly recommend not to do this, for your own sake of reliability. +#### `framebuffer` - WARNING 2: USB sticks are as susceptible to flash wear-out as SD cards are, making zram the better choice for a standard Pi to run off its internal SD card. +Enable or disable the Raspberry Pi framebuffer. -Standard openHABian install enables zram by default (#1). -You can disable zram and move the system over using menu options 37 (#5) once you attached a _safe_ external medium to your system (such as an SSD), but we recommend against doing so. -[To restate](#befair): this setup is not supported by us maintainers and you'll be on your very own to find and fix any problems you might run into. +::: details Example +``` +framebuffer="enable" +``` +::: -Finally, we strongly suggest you install Amanda (#4) right after you finish your setup. -Amanda is to take care to backup the whole system to be able to quickly restore it when in need. -This is not done by default because it requires a number of user inputs, but you should not skip it for your own safety! +### Wi-Fi Settings -## Setup notes -### `openhabian.conf` +#### `wifi_ssid` -You can actually set a number of parameters _before_ you run an unattended installation. -This applies to the RPi image on an SD card as well as to a manual installation. -You can also try with a different set of parameters if your initial attempt fails: +Just the name of your Wi-Fi network that you want to connect to. -- Flash the system image to your micro SD card as described, do not remove the SD card yet -- Use Windows file explorer to access the first SD card partition. Re-plug if needed to open in Windows file explorer, it's a vfat/FAT-32 (Windows) filesystem. -- Open the file `openhabian.conf` in a text editor -- Uncomment and complete the lines to contain the parameters you want to set -- Save, unmount/eject, remove and insert into the RPi and boot it -- Continue with the instructions for your hardware +::: details Example +``` +wifi_ssid="myWifiNetwork" +``` +::: -Mind the comments for each configuration parameter. Browse the next documentation section for more explanations. +#### `wifi_password` -#### Initial configuration -You can have openHABian import a working openHAB configuration right from the start at installation time like when you migrate or reinstall: -make the `initialconfig` parameter point to either a file or URL. -Note that you can only place config zipfiles on the 1st (Windows) partition, and that partition will finally be accessible as `/boot` from inside Linux. -So a filename would need to be `/boot/xxx.zip`. Default is `/boot/initial.zip`. -So if you have a openHAB configuration backup zipfile (created e.g. by using menu option 50), put it to the E: device that the first partition of your SD card shows up as on a Windows PC and change its name to 'initial.zip'. +The password for your Wi-Fi network. -#### Administration user -Raspberry Pi OS images include a Linux user (`pi`) that you can use for openHAB administration. -openHABian renames the user to what you specify in the `username` parameter and assigns the `userpw` password first, then it proceeds and makes various settings that are either useful (such as some aliases) or required to run openHAB. -You can also make use of this if you don't use the image but unattended installation on non-RPi hardware, openHABian will then _create_ that user for you if it does not yet exist. +::: details Example +``` +wifi_password="mySuperSecretPassword" +``` +::: -#### Admin key -Make the `adminkeyurl` point to an URL to contain a public SSH key. -This will be included with your administration user's `.ssh/authorized_keys` and the openHAB console so the admin user (yourself, usually) can login right after installation without a password. This helps with automating deployments. +#### `wifi_country` -#### Wi-Fi based setup notes -To setup openHABian via Wi-Fi only, make your SSID and password known to the system before the first boot. -In addition to the setup instructions given above, uncomment and complete the lines reading `wifi_ssid=""` and `wifi_password=""` in `openhabian.conf`. +The two letter country code for your current location. +Set this according to your current location or you may risk violating regulatory restrctions. -#### Disable zram -Zram is activated by default on fresh installations on ARM hardware. -If you want to disable zram for some reason, use `zraminstall=disable` in `openhabian.conf` to install without. +::: details Example +``` +wifi_country="US" +``` +::: -#### Debug mode -See [Troubleshooting](#troubleshooting) section if you run into trouble installing. -If you want to turn on debug mode edit `openhabian.conf` and set the `debugmode=` parameter to either `off`, `on` or `maximum`. -Mind you that if you intend to open an issue, we need you to provide the output of `debugmode=maximum` so if you're in interactive mode, set your terminal to record output. +### openHABian Settings -#### Auto backup -Auto backup is a marketing name for two distinct features that you can deploy in one go at _unattended_ installation time on a RPi (when you deploy the image). -Technically it is a "low-cost" version of disk mirroring PLUS the setup of the Amanda backup system which all by itself has been available in a long time. -So don't let the name confuse you. If you didn't choose to set this up at installation time, you can also individually select these functions via `openhabian-config` menu options 53 (mirroring) and 52 (Amanda). -Note mirroring is available on RPi hardware only while Amanda as the backup system is available on any openHABian-supported hardware-OS combo. +#### `repositoryurl` -#### SD mirroring -SD cards are known to 'wear out' the more you write to them. -The SD mirroring feature uses an USB-attached card writer to keep a 2nd SD card in (loose) sync with the internal card. In case of the primary SD card to fail, you can easily swap cards to relaunch your OH and get it working again within just minutes. You can even instruct others with physical access if you cannot be on site, and you can make use of this feature to create system copies that you can store off-site to recover your smart home server in case a disaster happens. - -To setup openHABian to automatically backup and mirror your internal SD card to an external storage unit, we suggest to use another SD card in an external card writer device so that in case your internal SD card fails, you can switch SD cards to get the system back up running fast. +The repository to clone openHABian from. +This is typically only used by developers to test changes. -We recommend to put in another card that has at least _twice_ the size of the internal card. We can make use of that extra space as storage for the backup system. -Note most "16GB" cards are not _exactly_ 16 GB and your mirror mustn't have less bytes than the internal one so at setup time, openHABian ensures the second card has at least the same size as your internal card. - -::: tip NO Do-It-Yourself mirroring -Note you must NOT use `dd` or any other tool such as 'Win32 disk imager' to copy an SD card or partition on your own. If you do and boot with source and destination cards plugged in, they will have the same partition IDs and this will likely mess up things and can irreversibly devastate your whole system. Use the `blkid` command in shell to see those IDs. This also means you must not take _mirrors_ of the _mirror_. -Also be aware that only the first two partitions are mirrored - the storage (3rd) partition will never be mirrored even if you have set that up for use as your backup area. +::: details Example +``` +repositoryurl="https://github.com/openhab/openhabian.git" +``` ::: -To setup mirroring right during unattended installation of a RPi (using the image flash method):
-Define `backupdrive=/dev/sdX` (replace X with the proper character) to enable this functionality right during unattended installation. -The first attached disk type device is usually called `/dev/sda`. -Use `storagecapacity=xxx` to override how much space to consume at most for Amanda backup storage (in MB). -openHABian will create partitions 1 and 2 to be mirrors of your internal card and will assign the remaining space to another partition that you can use for storage. -NOTE: if you do and _if_ the remaining space is sufficient, selecting this will also result in setting up the Amanda backup system on that extra space. -You can change where it stores its backup data via `storagedir=/storage`, but you cannot unselect the Amanda setup at this stage. -If you want to setup mirroring only and Amanda anywhere else but on the extra SD space, you must not choose unattended installation method (i.e. do not define `backupdrive`). -You can still setup both, mirroring and Amanda, separately at any later time using the 53 (mirroring) and 52 (Amanda) menu options. +#### `clonebranch` -Full mirroring of the full SD card will take place semiannually and only for the 2nd partition (Linux root), changes will be synced once every day. -See `systemctl list-timers`, timers are defined in `/etc/systemd/system/sd*.timer`. - - -Menu 5X provides interactive access to the aforementioned functions:
-`52 Amanda System Backup` will prepare an existing directory as your backup storage and make Amanda launch once a day. See the separate [Amanda setup document](openhabian-amanda.md). -`53 Setup SD mirroring` prepares the partitions on an SD card and sets up timers to execute both, a full mirroring and complementary rsync 'diff' runs. -`54 Raw copy SD` is a one-time raw copy (mirror) run. -`55 Sync SD` propagates (syncs) differences from your main SD card to your external card. - -In case of failure of your primary SD card, replace the broken SD card in the internal slot with your backup card from the external reader. Get another SD card that matches the size of the backup (now in internal slot) card and use menu option 54 to copy your active backup card back to the new one. - -#### Tailscale VPN network -Tailscale is a management toolset to establish a WireGuard based VPN between multiple systems if you want to connect to openHAB(ian) instances outside your LAN over Internet. -It'll take care to detect and open ports when you and your peers are located behind firewalls. -[Download the client](https://tailscale.com/download) and eventually get the Solo service plan from Tailscale, that's free for private use and will automatically be selected when you fire up your first VPN node. -The Windows client has a link to the admin console where you can create pre-auth one-time keys. -These you can put as the `preauthkey` into `openhabian.conf` to automatically deploy remote openHABian nodes (unattended install) and have them join the VPN. -The `tstags` option allows you to specify tags for use in [Tailscale ACL](https://tailscale.com/kb/1018/acls/) definition. - -#### IPv6 notes -You might encounter problems when you make use of IPv6 on some networks and systems. openHABian installation may stop or hang forever. -In that case _or if you are sure that you do not need IPv6 on your openHABian server_, you can disable IPv6. -Follow the instructions in the previous section and insert a line into `openhabian.conf` reading `ipv6=disable`. - -#### Fake hardware mode -If to install openHABian fails because you have a non-supported hardware or run an unsupported OS release, you can "fake" your hardware and OS to make openHABian behave as if you did own that HW/OS. -In `openhabian.conf`, uncomment and complete the lines reading `hw=`, `hwarch=` and/or `osrelease=` with the hw and os versions you want to attempt installation with. - -## Optional Components -openHABian comes with a number of additional tools to quickly install and set up additional home automation related software. -You'll find all of these in the [openHABian Configuration Tool](#openhabian-configuration-tool), menu option 20. - -- DEPRECATED [Frontail](https://github.com/mthenw/frontail) - openHAB Log Viewer accessible from [http://openhabian:9001](http://openhabian:9001) (only provided as is) -- [InfluxDB and Grafana](https://community.openhab.org/t/influxdb-grafana-persistence-and-graphing/13761/1) - persistence and graphing available from [http://openhabian:3000](http://openhabian:3000) -- [Eclipse Mosquitto](http://mosquitto.org) - Open Source MQTT v3.1/v3.1.1 Broker -- [Node-RED](https://nodered.org) - "Flow-based programming for the Internet of Things". Access at [http://openhabian:1880](http://openhabian:1880). -- [Homegear](https://www.homegear.eu/index.php/Main_Page) - Homematic control unit emulation -- [KNXd](http://michlstechblog.info/blog/raspberry-pi-eibknx-ip-gateway-and-router-with-knxd) - KNX daemon running at `224.0.23.12:3671/UDP` -- [OWServer](http://owfs.org/index.php?page=owserver_protocol) - 1wire control system -- [FIND](https://www.internalpositioning.com/) - the Framework for Internal Navigation and Discovery -- Mi Flora MQTT demon +The branch of the repository to use for openHABian. + +::: details Example +``` +clonebranch="openHAB" +``` + +#### `initialconfig` + +An initial configuration file to import when setting up openHAB. +This file must be a `.zip` archive created by `openhab-cli backup`. + +::: details Example +``` +initialconfig="/boot/initial.zip" +``` +::: + +#### `debugmode` -## Troubleshooting -If you're having problems with getting openHABian to install properly, check out the [debug guide](openhabian-DEBUG.md). It's also available on your system as `/opt/openhabian/docs/openhabian-DEBUG.md`. -You can ask for help on the [openHABian community forum](https://community.openhab.org/) when the debug guide doesn't help but please first, read and [mind the rules](https://community.openhab.org/t/how-to-ask-a-good-question-help-us-help-you/58396). +Debug log level for openHABian, valid options are: `off`, `on` (verbose output in log), or `maximum` (show every command in log). -If you want to get involved, you found a bug, or just want to see what's planned for the future, visit us on GitHub: +::: details Example +``` +debugmode="off" +``` +::: + +#### `apttimeout` + +APT timeout to wait for lock when multiple install actions are going on. + +::: details Example +``` +apttimeout="60" +``` +::: + +#### `java_opt` + +Java version to install, valid options are: `17`, `Zulu21-64`, or `BellSoft21`. + +::: details Example +``` +java_opt="17" +``` +::: + +### Fake Hardware + +#### `hw` + +Force treating your installation as if it was a specific type of hardware. + +::: details Valid Options +- `pi5` +- `pi4` +- `pi4_8gb` +- `cm4` +- `pi400` +- `pi3` +- `cm3` +- `pi3+` +- `cm3+` +- `pi2` +- `pi1` +- `cm1` +- `pi0` +- `pi0w` +- `pi0w2` +- `x86` +::: + +::: details Example +``` +hw="pi5" +``` +::: + +#### `hwarch` + +Force treating your installation as if it was a specific architecture. + +::: details Valid Options +- `x86_64` +- `amd64` +- `armv6l` +- `armv7l` +- `aarch64` +- `arm64` +::: + +::: details Example +``` +hwarch="x86_64" +``` +::: + +#### `osrelease` + +Force treating your installation as if it was a specific OS release. + +::: details Valid Options +- `raspios` +- `raspbian` +- `debian` +- `ubuntu` +- `stretch` +- `buster` +- `bullseye` +- `bookworm` +- `bionic` +- `focal` +::: + +::: details Example +``` +osrelease="raspios" +``` +::: + +### Other Settings + +#### `zraminstall` + +Enable or disable ZRAM installation. + +::: details Example +``` +zraminstall="enable" +``` +::: + +#### `hotspot` + +Enable or disable hotspot support when internet is not reachable. + +::: details Example +``` +hotspot="enable" +``` +::: + +#### `hotspotpw` + +Password to connect to the hotspot when internet is not reachable. + +::: details Example +``` +hotspotpw="openhabian" +``` +::: -- [https://github.com/openhab/openhabian/](https://github.com/openhab/openhabian/) +### Backup Settings - -### Where can I find a changelog for openHABian? -Official announcements are displayed on starting `openhabian-config` and stored in `NEWS.md` (a file in `/opt/openhabian`). -Release notes are also co-located with the download links [here](https://github.com/openhab/openhabian/releases). -If you want to stay in touch with all the latest code changes under the hood, see [commit history](https://github.com/openhab/openhabian/commits/main) for openHABian. -You'll also see commits "fly by" when executing the "Update" function within the openHABian Configuration Tool. +#### `backupdrive` - -### Did my Installation succeed? What to do in case of a problem? -openHABian setup will take 15 up to 45 minutes to complete all steps, depending on your device's performance and your internet connection. +Storage device to configure for backup. -Watch the progress on the console or the web interface at or if that name has become available. -Double-check the IP address and name with your router while you wait. -If there is absolutely no output for more than 10 minutes, there probably is a problem with the way your router or local network are setup. -Read on in the [Troubleshooting](#troubleshooting) section. -Set `debugmode=maximum` in `openhabian.conf` to see what openHABian is doing. +::: details Example +``` +backupdrive="/dev/sda" +``` +::: + +#### `storageconfig` + +Name of the backup configuration to configure for openHAB. + +::: details Example +``` +storageconfig="openhab-dir" +``` +::: + +#### `storagedir` + +Directory to mount the storage device to. + +::: details Example +``` +storagedir="/storage" +``` +::: + +#### `storagetapes` + +The number of Amanda storage tapes to configure for the backup. + +::: details Example +``` +storagetapes="15" +``` +::: + +#### `storagecapacity` + +The capacity of Amanda storage tapes to configure for the backup. + +::: details Example +``` +storagecapacity="1024" +``` +::: -After a few minutes of boot up time, you can [connect to the SSH console](https://www.raspberrypi.org/documentation/remote-access/ssh/windows.md) of your device. -During the setup process you'll be redirected to the live progress report of the setup (you can Ctrl-C to get into the shell). -The report can also be checked for errors at any time, see `/boot/first-boot.log`. +### Mail Relay Settings -The progress of a successful installation will look like this: +#### `adminmail` -![openHABian installation log](images/openHABian-install-log.png) +Mail account to use for the admin account. -Wait till the log tells you that the setup was "successful", then reconnect to the device. +::: details Example +``` +adminmail="john.doe@example.com" +``` +::: -#### SSH Login Screen +#### `relayuser` -If the installation was **successful** you will see the normal login screen as shown in the first screenshot. -If the installation was **not successful** you will see a warning and further instructions as shown in the second screenshot. +User account to use for the from address. -
-
openHABian installation successful
-
openHABian installation failed warning and instructions
-
+::: details Example +``` +relayuser="john.doe@example.com" +``` +::: -#### openHAB Dashboard +#### `relaypass` -After the installation of openHABian was successful, you should be able to access the openHAB dashboard: +Password to authenticate with the relay service. -- Raspberry Pi image setup: [http://openhabian:8080](http://openhabian:8080) -- In any case: [http://your-device-hostname:8080](http://your-device-hostname:8080) or [http://192.168.0.2:8080](http://192.168.0.2:8080) (replace name/IP with yours) +::: details Example +``` +relaypass="mySuperSecretPassword" +``` +::: -If you are not able to access your system via the openHAB dashboard or SSH after more than one hour, chances are high that your hardware setup is the problem. -Consult the [debug guide](openhabian-DEBUG.md) and move on from there. +#### `smarthost` - -openHABian is designed to install and work with the latest version of openHAB (currently 4.x). -We do not support migrating older installation's persistence/configuration files to the latest version. -Users will need to migrate and fix any issues with their persistence/configuration files on their own. -Note: we will upgrade to a new major version of openHAB after warning and asking the user for confirmation, but will not do so automatically. +Host of the mail relay service. +::: details Example +``` +smarthost="smtp.gmail.com" +``` +::: - -#### Where is the graphical user interface? +#### `smartport` -I've just installed openHABian and now I'm confused. -No fancy login screen, no windows, no mouse support. -What did I get into? +Port to connect to the mail relay service. -You are not the first one to get confused about the intended use case of openHABian. -Maybe it helps to not think of the RPi as a PC as we know it. -An RPi is not (well, not _necessarily_) to be used with a keyboard and display. -Its intended use case is to sit in a corner and provide a service reliably 24 hours a day, 7 days a week. -You already own a powerful PC or Mac to work on. +::: details Example +``` +smartport="587" +``` +::: + +### Tailscale Settings + +#### `preauthkey` + +A pre-configured key to connect to your tailscale network. -What we actually want openHABian to be is a **dedicated, headless system** to **reliably operate your home automation** on and to expose all interfaces needed to interact and configure it (MainUI, openHAB LogViewer, Samba Network Shares, openHABian maintenance tool, SSH, you-name-it). -If you know how to work with these interfaces, you are set for a way better experience than the alternatives. -The main challenge is to **get used to the Linux command line**, not even a GUI will relieve you from that in the long run. -If you are not willing to teach yourself a few fundamental Linux skills you will not become happy with any Linux system and should resort to a e.g. Windows machine. -However as you are willing to tinker with smart home technology, I'm sure you are ready to **teach yourself new stuff** and expand your experience. +::: details Example +``` +preauthkey="tskey-xxxxxxxxxxxxxxxxx" +``` +::: + +#### `tstags` + +Tags for the machine corresponding to the tailscale network. + +::: details Example +``` +tstags="tag:client" +``` +::: diff --git a/includes/generic/bash_profile b/includes/generic/bash_profile index 15576d8fd..1287b79a2 100644 --- a/includes/generic/bash_profile +++ b/includes/generic/bash_profile @@ -9,10 +9,10 @@ if [ -f "/opt/openHABian-install-failed" ]; then echo -e "are high setup will succeed on the second try.\\n" echo "In order to find the cause of the problem, have a look at the installation log:" echo -e " \e[90;01msudo cat /boot/first-boot.log\e[39;49;00m\\n" - echo "In order to restart the installation run:" + echo "You can try to restart the installation by running:" echo -e " \e[90;01msudo rm -f /opt/openHABian*; sudo reboot\e[39;49;00m\\n" - echo "If the error persists, please read the debug guide at:" - echo -e "\e[94;04mhttps://github.com/openhab/openhabian/blob/master/docs/openhabian-DEBUG.md\e[39;49;00m\\n" + echo "If the error persists, please read the troubleshooting guide at:" + echo -e "\e[94;04mhttps://github.com/openhab/openhabian/blob/main/docs/openhabian-troubleshooting.md\e[39;49;00m\\n" return 0 elif [ -f "/opt/openHABian-install-inprogress" ]; then echo -e -n "\\n\e[36;01mAttention! \e[39;49;00m"