Start with Markdownlint fro vscode editing. Initial linting error fixes. (#1377)
Signed-off-by: Jerome Luckenbach <github@luckenba.ch>pull/1380/head
Jerome Luckenbach
GitHub
parent
9a642dfb0c
commit
953e074c0a
|
|
@ -0,0 +1,8 @@
|
|||
{
|
||||
"default": true,
|
||||
"MD004": {
|
||||
"style": "dash"
|
||||
},
|
||||
"MD013": false,
|
||||
"MD025": false
|
||||
}
|
||||
|
|
@ -23,13 +23,11 @@ Armbian is a base operating system platform for single board computers.
|
|||
|
||||
OpenHab will run on any Armbian [supported hardware](https://www.armbian.com/download/?device_support=Supported) but it is recommended to choose boards that have at least:
|
||||
|
||||
|
||||
- 512 Kb of memory (on minimal or server image)
|
||||
- eMMC or a [quality SD card](https://docs.armbian.com/User-Guide_Getting-Started/#how-to-prepare-a-sd-card)
|
||||
- 4 core
|
||||
- wired networking
|
||||
|
||||
|
||||
|
||||
|
||||
## Supported images
|
||||
|
|
@ -42,14 +40,14 @@ You can [download](https://www.armbian.com/download/?device_support=Supported) a
|
|||
|
||||
1. Prepare Armbian as usual - [login as root / 1234, change root password, create username. You don't need to perform any other steps](https://docs.armbian.com/User-Guide_Getting-Started/).
|
||||
|
||||
2. Update
|
||||
1. Update
|
||||
|
||||
```shell
|
||||
sudo apt-get update
|
||||
sudo apt-get upgrade
|
||||
```
|
||||
|
||||
3. Run armbian-config
|
||||
1. Run armbian-config
|
||||
|
||||
```shell
|
||||
sudo armbian-config
|
||||
|
|
|
|||
|
|
@ -166,6 +166,7 @@ Finally run `sudo systemctl start openhab2.service` to start openHAB running.
|
|||
## Explanation of Arguments Passed to Docker
|
||||
|
||||
Note, always review the README on [Docker Hub](https://hub.docker.com/r/openhab/openhab/) for the most up to date set of recommended arguments and environment variables.
|
||||
|
||||
- `/usr/bin/docker run` : create a new container from the passed in Image (last argument)
|
||||
- `--name=openhab` : give the container a human remember able name
|
||||
- `--net=host` : by default Docker will place a container into its own network stack. However, openHAB requires UPnP discovery so this parameter makes the Docker container use the host's network stack.
|
||||
|
|
@ -238,7 +239,6 @@ docker exec \
|
|||
/bin/chmod o+rw /dev/ttyACM0
|
||||
```
|
||||
|
||||
|
||||
This command changes permissions of the specific device as expected (readable and writable for everyone).
|
||||
|
||||
::: tip Note
|
||||
|
|
|
|||
|
|
@ -17,10 +17,10 @@ Always keep this in mind when searching for help and solutions.
|
|||
|
||||
## Platform Recommendations
|
||||
|
||||
1. You are **new to openHAB** and want to give it a try? You are in luck:
|
||||
1. You are **new to openHAB** and want to give it a try? You are in luck:
|
||||
- Set up openHAB on your local PC or Mac in just a few steps.
|
||||
|
||||
1. You've gained some experience and want to use openHAB to seriously control your home?
|
||||
1. You've gained some experience and want to use openHAB to seriously control your home?
|
||||
Typical hardware and software requirements are:
|
||||
- **24/7 availability:** A dedicated system connected by Ethernet and running continuously.
|
||||
- **Energy and space efficient:** A device capable of performing the task at hand without being excessive for your needs.
|
||||
|
|
@ -74,12 +74,12 @@ OpenJDK 64-Bit Server VM Zulu11.43+55-CA (build 11.0.9.1+1-LTS, mixed mode)
|
|||
|
||||
Before you can start, two decisions have to be made:
|
||||
|
||||
1. openHAB is available as a platform independent archive file or through a package repository:
|
||||
1. openHAB is available as a platform independent archive file or through a package repository:
|
||||
- **Manual setup:** Download and extract a platform independent zip archive: [macOS](macos.html), [Windows](windows.html), [Linux](linux.html#manual-installation)
|
||||
- **Package setup:** Install from a package repository, using a package manager such as apt or yum.
|
||||
This option is only available for certain Linux distributions such as Debian or Ubuntu derivatives, but allows you to take advantage of automatic updates and is the recommended choice: [Linux (apt/deb)](linux.html#package-repository-installation)
|
||||
|
||||
2. Stable release or cutting edge:
|
||||
2. Stable release or cutting edge:
|
||||
- **Stable:** Use the latest official release [hosted on Bintray](https://bintray.com/openhab/mvn/openhab-distro) (recommended for new users).
|
||||
- **Snapshot:** Benefit from the latest changes in the daily created snapshot ([hosted on openhab.org](https://ci.openhab.org/)).
|
||||
|
||||
|
|
@ -91,9 +91,9 @@ Please follow the instructions in the installation article matching your platfor
|
|||
|
||||
After you get openHAB set up and running, there are a few additional setup steps you should consider:
|
||||
|
||||
- Configure a network share on your openHAB host system using [Linux Samba Share](linux.html#network-sharing) for easier remote editing of configuration files.
|
||||
- Configure a network share on your openHAB host system using [Linux Samba Share](linux.html#network-sharing) for easier remote editing of configuration files.
|
||||
|
||||
- Install [Visual Studio Code](https://code.visualstudio.com/Download) and the [openHAB VS Code Extension]({{base}}/configuration/editors.html#openhab-vs-code-extension) on your local machine, to manage your (remote) configuration files.
|
||||
- Install [Visual Studio Code](https://code.visualstudio.com/Download) and the [openHAB VS Code Extension]({{base}}/configuration/editors.html#openhab-vs-code-extension) on your local machine, to manage your (remote) configuration files.
|
||||
The openHAB VS Code Extension comes with built-in support for the openHAB syntax and elements.
|
||||
|
||||
## Getting started
|
||||
|
|
|
|||
|
|
@ -27,7 +27,8 @@ Linux file permissions is one of the biggest sources of issues, Linux novices ru
|
|||
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).
|
||||
|
||||
## Meeting the Requirements: ##
|
||||
## Meeting the Requirements
|
||||
|
||||
As a first step, please verify, that your system meets the [prerequisites](index.html#prerequisites).
|
||||
You may want to install Zulu, a fully certified Java build [as a package or manually](https://docs.azul.com/zulu/zuludocs/ZuluUserGuide/InstallingZulu/InstallZulu.htm).
|
||||
|
||||
|
|
@ -43,9 +44,10 @@ Make sure to download Zulu or Java **11**.
|
|||
## Installation
|
||||
|
||||
openHAB can be installed through
|
||||
- the openHABian project **(easiest method, ships with the openHABian configuration tool)**
|
||||
- a package repository (apt, yum)
|
||||
- manually from file.
|
||||
|
||||
- the openHABian project **(easiest method, ships with the openHABian configuration tool)**
|
||||
- a package repository (apt, yum)
|
||||
- manually from file.
|
||||
|
||||
The installation through the **openHABian project** and the use of the provided openHABian configuration tool is recommended for end users.
|
||||
|
||||
|
|
@ -54,6 +56,7 @@ Installing using the provided **package repository** (using `apt`, `apt-get`, `y
|
|||
The manual installation through a platform independent archive file is suited for users who know what they are doing.
|
||||
|
||||
### openHABian project
|
||||
|
||||
The easy step by step instruction can be found [here](openhabian.html).
|
||||
|
||||
### Package Repository Installation
|
||||
|
|
@ -77,7 +80,7 @@ sudo apt-get install apt-transport-https
|
|||
|
||||
Then, you can choose between, *Official (Stable)*, *Beta* or *Snapshot* builds:
|
||||
|
||||
- **Stable Release**
|
||||
- **Stable Release**
|
||||
|
||||
The stable builds contain the latest official release with tested features.
|
||||
|
||||
|
|
@ -87,7 +90,7 @@ Then, you can choose between, *Official (Stable)*, *Beta* or *Snapshot* builds:
|
|||
echo 'deb https://dl.bintray.com/openhab/apt-repo2 stable main' | sudo tee /etc/apt/sources.list.d/openhab.list
|
||||
```
|
||||
|
||||
- **Testing Release**
|
||||
- **Testing Release**
|
||||
|
||||
The beta and release candidate builds come out less frequently, but will contain new features that are currently in the testing phase.
|
||||
|
||||
|
|
@ -97,7 +100,7 @@ Then, you can choose between, *Official (Stable)*, *Beta* or *Snapshot* builds:
|
|||
echo 'deb https://openhab.jfrog.io/artifactory/openhab-linuxpkg testing main' | sudo tee /etc/apt/sources.list.d/openhab.list
|
||||
```
|
||||
|
||||
- **Snapshot Release**
|
||||
- **Snapshot Release**
|
||||
|
||||
The snapshot build is created [almost daily](https://ci.openhab.org/job/openhab-linuxpkg/), and include the latest changes to the openHAB core and add-ons.
|
||||
These changes are often unstable, so you should use this branch only for testing or development purposes.
|
||||
|
|
@ -138,7 +141,7 @@ sudo apt-get install openhab-addons
|
|||
The RPM repo information should be defined inside a file, make a new file at `/etc/yum.repos.d/openhab.repo` with the following contents depending on your choice of release.
|
||||
You may add all three to the same file, but make sure the desired repo is is set to `enabled=1`:
|
||||
|
||||
- **Stable Release**
|
||||
- **Stable Release**
|
||||
|
||||
The stable builds contain the latest official release with tested features.
|
||||
|
||||
|
|
@ -151,7 +154,7 @@ You may add all three to the same file, but make sure the desired repo is is set
|
|||
enabled=1
|
||||
```
|
||||
|
||||
- **Testing Release**
|
||||
- **Testing Release**
|
||||
|
||||
The beta or release candidate builds come out less frequently, but will contain new features that are currently in the testing phase.
|
||||
|
||||
|
|
@ -164,7 +167,7 @@ You may add all three to the same file, but make sure the desired repo is is set
|
|||
enabled=1
|
||||
```
|
||||
|
||||
- **Snapshot Release**
|
||||
- **Snapshot Release**
|
||||
|
||||
The snapshot build is created [almost daily](https://ci.openhab.org/job/openhab-linuxpkg/), and include the latest changes to the openHAB core and add-ons.
|
||||
These changes are often unstable, so you should use this branch only for testing or development purposes.
|
||||
|
|
@ -260,7 +263,7 @@ sudo systemctl enable openhab.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 Dashboard at [http://openhab-device:8080]() at this point.
|
||||
You should be able to reach the openHAB Dashboard at `http://openhab-device:8080` at this point.
|
||||
If you're new to openHAB, then you should checkout the [beginner's tutorial]({{base}}/tutorial/first_steps.html)!
|
||||
|
||||
|
||||
|
|
@ -450,7 +453,7 @@ We are going to download a platform independent archive file and extract it to t
|
|||
Choose between the latest Beta release or a Snapshot with all incoming contributions, created daily.
|
||||
As openHAB is still in an evolving state, the snapshot may be the **preferred choice**.
|
||||
|
||||
- **Official Release**
|
||||
- **Official Release**
|
||||
|
||||
Download and extract the latest offical stable version of openHAB from [our downloadpage](https://www.openhab.org/download/) to your host:
|
||||
|
||||
|
|
@ -461,11 +464,11 @@ As openHAB is still in an evolving state, the snapshot may be the **preferred ch
|
|||
rm openhab-download.zip
|
||||
```
|
||||
|
||||
- **Beta/RC Release**
|
||||
- **Beta/RC Release**
|
||||
|
||||
If available, beta or release candidate builds of openHAB can also be downloaded from [our downloadpage](https://www.openhab.org/download/) and extracted to your host as shown above.
|
||||
|
||||
- **Snapshot Release**
|
||||
- **Snapshot Release**
|
||||
|
||||
Download and extract the latest snapshot version of openHAB from [our downloadpage](https://www.openhab.org/download/) to your host. The process is analogue to above.
|
||||
|
||||
|
|
@ -477,7 +480,7 @@ sudo chown -hR openhab:openhab /opt/openhab
|
|||
```
|
||||
|
||||
Everything is ready for a first test run.
|
||||
**Execute** openHAB and you should be able to reach the openHAB Dashboard at [http://openhab-device:8080]() after a few minutes:
|
||||
**Execute** openHAB and you should be able to reach the openHAB Dashboard at `http://openhab-device:8080` after a few minutes:
|
||||
|
||||
```shell
|
||||
# execute as restricted user openhab:
|
||||
|
|
@ -563,7 +566,7 @@ This is especially important if you are working with the latest snapshot as chan
|
|||
openHAB uses a script to update to any other version, or from stable to snapshot and visa-versa.
|
||||
Your personal configuration will be retained on upgrades, but you should **stop openHAB** and perform a backup first.
|
||||
|
||||
- **Versions 2.1.0 and Above**
|
||||
- **Versions 2.1.0 and Above**
|
||||
|
||||
From version 2.1.0, openHAB is distributed with the update script included.
|
||||
This script should be called from within openHAB's root directory.
|
||||
|
|
@ -587,7 +590,7 @@ Your personal configuration will be retained on upgrades, but you should **stop
|
|||
sudo runtime/bin/update 2.2.0-SNAPSHOT
|
||||
```
|
||||
|
||||
- **Older Versions**
|
||||
- **Older Versions**
|
||||
|
||||
If you're using a version earlier than 2.1.0, then you can use the following commands in Terminal to download the script and run it.
|
||||
Assuming the openHAB directory is in `/opt/openhab`:
|
||||
|
|
@ -732,7 +735,7 @@ Next, add the desired share configurations to the end of the file:
|
|||
|
||||
<!-- TODO: Limit to configuration folder??? -->
|
||||
|
||||
- Package repository based installation:
|
||||
- Package repository based installation:
|
||||
|
||||
```ini
|
||||
[openHAB-userdata]
|
||||
|
|
@ -766,7 +769,7 @@ Next, add the desired share configurations to the end of the file:
|
|||
directory mask=0777
|
||||
```
|
||||
|
||||
- Manual installation:
|
||||
- Manual installation:
|
||||
|
||||
```ini
|
||||
[openHAB-files]
|
||||
|
|
|
|||
|
|
@ -23,16 +23,16 @@ If you're unfamiliar with using the macOS terminal, then feel free to follow the
|
|||
openHAB is packaged as a platform independent `zip` archive. Installation is as simple as unziping it into a unique folder.
|
||||
First, make sure that your system meets the [prerequisites](index.html#prerequisites).
|
||||
When you are running macOS BigSur or higher, make sure
|
||||
that you select the right platform depending on your hardware (x86 or ARM 64-bit).
|
||||
that you select the right platform depending on your hardware (x86 or ARM 64-bit).
|
||||
|
||||
You have the choice to use the current stable version or the latest snapshot build:
|
||||
|
||||
- **Stable**
|
||||
- **Stable**
|
||||
|
||||
The stable builds have undergone testing, it is the recommended version to download.
|
||||
Download the latest `openhab-3.x.x.zip` [here](https://www.openhab.org/download/).
|
||||
|
||||
- **Snapshot (Unstable)**
|
||||
- **Snapshot (Unstable)**
|
||||
|
||||
Snapshots are built daily, and contain the latest changes to openHAB's source code.
|
||||
These changes haven't undergone the same amount of testing as the stable releases, so only use them if you **need** a new feature.
|
||||
|
|
@ -79,11 +79,11 @@ The first run may take a while to process, wait until the "`openhab>`" prompt ap
|
|||
$ ./start.sh
|
||||
Launching the openHAB runtime...
|
||||
|
||||
_ _ _ ____
|
||||
___ ___ ___ ___ | | | | / \ | __ )
|
||||
/ _ \ / _ \ / _ \ / _ \ | |_| | / _ \ | _ \
|
||||
_ _ _ ____
|
||||
___ ___ ___ ___ | | | | / \ | __ )
|
||||
/ _ \ / _ \ / _ \ / _ \ | |_| | / _ \ | _ \
|
||||
| (_) | (_) | __/| | | || _ | / ___ \ | |_) )
|
||||
\___/| __/ \___/|_| |_||_| |_|/_/ \_\|____/
|
||||
\___/| __/ \___/|_| |_||_| |_|/_/ \_\|____/
|
||||
|_| 3.0.0 - Release Build
|
||||
|
||||
Use '<tab>' for a list of available commands
|
||||
|
|
@ -94,7 +94,7 @@ To exit, use '<ctrl-d>' or 'logout'.
|
|||
openhab>
|
||||
```
|
||||
|
||||
Without closing the terminal, open your favorite web browser and type the following URL: [http://localhost:8080](http://localhost:8080), you should see the openHAB welcome screen, and you're all set to [using openHAB]({{base}}/tutorial/first_steps.html).
|
||||
Without closing the terminal, open your favorite web browser and type the following URL: [http://localhost:8080](http://localhost:8080), you should see the openHAB welcome screen, and you're all set to [using openHAB]({{base}}/tutorial/first_steps.html).
|
||||
If you installed openHAB on a different device, replace localhost with the IP address of the device.
|
||||
|
||||
## Updating openHAB
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
layout: documentation
|
||||
title: QNAP NAS
|
||||
---
|
||||
|
||||
|
||||
{% include base.html %}
|
||||
|
||||
# QNAP NAS
|
||||
|
|
@ -17,34 +17,34 @@ Please find all details about the openHAB package for QNAP [here](https://github
|
|||
Check that your NAS has the most recent firmware version.
|
||||
Follow the instructions shown if a new version is announced when opening the admin GUI.
|
||||
|
||||
1. Download the QPKG from the [releases section over on GitHub](https://github.com/openhab/openhab-qnap-qpkg/releases).
|
||||
1. Download the QPKG from the [releases section over on GitHub](https://github.com/openhab/openhab-qnap-qpkg/releases).
|
||||
|
||||
2. Create a directory for your addons, configurations and userdata, by either
|
||||
2. Create a directory for your addons, configurations and userdata, by either
|
||||
- Creating a share called "openHAB" (recommended)
|
||||
- Creating a folder called "openHAB" inside the "Public" share
|
||||
- Not creating any of them and therefore using `.qpkg/openHAB2/distribution` for all data (for testing or demonstration)
|
||||
|
||||
3. Go to your NAS's App Center and make sure you have got "JRE" (for x86-CPU based NAS) or "JRE_ARM" (for ARM-CPU based NAS) installed.
|
||||
3. Go to your NAS's App Center and make sure you have got "JRE" (for x86-CPU based NAS) or "JRE_ARM" (for ARM-CPU based NAS) installed.
|
||||
If that is not the case, go to the "Developer-Tools" section of the App Center, install the appropriate version and wait for a while until the Java installation has finished.
|
||||
|
||||
4. Open the "Install manually" dialog in the App Center by clicking the gear-wheel on the upper-right corner of the App Center and choose the `qpkg` you have downloaded.
|
||||
4. Open the "Install manually" dialog in the App Center by clicking the gear-wheel on the upper-right corner of the App Center and choose the `qpkg` you have downloaded.
|
||||
|
||||
|
||||
|
||||
5. Confirm the installation
|
||||
5. Confirm the installation
|
||||
|
||||
|
||||
|
||||
6. Wait while the package is being installed
|
||||
6. Wait while the package is being installed
|
||||
|
||||
|
||||
|
||||
7. When finished just close the dialog and wait for a while until openHAB has completely started.
|
||||
7. When finished just close the dialog and wait for a while until openHAB has completely started.
|
||||
This may take several minutes.
|
||||
|
||||
|
||||
|
||||
8. Access openHAB via "[http://NAS_IP_or_DNS_address:8090](#)".
|
||||
8. Access openHAB via `http://NAS_IP_or_DNS_address:8090`.
|
||||
If the interface does not start, retry after another minute.
|
||||
The initial startup takes some time.
|
||||
|
||||
|
|
@ -52,9 +52,9 @@ Follow the instructions shown if a new version is announced when opening the adm
|
|||
|
||||
If you want to keep configuration files, copy them to a save place outside of the openhab-path.
|
||||
|
||||
1. Go to the "App Center" and remove the app like any other.
|
||||
1. Go to the "App Center" and remove the app like any other.
|
||||
|
||||
2. Additionally if wanted or needed, please remove the folders "addons", "conf" and "userdata" from the your directory, eg. "openHAB2" share or "Public"/openHAB2
|
||||
2. Additionally if wanted or needed, please remove the folders "addons", "conf" and "userdata" from the your directory, eg. "openHAB2" share or "Public"/openHAB2
|
||||
If you have installed openHAB2 to `.qpkg` (see "How to install", third option) then all files get removed automatically.
|
||||
|
||||
## Known issues
|
||||
|
|
|
|||
|
|
@ -68,6 +68,7 @@ openHAB will see these incoming requests as originating from the local loopback
|
|||
The simplest way to get hold of such an openHAB Cloud is to register an account at [myopenHAB.org](https://www.myopenhab.org/), which is operated by the [openHAB Foundation](https://www.openhabfoundation.org/).
|
||||
|
||||
{: #nginx-reverse-proxy}
|
||||
|
||||
### Running openHAB Behind a Reverse Proxy
|
||||
|
||||
A reverse proxy simply directs client requests to the appropriate server.
|
||||
|
|
@ -105,11 +106,13 @@ The good news is that [openHABian](openhabian) already offers the possibility to
|
|||
- [Further Reading](#nginx-further-reading)
|
||||
|
||||
{: #nginx-setup}
|
||||
|
||||
#### Setting up NGINX
|
||||
|
||||
These are the steps required to use [**NGINX**](https://nginx.org), a lightweight HTTP server, although you can use **Apache HTTP** server or any other HTTP server which supports reverse proxying.
|
||||
|
||||
{: #nginx-setup-install}
|
||||
|
||||
##### Installation
|
||||
|
||||
NGINX runs as a service in most Linux distributions, installation should be as simple as:
|
||||
|
|
@ -122,6 +125,7 @@ Once installed, you can test to see if the service is running correctly by going
|
|||
If you don't, you may need to check your firewall or ports and check if port 80 (and 443 for HTTPS later) is not blocked and that services can use it.
|
||||
|
||||
{: #nginx-setup-config}
|
||||
|
||||
##### Basic Configuration
|
||||
|
||||
NGINX configures the server when it starts up based on configuration files.
|
||||
|
|
@ -168,12 +172,14 @@ sudo service nginx restart
|
|||
...and then go to `http://mydomain_or_myip` to see your openHAB server.
|
||||
|
||||
{: #nginx-auth}
|
||||
|
||||
#### Authentication with NGINX
|
||||
|
||||
For further security, you may wish to ask for a **username and password** before users have access to openHAB.
|
||||
This is fairly simple in NGINX once you have the reverse proxy setup, you just need to provide the server with a basic authentication user file.
|
||||
|
||||
{: #nginx-auth-user}
|
||||
|
||||
##### Creating the First User
|
||||
|
||||
You will be using *htpasswd* to generate a username/password file, this utility can be found in the apache2-utils package:
|
||||
|
|
@ -192,6 +198,7 @@ You will receive a prompt to create a password for this username, once finished
|
|||
You're then free to reference the file to NGINX.
|
||||
|
||||
{: #nginx-auth-file}
|
||||
|
||||
##### Referencing the File in the NGINX Configuration
|
||||
|
||||
Now the configuration file (`/etc/nginx/sites-enabled/openhab`) needs to be edited to use this password.
|
||||
|
|
@ -205,6 +212,7 @@ Open the configuration file and **add** the following lines underneath the proxy
|
|||
Once done, **test and restart your NGINX service** and authentication should now be enabled on your server!
|
||||
|
||||
{: #nginx-auth-users}
|
||||
|
||||
##### Adding or Removing users
|
||||
|
||||
To add new users to your site, you must use following command, **do not** use the `-c` modifier again as this will remove all previously created users:
|
||||
|
|
@ -222,6 +230,7 @@ sudo htpasswd -D /etc/nginx/.htpasswd username
|
|||
Once again, any changes you make to these files **must be followed with restarting the NGINX service** otherwise no changes will be made.
|
||||
|
||||
{: #nginx-satisfy}
|
||||
|
||||
#### Making Exceptions for Specific IP addresses
|
||||
|
||||
It is often desirable to allow specific IPs (e.g. the local network) to access openHAB without needing to prompt for a password or to block everyone else entirely.
|
||||
|
|
@ -239,6 +248,7 @@ NGINX will allow anyone within the 192.168.0.0/24 range **and** the localhost to
|
|||
If you have setup a password following the previous section, then the rest will be prompted for a password for access.
|
||||
|
||||
{: #nginx-domain}
|
||||
|
||||
#### Setting up a Domain
|
||||
|
||||
To generate a trusted certificate, you need to own a domain. To acquire your own domain, you can use one of the following methods:
|
||||
|
|
@ -250,6 +260,7 @@ To generate a trusted certificate, you need to own a domain. To acquire your own
|
|||
| Using a "Dynamic DNS" sevice | [No-IP](https://www.noip.com), [Dyn](https://www.dyn.com/dns), [FreeDNS](https://freedns.afraid.org) | Uses a client to automatically update your IP to a domain of you choice, some Dynamic DNS services (like FreeDNS) offer a free domain too. |
|
||||
|
||||
{: #nginx-https}
|
||||
|
||||
#### Enabling HTTPS
|
||||
|
||||
Encrypting the communication between client and the server is important because it protects against eavesdropping and possible forgery.
|
||||
|
|
@ -259,6 +270,7 @@ If you have a **valid domain and can change the DNS** to point towards your IP,
|
|||
If you need to use an internal or external IP to connect to openHAB, follow the [instructions for OpenSSL](#nginx-openssl)
|
||||
|
||||
{: #nginx-openssl}
|
||||
|
||||
#### Using OpenSSL to Generate Self-Signed Certificates
|
||||
|
||||
OpenSSL is also packaged for most Linux distributions, installing it should be as simple as:
|
||||
|
|
@ -283,6 +295,7 @@ You will be prompted for some information which you will need to fill out for th
|
|||
Common Name (e.g. server FQDN or YOUR name) []: xx.xx.xx.xx
|
||||
|
||||
{: #nginx-openssl-add}
|
||||
|
||||
##### Adding the Certificates to Your Proxy Server
|
||||
|
||||
The certificate and key should have been placed in `/etc/ssl/`.
|
||||
|
|
@ -295,13 +308,17 @@ In the NGINX configuration, place the following underneath your `server_name` va
|
|||
```
|
||||
|
||||
{: #nginx-letsencrypt}
|
||||
|
||||
#### Using Let's Encrypt to Generate Trusted Certificates
|
||||
|
||||
**Skip this step if you have no domain name or have already followed the instructions for OpenSSL**
|
||||
::: tip
|
||||
Skip this step if you have no domain name or have already followed the instructions for OpenSSL
|
||||
:::
|
||||
|
||||
Let's Encrypt is a service that allows anyone with a valid domain to automatically generate a trusted certificate, these certificates are usually accepted by a browser without any warnings.
|
||||
|
||||
{: #nginx-letsencrypt-generation}
|
||||
|
||||
##### Setting up the NGINX Proxy Server to Handle the Certificate Generation Procedure
|
||||
|
||||
Let's Encrypt needs to validate that the server has control of the domain.
|
||||
|
|
@ -323,6 +340,7 @@ Next add the new location parameter to your NGINX config, this should be **place
|
|||
```
|
||||
|
||||
{: #nginx-letsencrypt-certbot}
|
||||
|
||||
##### Using Certbot
|
||||
|
||||
Certbot is a tool which simplifies the process of obtaining secure certificates.
|
||||
|
|
@ -334,6 +352,7 @@ sudo certbot certonly --webroot -w /var/www/mydomain -d mydomain
|
|||
```
|
||||
|
||||
{: #nginx-letsencrypt-add}
|
||||
|
||||
##### Adding the Certificates to Your Proxy Server
|
||||
|
||||
The certificate and key should have been placed in `/etc/letsencrypt/live/mydomain_or_myip`.
|
||||
|
|
@ -347,6 +366,7 @@ In the NGINX configuration, place the following underneath your server_name vari
|
|||
```
|
||||
|
||||
{: #nginx-https-listen}
|
||||
|
||||
#### Setting Your NGINX Server to Listen to the HTTPS Port
|
||||
|
||||
Regardless of the option you choose, make sure you change the port to listen in on HTTPS traffic.
|
||||
|
|
@ -361,6 +381,7 @@ You can check by going to `https://mydomain_or_myip` and confirming with your br
|
|||
If you want to keep hold of a HTTP server for some reason, just add `listen 80;` and remove the Strict-Transport-Security line.
|
||||
|
||||
{: #nginx-httpredirect}
|
||||
|
||||
#### Redirecting HTTP Traffic to HTTPS
|
||||
|
||||
You may want to redirect all HTTP traffic to HTTPS, you can do this by adding the following to the NGINX configuration.
|
||||
|
|
@ -386,6 +407,7 @@ server {
|
|||
```
|
||||
|
||||
{: #nginx-summary}
|
||||
|
||||
#### Putting it All Together
|
||||
|
||||
After following all the steps on this page, you *should* have a NGINX server configuration (`/etc/nginx/sites-enabled/openhab`) that looks like this:
|
||||
|
|
@ -426,7 +448,9 @@ server {
|
|||
}
|
||||
}
|
||||
```
|
||||
|
||||
{: #synology-remote-config}
|
||||
|
||||
#### Configuration on Synology DiskStation
|
||||
|
||||
Synology DSM (as of 6.2) has the ability to automatically acquire certificates from Let's Encrypt and renew them every 90 days as required.
|
||||
|
|
@ -474,7 +498,7 @@ Create two reverse proxies as follows:
|
|||
|Destination Hostname: |localhost |
|
||||
|Destination Port: |8080 (or whichever HTTP port your openHAB instance is on)|
|
||||
|
||||
Verify that the reverse proxy is working as expected - try http://your-hostname.com and https://your-hostname.com - you should end up at the openHAB landing page in both cases, but will get a security warning for the https site.
|
||||
Verify that the reverse proxy is working as expected - try <http://your-hostname.com> and <https://your-hostname.com> - you should end up at the openHAB landing page in both cases, but will get a security warning for the https site.
|
||||
|
||||
Next, acquire certificates from Let's Encrypt using the GUI in DSM.
|
||||
|
||||
|
|
@ -504,7 +528,7 @@ If it's not selected, update it.
|
|||
|etc etc |synology.com |
|
||||
|
||||
Once this is done, update the CAA record for your-hostname.com with your registrar (exact process will vary by registrar).
|
||||
Within an hour or so, you should not receive the security warning for https://your-hostname.com.
|
||||
Within an hour or so, you should not receive the security warning for <https://your-hostname.com>.
|
||||
|
||||
Next, you must add authentication to the reverse proxy.
|
||||
There's no GUI way to do this, so we need to create another small NGINX virtual host on the DiskStation.
|
||||
|
|
@ -512,9 +536,11 @@ There's no GUI way to do this, so we need to create another small NGINX virtual
|
|||
Log into your DiskStation by SSH.
|
||||
Use the admin username and password.
|
||||
Create a .htpasswd file in your openHAB userdata folder (your userdata location may vary, update accordingly):
|
||||
|
||||
```shell
|
||||
htpasswd -c /volume1/openHAB/userdata/.htpasswd username
|
||||
```
|
||||
|
||||
Next, add a very simple NGINX configuration similar to that created above, but without the SSL parameters.
|
||||
DSM comes with vi installed by default, but you may wish to [install nano](https://anto.online/other/how-to-install-nano-on-your-synology-nas/)
|
||||
|
||||
|
|
@ -555,11 +581,13 @@ server {
|
|||
|
||||
}
|
||||
```
|
||||
|
||||
Once you are done, save the file, restart and test NGINX:
|
||||
|
||||
```shell
|
||||
sudo nginx -s reload && sudo nginx -t
|
||||
```
|
||||
|
||||
As above, the first part of the file redirects any HTTP queries to HTTPS directly.
|
||||
If you don't get any errors, update the reverse proxy settings in the DSM GUI to point to these new endpoints.
|
||||
Back in the GUI, go to Control Panel > Application Portal > Reverse Proxy, make the updates below:
|
||||
|
|
@ -576,15 +604,18 @@ Back in the GUI, go to Control Panel > Application Portal > Reverse Proxy, make
|
|||
We do this 'double' redirect to take advantage of the GUI certificate handling in DSM - this is the equivalent of CertBot for a linux installation.
|
||||
:::
|
||||
|
||||
Give it a try again - you should now get redirected to https://your-hostname.com from http://your-hostname.com, and should receive a username and password prompt before you see the openHAB landing page.
|
||||
Give it a try again - you should now get redirected to <https://your-hostname.com> from <http://your-hostname.com>, and should receive a username and password prompt before you see the openHAB landing page.
|
||||
|
||||
If you need to troubleshoot the nginx server, SSH into your DiskStation, and check the NGINX error log:
|
||||
|
||||
```shell
|
||||
sudo tail -f /var/log/nginx/error.log
|
||||
```
|
||||
|
||||
This log will update in real-time, so do whatever it was that you were having issues with again, and you'll see the error.
|
||||
|
||||
{: #nginx-https-security}
|
||||
|
||||
#### Additional HTTPS Security
|
||||
|
||||
To test your security settings [SSL Labs](https://www.ssllabs.com/ssltest/) provides a tool for testing your domain against ideal settings (Make sure you check "Do not show the results on the boards" if you dont want your domain seen).
|
||||
|
|
@ -619,6 +650,7 @@ Feel free to test the new configuration again on [SSL Labs](https://www.ssllabs.
|
|||
If you're achieving A or A+ here, then your client-openHAB communication is very secure.
|
||||
|
||||
{: #nginx-further-reading}
|
||||
|
||||
#### Further Reading
|
||||
|
||||
The setup above is a suggestion for high compatibility with an A+ rating at the time of writing, however flaws in these settings (particularly the cyphers) may become known overtime.
|
||||
|
|
|
|||
|
|
@ -54,8 +54,8 @@ If your NAS cannot connect to the internet, the installer will tell you to downl
|
|||
|
||||
The location of configuration files by openHAB differs depending on wether or not a shared folder named `public` exists:
|
||||
|
||||
* with public share folder: `/volume1/public/openHAB2/conf/`
|
||||
* without public share folder: `/volume1/@appstore/openHAB2/conf/`
|
||||
- with public share folder: `/volume1/public/openHAB2/conf/`
|
||||
- without public share folder: `/volume1/@appstore/openHAB2/conf/`
|
||||
|
||||
For certain Synology models the `public` folder is created automatically during the first setup.
|
||||
The administrator can also create a public shared folder if desired.
|
||||
|
|
|
|||
|
|
@ -16,38 +16,41 @@ This page is structured as follows:
|
|||
- TOC
|
||||
{:toc}
|
||||
|
||||
## Preparation of the environment.
|
||||
## Preparation of the environment
|
||||
|
||||
### Before you start
|
||||
|
||||
Please be sure you have installed the required supporting applications as described in [Prerequisites]({{base}}/installation/index.html#prerequisites).
|
||||
|
||||
### Set the `JAVA_HOME` System Environment Variable in Windows
|
||||
|
||||
### Set the `JAVA_HOME` System Environment Variable in Windows.
|
||||
- Navigate to: Control Panel ➡️ System and Security ➡️ System ➡️ Advanced System Settings ➡️ Environment Variables ➡️ System Variables
|
||||
- Create a New System Variable named JAVA_HOME (or update the existing one) to match the installation directory of the Java Platform chosen and installed in the step [Prerequisites]({{base}}/installation/index.html#prerequisites).
|
||||
- Navigate to: Control Panel ➡️ System and Security ➡️ System ➡️ Advanced System Settings ➡️ Environment Variables ➡️ System Variables
|
||||
- Create a New System Variable named JAVA_HOME (or update the existing one) to match the installation directory of the Java Platform chosen and installed in the step [Prerequisites]({{base}}/installation/index.html#prerequisites).
|
||||
|
||||
|
||||
|
||||
### Choose a folder name for the openHAB installation.
|
||||
### Choose a folder name for the openHAB installation
|
||||
|
||||
The name must **contain no spaces**. On this page, we will be using `C:\openHAB` as an example.
|
||||
|
||||
## Installation
|
||||
|
||||
### Install openHAB
|
||||
|
||||
The openHAB runtime is distributed using a platform-independent zip file.
|
||||
To install it, follow these simple steps:
|
||||
|
||||
1. Download the latest Windows Stable or Snapshot ZIP archive file for manual installation from the [Download](https://www.openhab.org/download/) page.
|
||||
1. Download the latest Windows Stable or Snapshot ZIP archive file for manual installation from the [Download](https://www.openhab.org/download/) page.
|
||||
|
||||
2. Unzip the file in your chosen directory (e.g. `C:\openHAB`)
|
||||
2. Unzip the file in your chosen directory (e.g. `C:\openHAB`)
|
||||
|
||||
|
||||
|
||||
3. Start the server: Launch the runtime by executing the script `C:\openHAB\start.bat` and wait a while for it to start and complete.
|
||||
3. Start the server: Launch the runtime by executing the script `C:\openHAB\start.bat` and wait a while for it to start and complete.
|
||||
|
||||
|
||||
|
||||
4. Point your browser to `http://localhost:8080`.
|
||||
4. Point your browser to `http://localhost:8080`.
|
||||
You should be looking at the openHAB page requesting you to set up an administrator username and password:
|
||||
|
||||
|
||||
|
|
@ -63,10 +66,11 @@ By installing the openHAB process as a service in Windows, you can:
|
|||
- Launch it automatically upon system startup
|
||||
- Run it in the background
|
||||
|
||||
**Windows Service Installation Steps**
|
||||
#### Windows Service Installation Steps
|
||||
|
||||
1. Complete the [prerequisites](#prerequisites) and regular [installation](#installation) steps.
|
||||
2. Issue the following two commands in your openHAB console:
|
||||
|
||||
1. Complete the [prerequisites](#prerequisites) and regular [installation](#installation) steps.
|
||||
2. Issue the following two commands in your openHAB console:
|
||||
```shell
|
||||
feature:install service-wrapper
|
||||
wrapper:install --name "openHAB" --display "openHAB" --description "openHAB Service"
|
||||
|
|
@ -74,9 +78,9 @@ By installing the openHAB process as a service in Windows, you can:
|
|||
|
||||
|
||||
|
||||
3. Shutdown the openHAB instance by typing `logout` in the currently running console.
|
||||
3. Shutdown the openHAB instance by typing `logout` in the currently running console.
|
||||
|
||||
4. Update the newly created `C:\openHAB\userdata\etc\openHAB-wrapper.conf` to include all necessary parameters:
|
||||
4. Update the newly created `C:\openHAB\userdata\etc\openHAB-wrapper.conf` to include all necessary parameters:
|
||||
|
||||
- Copy all the config text from the below section and paste it in your `openHAB-wrapper.conf`, replacing all existing content.
|
||||
- Adapt the first entry (`OPENHAB_HOME`) to match your openHAB installation directory.
|
||||
|
|
@ -150,7 +154,7 @@ By installing the openHAB process as a service in Windows, you can:
|
|||
wrapper.ntservice.interactive=false
|
||||
```
|
||||
|
||||
5. Open an elevated command prompt and type the following commands:
|
||||
5. Open an elevated command prompt and type the following commands:
|
||||
|
||||
```text
|
||||
C:\openHAB\userdata\bin\openHAB-service.bat install
|
||||
|
|
@ -161,18 +165,17 @@ By installing the openHAB process as a service in Windows, you can:
|
|||
|
||||
|
||||
|
||||
6. Your openHAB Windows service is now installed and running.
|
||||
6. Your openHAB Windows service is now installed and running.
|
||||
Validate proper operations by:
|
||||
|
||||
- Browsing to [http://localhost:8080](http://localhost:8080)
|
||||
- Browsing to [http://localhost:8080](http://localhost:8080)
|
||||
|
||||
- Verifying that the Windows Service is running and set to Automatic Startup type.
|
||||
- Verifying that the Windows Service is running and set to Automatic Startup type.
|
||||
Use `services.msc` and find the `openHAB` service.
|
||||
|
||||
|
||||
|
||||
- Logging in with an SSH client to the console (see info below)
|
||||
|
||||
- Logging in with an SSH client to the console (see info below)
|
||||
|
||||
### File Locations
|
||||
|
||||
|
|
@ -188,13 +191,14 @@ Assuming a successful install, you will now have various folders inside `C:\open
|
|||
| Service configuration | `C:\openHAB\userdata\etc` |
|
||||
|
||||
## What next?
|
||||
|
||||
You can:
|
||||
|
||||
- continue reading the [Additional steps]({{base}}/installation/index.md#additional-steps) section of the Installation overview
|
||||
- read more about how to handle basic maintenance tasks, in the section below
|
||||
|
||||
## Maintenance
|
||||
|
||||
|
||||
### Backup
|
||||
|
||||
Make sure that you make regular backups of the **conf** and **userdata** folders, you can zip and unzip these folders too and from openHAB installations (even across most versions).
|
||||
|
|
@ -211,15 +215,19 @@ cd C:\openHAB
|
|||
. .\runtime\bin\update.ps1
|
||||
Update-openHAB -OHVersion x.x.x
|
||||
```
|
||||
|
||||
Now that openHAB has updated, you only need to run the above commands again for future versions.
|
||||
|
||||
### Uninstallation
|
||||
|
||||
- perform a backup as described above
|
||||
- uninstall openHAB as a Windows service: run PowerShell as an administrator and use the following commands
|
||||
```
|
||||
|
||||
```text
|
||||
net stop openHAB
|
||||
C:\openHAB\userdata\bin\openHAB-service.bat remove
|
||||
```
|
||||
|
||||
- you can delete the whole contents of the C:\openHAB\ folder.
|
||||
|
||||
### Connecting to the openHAB console
|
||||
|
|
@ -227,13 +235,13 @@ C:\openHAB\userdata\bin\openHAB-service.bat remove
|
|||
You can connect to openHAB's console using the the `C:\openHAB\runtime\bin\client.bat` script on the local machine.
|
||||
Alternatively, you can use a standard SSH client:
|
||||
|
||||
- Install an SSH client application, e.g., [Putty](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html), [KiTTY](http://kitty.9bis.net/) or [Xshell 5](https://www.netsarang.com/products/xsh_overview.html)
|
||||
- Install an SSH client application, e.g., [Putty](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html), [KiTTY](http://kitty.9bis.net/) or [Xshell 5](https://www.netsarang.com/products/xsh_overview.html)
|
||||
|
||||
- Setup a session with the following parameters:
|
||||
- Host: 127.0.0.1
|
||||
- Port: 8101
|
||||
- Username: `openhab`
|
||||
- Password: `habopen`
|
||||
- Setup a session with the following parameters:
|
||||
- Host: 127.0.0.1
|
||||
- Port: 8101
|
||||
- Username: `openhab`
|
||||
- Password: `habopen`
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue