diff --git a/README.md b/README.md index 67229b6..7291803 100644 --- a/README.md +++ b/README.md @@ -158,7 +158,7 @@ When **Check for updates** is enabled for a container entry, SSH Docker also cre Navigate to **Settings → Updates** in Home Assistant. Containers with a pending image update are listed there. Click the container's update card and then **Install** to trigger a container recreation using the `docker_create` executable on the remote host — exactly the same operation as clicking **⬆ Update** in the sidebar panel. -> **Requires** the `docker_create` executable to be present on the remote host. See [Custom Executables](#%EF%B8%8F-custom-executables) for details. +> **Requires** the `docker_create` executable to be present on the remote host. See [Custom Executables](#-custom-executables) for details. While the installation is running the entity reports `in_progress: true` and the update card shows a progress indicator. Once completed the sensor is refreshed automatically to reflect the new container state. @@ -385,6 +385,24 @@ Community contributions for additional languages are welcome! --- +## ❗ Error Codes + +Errors shown while adding or reconfiguring a container are prefixed with a code. + +| Code | Meaning | What to do | +|------|-----------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| E001 | Neither password nor key file was provided. | Provide one of them. | +| E002 | Cannot connect to the remote host. | Check host, port and network. | +| E003 | The docker command exited with an error. This also happens if the executable was not found when the command is prefixed (e.g. `sudo docker`). | Check the docker command, that the executable exists on the host (use its absolute path, e.g. `sudo /usr/bin/docker`), and that the user may run it (e.g. `sudo` or docker group). | +| E004 | The host key could not be verified. | Check the known hosts file or disable the known hosts check. | +| E005 | SSH login failed. | Check username and password/key file. | +| E006 | Host is not reachable. | Check the host address and network. | +| E007 | The connection timed out. | Check that the host is online and the port is correct. | +| E008 | The container name was not found on the host. | Check the name with `docker ps -a` on the host. | +| E009 | The docker executable was not found (exit status 127). | Non-interactive SSH sessions may not have `docker` on the `PATH` (common on QNAP/Synology NAS). Enter the absolute path as Docker Command (e.g. `/usr/bin/docker`) or symlink it into `/usr/bin`. | +| E010 | The known hosts file was not found (SSH check enabled). | Provide the path to an existing known hosts file, create the default `~/.ssh/known_hosts` of the user running Home Assistant, or disable *Check Known Hosts*. | +| E011 | The known hosts file was provided but 'Check Known Hosts' is disabled. | Either enable 'Check Known Hosts' or remove the known hosts file path. | + ## ⚠️ Known Issues - If you are using HassOS and enable `check_known_hosts` without explicitly providing `known_hosts`, this may fail because the default known hosts file may not be accessible from within Home Assistant. Either disable host checking (not recommended) or provide `known_hosts` explicitly. diff --git a/options_flow.py b/options_flow.py index 7e65541..a4929c4 100644 --- a/options_flow.py +++ b/options_flow.py @@ -75,6 +75,8 @@ async def validate_and_build_options( user_input[CONF_HOST], exit_status, ) + if exit_status == 127: + return {}, "docker_command_not_found" return {}, "docker_command_failed" except ServiceValidationError as exc: translation_key = exc.translation_key if hasattr(exc, "translation_key") else "cannot_connect" @@ -91,6 +93,23 @@ async def validate_and_build_options( exc, ) return {}, "cannot_connect" + except FileNotFoundError as exc: + _LOGGER.warning( + "SSH validation for host %s raised FileNotFoundError: %s", + user_input[CONF_HOST], + exc, + ) + from pathlib import Path + + known_hosts = user_input.get(CONF_KNOWN_HOSTS) or "~/.ssh/known_hosts" + if ( + user_input.get(CONF_CHECK_KNOWN_HOSTS, DEFAULT_CHECK_KNOWN_HOSTS) + and exc.filename is not None + and Path(exc.filename).expanduser().absolute() + == Path(known_hosts).expanduser().absolute() + ): + return {}, "known_hosts_not_found" + return {}, "cannot_connect" except Exception as exc: # pylint: disable=broad-except _LOGGER.warning( "SSH validation for host %s raised an unexpected exception: %s", diff --git a/strings.json b/strings.json index c294aef..927ec60 100644 --- a/strings.json +++ b/strings.json @@ -37,14 +37,17 @@ } }, "error": { - "password_or_key_file_required": "Either password or key file must be provided.", - "cannot_connect": "Cannot connect to the remote host.", - "docker_command_failed": "The docker command failed. Check the docker command and permissions.", - "host_key_not_verifiable": "The host key could not be verified.", - "login_failed": "SSH login failed. Check username and password/key file.", - "host_not_reachable": "Host is not reachable.", - "connection_timed_out": "Connection to the host timed out.", - "docker_service_not_found": "The service name was not found on the remote host. Check the name and make sure the container exists." + "password_or_key_file_required": "[E001] Either password or key file must be provided.", + "cannot_connect": "[E002] Cannot connect to the remote host.", + "docker_command_failed": "[E003] The docker command failed. Check that the docker command is correct, that the executable exists on the remote host (use its absolute path, especially with `sudo`), and that the user has permission to run it.", + "host_key_not_verifiable": "[E004] The host key could not be verified.", + "login_failed": "[E005] SSH login failed. Check username and password/key file.", + "host_not_reachable": "[E006] Host is not reachable.", + "connection_timed_out": "[E007] Connection to the host timed out.", + "docker_service_not_found": "[E008] The service name was not found on the remote host. Check the name and make sure the container exists.", + "docker_command_not_found": "[E009] The docker executable was not found on the remote host. Use the absolute path to the executable (e.g. /usr/bin/docker) or add it to the PATH of non-interactive SSH sessions.", + "known_hosts_not_found": "[E010] The known hosts file was not found. Provide the path to an existing known hosts file, create the default one (~/.ssh/known_hosts) on the Home Assistant machine, or disable 'Check Known Hosts'.", + "known_hosts_with_check_disabled": "[E011] The known hosts file was provided but 'Check Known Hosts' is disabled. Either enable 'Check Known Hosts' or remove the known hosts file path." }, "abort": { "service_not_found": "The service ssh_command.execute was not found. Please install SSH Command through HACS and add it as an integration.", @@ -85,13 +88,16 @@ } }, "error": { - "password_or_key_file_required": "Either password or key file must be provided.", - "cannot_connect": "Cannot connect to the remote host.", - "docker_command_failed": "The docker command failed. Check the docker command and permissions.", - "host_key_not_verifiable": "The host key could not be verified.", - "login_failed": "SSH login failed. Check username and password/key file.", - "host_not_reachable": "Host is not reachable.", - "connection_timed_out": "Connection to the host timed out." + "password_or_key_file_required": "[E001] Either password or key file must be provided.", + "cannot_connect": "[E002] Cannot connect to the remote host.", + "docker_command_failed": "[E003] The docker command failed. Check that the docker command is correct, that the executable exists on the remote host (use its absolute path, especially with `sudo`), and that the user has permission to run it.", + "host_key_not_verifiable": "[E004] The host key could not be verified.", + "login_failed": "[E005] SSH login failed. Check username and password/key file.", + "host_not_reachable": "[E006] Host is not reachable.", + "connection_timed_out": "[E007] Connection to the host timed out.", + "docker_command_not_found": "[E009] The docker executable was not found on the remote host. Use the absolute path to the executable (e.g. /usr/bin/docker) or add it to the PATH of non-interactive SSH sessions.", + "known_hosts_not_found": "[E010] The known hosts file was not found. Provide the path to an existing known hosts file, create the default one (~/.ssh/known_hosts) on the Home Assistant machine, or disable 'Check Known Hosts'.", + "known_hosts_with_check_disabled": "[E011] The known hosts file was provided but 'Check Known Hosts' is disabled. Either enable 'Check Known Hosts' or remove the known hosts file path." } }, "services": { diff --git a/translations/de.json b/translations/de.json index 9667dbf..413f478 100644 --- a/translations/de.json +++ b/translations/de.json @@ -37,14 +37,17 @@ } }, "error": { - "password_or_key_file_required": "Es muss entweder ein Passwort oder eine Schlüsseldatei angegeben werden.", - "cannot_connect": "Es kann keine Verbindung zum entfernten Host hergestellt werden.", - "docker_command_failed": "Der Docker-Befehl ist fehlgeschlagen. Überprüfen Sie den Docker-Befehl und die Berechtigungen.", - "host_key_not_verifiable": "Der Host-Schlüssel konnte nicht verifiziert werden.", - "login_failed": "SSH-Anmeldung fehlgeschlagen. Überprüfen Sie Benutzername und Passwort/Schlüsseldatei.", - "host_not_reachable": "Host ist nicht erreichbar.", - "connection_timed_out": "Die Verbindung zum Host hat das Zeitlimit überschritten.", - "docker_service_not_found": "Der Dienstname wurde auf dem entfernten Host nicht gefunden. Überprüfen Sie den Namen und stellen Sie sicher, dass der Container existiert." + "password_or_key_file_required": "[E001] Es muss entweder ein Passwort oder eine Schlüsseldatei angegeben werden.", + "cannot_connect": "[E002] Es kann keine Verbindung zum entfernten Host hergestellt werden.", + "docker_command_failed": "[E003] Der Docker-Befehl ist fehlgeschlagen. Prüfen Sie, ob der Docker-Befehl korrekt ist, die ausführbare Datei auf dem entfernten Host existiert (verwenden Sie insbesondere mit `sudo` den absoluten Pfad) und der Benutzer sie ausführen darf.", + "host_key_not_verifiable": "[E004] Der Host-Schlüssel konnte nicht verifiziert werden.", + "login_failed": "[E005] SSH-Anmeldung fehlgeschlagen. Überprüfen Sie Benutzername und Passwort/Schlüsseldatei.", + "host_not_reachable": "[E006] Host ist nicht erreichbar.", + "connection_timed_out": "[E007] Die Verbindung zum Host hat das Zeitlimit überschritten.", + "docker_service_not_found": "[E008] Der Dienstname wurde auf dem entfernten Host nicht gefunden. Überprüfen Sie den Namen und stellen Sie sicher, dass der Container existiert.", + "docker_command_not_found": "[E009] Die ausführbare Docker-Datei wurde auf dem entfernten Host nicht gefunden. Verwenden Sie den absoluten Pfad zur Datei (z. B. /usr/bin/docker) oder fügen Sie sie dem PATH nicht-interaktiver SSH-Sitzungen hinzu.", + "known_hosts_not_found": "[E010] Die known_hosts-Datei wurde nicht gefunden. Geben Sie den Pfad zu einer vorhandenen known_hosts-Datei an, legen Sie die Standarddatei (~/.ssh/known_hosts) auf dem Home-Assistant-Rechner an oder deaktivieren Sie 'Bekannte Hosts prüfen'.", + "known_hosts_with_check_disabled": "[E011] Die known_hosts-Datei wurde angegeben, aber die Option 'Bekannte Hosts prüfen' ist deaktiviert. Entweder aktivieren Sie die Option oder entfernen Sie den Pfad zur known_hosts-Datei." }, "abort": { "service_not_found": "Der Service ssh_command.execute wurde nicht gefunden. Bitte installiere SSH Command in HACS und füge die Integration hinzu.", @@ -85,13 +88,16 @@ } }, "error": { - "password_or_key_file_required": "Es muss entweder ein Passwort oder eine Schlüsseldatei angegeben werden.", - "cannot_connect": "Es kann keine Verbindung zum entfernten Host hergestellt werden.", - "docker_command_failed": "Der Docker-Befehl ist fehlgeschlagen. Überprüfen Sie den Docker-Befehl und die Berechtigungen.", - "host_key_not_verifiable": "Der Host-Schlüssel konnte nicht verifiziert werden.", - "login_failed": "SSH-Anmeldung fehlgeschlagen. Überprüfen Sie Benutzername und Passwort/Schlüsseldatei.", - "host_not_reachable": "Host ist nicht erreichbar.", - "connection_timed_out": "Die Verbindung zum Host hat das Zeitlimit überschritten." + "password_or_key_file_required": "[E001] Es muss entweder ein Passwort oder eine Schlüsseldatei angegeben werden.", + "cannot_connect": "[E002] Es kann keine Verbindung zum entfernten Host hergestellt werden.", + "docker_command_failed": "[E003] Der Docker-Befehl ist fehlgeschlagen. Prüfen Sie, ob der Docker-Befehl korrekt ist, die ausführbare Datei auf dem entfernten Host existiert (verwenden Sie insbesondere mit `sudo` den absoluten Pfad) und der Benutzer sie ausführen darf.", + "host_key_not_verifiable": "[E004] Der Host-Schlüssel konnte nicht verifiziert werden.", + "login_failed": "[E005] SSH-Anmeldung fehlgeschlagen. Überprüfen Sie Benutzername und Passwort/Schlüsseldatei.", + "host_not_reachable": "[E006] Host ist nicht erreichbar.", + "connection_timed_out": "[E007] Die Verbindung zum Host hat das Zeitlimit überschritten.", + "docker_command_not_found": "[E009] Die ausführbare Docker-Datei wurde auf dem entfernten Host nicht gefunden. Verwenden Sie den absoluten Pfad zur Datei (z. B. /usr/bin/docker) oder fügen Sie sie dem PATH nicht-interaktiver SSH-Sitzungen hinzu.", + "known_hosts_not_found": "[E010] Die known_hosts-Datei wurde nicht gefunden. Geben Sie den Pfad zu einer vorhandenen known_hosts-Datei an, legen Sie die Standarddatei (~/.ssh/known_hosts) auf dem Home-Assistant-Rechner an oder deaktivieren Sie 'Bekannte Hosts prüfen'.", + "known_hosts_with_check_disabled": "[E011] Die known_hosts-Datei wurde angegeben, aber die Option 'Bekannte Hosts prüfen' ist deaktiviert. Entweder aktivieren Sie die Option oder entfernen Sie den Pfad zur known_hosts-Datei." } }, "services": { diff --git a/translations/en.json b/translations/en.json index c294aef..927ec60 100644 --- a/translations/en.json +++ b/translations/en.json @@ -37,14 +37,17 @@ } }, "error": { - "password_or_key_file_required": "Either password or key file must be provided.", - "cannot_connect": "Cannot connect to the remote host.", - "docker_command_failed": "The docker command failed. Check the docker command and permissions.", - "host_key_not_verifiable": "The host key could not be verified.", - "login_failed": "SSH login failed. Check username and password/key file.", - "host_not_reachable": "Host is not reachable.", - "connection_timed_out": "Connection to the host timed out.", - "docker_service_not_found": "The service name was not found on the remote host. Check the name and make sure the container exists." + "password_or_key_file_required": "[E001] Either password or key file must be provided.", + "cannot_connect": "[E002] Cannot connect to the remote host.", + "docker_command_failed": "[E003] The docker command failed. Check that the docker command is correct, that the executable exists on the remote host (use its absolute path, especially with `sudo`), and that the user has permission to run it.", + "host_key_not_verifiable": "[E004] The host key could not be verified.", + "login_failed": "[E005] SSH login failed. Check username and password/key file.", + "host_not_reachable": "[E006] Host is not reachable.", + "connection_timed_out": "[E007] Connection to the host timed out.", + "docker_service_not_found": "[E008] The service name was not found on the remote host. Check the name and make sure the container exists.", + "docker_command_not_found": "[E009] The docker executable was not found on the remote host. Use the absolute path to the executable (e.g. /usr/bin/docker) or add it to the PATH of non-interactive SSH sessions.", + "known_hosts_not_found": "[E010] The known hosts file was not found. Provide the path to an existing known hosts file, create the default one (~/.ssh/known_hosts) on the Home Assistant machine, or disable 'Check Known Hosts'.", + "known_hosts_with_check_disabled": "[E011] The known hosts file was provided but 'Check Known Hosts' is disabled. Either enable 'Check Known Hosts' or remove the known hosts file path." }, "abort": { "service_not_found": "The service ssh_command.execute was not found. Please install SSH Command through HACS and add it as an integration.", @@ -85,13 +88,16 @@ } }, "error": { - "password_or_key_file_required": "Either password or key file must be provided.", - "cannot_connect": "Cannot connect to the remote host.", - "docker_command_failed": "The docker command failed. Check the docker command and permissions.", - "host_key_not_verifiable": "The host key could not be verified.", - "login_failed": "SSH login failed. Check username and password/key file.", - "host_not_reachable": "Host is not reachable.", - "connection_timed_out": "Connection to the host timed out." + "password_or_key_file_required": "[E001] Either password or key file must be provided.", + "cannot_connect": "[E002] Cannot connect to the remote host.", + "docker_command_failed": "[E003] The docker command failed. Check that the docker command is correct, that the executable exists on the remote host (use its absolute path, especially with `sudo`), and that the user has permission to run it.", + "host_key_not_verifiable": "[E004] The host key could not be verified.", + "login_failed": "[E005] SSH login failed. Check username and password/key file.", + "host_not_reachable": "[E006] Host is not reachable.", + "connection_timed_out": "[E007] Connection to the host timed out.", + "docker_command_not_found": "[E009] The docker executable was not found on the remote host. Use the absolute path to the executable (e.g. /usr/bin/docker) or add it to the PATH of non-interactive SSH sessions.", + "known_hosts_not_found": "[E010] The known hosts file was not found. Provide the path to an existing known hosts file, create the default one (~/.ssh/known_hosts) on the Home Assistant machine, or disable 'Check Known Hosts'.", + "known_hosts_with_check_disabled": "[E011] The known hosts file was provided but 'Check Known Hosts' is disabled. Either enable 'Check Known Hosts' or remove the known hosts file path." } }, "services": {