allow for disabling IPv6 in openhabian.conf (openhab#888)

* allow for ipv6=disable in openhabian.conf

Signed-off-by: Markus Storm <[email protected]>

build-image/openhabian.conf

@@ -25,15 +25,20 @@ wifi_psk=""
 # See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 or /usr/share/zoneinfo/zone.tab
 wifi_country=""
 
-# repo to clone from (if not master for build and test)
+# Eventually disable all IPv6 e.g. on installation problems
+# values: "enable", "disable"
+ipv6=disable
+
+# repo and branch to clone from
 repositoryurl=https://github.com/openhab/openhabian.git
 clonebranch=master
+
 # debug verbosity mode
-# unattended, unattended_debug (verbose output in log) or debug_maximum (show every command)
+# values: "unattended", "unattended_debug" (verbose output in log) or "debug_maximum" (show every command in either mode)
 mode=unattended
 
 # Java architecture mode
-# Use 32-bit or 64-bit
-java_arch=64-bit
+# values: "Zulu32", "Zulu64" or "AdoptOpenJDK"
+java_arch=32-bit
 
 # vim: filetype=sh

build-image/openhabian.pi-raspbian.conf

@@ -28,12 +28,13 @@ wifi_country=""
 # repo to clone from (if not master for build and test)
 repositoryurl=https://github.com/openhab/openhabian.git
 clonebranch=master
+
 # debug verbosity mode
-# unattended, unattended_debug (verbose output in log) or debug_maximum (show every command)
+# values: "unattended", "unattended_debug" (verbose output in log) or "debug_maximum" (show every command in either mode)
 mode=unattended
 
 # Java architecture mode
-# Use 32-bit or 64-bit
+# values: "Zulu32", "Zulu64" or "AdoptOpenJDK"
 java_arch=32-bit
 
 # vim: filetype=sh

docs/openhabian-DEBUG.md

@@ -1,7 +1,7 @@
 ---
 layout: documentation
 title: openHABian
-source: https://github.com/openhab/openhabian/blob/master/docs/openhabiab-DEBUG.md
+source: https://github.com/openhab/openhabian/blob/master/docs/openhabian-DEBUG.md
 ---
 
 <!-- Attention authors: Do not edit directly. Please add your changes to the appropriate source repository -->
@@ -26,12 +26,17 @@ Next, you need your router (or a different device) to provide properly configure
 The DHCP server also has to announce which DNS resolver to use so your box 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 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 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](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. Please Google for how to accomplish that.
 
 
 ## Install
-Etch-Burn-d(isk)d(ump)-Flash-whatever the image to an SD card, insert it and boot from there.
-If you have one available, attach a console (monitor and keyboard) to follow the install process. If you don't have any, try to access the web console at `http://<yourhostip>:80/first-boot.txt`.
+Etch-Burn-d(isk)d(ump)-Flash-whatever the image to an SD card.
+
+Mind you that at this stage, you can access the openHABian config file to set parameters to affect install. See the description in [openhabian.md](https://github.com/openhab/openhabian/blob/master/docs/openhabian.md) on WiFi boot how to mount your SD card and modify `openhabian.conf`. You can also do that later times via SSH login, but in case your system does not properly obtain any IP address, you would be out of luck.
+
+If you have one available, attach a console (monitor and keyboard) to follow the install process. Now insert the SD card and turn on your system.
+If you don't have any console, try to access the web console at `http://<yourhostip>:80/first-boot.txt`.
 It will display the contents of `/boot/first-log.boot` at intervals of 2 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.
 

docs/openhabian.md

@@ -21,7 +21,7 @@ To that end, the project provides two things:
 * Complete **SD-card images pre-configured with openHAB** and many other openHAB- and Hardware-specific preparations for the Raspberry Pi and the Pine A64
 * The openHABian Configuration Tool to set up and configure openHAB and many related things on any Debian/Ubuntu based system
 
-#### Table of Content
+#### Table of Contents
 
 {::options toc_levels="2..3"/}
 
@@ -64,7 +64,7 @@ Additionally the **openHABian Configuration Tool** [`openhabian-config`](#openha
 
 Here you'll find supported and tested installation platforms and instructions.
 
-### Raspberry Pi (Prepackaged SD-Card Image)
+### Raspberry Pi (Prepackaged SD Card Image)
 
 **Flash, plug, wait, enjoy:**
 The provided image is based on the [Raspbian Lite](https://www.raspberrypi.org/downloads/raspbian) standard system.
@@ -139,11 +139,23 @@ For the setup on Wi-Fi, you'll need to make your SSID and password known to the
 Additionally to the setup instructions given above, the following steps are needed:
 
 - Flash the system image to your micro SD card as described, do not remove the SD card yet
-- Access the first SD card partition from the file explorer of your choice (e.g. Windows file explorer)
+- Access the first SD card partition using the file explorer. It's a vfat (Windows) filesystem.
+  (we assume you're using a Windows, Mac or other desktop system to flash the SD)
 - Open the file `openhabian.conf` in a text editor
-- Uncomment and fill in `wifi_ssid="My Wi-Fi SSID"` and `wifi_psk="password123"`
+- Uncomment and complete the lines reading `wifi_ssid="My Wi-Fi SSID"` and `wifi_psk="password123"`
 - Save, Unmount, Insert, Boot
-- Continue with the instructions for the Raspberry Pi or Pine A64
+- Continue with the instructions for your hardware
+
+{: #debug-mode}
+### Debug mode
+See [Troubleshooting] section if you run into trouble installing. If you want to turn on debug mode, follow the instructions in the previous section and insert a line into `openhabian.conf` reading either `mode=unattended_debug` or better right away `mode=debug_maximum`.
+
+{: #ipv6-notes}
+### 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`.
 
 {: #openhabian-config}
 ## openHABian Configuration Tool
@@ -253,7 +265,7 @@ If you want to get involved, you found a bug, or just want to see what's planned
 {: #changelog}
 #### Where can I find a changelog for openHABian?
 
-The official changelog announcements are posted [here](https://community.openhab.org/t/13379/1) and [here](https://github.com/openhab/openhabian/releases), be sure to check these out regularly.
+The official changelog announcements are posted [here](https://community.openhab.org/t/13379/1) and [here](https://github.com/openhab/openhabian/releases), be sure to check these out for your version.
 If you want to stay in touch with all the latest code changes under the hood, see the [commit history](https://github.com/openhab/openhabian/commits/master) for openHABian.
 You'll also see added commits when executing the "Update" function within the openHABian Configuration Tool.
 
@@ -265,6 +277,7 @@ Remember to stay calm.
 The openHABian setup will take 15 up to 45 minutes to complete all steps.
 This time highly depends on your device's performance, your internet connection and sometimes even on the load of external servers.
 
+
 <!--
 ##### LED Indication (RPi only)
 
@@ -279,16 +292,20 @@ During and after the first boot of your Raspberry Pi, the green on-board LED wil
 The progress indication via the **green Raspberry Pi LED** is currently not possible and hence not part of the openHABian v1.3+ image.
 We will re-add the functionality as soon as the underlying issue is resolved.
 
-##### openHAB Dashboard
+##### Progress Report
 
-After the installation of openHABian was successful, you should be able to access the openHAB dashboard:
+Watch the progress on the console or the web interface at https://<yourip>/ or http://openhab/ if that name has become available.
 
-- Raspberry Pi image setup: [http://openhab:8080](http://openhab: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)
+Double-check the address and name with your router while you wait.
+
+If there is absolutely no output for more than 10 minutes, your installation has failed in the first initialization phase. There probably is a problem
+with the way your router or local network are setup.
 
-##### SSH Progress Report
+You might want to try disabling IPv6.
+Read on in the [Troubleshooting] section or move on to the [DEBUG guide](https://github.com/openhab/openhabian/blob/master/docs/openhabian-DEBUG.md).
 
-It is always possible to [connect to the SSH console](https://www.raspberrypi.org/documentation/remote-access/ssh/windows.md) of your device (after a few minutes of boot up time).
+
+It is also always possible to [connect to the SSH console](https://www.raspberrypi.org/documentation/remote-access/ssh/windows.md) of your device (after a few minutes of boot up time).
 During the setup process you'll be redirected to the live progress report of the setup.
 The report can also be checked for errors after the installation finished by executing: `cat /boot/first-boot.log`
 
@@ -308,6 +325,13 @@ If the installation was **not successful** you will see a warning and further in
   <div class="col s12 m5 offset-m2"><img src="images/openHABian-install-failed.png" alt="openHABian installation failed warning and instructions" title="openHABian installation failed warning and instructions"></div>
 </div>
 
+##### openHAB Dashboard
+
+After the installation of openHABian was successful, you should be able to access the openHAB dashboard:
+
+- Raspberry Pi image setup: [http://openhab:8080](http://openhab: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)
+
 ##### What Next?
 
 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.

functions/openhabian.bash

@@ -131,3 +131,46 @@ ua-netinst_check() {
     if ! (whiptail --title "openHABian Raspberry Pi ua-netinst image detected" --yes-button "Continue" --no-button "Cancel" --yesno "$introtext" 20 80) then return 0; fi
   fi
 }
+
+choose_ipv6() {
+  local IPV6_DISABLE="net.ipv6.conf.all.disable_ipv6"
+
+  # shellcheck disable=SC2154
+  if [[ "$ipv6" == "disable" ]]; then
+    if ! grep -qE "^${IPV6_DISABLE}" "${SYSCTL_INIT}"; then
+      disable_ipv6 yes
+    fi
+  else
+    if [[ "$ipv6" == "enable" ]]; then
+      disable_ipv6 no
+    fi
+  fi
+
+  sysctl -p
+}
+
+# arguments: "yes", "no"
+disable_ipv6() {
+  local APT_IPV6_DISABLE='Acquire::ForceIPv4 "true";'
+  local APT_INIT=/etc/apt/apt.conf/S90force-ipv4
+  local IPV6_DISABLE="net.ipv6.conf.all.disable_ipv6"
+  local SYSCTL_INIT="/etc/sysctl.d/99-sysctl.conf"
+
+  if [[ "$1" == "yes" ]]; then
+    echo "${APT_IPV6_DISABLE}" | sudo tee "${APT_INIT}"
+
+    if ! grep -qE "^${IPV6_DISABLE}" "${SYSCTL_INIT}"; then
+      ( echo ""
+        echo "###################################################################"
+        echo "# disable all IPv6 functionality" >> "${SYSCTL_INIT}"
+        echo "${IPV6_DISABLE}=1"
+      )	>> "${SYSCTL_INIT}"
+    else
+      sed -i "s/^# ${IPV6_ENABLE}.*/${IPV6_ENABLE}/g" "${SYSCTL_INIT}"
+    fi
+  else
+    rm -f "${APT_INIT}"
+    sed -i "s/^${IPV6_ENABLE}.*/# ${IPV6_ENABLE}/g" "${SYSCTL_INIT}"
+  fi
+}
+

openhabian-setup.sh

@@ -66,6 +66,10 @@ for shfile in "$BASEDIR"/functions/*.bash; do source "$shfile"; done
 
 # avoid potential crash when deleting directory we started from
 OLDWD=$(pwd) && cd /opt || exit 1
+
+# disable ipv6 if requested in openhabian.conf (eventually reboots)
+choose_ipv6
+
 if [[ -n "$UNATTENDED" ]]; then
   # apt/dpkg commands will not try interactive dialogs
   export DEBIAN_FRONTEND=noninteractive

openhabian.conf.dist

@@ -24,15 +24,20 @@ system_default_locale="en_US.UTF-8"
 wifi_ssid=""
 wifi_psk=""
 
-# repo to clone from (if not master for build and test)
+# Eventually disable all IPv6 e.g. on installation problems
+# values: "enable", "disable"
+ipv6=disable
+
+# repo and branch to clone from
 repositoryurl=https://github.com/openhab/openhabian.git
 clonebranch=master
+
 # debug verbosity mode
-# unattended, unattended_debug (verbose output in log) or debug_maximum (show every command)
+# values: "unattended", "unattended_debug" (verbose output in log) or "debug_maximum" (show every command in either mode)
 mode=unattended
 
 # Java architecture mode
-# Use 32-bit or 64-bit
-java_arch=64-bit
+# values: "Zulu32", "Zulu64" or "AdoptOpenJDK"
+java_arch=32-bit
 
 # vim: filetype=sh