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

[Console] Update whole Karaf console article (#352) 

Resolves #168
Resolves #298 
Resolves #299 
Resolves #345

* Clarify console access via localhost (#168)

Also, minor editing for clarity and ease of use.
Signed-off-by: Shaun Currier <shaun.currier@gmail.com> (github: ShaunCurrier)

* Refresh successful console connection example

Make ssh command ordering more conventional
Signed-off-by: Shaun Currier shaun.currier@gmail.com (github: ShaunCurrier)

* Add detailed console password and port change (#345)

Also reorganized headers to accommodate new detail and for easier navigation.

* Link to bind to all interfaces header

* Add walkthrough for console connection.

Also, clean up wording about distinction of interactive vs. service mode console access.

* Minor cleanups from proofing

* Minor fixes from building and proofing

* Revise whole article

Signed-off-by: Thomas Dietrich <thomas.dietrich@tu-ilmenau.de> (github: ThomDietrich)

* Update console.md

Signed-off-by: Thomas Dietrich <thomas.dietrich@tu-ilmenau.de> (github: ThomDietrich)
pull/366/head
ShaunCurrier 2017-03-18 07:05:00 -05:00 committed by Thomas Dietrich
parent c0efe6050b
commit 943f2a1164
1 changed files with 112 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

148
administration/console.md
View File

@ -9,30 +9,62 @@ title: The Console
The console offers the option to:
* monitor the [log](logging.html#karaf-console) in realtime
* manage [bundles](bundles.html)
* [runtime commands](runtime.html)
* Monitor the [log](logging.html#karaf-console) in realtime
* Manage [bundles](bundles.html)
* Execute [runtime commands](runtime.html)
## Accessing the Console
Accessing the console depends on the start mode of openHAB.
The manually start using shell/batch script ends directly in the console.
The method to access the console depends on how openHAB was started.
If openHAB runs a service, the console can be accessed using ssh to the openHAB host on port 8101.
The default username/password is **openhab/habopen**.
Be aware, that the first connection attempt may take a few seconds longer.
* 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.
In both cases, the console can 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:
```shell
ssh -p 8101 openhab@localhost
```
ssh openhab@localhost -p 8101
*Note:* By default, connection is only allowed from localhost, i.e. only from the machine running openHAB.
Connections are intentionally not allowed from remote hosts due to security concerns.
To change this, see [Bind Console to All Interfaces](#bind-console-to-all-interfaces).
A security warning is expected upon the first connection:
```text
The authenticity of host '[localhost]:8101 ([127.0.0.1]:8101)' can't be established.
RSA key fingerprint is SHA256:XjQxBPit+K5m3HuSsEUI/842NTCxLTu3EMGGBuQKNVg.
Are you sure you want to continue connecting (yes/no)?
```
Enter `yes` to proceed.
```text
Warning: Permanently added '[localhost]:8101' (RSA) to the list of known hosts.
Password authentication
Password:
```
The default username/password is **openhab:habopen**, so enter `habopen` at the password prompt.
The first successful connection triggers generation of the Karaf remote console key and will take a few seconds longer than subsequent attempts.
*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.
After successful connection and authentication, the console will appear:
```text
__ _____ ____
____ ____ ___ ____ / / / / | / __ )
/ __ \/ __ \/ _ \/ __ \/ /_/ / /| | / __ |
/ /_/ / /_/ / __/ / / / __ / ___ |/ /_/ /
\____/ .___/\___/_/ /_/_/ /_/_/ |_/_____/
/_/ 2.0.0-SNAPSHOT
/_/ 2.0.0
Release Build
Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
@ -43,27 +75,22 @@ openhab>
## Using the Console
**Help** is listing all available commands:
The command `help` is listing all available commands or describes a specific subsystem/command:
```
```text
openhab> help
```
or describes a specific subsystem/command:
```
...
openhab> help bundle
...
openhab> help bundle:stop
...
```
The console also supports auto-completion during input.
Auto-completion proposes possible commands based on the current input and is triggered by the **tab** key.
So for example entering _bun_ and pressing the tab key will result in:
Auto-completion proposes possible commands based on the current input and is triggered by a &lt;TAB&gt; press on your keyboard.
So for example entering "*bund*" and pressing the &lt;TAB&gt; key will first extend to the only viable candidate "bundle", a subsequent &lt;TAB&gt; press will result in:
```
```text
openhab> bundle
bundle bundle:capabilities bundle:classes bundle:diag bundle:dynamic-import
bundle:find-class bundle:headers bundle:id bundle:info bundle:install
@ -72,9 +99,9 @@ bundle:restart bundle:services bundle:start bundl
bundle:tree-show bundle:uninstall bundle:update bundle:watch
```
Another useful feature the **\| (pipe)** and **grep** functionality which filters long output lists:
Another useful feature is the combination of the `|` (pipe) and `grep` functionality, which can be used to filter output:
```
```text
openhab> bundle:list | grep openHAB
164 | Active | 90 | 2.0.0.201607210102 | openHAB Core
165 | Active | 80 | 2.0.0.201607210102 | openHAB Karaf Integration
@ -84,25 +111,74 @@ openhab> bundle:list | grep openHAB
The session is ended by using the logout command:
```
```text
openhab> logout
```
## Bind Console to all Interfaces
Learn about all available commands by using the initially introduced `help` command.
By default openHAB binds its shell to localhost only due to obvious security reasons.
If you are on a local network or you are fully aware of all risks of exposing your system to the public, you can change the bind address in the configuration file `org.apache.karaf.shell.cfg` under the openHAB `<userdata>/etc` path.
Replace the `sshHost` IP "127.0.0.1" by "0.0.0.0" to bind to all available network interfaces.
Please be aware, that the console will now be accessible from all devices and is only secured by the password defined in `users.properties` (same path).
You should thereby change the default password.
## Modifying the Console Settings
The above can be accomplished by the following Linux shell command (on an apt/deb-based installation, you might need to adapt the path for other installations):
Changing the console password, interface, and port is described here.
```
sudo sed -i -e "s/sshHost = 127.0.0.1/sshHost = 0.0.0.0/g" /var/lib/openhab2/etc/org.apache.karaf.shell.cfg
sudo sed -i -e "s/openhab = habopen/openhab = securePassword/g" /var/lib/openhab2/etc/users.properties
### Console Settings Files and Directories
The pertinent files controlling console settings are stored under `$OPENHAB_USERDATA/etc/`:
| File | Purpose |
|------------------------------|--------------------------------|
| `org.apache.karaf.shell.cfg` | Controls most console settings |
| `users.properties` | Stores console password |
The exact locations of these files will vary based on your platform and installation method, e.g. `/var/lib/openhab2/etc/` or `openhab2/userdata/etc/`.
### Changing the Password
The password is stored in the file `users.properties`, located in the `etc` directory as [mentioned above](#console-settings-files-and-directories).
By default, the line with the password contains the text `openhab = `, followed by the current password (e.g. `habopen`) or a password hash (e.g. `{CRYPT}4AE1A0FD...{CRYPT}`).
To change the authentication password edit the file manually, replacing the password or password hash (including `{CRYPT}`) with your new password in clear text.
Alternately, run the following Linux shell command, which will perform the replacement for you.
Substitute `securePassword` with your desired password.
```shell
sudo sed -i -e "s/openhab = .*,/openhab = securePassword/g" /var/lib/openhab2/etc/users.properties
```
-----
Depending on your system, you may have to [change the directory](#console-settings-files-and-directories) at the end of the command.
Please restart openHAB for the changes to take effect. The clear text password will be replaced by a unique cryptographic password hash.
Please check the [Karaf reference](http://karaf.apache.org/manual/latest/) for more details.
### Bind Console to All Interfaces
The network interface configuration is defined in the file `org.apache.karaf.shell.cfg`, located in the `etc` directory as [mentioned above](#console-settings-files-and-directories).
The `sshHost` entry controls the interface address to bind to.
`sshHost = 127.0.0.1` (localhost) is the default due to obvious security reasons.
If you are on a local network or you are fully aware of all risks of exposing your system to the public, you can change the bind address.
Replace the `sshHost` IP `127.0.0.1` by `0.0.0.0` to bind to all available network interfaces.
Please be aware, that the console will now be accessible from all devices in your subnet and is only secured by the password defined in `users.properties` (same path).
You should thereby [change the password](#changing-the-password).
The above can be accomplished by the following Linux shell command.
Depending on your system, you may have to substitute [the directory](#console-settings-files-and-directories) at the end of the command.
```shell
sudo sed -i -e "s/sshHost = .*/sshHost = 0.0.0.0/g" /var/lib/openhab2/etc/org.apache.karaf.shell.cfg
```
### Change the Port Number
The SSH port configuration is done through the file `org.apache.karaf.shell.cfg`, located in the `etc` directory as [mentioned above](#console-settings-files-and-directories).
The `sshPort` entry controls the port number.
`sshPort = 8101` is the default, but can be changed to any available port per your choosing.
Alternately, run the following Linux shell command, which will perform the replacement for you.
Substitute `1234` with your desired port number.
Depending on your system, you may have to substitute [the directory](#console-settings-files-and-directories) at the end of the command.
```shell
sudo sed -i -e "s/sshPort = .*/sshPort = 1234/g" /var/lib/openhab2/etc/org.apache.karaf.shell.cfg
```
----
Please check the [Apache Karaf reference](http://karaf.apache.org/manual/latest/) for more details.