Home Assistant Community Add-on: SSH & Web Terminal

This add-on is provided by the Home Assistant Community Add-ons project.

GitHub Release GitLab CI Project Stage Project Maintenance

Supports armhf Architecture Supports armv7 Architecture Supports aarch64 Architecture Supports amd64 Architecture Supports i386 Architecture

About


This add-on allows you to log in to your Home Assistant instance using SSH or a Web Terminal, giving you to access your folders and also includes a command-line tool to do things like restart, update, and check your instance.

This is an enhanced version of the provided SSH add-on by Home Assistant and focusses on security, usability, flexibility and also provides access using a web interface.

Features


This add-on, of course, provides an SSH server, based on OpenSSH and
a web-based Terminal (which can be included in your Home Assistant frontend) as
well. Additionally, it comes out of the box with the following:

  • Access your command line right from the Home Assistant frontend!
  • A secure default configuration of SSH:
    • Only allows login by the configured user, even if more users are created.
    • Only uses known secure ciphers and algorithms.
    • Limits login attempts to hold off brute-force attacks better.
    • Many more security tweaks, this addon passes all ssh-audit checks
      without warnings!
  • Passwords are checked with HaveIBeenPwned using K-anonymity.
  • Comes with an SSH compatibility mode option to allow older clients to connect.
  • Support for Mosh allowing roaming and supports intermittent connectivity.
  • SFTP support is disabled by default but is user configurable.
  • Compatible if Home Assistant was installed via the generic Linux installer.
  • Username is configurable, so root is no longer mandatory.
  • Persists custom SSH client settings & keys between add-on restarts
  • Hardware access to your audio, uart/serial devices and GPIO pins.
  • Runs with more privileges, allowing you to debug and test more situations.
  • Has access to the dbus of the host system.
  • Has the option to access the Docker instance running on the host system.
  • Runs on host level network, allowing you to open ports or run little daemons.
  • Have custom Alpine packages installed on start. This allows you to install
    your favorite tools, which will be available every single time you log in.
  • Execute custom commands on add-on start so that you can customize the
    shell to your likings.
  • ZSH as its default shell. Easier to use for the beginner, more advanced
    for the more experienced user. It even comes preloaded with
    “Oh My ZSH”, with some plugins enabled as well.
  • Bash: If ZSH is not your cup of tea, Bash can be enabled again, which
    includes Bash completion for both the Home Assistant CLI and the Home Assistant Core CLI.
  • Contains a sensible set of tools right out of the box: curl, Wget, RSync, GIT,
    Nmap, Mosquitto client, MariaDB/MySQL client, Awake (“wake on LAN”), Nano,
    Vim, tmux, and a bunch commonly used networking tools.
  • Has the Home Assistant CLI (hass-cli) command line tool pre-installed and
    pre-configured.
  • Support executing commands inside using a Home Assistant service call, e.g.,
    for use with automations.

Installation


The installation of this add-on is pretty straightforward and not different in comparison to installing any other Home Assistant add-on.

  1. Search for the “SSH & Web Terminal” add-on in the add-on store and install it.
  2. Configure the username and password/authorized_keys options.
  3. Start the “SSH & Web Terminal” add-on.
  4. Check the logs of the “SSH & Web Terminal” add-on to see if everything
    went well.

:books: Please read the documentation for more information about the use and configuration of this add-on.

Support


You can always try to get support from the community here at the Home Assistant community forums, join the conversation!

Questions? You have several options to get them answered:

You could also open an issue on GitHub, in case you ran into a bug, or maybe you have an idea on improving the addon:

:information_source: At this moment our Home Assistant Community Add-ons Discord chat server and GitHub are our only official support channels. All others rely on community effort.

Repository on GitHub


Looking for more add-ons?


The primary goal of our add-ons project is to provide you (as an Hassio / Home Assistant user) with additional, high quality, add-ons that allow you to take your automated home to the next level.

Check out some of our other add-ons in our Home Assistant Community Add-ons project.

8 Likes

About the author of this add-on

Hi there!

I am Franck Nijhof, and I have 30 years of programming experience, in many languages. I am using this experience to work on the Home Assistant project by giving back my knowledge and time to the open source community.

The add-on you are currently looking at right now was developed/packaged by me. It is not the only add-on I have created; there are many many more :wink:

However, I have a problem… I am an addict. A :coffee: addict that is. Lucky for you, I turn that C8H10N4O2 (caffeine molecule) into code (and add-ons)!

If you want to show your appreciation, consider supporting me for buying a cup of high octane wakey juice via one of the platforms below! :heart:

Sponsor Frenck via GitHub Sponsors

Support Frenck on Patreon

Enjoy your add-on, while I enjoy the brain juice. :coffee:

Thanks for all the :two_hearts:

…/Frenck

Join our Discord server Follow me on Twitter Flollow me on Instragram Follow me on GitHub Follow me on YouTube Follow me on Twitch patreon-icon

P.S.: In case you want to ask me a question: AMA (Ask Me Anything). Most of the time I am online at the Discord chat. (I go by @Frenck in there as well).

2 Likes

I’ve installed the SSH addon from the repository today, mainly because of the tmux support.
However, I can’t get neither the hassio commands inside the terminal to work, nor the SFTP option.

hassio homeassistant check, hassio homeassistant logs and hassio supervisor logs all give API error:

Is that a bug or do I need to configure something? It did work with the standard SSH addon shipped with Hass.io, though.

For the SFTP connection I tried to use Cyberduck as a client. When trying to connect I only get the following error message:
Unable to reach a settlement: [hmac-sha1, hmac-sha1-96, hmac-md5, hmac-md5-96, hmac-sha2-256, hmac-sha2-512] and [[email protected], [email protected], [email protected]]

For the same connection attempt the SSH addon log gives the following:
Unable to negotiate with 192.168.x.y port z: no matching MAC found. Their offer: hmac-sha1,hmac-sha1-96,hmac-md5,hmac-md5-96,hmac-sha2-256,hmac-sha2-512 [preauth]

Any idea how to fix that?

The clients you are using seem not to support the latest security encryption algorithms and ciphers.
Consider upgrading the tools you are using, or switch to tools which do support these.

:tada: Add-on: SSH - Secure Shell v2.0.0

Full Changelog

Added

  • Added CodeClimate
  • Added CircleCI
  • Added support for Hass.io’s extended label schema
  • Added persistency of the ~/.ssh folder
  • Added compatibility mode

Changed

  • Migrated to the new Hass.io build system
  • Migrated to our new base images
  • Rewrite of add-on onto the S6 process supervisor
  • Upgraded the hassio CLI

This update is now available in your Hass.io panel.

:tada: Add-on: SSH - Secure Shell v2.0.1

Full Changelog

Fixed

  • File authorized_keys has incorrect permissions

This update is now available in your Hass.io panel.

1 Like

Hello,

I still seem to be having issues with authorized_keys. After upgrading to v2.0.1 I am now receiving this error:

Authentication refused: bad ownership or modes for directory /etc/ssh

Is there anything additional I need to look into on my end?

Thanks!

Hi @dancwilliams, sorry to hear that :frowning:

I did not experience this myself on both of my instances (Raspberry Pi and a Generic Linux installation).
Nevertheless, thank you for the report! I will look into it an report back asap.

@frenck,

No worries. I am on a Raspberry Pi 3 as well. I appreciate it.

Otherwise I love the setup! Appreciate all the work for sure!

Also seeing the same director ownership error @dancwilliams error with ssh 2.0.1 and RPI3.

@wackydoo & @dancwilliams
I’ve confirmed the issue a couple of minutes ago.
The issue does not occur when the add-on was build locally, which is odd.
I’m currently working on a fix.

1 Like

:tada: Add-on: SSH - Secure Shell v2.0.2

Full Changelog

Fixed

  • Directory /etc/ssh/ has incorrect permissions

Thanks to @wackydoo and @dancwilliams for reporting this issue! :1st_place_medal:

This update is now available in your Hass.io panel.

Thanks for knocking this out!

As soon as I see the update available in Hassio I will give it a test.

@dancwilliams The update is already available, just go to the add-on “store”, in the top right, hit the refresh button. Wait a couple of seconds and the update will pop-up!

1 Like

Totally missed the refresh button…don’t mind me.

Got it upgraded and the keys work great! Thanks again!

1 Like

stupid question, sorry … what is the difference between the SSH - Secure Shell and. the “default” SSH server ?

@nsoares That is not a stupid question at all!

This is an enhanced version of the provided SSH add-on by Home Assistant and focusses on security, usability and flexibility.

The add-on, of course, provides an SSH server, based on OpenSSH.
Additionally, it comes out of the box with the following:

  • A secure default configuration of SSH:
    • Only allows login by the configured user, even if more users are created.
    • Only uses known secure ciphers and algorithms.
    • Limits login attempts to hold of brute-force attacks better.
    • Many more security tweaks, this addon passes all ssh-audit checks
      without warnings!
  • Comes with compatibility mode option to allow older clients to connect.
  • SFTP support is disabled by default but is user configurable.
  • Compatible if Hass.io was installed via the generic Linux installer.
  • Username is configurable, so root is no longer mandatory.
  • Persists custom SSH client settings & keys between add-on restarts
  • Log levels for allowing you to triage issues easier.
  • Have custom Alpine packages installed on start. This allows you to install
    your favorite tools, which will be available every single time you log in.
  • Execute custom commands on add-on start so that you can customize the
    shell to your likings.
  • ZSH as its default shell. Easier to use for the beginner, more advanced
    for the more experienced user. It even comes preloaded with
    “Oh My ZSH”, with some plugins enabled as well.
  • Contains a sensible set of tools right out of the box: curl, Wget, RSync, GIT,
    Nmap, Mosquitto client, MariaDB/MySQL client, Awake (“wake on LAN”), Nano,
    Vim, tmux, and a bunch commonly used networking tools.
3 Likes

:tada: Add-on: SSH - Secure Shell v2.0.3

Full Changelog

Changed

  • Updated base images to v1.0.1

This update is now available in your Hass.io panel.

:tada: Add-on: SSH - Secure Shell v2.0.4

Full Changelog

Fixed

  • Preserves environment variables on user change to fix time zone issue

Removed

  • Removes repository.json to prevent user to install wrong repo
  • Removes Gratipay from README, since it is EOL

This update is now available in your Hass.io panel.

:tada: Add-on: SSH - Secure Shell v2.0.4

Full Changelog

Changed

  • Upgrades add-on base image to v1.2.0
  • Improves sshd S6 run script
  • Updates add-on URLs to new community forum URL
  • Moves copy of rootfs at a later stage

This update is now available in your Hass.io panel.