Skip to content

Latest commit

 

History

History
120 lines (74 loc) · 5.39 KB

DOCS.md

File metadata and controls

120 lines (74 loc) · 5.39 KB
Raw

Home Assistant Add-on: Terminal & SSH

Installation

Follow these steps to get the add-on installed on your system:

  1. This add-on is only visible to "Advanced Mode" users. To enable advanced mode, go to Profile -> and turn on Advanced Mode.
  2. Navigate in your Home Assistant frontend to Settings -> Add-ons -> Add-on store.
  3. Find the "Terminal & SSH" add-on and click it.
  4. Click on the "INSTALL" button.

How to use

This add-on adds two main features to your Home Assistant installation:

  • a web terminal that you can use from your browser, and
  • enable connecting to your system using an SSH client.

Regardless of how you connect (using the web terminal or using an SSH client), you end up in this add-on's container. The Home Assistant configuration directory is located on the path /config.

This add-on comes bundled with The Home Assistant CLI. Try it out using:

ha help

The Web Terminal

You can access the web terminal by clicking the "Open Web UI" button on this add-on's Info tab. If you set the "Show in sidebar" setting (found on the same Info tab) to "on", a shortcut is added to the sidebar allowing you to access the web terminal quickly.

To copy text from the Web UI:

  1. Hold down the SHIFT key.
  2. Select the text you want to copy using your mouse.
  3. On releasing the left mouse button, the text gets copied to your system clipboard.

To paste text into the Web UI:

  1. Press SHIFT + INSERT.

SSH Server Connection

Remote SSH access from the network is disabled by default (See Network below). To connect using an SSH client, such as PuTTY or Linux terminal, you need to supply additional configuration for this add-on. To enable SSH connectivity, you need to:

  • Provide authentication credentials - a password or SSH key(s)
  • Specify which TCP port to bind to, on the Home Assistant host

You can then connect to the port specified, using the username root. Please note that enabling the SSH Server potentially makes your Home Assistant system less secure, as it might enable anyone on the internet to try to access your system. The security of your system also depends on your network set up, router settings, use of firewalls, etc. As a general recommendation, you should not activate this part of the add-on unless you understand the ramifications.

If you enable connecting to the SSH Server using an SSH client, you are strongly recommended to use private/public keys to log in. As long as you keep the private part of your key safe, this makes your system much harder to break into. Using passwords is, therefore, generally considered a less secure mechanism. To generate private/public SSH keys, follow the instructions for Windows and these for other platforms.

Note: While following the instructions above, select ECDSA as Type of key to generate instead of RSA. RSA is no longer supported.

Enabling login via password will disable key-based login. You can not run both variants at the same time.

Configuration

Add-on configuration:

authorized_keys:
  - "ssh-rsa AKDJD3839...== my-key"
password: ''
apks: []
server:
  tcp_forwarding: false

Option: apks

Additional software packages to install in the add-on container.

Option: authorized_keys

Your public keys that you wish to accept for login. You can authorize multiple keys by adding multiple public keys to the list.

If you get errors when adding your key, it is likely that the public key you're trying to add, contains characters that intervene with YAML syntax. Try enclosing your key in double quotes to avoid this issue.

Option: password

Set a password for login. We do NOT recommend this variant.

Option group server

Some SSH server options.

Option tcp_forwarding

Specifies whether TCP port forwarding (-L -R etc.) is permitted or not.

Note: Enabling this option lowers the security of your SSH server! Nevertheless, this warning is debatable.

Network

This section is only relevant if you want to connect to Home Assistant using an SSH client, such as PuTTY or Linux terminal. To enable SSH remote access from the Network, specify the desired SSH TCP server port in the Network configuration input box. The number you enter will be used to map that port from the host into the running "Terminal & SSH" add-on. The standard port used for the SSH protocol is 22.

Remote SSH access can be disabled again, by clearing the input box, saving the configuration and restarting the add-on.

Known issues and limitations

  • This add-on will not enable you to install packages or do anything as root. This is not working with Home Assistant.

Support

Got questions?

You have several options to get them answered:

In case you've found a bug, please open an issue on our GitHub.