From d4a3af2f94f3141cb64fd020c9a94ea860c735e9 Mon Sep 17 00:00:00 2001 From: Jerome Luckenbach Date: Fri, 25 Dec 2020 17:43:09 +0100 Subject: [PATCH] Start with Markdownlint fro vscode editing. Initial linting error fixes. Signed-off-by: Jerome Luckenbach --- .markdownlint.json | 8 +++++ installation/armbian.md | 6 ++-- installation/docker.md | 2 +- installation/index.md | 12 ++++---- installation/linux.md | 41 +++++++++++++------------ installation/macos.md | 16 +++++----- installation/qnap.md | 22 +++++++------- installation/security.md | 40 ++++++++++++++++++++++--- installation/synology.md | 4 +-- installation/windows.md | 64 ++++++++++++++++++++++------------------ 10 files changed, 132 insertions(+), 83 deletions(-) create mode 100644 .markdownlint.json diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000000..744d5bd7e8 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,8 @@ +{ + "default": true, + "MD004": { + "style": "dash" + }, + "MD013": false, + "MD025": false +} \ No newline at end of file diff --git a/installation/armbian.md b/installation/armbian.md index fd181f0ed6..a9ca56cb99 100644 --- a/installation/armbian.md +++ b/installation/armbian.md @@ -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 - ![Armbian](images/boards1.png) ## 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 diff --git a/installation/docker.md b/installation/docker.md index 7cb9873329..e9938d1316 100644 --- a/installation/docker.md +++ b/installation/docker.md @@ -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 diff --git a/installation/index.md b/installation/index.md index e2ba4b7837..51c96d7ff3 100644 --- a/installation/index.md +++ b/installation/index.md @@ -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 diff --git a/installation/linux.md b/installation/linux.md index 46de4a4189..c65a883d30 100644 --- a/installation/linux.md +++ b/installation/linux.md @@ -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)! ![The openHAB Dashboard page](images/Home_Openhab_3.png) @@ -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: -- 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] diff --git a/installation/macos.md b/installation/macos.md index 7378d5502c..3ea90663b5 100644 --- a/installation/macos.md +++ b/installation/macos.md @@ -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 '' for a list of available commands @@ -94,7 +94,7 @@ To exit, use '' 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 diff --git a/installation/qnap.md b/installation/qnap.md index 5d6b5996db..04b7ada3f5 100644 --- a/installation/qnap.md +++ b/installation/qnap.md @@ -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. ![AppCenter choose](https://github.com/openhab/openhab-qnap-qpkg/raw/master/docs/QTS_4.2.0_AppCenter%20choose.png) -5. Confirm the installation +5. Confirm the installation ![AppCenter confirm](https://github.com/openhab/openhab-qnap-qpkg/raw/master/docs/QTS_4.2.0_AppCenter%20confirm.png) -6. Wait while the package is being installed +6. Wait while the package is being installed ![AppCenter installing](https://github.com/openhab/openhab-qnap-qpkg/raw/master/docs/QTS_4.2.0_AppCenter%20installing.png) -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. ![AppCenter finished](https://github.com/openhab/openhab-qnap-qpkg/raw/master/docs/QTS_4.2.0_AppCenter%20finished.png) -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 diff --git a/installation/security.md b/installation/security.md index 24869abaf3..947398a652 100644 --- a/installation/security.md +++ b/installation/security.md @@ -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 and - 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 . 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 from , 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. diff --git a/installation/synology.md b/installation/synology.md index d1e6fcab52..c4671cbc4d 100644 --- a/installation/synology.md +++ b/installation/synology.md @@ -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. diff --git a/installation/windows.md b/installation/windows.md index 97ae33a3b6..8ebbec2b7a 100644 --- a/installation/windows.md +++ b/installation/windows.md @@ -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). ![JAVA_HOME](images/JAVA_HOME.png) -### 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`) ![openHAB Folders](images/openHAB_Folders.png) -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. ![Karaf_Windows](images/Karaf_Windows.png) -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: ![Home_OH_adminCreate](images/Home_OH_adminCreate.png) @@ -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: ![Wrapper Install_Windows](images/Wrapper_Install_Windows.jpg) -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: ![Wrapper_Start_Windows](images/Wrapper_Start_Windows.jpg) -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. ![Windows Service](images/Windows_Service.jpg) - - 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` ![SSH Connection 1](images/SSH_Connection_1.jpg)