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

Update Linux and Console instructions for 2.2.0 (#588) 

* Update Linux instructions for 2.2.0

Signed-off-by: Ben Clark <ben@benjyc.uk>

* Correct console link

Signed-off-by: Ben Clark <ben@benjyc.uk>

* Add warning about known_hosts file using SSH

And suggest using the Karaf console script instead of SSH on localhost.

Signed-off-by: Ben Clark <ben@benjyc.uk>

* Add user/pass info at relevant point.

Signed-off-by: Ben Clark <ben@benjyc.uk>

* Update windows with client script note.

Signed-off-by: Ben Clark <ben@benjyc.uk>

* Update console page according to reviews

Signed-off-by: Ben Clark <ben@benjyc.uk>

* Update Linux page according to reviews

Signed-off-by: Ben Clark <ben@benjyc.uk>
pull/595/head
Ben Clark 2017-12-16 23:57:32 +00:00 committed by Brad Gilmer
parent 190bd935f9
commit 9bbabfce14
3 changed files with 63 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
administration/console.md
View File

@ -17,10 +17,15 @@ The console offers the option to:
The method to access the console depends on how openHAB was started.
* When started in interactive mode using the provided command line scripts, openHAB naturally transitions directly to the console prompt.
* When started as a service (e.g. when installed from our package repository), openHAB is running as a background process.
* When started in interactive mode using the provided command line scripts (e.g. `start.sh` or `start.bat`), openHAB naturally transitions directly to the console prompt.
* When started as a service (i.e. when openHAB is running as a background process), access to the console is given by running the `$OPENHAB_RUNTIME/bin/client` (`client.bat` for Windows) script or by [connecting via SSH](#connecting-via-ssh).
Linux package based installations can also use the command `openhab-cli console`.
In both cases, the console can be reached via secure shell connection ([SSH](https://en.wikipedia.org/wiki/Secure_Shell)).
The default username/password is **openhab:habopen**, so enter `habopen` at the password prompt.
### Connecting via SSH
The console can also be reached via secure shell connection ([SSH](https://en.wikipedia.org/wiki/Secure_Shell)).
To reach the console using SSH, use the following command to connect to the localhost interface on TCP port 8101:
@ -55,6 +60,8 @@ The first successful connection triggers generation of the Karaf remote console
*Note:* On slower systems, such as Raspberry Pi or Pine64, this first SSH connection may even time out.
If this happens, simply try connecting again until successful.
## Using the Console
After successful connection and authentication, the console will appear:
```text
@ -63,7 +70,7 @@ After successful connection and authentication, the console will appear:
/ __ \/ __ \/ _ \/ __ \/ /_/ / /| | / __ |
/ /_/ / /_/ / __/ / / / __ / ___ |/ /_/ /
\____/ .___/\___/_/ /_/_/ /_/_/ |_/_____/
/_/ 2.0.0
/_/ 2.2.0
Release Build
Hit '<tab>' for a list of available commands
@ -73,8 +80,6 @@ Hit '<ctrl-d>' or type 'system:shutdown' or 'logout' to shutdown openHAB.
openhab>
```
## Using the Console
The command `help` is listing all available commands or describes a specific subsystem/command:
```text

140
installation/linux.md
View File

@ -269,6 +269,9 @@ Systems based on **systemd** (e.g. Debian 8, Ubuntu 15.x, Raspbian Jessie and ne
# Stop the openHAB background service
sudo systemctl stop openhab2.service
# Get the service log since the last boot
sudo journalctl -u openhab2.service -b
# Make openHAB automatically start after booting the Linux host
sudo systemctl daemon-reload
@ -278,6 +281,26 @@ Systems based on **systemd** (e.g. Debian 8, Ubuntu 15.x, Raspbian Jessie and ne
{% include collapsible/item-end.html %}
{% include collapsible/end.html %}
#### Command Line Interface (CLI)
After installing openHAB, a shortcut named `openhab-cli` provides access to the openHAB-specific commands (such as [backup, restore](#backup-and-restore), and [console]({{base}}/administration/console.html)).
To use the shortcuts in a terminal, simply type `openhab-cli` followed by the command.
For example:
```shell
Usage: openhab-cli command [options]
Possible commands:
start [--debug] -- Starts openHAB in the terminal.
stop -- Stops any running instance of openHAB.
status -- Checks to see if openHAB is running.
console -- Opens the openHAB console.
backup [filename] -- Stores the current configuration of openHAB.
restore filename -- Restores the openHAB configuration from a backup.
showlogs -- Displays the log messages of openHAB.
info -- Displays distribution information.
```
#### Changing Versions
To stay up to date with new releases, you should do regular upgrades.
@ -343,67 +366,6 @@ sudo yum install openhab2-2.1.0-1
{% include collapsible/item-end.html %}
{% include collapsible/end.html %}
#### Backup and Restore
To make a backup of your openHAB 2 system, you need to retain your configuration and userdata files.
As of version 2.2.0, you can use openHAB's scripts for storing your configuration in a zip file.
By default, the script saves the zip file in `/var/lib/openhab2/backups` for automatic installs and `openhab2/backups` for manual installs.
You can change the default path by setting the $OPENHAB_BACKUPS environment variable.
```shell
sudo $OPENHAB_RUNTIME/bin/backup
## OR ##
sudo $OPENHAB_RUNTIME/bin/backup /path/to/backups/folder/myBackup.zip
```
To restore from these generated files:
```shell
sudo $OPENHAB_RUNTIME/bin/restore $OPENHAB_BACKUPS/myBackup.zip
```
If you're unsure how to use the above files, just use `--help` or `-h`:
```shell
$OPENHAB_RUNTIME/bin/backup --help
```
Otherwise, you may do this manually by:
```shell
# stop openhab instance (here: systemd service)
sudo systemctl stop openhab2.service
# prepare backup folder, replace by your desired destination
BACKUPDIR="/srv/openhab2-backup/openhab2-backup-$(date +%Y%m%d_%H%M%S)"
mkdir -p $BACKUPDIR
# backup current installation with settings
cp -arv /etc/openhab2 "$BACKUPDIR/conf"
cp -arv /var/lib/openhab2 "$BACKUPDIR/userdata"
rm -rf "$BACKUPDIR/userdata/cache"
rm -rf "$BACKUPDIR/userdata/tmp"
# restart openhab instance
sudo systemctl start openhab2.service
```
If you later want to restore these manual settings, just replace them.
You may want to delete the existing data first.
```shell
# stop openhab instance (here: systemd service)
sudo systemctl stop openhab2.service
# restore data and fix permissions
sudo cp -arv /srv/openhab2-backup/openhab2-backup-20160131_235959/conf/* /etc/openhab2/
sudo cp -arv /srv/openhab2-backup/openhab2-backup-20160131_235959/userdata/* /var/lib/openhab2/
sudo chown -R openhab /var/lib/openhab2
# restart openhab instance
sudo systemctl start openhab2.service
```
#### Uninstall
To uninstall openHAB 2 and get rid of all related files managed by the package manager, make a backup, then uninstall openHAB and remove the repository:
@ -552,35 +514,6 @@ The output of `status` after a successful execution should be similar to:
When running a manual installation, it is possible to pre-download add-ons or legacy add-ons if you want to install any bindings at a later date without connecting to the internet.
Simply download the kar files (the latest builds can be found [here](https://openhab.ci.cloudbees.com/job/openHAB-Distribution/)) and move them to the `/opt/openhab2/addons` folder.
#### Backup and Restore
We recommend a backup before each upgrade, or before any major change to a configuration. 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:
```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
```
You may restore these files by moving them back into your openhab folder, where `20170626_201143` is an example of the timestamp set on the folder earlier:
```shell
# restore configuration and userdata
sudo cp -arv /opt/openhab2-backup-20170626_201143/conf /opt/openhab2/
sudo cp -arv /opt/openhab2-backup-20170626_201143/userdata /opt/openhab2/
# fix permissions
sudo chown -hR openhab:openhab /opt/openhab2
# restart openhab instance
sudo systemctl start openhab2.service
```
#### Upgrade
To stay up to date with new releases, you should do regular upgrades of your manual installation.
@ -646,9 +579,34 @@ sudo rm /lib/systemd/system/openhab2.service
| Backups folder | `/var/lib/openhab2/backups` | `/opt/openhab2/backups` |
| Service configuration | `/etc/default/openhab2` | (not preconfigured) |
## Backup and Restore
It is recommended to make a backup of your configuration before *any* major change.
To make a backup of openHAB2, you need to retain your configuration and userdata files.
openHAB comes with scripts for storing your configuration in a zip file which is saved in `/var/lib/openhab2/backups` for automatic installs and `openhab2/backups` for manual installs.
You can change the default path by setting the $OPENHAB_BACKUPS environment variable.
```shell
sudo $OPENHAB_RUNTIME/bin/backup
## OR ##
sudo $OPENHAB_RUNTIME/bin/backup /path/to/backups/folder/myBackup.zip
```
To restore from these generated files:
```shell
sudo $OPENHAB_RUNTIME/bin/restore $OPENHAB_BACKUPS/myBackup.zip
```
If you're unsure how to use the above files, just use `--help` or `-h`:
```shell
$OPENHAB_RUNTIME/bin/backup --help
```
## 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.
You can learn more about openHAB and how it works by looking at your 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:

3
installation/windows.md
View File

@ -218,6 +218,9 @@ By installing the openHAB process as a service in Windows, you can:
### Connecting to the openHAB console
You can connect to openHAB's console using the the `C:\openHAB2\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)
- Setup a session with the following parameters: