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

Update installation Linux and RPi (#73) 

user-menu.html the changes are 95% spaces/tabs/formatting/indention fixes.

apt.md was removed because there should be only one article for Linux (besides one for Mac, one for Windows, ...), containing both installation methods and all other related topics. Having one of the methods in an extra file doesn't make sense.

linux.md apt as base, a few things from the rasspi document, many new chapters. Still missing: de/reinstallation, backup, manual->non-root, manual->upgrade, probably more

rasppi.md moved a few chapters to linux.md



Squash commits
Update
Add first half of manual installation instructions
Update linux.md
Update linux.md
Update linux.md
Update linux.md
Update linux.md
Update linux.md
Update linux.md
Update linux.md
Update linux.md
Add notes on apt snapshot installation
Update rasppi and index
Add backup info
Fix small details
pull/76/head
Thomas Dietrich 2016-08-14 22:50:23 +02:00 committed by GitHub
parent 7616075b03
commit c14c0ee42b
6 changed files with 579 additions and 394 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
_includes/user-menu.html
View File

@ -5,54 +5,53 @@
<li><a href="{{docu}}/concepts/index.html">Concepts</a>
<ul>
<li><a href="{{docu}}/concepts/index.html">Overview</a>
<li><a href="{{docu}}/concepts/items.html">Items</a></li>
<li><a href="{{docu}}/concepts/things.html">Things</a></li>
<li><a href="{{docu}}/concepts/discovery.html">Inbox & Discovery</a></li>
</ul>
</li>
<li><a href="{{docu}}/installation/index.html">Installation</a>
<li><a href="{{docu}}/concepts/items.html">Items</a></li>
<li><a href="{{docu}}/concepts/things.html">Things</a></li>
<li><a href="{{docu}}/concepts/discovery.html">Inbox &amp; Discovery</a></li>
</ul>
</li>
<li><a href="{{docu}}/installation/index.html">Installation</a>
<ul>
<li><a href="{{docu}}/installation/index.html">Overview</a></li>
<li><a href="{{docu}}/installation/linux.html">Linux</a></li>
<li><a href="{{docu}}/installation/macosx.html">Mac OS X</a></li>
<li><a href="{{docu}}/installation/windows.html">Windows</a></li>
<li><a href="{{docu}}/installation/docker.html">Docker</a></li>
<li><a href="{{docu}}/installation/rasppi.html">Raspberry Pi</a></li>
<li><a href="{{docu}}/installation/pine.html">PINE64</a></li>
<li><a href="{{docu}}/installation/synology.html">Synology</a></li>
<li><a href="{{docu}}/installation/designer.html">openHAB Designer</a></li>
</ul>
</li>
<li><a href="{{docu}}/configuration/jetty.html">Configuration</a>
<ul>
<li><a href="{{docu}}/configuration/jetty.html">Reverse Proxy</a></li>
</ul>
</li>
<li><a href="{{docu}}/administration/index.html">Administration</a>
<ul>
<li><a href="{{docu}}/administration/index.html">Overview</a></li>
<li><a href="{{docu}}/administration/console.html">Console</a></li>
<li><a href="{{docu}}/administration/logging.html">Logging</a></li>
<li><a href="{{docu}}/administration/bundles.html">Bundle Management</a></li>
<li><a href="{{docu}}/administration/runtime.html">Runtime Commands</a></li>
</ul>
</li>
<li><a href="{{docu}}/features/index.html">Features</a>
<ul>
<li><a href="{{docu}}/features/index.html">Overview</a></li>
<li><a href="{{docu}}/features/sitemap.html">Sitemaps</a></li>
<li><a href="{{docu}}/features/persistence.html">Persistence</a></li>
<li><a href="{{docu}}/features/automation/ruledsl.html">Automation</a>
<ul>
<li><a href="{{docu}}/features/automation/ruledsl.html">Textual Rules</a></li>
<li><a href="{{docu}}/features/automation/ngrules.html">Next-Gen Rules</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="{{docu}}/addons/index.html">Add-ons</a></li>
<ul>
<li><a href="{{docu}}/installation/index.html">Overview</a></li>
<li><a href="{{docu}}/installation/apt.html">Linux (APT)</a></li>
<li><a href="{{docu}}/installation/linux.html">Linux (manual)</a></li>
<li><a href="{{docu}}/installation/rasppi.html">Raspberry Pi</a></li>
<li><a href="{{docu}}/installation/pine.html">PINE64</a></li>
<li><a href="{{docu}}/installation/macosx.html">Mac OS X</a></li>
<li><a href="{{docu}}/installation/windows.html">Windows</a></li>
<li><a href="{{docu}}/installation/docker.html">Docker</a></li>
<li><a href="{{docu}}/installation/synology.html">Synology</a></li>
<li><a href="{{docu}}/installation/designer.html">openHAB Designer</a></li>
</ul>
</li>
<li><a href="{{docu}}/configuration/jetty.html">Configuration</a>
<ul>
<li><a href="{{docu}}/configuration/jetty.html">Reverse Proxy</a></li>
</ul>
</li>
<li><a href="{{docu}}/administration/index.html">Administration</a>
<ul>
<li><a href="{{docu}}/administration/index.html">Overview</a></li>
<li><a href="{{docu}}/administration/console.html">Console</a></li>
<li><a href="{{docu}}/administration/logging.html">Logging</a></li>
<li><a href="{{docu}}/administration/bundles.html">Bundle Management</a></li>
<li><a href="{{docu}}/administration/runtime.html">Runtime Commands</a></li>
</ul>
</li>
<li><a href="{{docu}}/features/index.html">Features</a>
<ul>
<li><a href="{{docu}}/features/index.html">Overview</a></li>
<li><a href="{{docu}}/features/sitemap.html">Sitemaps</a></li>
<li><a href="{{docu}}/features/persistence.html">Persistence</a></li>
<li><a href="{{docu}}/features/automation/ruledsl.html">Automation</a>
<ul>
<li><a href="{{docu}}/features/automation/ruledsl.html">Textual Rules</a></li>
<li><a href="{{docu}}/features/automation/ngrules.html">Next-Gen Rules</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="{{docu}}/addons/index.html">Add-ons</a></li>
<ul>
<li><a href="{{docu}}/addons/index.html">Overview</a></li>
<li><a href="{{docu}}/addons/bindings.html">Bindings</a>
<ul>
@ -76,15 +75,14 @@
<li><a href="{{docu}}/addons/iconsets/classic/readme.html">Classic Iconset</a></li>
</ul>
</li>
<li><a href="{{docu}}/addons/1xaddons.html">1.x Add-ons</a></li>
</ul>
</li>
<li><a href="{{docu}}/appendix/contributing.html">Appendix</a></li>
<ul>
<li><a href="{{docu}}/appendix/downloads.html">Downloads</a></li>
<li><a href="{{docu}}/appendix/examples/index.html">Examples</a></li>
<li><a href="{{docu}}/appendix/troubleshooting.html">Troubleshooting</a></li>
<li><a href="{{docu}}/appendix/contributing.html">Contributing</a></li>
</ul>
</li>
<li><a href="{{docu}}/addons/1xaddons.html">1.x Add-ons</a></li>
</ul>
</li>
<li><a href="{{docu}}/appendix/contributing.html">Appendix</a></li>
<ul>
<li><a href="{{docu}}/appendix/downloads.html">Downloads</a></li>
<li><a href="{{docu}}/appendix/examples/index.html">Examples</a></li>
<li><a href="{{docu}}/appendix/troubleshooting.html">Troubleshooting</a></li>
<li><a href="{{docu}}/appendix/contributing.html">Contributing</a></li>
</ul>
</ul>

132
installation/apt.md
View File

@ -1,132 +0,0 @@
---
layout: documentation
---
{% include base.html %}
# Installation on Linux through APT
1. Install prerequisites
1. Add the openHAB Bintray Repositories key to the apt-keyring
- with wget:
```
wget -qO - 'https://bintray.com/user/downloadSubjectPublicKey?username=openhab' | sudo apt-key add -
```
- or with curl:
```
curl 'https://bintray.com/user/downloadSubjectPublicKey?username=openhab' | sudo apt-key add -
```
1. Add openHAB apt repository to the apt sources list (Note: the current openhab.list file will be overwritten)
- To install a beta releases use:
```
echo 'deb http://dl.bintray.com/openhab/apt-repo2 testing main' | sudo tee /etc/apt/sources.list.d/openhab.list
```
- For stable releases use:
```
echo 'deb http://dl.bintray.com/openhab/apt-repo2 stable main' | sudo tee /etc/apt/sources.list.d/openhab.list
```
1. Resynchronize the package index
```
sudo apt-get update
```
1. Install openHAB
- Either use the offline distribution which is full blown and comes with all addons. Additional addons will be
installed an request from your local disk.
```
sudo apt-get install openhab2-offline
```
- Or the online distribution which will install additional addons on request from the internet.
```
sudo apt-get install openhab2-online
```
1. Start openHAB - manually
- Init based on sysVinit (e.g. Debian 7 / Ubuntu 14.x and earlier)
```
sudo /etc/init.d/openhab2 start
sudo /etc/init.d/openhab2 status
```
- Init based on systemd (e.g. Debian 8 / Ubuntu 15.x and newer)
```
sudo systemctl start openhab2
```
1. Start openHAB - at system startup
- Init based on sysVinit (e.g. Debian 7 / Ubuntu 14.x and earlier)
```
sudo update-rc.d openhab2 defaults
```
- or using Init based on systemd (e.g. Debian 8 / Ubuntu 15.x and newer)
```
sudo systemctl daemon-reload
sudo systemctl enable openhab2
```
# To Upgrade
Note: changed configuration files will be retained even on upgrades.
```
sudo apt-get update
sudo apt-get upgrade
```
# File Locations
| service configuration | `/etc/default/openhab2` |
| site configuration | `/etc/openhab2` |
| log files | `/var/log/openhab2` |
| userdata like rrd4j databases | `/var/lib/openhab2` and subdirectories |
| openHAB application | `/usr/share/openhab2` |
# Advanced Setup - Apt Repository Distributions
* stable
The latest stable openHAB release will be installed.
* testing
The latest release candidate of openHAB will be installed.
* version based distribution names (2.0.0.b3, 2.0.0, ...)
All Releases are available as with a distribution name corresponding to the version name.
If you want to stick your installation to a specific version use one of these distribution names.
The installation will only be upgraded if you change the sources.list to another version.
Therefore `apt-get update && apt-get upgrade` can be safely used for the other Linux software.
Examples:
```
echo "deb https://dl.bintray.com/openhab/apt-repo2 2.0.0.b3 main" | sudo tee -a /etc/apt/sources.list
echo "deb https://dl.bintray.com/openhab/apt-repo 2.0.0 main" | sudo tee -a /etc/apt/sources.list
```

BIN
installation/images/Accueil_Openhab_2.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 92 KiB

After

Width:  |  Height:  |  Size: 97 KiB

45
installation/index.md
View File

@ -1,6 +1,6 @@
---
layout: documentation
title: Installation Overwiew
title: Installation Overview
---
{% include base.html %}
@ -12,7 +12,7 @@ As such, it only depends on a [Java Development Kit](http://java.com/de/download
openHAB can be executed on different versions of **Mac OS X** and **Windows** and many different variants of **Linux** (Ubuntu, Raspbian, ...).
Please be aware of the fact, that openHAB 2 is based on a new core and introduces new concepts.
Therefore, tutorials and help you may find on the internet for openhab 1 **might** be outdated!
Therefore, tutorials and help you may find on the internet for openHAB 1 **might** be outdated!
## Platform Recommendations
@ -25,40 +25,41 @@ Therefore, tutorials and help you may find on the internet for openhab 1 **might
- **Energy and space efficient:** A device capable of performing the task at hand without being exaggerated
- **Extendibility:** Your system should be capable of running additional software like an MQTT broker or a persistence and graphing software.
- **Peripherals:** Depending on your home automation hardware, you will need additional peripheral devices such as a WiFi interface or a special USB radio module.
Many devices are suited to host a continuous installation of openHAB 2.
The [Raspberry Pi](rasppi.html) as a minimal sufficient device is quite popular, experiences with many other devices can be found in the [community forum hardware section](https://community.openhab.org/c/hardware/server).
## Prerequisites
Make sure that you have an up to date version of the [Oracle Java Development Kit](http://java.com/de/download/manual.jsp) on your host system installed.
Oracle Java Version 8 is recommended for openHAB.
A famous choice is OpenJDK, however, Oracle Java Version 8 is recommended for openHAB.
openHAB may be unstable and slower executed by OpenJDK.
A famous alternative to Oracle Java is the OpenJDK.
Note that openHAB may be unstable and slower executed by OpenJDK, it is therefor **recommended** to switch to Oracle Java if possible.
> Oracle Java offers significant performance advantages over OpenJDK on ARM platforms, and will expand the range of Java applications that run well [on the Raspberry Pi].
Check your current Java version by opening a console and typing "java -version":
```
console$ java -version
```text
java version "1.8.0 73"
Java(TM) SE Runtime Environment (build 1.8.0_73-b02)
Java HotSpot(TM) 64-Bit Server VM (build 25.73-b02, mixed mode)
```
If your output differs, please install Oracle Java 8.
## Setup variants
Before you can start, three decisions have to be made:
1. openHAB 2 is available as a platform independent archive file or through a package repository:
- **Manual setup:** Download and extract a platform independent zip archive: [Mac OS X](macosx.html), [Windows](windows.html), [Linux](linux.html)
- **Manual setup:** Download and extract a platform independent zip archive: [Mac OS X](macosx.html), [Windows](windows.html), [Linux](linux.html#manual-installation)
- **Package setup:** Install though a package repository, including automatic updates.
This option is only available for Debian or Ubuntu derivatives: [Linux (apt/deb)](apt.html)
This option is only available for Debian or Ubuntu derivatives and the recommended choice: [Linux (apt/deb)](linux.html#package-repository-installation)
2. Stable release or cutting edge:
- **Stable:** Use the latest official release ([hosted on Bintray](https://bintray.com/openhab/mvn/openhab-distro)).
- **Snapshot:** Benefit from the latest changes in the daily created snapshot ([hosted on CloudBees](https://openhab.ci.cloudbees.com/job/openHAB-Distribution)).
Because openHAB 2 is still under heavy development, it is recommended for experienced users to use the latest snapshot.
3. The distribution is available in two flavors:
@ -75,11 +76,11 @@ Please follow the instructions in the installation article matching your platfor
After you got openHAB 2 set up and running, there are a few additional setup steps you should consider:
* Configure a network share on your openHAB host device and mount it locally: [Samba Share](rasppi.html)
* Configure a network share on your openHAB host device and mount it locally: [Linux Samba Share](linux.html#network-sharing), Windows file sharing, ...
* Install the [Eclipse SmartHome Designer](designer.html) on your local machine, to manage your (remote) configuration files.
The designer comes with built-in support for the openHAB syntax and elements.
## Getting started
## Getting started
With the openHAB 2 distribution up and running, you should now continue with
the [Demo Tutorial](http://docs.openhab.org/tutorials/demo.html),
@ -101,8 +102,8 @@ You will find the following folders:
- `runtime`: This contains the openHAB binaries, there should normally be no need to touch anything in here - the whole folder can be considered to be read-only.
- `userdata`: Here you will find all the data that is generated during runtime: log files, database files, etc. In theory this should be the only folder where openHAB needs write permission on.
- `addons`: Here you can drop add-ons (or any other OSGi bundles) that you want to be deployed in your instance. These can be add-ons for openHAB 1.x and 2.x likewise. Note that all "normal" add-ons are already included in the openHAB distribution and all you need is to name them in your 'addons.cfg' file (see below). Hence the `addons` folder is mainly useful if you have received jars from other sources and want to install and test them. Please note that removing a file from this folder will not uninstall the add-on. To uninstall it, you will have to use the console command bundle:uninstall.
## Choosing a Base Package and Add-ons to be Installed
## Choosing a Base Package and Add-ons to be Installed
If you do not do any changes to the distribution, it will by default install a standard package, which comes with the most common UIs.
@ -140,7 +141,7 @@ misc = myopenhab
```
Many add-ons require some configuration. In openHAB 1.x, this was done in the central `openhab.cfg` file. In openHAB 2.x this has changed to separate files in the folder `conf/services`, e.g. the add-on 'acme' is configured in the file `conf/services/acme.cfg`.
Likewise, the syntax in the configuration files has changed to not require the namespace anymore, i.e. instead of
```
@ -177,7 +178,7 @@ For example:
```
export EXTRA_JAVA_OPTS=-Dgnu.io.rxtx.SerialPorts=/dev/ttyAMA0
```
```
## Starting the Runtime
@ -193,23 +194,23 @@ openHAB uses Apache Karaf and thus comes with a very powerful shell for managing
- `log:exception-display`: Show the last exception of the log file.
- `log:set DEBUG org.openhab.binding.sonos`: Enables debug logging for a certain binding.
- `feature:list`: Lists all features available and shows there status. openHAB add-ons are made available as such Karaf features.
- `feature:install openhab-binding-knx`: Installs a certain add-on (here KNX).
- `feature:install openhab-binding-knx`: Installs a certain add-on (here KNX).
- `bundle:list -s`: Lists all installed bundles with their symbolic name.
- `logout`: Shuts down openHAB.
## Registering openHAB as a System Service in the OS
Karaf provides the possibility to be automatically started on system startup as a service. As different mechanisms are required for the different operating systems, Karaf detects your OS and generates the required files.
Karaf provides the possibility to be automatically started on system startup as a service. As different mechanisms are required for the different operating systems, Karaf detects your OS and generates the required files.
This capability is currently not available for ARM based devices (e.g. Raspberry Pi 1 and 2) but further below shows the manual steps needed. On Linux systems, you can use the command ```arch``` to show which CPU architecture is being used.
To install openHAB as a service, call
```
openhab:install-service
openhab:install-service
```
in the shell and make sure that the folder `<openhab root folder>/runtime/karaf` is writable (only required at this time, you can make it read-only again afterwards).
The files are then generated for you and a short guide is displayed on what further actions you need to take to register it as a system service.
-->

481
installation/linux.md
View File

@ -1,10 +1,487 @@
---
layout: documentation
title: openHAB 2 on Linux
---
{% include base.html %}
# Installation on Linux
# openHAB 2 on Linux
to be done...
<!-- TODO th
* de/reinstallation
* manual non-root
-->
The following instructions will guide you through the process of setting up openHAB 2 and recommended packages on a Linux system, with the focus on Debian/Ubuntu derivatives.
openHAB 2 can be set up and executed on other Linux distributions, the steps may slightly differ.
All instructions can be executed in a terminal or remotely via SSH connection.
This page is structured as follows:
{::options toc_levels="2..4"/}
* TOC
{:toc}
If you are unfamiliar with Linux, SSH and the Linux console or if you want to improve your skills, read up on these important topics.
A lot of helpful articles can be found on the internet, for example:
* "Learn the ways of Linux-fu, for free" interactively with exercises at [linuxjourney.com](https://linuxjourney.com).
Linux file permissions is one of the biggest sources of issues, Linux novices run into.
If you find yourself in a situation, where you have **no write access** to the openHAB configuration or system files, wrong permissions and/or the incorrect use of `sudo` are often the cause.
Train your understanding of Linux permissions at [linuxjourney.com/lesson/file-permissions](https://linuxjourney.com/lesson/file-permissions).
## Installation
As a first step, please verify, that your system meets the [prerequisites](index.html#prerequisites).
If you need to install Oracle Java 8, execute:
```shell
sudo apt-get update && sudo apt-get install oracle-java8-jdk
```
openHAB 2 can be installed though a package repository or manually from file.
The installation through a provided **package repository** (using `apt-get`) is **recommended** for end users.
The manual installation through a platform independent archive file is suited for users who know what they are doing and systems with a non-Debian distribution, not using the apt/deb package system.
### Package Repository Installation
Installation through a package repository is the recommended choice on Debian/Ubuntu derivatives.
Alternatively resort to the [manual installation approach](linux.html#manual-installation).
Choose between the latest Beta release or a Snapshot with all incoming contributions, rebuild on [every change](https://oss.jfrog.org/webapp/#/builds/openHAB-Distribution).
As openHAB 2 is still in an evolving state, the snapshot may be the **preferred choice**.
The repository URLs will be stored in the file `/etc/apt/sources.list.d/openhab.list`.
Be careful to not have conflicting repositories in your sources list.
Decide between two options:
* **Beta Release**
Add the **openHAB 2 Beta repository** to your systems apt sources list (will overwrite your existing `openhab.list`):
```shell
echo 'deb http://dl.bintray.com/openhab/apt-repo2 testing main' | sudo tee /etc/apt/sources.list.d/openhab.list
```
Additionally, you need to add the openHAB 2 Bintray repositories key to your package manager by using either `wget` or `curl`:
```shell
wget -qO - 'https://bintray.com/user/downloadSubjectPublicKey?username=openhab' | sudo apt-key add -
# or
curl 'https://bintray.com/user/downloadSubjectPublicKey?username=openhab' | sudo apt-key add -
```
* **Snapshot Release**
Add the **openHAB 2 Snapshot repositories** to your systems apt sources list (will overwrite your existing `openhab.list`):
```shell
echo 'deb https://openhab.ci.cloudbees.com/job/openHAB-Distribution/ws/distributions/openhab-offline/target/apt-repo/ /' | sudo tee /etc/apt/sources.list.d/openhab.list
echo 'deb https://openhab.ci.cloudbees.com/job/openHAB-Distribution/ws/distributions/openhab-online/target/apt-repo/ /' | sudo tee --append /etc/apt/sources.list.d/openhab.list
```
Note: CloudBees provides the openHAB 2 repositories through HTTPS.
If your system fails at the next step, install the missing dependency: `sudo apt-get install apt-transport-https`
Scan the newly added repository and resynchronize the package index:
```shell
sudo apt-get update
```
Finally install openHAB 2 as either offline or online distribution.
The **offline distribution** is full blown and comes with all add-ons, the **online distribution** will install additional add-ons on request from the internet.
```shell
sudo apt-get install openhab2-offline
# or
sudo apt-get install openhab2-online
```
If everything went well, start openHAB and register it to be automatically executed at system startup:
* Linux init systems based on **sysVinit** (e.g. Debian 7 / Ubuntu 14.x and earlier):
```shell
sudo /etc/init.d/openhab2 start
sudo /etc/init.d/openhab2 status
sudo update-rc.d openhab2 defaults
```
* Linux init systems based on **systemd** (e.g. Debian 8 / Ubuntu 15.x and newer):
```shell
sudo systemctl start openhab2.service
sudo systemctl status openhab2.service
sudo systemctl daemon-reload
sudo systemctl enable openhab2.service
```
The first start may take **up to 15 minutes**, this is a good time to reward yourself with hot coffee or a freshly brewed tea!
You should be able to reach the openHAB 2 portal at [http://openhab-device:8080](http://192.168.0.3:8080) at this point.
![The openHAB 2 portal page](images/Accueil_Openhab_2.png)
#### Upgrade
To stay up to date with new releases, you should do regular upgrades.
This is especially important if you are working with the latest snapshot as changes and fixes are incorporated [constantly](https://oss.jfrog.org/webapp/#/builds/openHAB-Distribution).
Your personal configuration will be retained on upgrades.
We still recommend a backup before each upgrade.
Upgrading is as easy as:
```shell
sudo apt-get update
sudo apt-get upgrade
```
Execute this additional command if you are working with the latest snapshot from CloudBees (every few weeks should suffice):
```shell
sudo apt-get --reinstall install openhab2-offline
# respectively
sudo apt-get --reinstall install openhab2-online
```
Reason: Snapshot builds are not provided as distinguishable versioned releases.
As such, apt does not detect the new snapshot as a possible upgrade.
To verify a new version is available and installed, check the [build history](https://oss.jfrog.org/webapp/#/builds/openHAB-Distribution) and the build version in the Karaf console before and after upgrade.
#### Backup and Restore
To make a backup of your openHAB 2 system, you need to retain your configuration and userdata files.
```shell
# stop openhab instance (here: systemd service)
sudo systemctl stop openhab2.service
# backup current installation with settings
TIMESTAMP=`date +%Y%m%d_%H%M%S`;
mkdir ~/openhab2-backup-$TIMESTAMP
cp -arv /etc/openhab2 ~/openhab2-backup-$TIMESTAMP/conf
cp -arv /var/lib/openhab2 ~/openhab2-backup-$TIMESTAMP/userdata
# restart openhab instance
sudo systemctl start openhab2.service
```
If you later want to restore settings, just replace them.
Maybe you will need to delete the existing data first.
```shell
# stop openhab instance (here: systemd service)
sudo systemctl stop openhab2.service
# restore data
sudo cp -arv /opt/openhab2-backup-20160131_235959/conf/* /etc/openhab2/
sudo cp -arv /opt/openhab2-backup-20160131_235959/userdata/* /var/lib/openhab2/
# restart openhab instance
sudo systemctl start openhab2.service
```
### Manual Installation
The manual installation/setup is an alternative to the otherwise **recommended** [installation through package repository](#package-repository-installation).
First, create a Linux system user for openHAB.
This user will later serve to execute the openHAB runtime with restricted permissions and can be used by other services like Samba if desired.
```shell
sudo adduser --system --no-create-home --group --disabled-login openhab
```
We are going to download a platform independent archive file and extract it to the path `/opt/openhab2`.
Choose between the latest Beta release or a Snapshot with all incoming contributions, created daily.
As openHAB 2 is still in an evolving state, the snapshot may be the **preferred choice**.
* **Beta Release**
Download and extract the desired **offline or online** beta version of openHAB 2 from [bintray.com/openhab](https://bintray.com/openhab/mvn/openhab-distro) to your host.
We will use `openhab-offline-2.0.0.b3.zip` as an example:
```shell
cd /tmp
wget -O openhab-download.zip https://bintray.com/openhab/mvn/download_file?file_path=org%2Fopenhab%2Fdistro%2Fopenhab-offline%2F2.0.0.b3%2Fopenhab-offline-2.0.0.b3.zip
sudo unzip openhab-download.zip -d /opt/openhab2
rm openhab-download.zip
```
* **Snapshot Release**
Download and extract the latest **offline or online** snapshot version of openHAB 2 as a **zip file** from [openhab.ci.cloudbees.com](https://openhab.ci.cloudbees.com/job/openHAB-Distribution) to your host.
We will use `openhab-offline-2.0.0-SNAPSHOT.zip` as an example:
```shell
cd /tmp
wget https://openhab.ci.cloudbees.com/job/openHAB-Distribution/lastSuccessfulBuild/artifact/distributions/openhab-offline/target/openhab-offline-2.0.0-SNAPSHOT.zip
sudo unzip openhab-offline-2.0.0-SNAPSHOT.zip -d /opt/openhab2
rm openhab-offline-2.0.0-SNAPSHOT.zip
```
The extracted openHAB files should belong to the earlier created openhab user. Execute:
```shell
sudo chown -hR openhab:openhab /opt/openhab2
```
Everything is ready for a first test run.
Execute openHAB and you should be able to reach the openHAB 2 Portal at [http://openhab-device:8080](http://192.168.0.3:8080) after a few minutes:
<!-- Note to author: Yes Yes, this will be changed ;) -->
```shell
sudo /opt/openhab2/start.sh
```
You will see the openHAB Karaf Console in your terminal and can directly interact with it.
An important downside is, that openHAB will be terminated, as soon as you close your terminal.
To work around that, a quick solution is, to execute openHAB in a detached [screen](https://www.howtoforge.com/linux_screen) terminal:
```shell
screen -d -m /opt/openhab2/start.sh
```
A cleaner approach is to create a Linux service, described next.
#### Service
The following instructions are intended for a Linux init system based on **systemd** (e.g. Debian 8 / Ubuntu 15.x and newer).
This will allow you to register openHAB as a service, so that it runs at startup and automatically restarts if openHAB crashes.
The service will be running with the privileges of the user "openhab" and expects the openHAB files under `/opt/openhab2`.
Create the file `/lib/systemd/system/openhab2.service` with the following content:
```ini
[Unit]
Description=The openHAB 2 Home Automation Bus Solution
Documentation=http://docs.openhab.org
Wants=network-online.target
After=network-online.target
[Service]
Type=simple
User=openhab
Group=openhab
GuessMainPID=yes
WorkingDirectory=/opt/openhab2
#EnvironmentFile=/etc/default/openhab2
ExecStart=/opt/openhab2/start.sh (server???)
ExecStop=kill -SIGINT $MAINPID
Restart=on-failure
[Install]
WantedBy=multi-user.target
```
Next, start the service and retrieve status information:
```shell
sudo systemctl start openhab2.service
sudo systemctl status openhab2.service
```
The output of `status` after a successful execution should be similar to:
```text
openhab2.service - The openHAB 2 Home Automation Bus Solution
Loaded: loaded (/lib/systemd/system/openhab2.service; enabled)
Active: active (running) since Thu 2016-08-14 01:16:00 GMT; 18h ago
Docs: http://docs.openhab.org
```
If everything went fine, enable the service to be executed on system startup:
```shell
# initialize the new service (execute only once)
sudo systemctl daemon-reload
sudo systemctl enable openhab2.service
```
#### Upgrade, Backup and Restore
To stay up to date with new releases, you should do regular upgrades of your manual installation.
This is especially important if you are working with the latest snapshot as changes and fixes are incorporated [constantly](https://oss.jfrog.org/webapp/#/builds/openHAB-Distribution).
Your personal configuration will be retained on upgrades.
We still recommend a backup before each upgrade.
To upgrade your manual installation, you simply need to replace the openHAB runtime files.
Make sure to first **stop your openHAB instance**.
To make a backup of your openHAB 2 system, you need to retain your configuration and userdata files.
The following shell commands will create a backup, install the newest openHAB 2 version and restore settings:
```shell
# stop openhab instance (here: systemd service)
sudo systemctl stop openhab2.service
# backup current installation with settings
TIMESTAMP=`date +%Y%m%d_%H%M%S`;
sudo mv /opt/openhab2 /opt/openhab2-backup-$TIMESTAMP
# download new version (please replace URL)
cd /tmp
wget https://openhab.ci.cloudbees.com/job/openHAB-Distribution/lastSuccessfulBuild/artifact/distributions/openhab-offline/target/openhab-offline-2.0.0-SNAPSHOT.zip
sudo unzip openhab-offline-2.0.0-SNAPSHOT.zip -d /opt/openhab2
rm openhab-offline-2.0.0-SNAPSHOT.zip
# restore configuration and userdata
sudo cp -arv /opt/openhab2-backup-$TIMESTAMP/conf /opt/openhab2/
sudo cp -arv /opt/openhab2-backup-$TIMESTAMP/userdata /opt/openhab2/
# fix permissions
sudo chown -hR openhab:openhab /opt/openhab2
# restart openhab instance
sudo systemctl start openhab2.service
```
## File Locations
| | Repository Installation | Manual Installation (according to [guide](#manual-installation)) |
|:--------------------------------:|:-------------------------|:------------------------------------------------------------------|
| openHAB application | `/usr/share/openhab2` | `/opt/openhab2` |
| Site configuration | `/etc/openhab2` | `/opt/openhab2/conf` |
| Log files | `/var/log/openhab2` | `/opt/openhab2/userdata/logs` |
| Userdata like rrd4j databases | `/var/lib/openhab2` | `/opt/openhab2/userdata` |
| Service configuration | `/etc/default/openhab2` | (not preconfigured) |
## Network Sharing
openHAB depends on configuration files and folders with custom content (details in [Configuration](http://docs.openhab.org/configuration/index.html) articles).
Because your openHAB installation most probably is stored on a remote device, being able to easily access and modify these files from your local PC or Mac is important, therefore setting up a Samba network share is highly recommended.
The [Eclipse SmartHome Designer](http://docs.openhab.org/installation/designer.html) software does also depend on a mounted share to access the openHAB configuration files.
We will now guide you through the Samba network shares setup process.
Start by installing Samba. Afterwards open it's configuration file in your favorite editor:
```shell
sudo apt-get install samba samba-common-bin
sudo vim /etc/samba/smb.conf
```
Change the workgroup name if needed, otherwise uncomment and enable WINS support:
```ini
wins support = yes
```
Next, add the desired share configurations to the end of the file:
<!-- Note to author: Do not name share "openhab". Depending on the host system, a share for the home of user "openhab" will be created.-->
<!-- TODO: Limit to configuration folder??? -->
* Package repository based installation:
```ini
[openHAB-sys]
comment=openHAB2 application
path=/usr/share/openhab2
browseable=Yes
writeable=Yes
only guest=no
public=no
create mask=0777
directory mask=0777
[openHAB-conf]
comment=openHAB2 site configuration
path=/etc/openhab2
browseable=Yes
writeable=Yes
only guest=no
public=no
create mask=0777
directory mask=0777
```
* Manual installation:
```ini
[openHAB-files]
comment=openHAB2
path=/opt/openhab2
browseable=Yes
writeable=Yes
only guest=no
public=no
create mask=0777
directory mask=0777
```
Save and close the samba configuration file.
The shares are configured to be not open for guests nor to the public.
Let's activate the "openhab" user as a samba user and set his password (e.g. "habopen"):
```shell
sudo smbpasswd -a openhab
```
Be aware, that creating and later using a specific user will ensure, that [permissions](#permissions) are honored.
Make sure, the "openhab" user has ownership and/or write access to the openHAB configuration files.
This can be accomplished by executing:
```shell
sudo chown -hR openhab:openhab /etc/openhab2 /opt/openhab2/conf
```
Finally check the configuration file for correctness and restart Samba to load the new settings:
```shell
testparm
# Linux init systems based on sysVinit
sudo service smbd restart
# Linux init systems based on systemd
sudo systemctl restart smbd.service
```
### Mounting Locally
After setting up and restarting Samba, check your connection to the shared folder and create a permanent mount.
Check the network devices manager of your local operating system to find and access your openHAB host and share.
These might however not be auto-discovered. You can also manually connect:
* **On Mac OS X:** Open Finder → Go → Connect to Server: `smb://openhab@openhab-device.local`
* **On Windows:** Open Windows Explorer → Address bar: `\\openhab-device.local` → Right click a share and assign a drive letter
Be sure to use the actual host name instead of `openhab-device`.
When asked, authenticate with the username "openhab" and the chosen password.
If you are not able to connect, try with the IP of your device (e.g. `smb://openhab@192.168.0.2` or `\\192.168.0.2`).
If everything went well, you are set and ready to start [configuring](http://docs.openhab.org/configuration/index.html) your openHAB system.
## Viewing Log Messages
In order to get more insight on what your openHAB system is doing and to see occurring error messages, it is recommended to always have a look on the openHAB log files. These will tell you everything you might need to know. Execute the following command in one session or have both files separated in sessions side by side:
* Package repository based installation:
```shell
tail -f /var/log/openhab2/openhab.log -f /var/log/openhab2/events.log
```
* Manual installation:
```shell
tail -f /opt/openhab2/userdata/logs/openhab.log -f /opt/openhab2/userdata/logs/events.log
```
You could even set up an SSH configuration (in Putty or similar) to automatically connect and execute the commands every time you start working on your setup.
With openHAB 2 you can also [use the Karaf console](http://docs.openhab.org/administration/logging.html#karaf-console) to have a colored glance at the logging information.

201
installation/rasppi.md
View File

@ -17,15 +17,13 @@ Be sure to use a [Raspberry Pi Generation 2](https://en.wikipedia.org/wiki/Raspb
In this article you will find **suggestions** on how to configure a dedicated Raspberry Pi to run as openHAB server.
Your personal preferences and needs may differ!
There’s no pre-configured image for openHAB yet.
There's no pre-configured image for openHAB yet.
Setting up openHAB shouldn't be a problem following the instructions below.
If you are unfamiliar with Linux, SSH and the Linux console or if you want to improve your skills, read up on these important topics.
A lot of helpful articles can be found on the internet, including:
If you get stuck at any point or want to learn more about the possibilities of the Raspberry Pi and Linux, many tutorials can be found on the internet, including:
* The [raspberrypi.org help articles](https://www.raspberrypi.org/help).
* Technical in-detail articles at [eLinux.org](http://elinux.org/RPi_Tutorials).
* "Learn the ways of Linux-fu, for free" interactively with exercises at [linuxjourney.com](https://linuxjourney.com/).
## Recommended Setup
@ -36,196 +34,39 @@ You will need:
* Power supply
* Ethernet connection
For the beginning, we recommend to [download](https://www.raspberrypi.org/downloads/raspbian) and [install](https://www.raspberrypi.org/documentation/installation/installing-images/README.md) the latest Raspbian SD card image (not the "lite" version).
Get your SD card and network cable plugged in, power up, and connect through the SSH remote console.
For the beginning, we recommend to [download](https://www.raspberrypi.org/downloads/raspbian) and [install](https://www.raspberrypi.org/documentation/installation/installing-images/README.md) the latest Raspbian SD card image.
You may choose the "Lite" version.
Execute the Raspbian configuration menu by running: `sudo raspi-config`
Get your SD card and network cable plugged in, power up, and connect through the SSH remote console.
Booting up takes up to 10 minutes.
To connect with an SSH client (like Putty), you need to know the IP address or hostname of your device.
A standard Raspbian setup should be reachable either by the hostname "raspberrypi" or though the local domain name "raspberrypi.local".
If you are not able to connect, check your routers web frontend for newly connected devices.
Connected via SSH, execute the Raspbian configuration menu by running `sudo raspi-config`. Go through the following steps:
* Expand the file system
* Change your password
* (Change the host name, default: "raspberrypi")
* From the advanced menu, change the memory split to "16"
* (Change the host name if you wish, e.g. "openhabpi")
* From the advanced menu, change the memory split for the GPU to "16"
* Restart
As a good practice, run a full upgrade and install packages you like or need (a set of helpful packages is given as an example):
```
```shell
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install screen mc vim nano curl wget unzip git htop vfu
sudo apt-get install screen mc vim git htop
```
Install openHAB on Linux. This can be done two ways:
Raspbian in the latest full versions already includes the [required](index.html#prerequisites) Oracle Java 8.
If you are using "Raspbian Lite" you need to install it:
* [Installation on Linux manually](linux.html)
* [Installation on Linux through APT](apt.html) (recommended)
### Permissions
<!-- Note to author: May be moved to linux.html while you are at it -->
Linux file permissions is one of the biggest sources of issues, Linux novices run into.
If you find yourself in a situation, where you have **no write access** to the openHAB configuration or system files, wrong permissions and/or the incorrect use of `sudo` are often the cause.
Train your understanding of Linux permissions at [linuxjourney.com/lesson/file-permissions](https://linuxjourney.com/lesson/file-permissions).
## Network Share
openHAB depends on configuration files and folders with custom content (details in [Configuration](http://docs.openhab.org/configuration/index.html) articles).
Because your openHAB installation is stored on a remote device, being able to easily access and modify these files from your local PC or Mac is important.
The recommended [Eclipse SmartHome Designer](http://docs.openhab.org/installation/designer.html) software does also depend on a mounted share to access the openHAB configuration files.
We will now guide you through the Samba network shares setup process.
Start by installing Samba. Afterwards open it's config file in your favorite editor:
```
sudo apt-get install samba samba-common-bin
sudo nano /etc/samba/smb.conf
```shell
sudo apt-get install oracle-java8-jdk
```
Change the workgroup name if needed, otherwise uncomment and enable WINS support:
```
wins support = yes
```
Next, add the following lines to the end of the file:
```
[openHAB]
comment=openHAB2 application
path=/usr/share/openhab2
browseable=Yes
writeable=Yes
only guest=no
public=no
create mask=0777
directory mask=0777
[openHAB-etc]
comment=openHAB2 site configuration
path=/etc/openhab2
browseable=Yes
writeable=Yes
only guest=no
public=no
create mask=0777
directory mask=0777
```
Save and close the samba configuration file.
As you can see, we are creating two shares, one for the openHAB application files, one for the configuration files.
Please take note, that the mentioned paths will differ if you did not install through the package repository.
The shares are configured to be not open for guests or to the public.
Let's create an "openhab" samba user and set his password (e.g. "habopen"):
```
sudo smbpasswd -a openhab
```
Be aware, that creating and later using a specific user will ensure, that [permissions](#permissions) are honored.
Transfer the ownership of all openHAB files to the "openhab" user, making sure you will be able to write them:
```
sudo chown -hR openhab:openhab /etc/openhab2 /usr/share/openhab2
```
Finally restart Samba:
```
sudo update-rc.d smbd enable
sudo update-rc.d nmbd enable
sudo service smbd restart
```
### Mounting Locally
After setting up and restarting Samba, check your connection to the shared folders and and create permanent mounts.
The shares might not be auto-discovered on your systems network devices page.
You'll have to manually connect:
* **On Mac OS X:** Open Finder -> Go -> Connect to Server: `smb://openhab@raspberrypi.local`
* **On Windows:** Open Windows Explorer -> Address bar: `\\raspberrypi.local` -> Right click a share and assign a drive letter
When asked, authenticate with the username openhab and the chosen password.
Be sure to use the right host name if you changed it to something different than "raspberrypi".
If you are not able to connect, try with the IP of your Raspberry Pi (e.g. `smb://openhab@192.168.0.2` or `\\192.168.0.2`).
If everything went well, you are set and ready to start [configuring](http://docs.openhab.org/configuration/index.html) your openHAB system.
## Viewing the Log Messages
<!-- Note to author: This part may be moved to a different article -->
In order to get more insight on what your openHAB system is doing and to see occurring error messages, it is recommended to always have a look on the openHAB log files. These will tell you everything you might need to know. Execute the following command in one session or have both files separated in sessions side by side:
```
tail -f /var/log/openhab2/openhab.log -f /var/log/openhab2/events.log
```
You could even set up an SSH configuration (in putty or similar) to automatically connect and execute the commands every time you start working on your setup.
With openHAB 2 you can also [use the Karaf console](http://docs.openhab.org/administration/logging.html#karaf-console) to have a colored glance at the logging information.
## Service
The following instructions are only relevant if you did a manual (non-apt) installation!
<!-- Note to author: Please move to linux.html while you are at it ;) -->
Under Raspbian Jessie, the following steps will allow you to register openHAB as a service, so that it runs at startup and automatically restarts if openHAB crashes.
1. Make sure openHAB is installed somewhere, for the purpose of this guide it's installed in /opt/openhab2.
2. Create the following file called "openhab.service" in /lib/systemd/system/ replacing the username with whichever user runs openHAB on your setup.
```ini
[Unit]
Description=Starts and stops the openHAB Home Automation Bus
Documentation=http://www.openhab.org
Wants=network-online.target
After=network-online.target
[Service]
Type=simple
GuessMainPID=yes
User=**enter your openhab username here**
ExecStart=/opt/openhab2/start.sh
ExecStop=kill -SIGINT $MAINPID
Restart=on-failure
WorkingDirectory=/opt/openhab2
[Install]
WantedBy=multi-user.target
```
3. Run the following commands to enable the service, start the service and check the status of the service respectively.
```
sudo systemctl enable openhab
sudo systemctl start openhab
sudo systemctl status openhab
```
4. Assuming all looks good when you checked the status of the service, i.e. you see something like the below on your command line, then it should now be setup to run as a service.
```text
openhab.service - Starts and stops the openHAB Home Automation Bus
Loaded: loaded (/etc/systemd/system/openhab.service; enabled)
Active: active (running) since Thu 2016-01-14 01:16:00 GMT; 18h ago
Docs: http://www.openhab.org
```
5. If you need to stop openHAB use the following command.
```
sudo systemctl stop openhab
```
6. If you need to disable the service so that it doesn't run at startup use the following command.
```
sudo systemctl disable openhab
```
Install openHAB on your Raspberry Pi, as it is described in the [openHAB 2 on Linux](linux.html) article:
* [Package Repository based Installation on Linux](linux.html#package-repository-installation)