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

Override karaf console settings in runtime.cfg (#2220) 

Add a section about key-based authentication

Signed-off-by: Jimmy Tanagra <jcode@tanagra.id.au>
pull/2230/head
jimtng 2024-02-06 04:48:58 +10:00 committed by GitHub
parent 5e1ed479e3
commit 1dd9d89464
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 53 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
administration/console.md
View File

@ -59,7 +59,7 @@ The first successful connection triggers generation of the Karaf remote console
::: tip Note ::: tip Note
On slower systems, such as Raspberry Pi or Pine64, this first SSH connection may even time out. 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. If this happened, simply try connecting again until successful.
::: :::
## Using the Console ## Using the Console
@ -72,7 +72,7 @@ After successful connection and authentication, the console will appear:
/ _ \ / _ \ / _ \ / _ \ | |_| | / _ \ | _ \ / _ \ / _ \ / _ \ / _ \ | |_| | / _ \ | _ \
| (_) | (_) | __/| | | || _ | / ___ \ | |_) ) | (_) | (_) | __/| | | || _ | / ___ \ | |_) )
\___/| __/ \___/|_| |_||_| |_|/_/ \_\|____/ \___/| __/ \___/|_| |_||_| |_|/_/ \_\|____/
|_| 3.0.0 - Release Build |_| 4.2.0 - Release Build
Use '<tab>' for a list of available commands Use '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command. and '[cmd] --help' for help on a specific command.
@ -81,7 +81,7 @@ To exit, use '<ctrl-d>' or 'logout'.
openhab> openhab>
``` ```
The command `help` is listing all available commands or describes a specific subsystem/command: The command `help` lists all available commands or describes a specific subsystem/command:
```text ```text
openhab> help openhab> help
@ -109,15 +109,15 @@ Another useful feature is the combination of the `|` (pipe) and `grep` functiona
```text ```text
openhab> bundle:list | grep openHAB openhab> bundle:list | grep openHAB
128 x Active x 80 x 3.0.0 x openHAB Core :: Bundles :: Core 135 │ Active │ 80 │ 4.2.0 │ openHAB Core :: Bundles :: Core
129 x Active x 80 x 3.0.0 x openHAB Core :: Bundles :: Audio 136 │ Active │ 80 │ 4.2.0 │ openHAB Core :: Bundles :: Add-on XML
130 x Active x 80 x 3.0.0 x openHAB Core :: Bundles :: JAAS Authentication 137 │ Active │ 80 │ 4.2.0 │ openHAB Core :: Bundles :: Audio
131 x Active x 80 x 3.0.0 x openHAB Core :: Bundles :: OAuth2Client 138 │ Active │ 80 │ 4.2.0 │ openHAB Core :: Bundles :: Automation
132 x Active x 80 x 3.0.0 x openHAB Core :: Bundles :: Automation 139 │ Active │ 80 │ 4.2.0 │ openHAB Core :: Bundles :: Automation Media Modules
... ...
``` ```
The session is ended by using the logout command: The session is ended by using the logout command (or by pressing ctrl-d):
```text ```text
openhab> logout openhab> logout
@ -134,14 +134,23 @@ Changing the console password, interface, and port is described here.
The pertinent files controlling console settings are stored under `$OPENHAB_USERDATA/etc/`: The pertinent files controlling console settings are stored under `$OPENHAB_USERDATA/etc/`:
| File | Purpose | | File | Purpose |
|------------------------------|--------------------------------| | ---------------------------- | -------------------------------------- |
| `org.apache.karaf.shell.cfg` | Controls most console settings | | `org.apache.karaf.shell.cfg` | Controls most console settings |
| `users.properties` | Stores console password | | `users.properties` | Stores the list of users and passwords |
| `keys.properties` | Stores the list of users and ssh keys |
The exact locations of these files will vary based on your platform and installation method, e.g. `/var/lib/openhab/etc/` or `openhab/userdata/etc/`. The exact locations of these files will vary based on your platform and installation method, e.g. `/var/lib/openhab/etc/` or `openhab/userdata/etc/`.
Be aware that the these files may get overwritten when upgrading openHAB. Be aware that these files may get overwritten when upgrading openHAB.
To add custom parameters or overwrite the default values, you can change the configuration file `runtime.cfg` which can be found in the `$OPENHAB_CONF/services` directory, e.g. `/etc/openhab/services/runtime.cfg`. You can customize any of the console settings from `org.apache.karaf.shell.cfg` by adding the relevant entries inside the `runtime.cfg` file which can be found in the `$OPENHAB_CONF/services` directory, e.g. `/etc/openhab/services/runtime.cfg`.
When adding your custom settings into `runtime.cfg`, prefix the configuration key with `org.apache.karaf.shell:`. See the examples in the sections below.
:::tip Note
The users and passwords here are not to be confused with the web UI login.
The users listed in the above files are for logging into the console.
To manage web UI users, use `openhab:users` console command.
:::
### Changing the Password ### Changing the Password
@ -161,14 +170,11 @@ Please restart openHAB for the changes to take effect. The clear text password w
### Bind Console to All Interfaces ### 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).
As this file may get overwritten when upgrading openHAB, you can change this parameter in the `runtime.cfg` file which can be found in the `$OPENHAB_CONF/services` directory, e.g. `/etc/openhab/services/runtime.cfg`.
The `sshHost` entry controls the interface address to bind to. The `sshHost` entry controls the interface address to bind to.
`sshHost = 127.0.0.1` (localhost) is the default due to obvious security reasons. `sshHost = 127.0.0.1` (localhost) is the default due to obvious security reasons.
If you are on a secure network or you are fully aware of all of the risks of exposing your system to the public, you can change the bind address. If you are on a secure network or you are fully aware of all of the 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. 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 only secured by the password defined in `users.properties` (same path). Please be aware that the console will now be accessible from any device that can reach this host and it is only secured by the password defined in `users.properties` (same path).
You should therefore [change the password](#changing-the-password)! You should therefore [change the password](#changing-the-password)!
Depending on your network configuration the console may also be exposed to the public internet, so check your routing and firewall configuration. Depending on your network configuration the console may also be exposed to the public internet, so check your routing and firewall configuration.
@ -180,15 +186,38 @@ in `services/runtime.cfg`.
### Change the Port Number ### 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. The `sshPort` entry controls the port number.
`sshPort = 8101` is the default, but can be changed to any available port of your choosing. `sshPort = 8101` is the default.
To change it, add the following line to the `runtime.cfg` file inside `$OPENHAB_CONF/services` directory.
```shell
org.apache.karaf.shell:sshPort = 1234
```
Alternately, run the following Linux shell command, which will perform the replacement for you.
Substitute `1234` with your desired port number. 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.
```sudo sed -i -e "s/sshPort = .*/sshPort = 1234/g" /var/lib/openhab/etc/org.apache.karaf.shell.cfg``` ### Using Key-Based Authentication
The Karaf console can also accept key-based authentication to enable passwordless login.
The list of users with their associated key is stored in the `keys.properties` file inside the `$OPENHAB_USERDATA/etc/` directory.
The format of this file is: `[username]=[key],_g_:admingroup`.
To set up passwordless login, create your ssh key-pair if you haven't got one, e.g. using ssh-keygen, or PuTTYgen.
Then add the public key into the `keys.properties` file.
For example, to allow user `openhab` to login with key-based authentication:
```shell
openhab=AAAAB3NzaC1yc2EAAAADAQABAAAAgQC49lufVEVq9uCzLeCdP84ubVZioQl2NRjjBZiil7vvRZzEuFBP8gnkc+6SHsDibH858gcfYg5dHrpW0yfFV6FUi0CSB3hrSisI2LDXcB8gxvVRKqL0nM9ITqesNiDfUPP1UL00+N4sqTGIjwaBmo5c6bpfxJE9C59VQBL412t9tQ==,_g_:admingroup
```
The username `openhab` above is not a special username.
It can be anything that you prefer.
Multiple login/keys can be added into this file.
Note that this does not automatically disable the password-based login.
For security reasons, be sure to [change the default password](#changing-the-password), or remove the user from password login if your host is publicly accessible.
## More Information ## More Information