Doplněk Terminal & SSH

Terminal & SSH je jeden z nejužitečnějších doplňků pro Home Assistant, který vám umožní přístup k příkazovému řádku přímo z webového rozhraní a také vzdálené připojení přes SSH protokol. Díky tomuto addonu můžete provádět pokročilou správu systému, upravovat konfigurační soubory, instalovat balíčky, debugovat problémy a mnoho dalšího - a to vše bez nutnosti fyzického přístupu k zařízení.

Dva v jednom

Tento addon kombinuje dva nástroje - webový terminál dostupný přímo v Home Assistant rozhraní a plnohodnotný SSH server pro vzdálené připojení z libovolného SSH klienta.

K čemu se dá addon použít

Addon má hned několik oblastí možných použití:

Správa konfiguračních souborů

• Úprava configuration.yaml a dalších konfiguračních souborů pomocí editorů jako Nano nebo Vim
• Rychlá kontrola syntaxe pomocí Home Assistant CLI příkazu ha core check
• Prohlížení a úprava souborů automatizací, skriptů a šablon

Debugging a diagnostika

• Sledování logů v reálném čase pomocí ha core logs -f
• Kontrola stavu služeb a doplňků
• Testování síťových spojení pomocí nástrojů jako ping, nmap, curl
• Přístup k databázi (pokud používáte MariaDB nebo PostgreSQL addon)

Pokročilá správa systému

• Instalace dalších balíčků potřebných pro vaše projekty
• Správa Docker kontejnerů (pokud je povolený přístup k Docker socketu)
• Nastavení vlastních systémových úprav a skriptů
• Přístup k hardwaru (audio zařízení, UART/sériové porty, GPIO piny)

Home Assistant CLI

Addon obsahuje předinstalované Home Assistant CLI (ha) - mocný nástroj pro správu Home Assistantu přímo z příkazové řádky.

# Příklady použití HA CLI
ha core info              # Informace o Home Assistant Core
ha core restart           # Restart Home Assistant
ha supervisor update      # Aktualizace Supervisoru
ha addons list            # Seznam všech addonů
ha core check             # Kontrola konfigurace

Instalace

Tento addon je součástí oficiálních doplňků Home Assistant, takže jeho instalace je velmi jednoduchá.

Pokročilý režim

Addon Terminal & SSH je viditelný pouze pro uživatele s povoleným pokročilým režimem. Pokud addon nevidíte, přejděte do svého profilu (kliknutím na své jméno v levém dolním rohu) a zapněte možnost Pokročilý režim.

Postup instalace

1. V Home Assistantu přejděte do Nastavení → Doplňky → Obchod s doplňky

2. Najděte addon Terminal & SSH (můžete použít vyhledávání)

   

3. Klikněte na addon a poté na tlačítko NAINSTALOVAT

4. Počkejte na dokončení instalace

Po úspěšné instalaci se zobrazí stránka s informacemi o addonu.

Konfigurace

Před prvním spuštěním je nutné provést základní konfiguraci addonu. V první řadě musíte nastavit způsob přihlášení a případně další volby podle vašich potřeb.

Nastavení přihlášení

V konfiguraci addonu v sekci Volby musíte zvolit způsob autentizace. Máte dvě možnosti:

1. SSH klíče (doporučeno)

Nejbezpečnější způsob přihlášení je pomocí SSH klíčů. Do pole Authorized keys vložíte jeden nebo více veřejných SSH klíčů.

Příklad veřejného klíče:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAbCdEfGhIjKlMnOpQrStUvWxYz... user@laptop

Generování SSH klíče

Pokud ještě nemáte SSH klíč, můžete si ho vygenerovat:

Na macOS/Linux:

ssh-keygen -t ed25519 -C "[email protected]"

Na Windows (PowerShell):

ssh-keygen -t ed25519 -C "[email protected]"

Veřejný klíč najdete v souboru ~/.ssh/id_ed25519.pub (nebo %USERPROFILE%\.ssh\id_ed25519.pub na Windows).

2. Heslo (nedoporučeno)

Méně bezpečný způsob je použití hesla. Vypněte volbu Password a zadejte silné heslo.

Bezpečnostní upozornění

Použití hesla je výrazně méně bezpečné než SSH klíče. Heslo může být ukradeno, uhodnuté nebo zachycené. Používejte tento způsob pouze pokud nemůžete použít SSH klíče.

Dodatečné balíčky (volitelné)

Pokud potřebujete v terminálu používat specifické nástroje, které nejsou standardně nainstalované, můžete je přidat do sekce Packages.

Příklady užitečných balíčků:

• python3 - Python 3 interpreter
• py3-pip - Python package manager
• git - verzovací systém
• htop - pokročilý správce procesů
• tmux - terminálový multiplexer

Síťové nastavení (pro vzdálené SSH připojení)

Pokud chcete umožnit připojení přes SSH z lokální sítě nebo z jiného počítače, musíte nastavit síťový port.

Sjeďte dolů do sekce Network a nastavte:

• Číslo portu - standardně se používá port 22, ale můžete použít i jiný, například 2222 nebo 22222
• Tento port bude namapován z hostitelského systému do addonu

Důležité pro Virtual Machine / Proxmox

Pokud běží Home Assistant ve virtuálním stroji (například na Proxmoxu), může bý potřeba nejprve povolit síťový port pro SSH přístup. Ve výchozím stavu je vzdálený SSH přístup zakázán z bezpečnostních důvodů.

Vypnutí SSH přístupu

SSH přístup můžete kdykoli vypnout tím, že vymažete číslo portu z Network nastavení, uložíte konfiguraci a restartujete addon.

Vlastní port

Pokud již máte na hostitelském systému běžící SSH server na portu 22, použijte jiný port, například 2222 nebo 22222. Při připojení pak musíte tento port specifikovat pomocí parametru -p.

Spuštění addonu

Po dokončení konfigurace:

1. Klikněte na tlačítko ULOŽIT pro uložení konfigurace
2. Přejděte na záložku Informace
3. Klikněte na tlačítko SPUSTIT
4. Zkontrolujte záložku Protokol, že vše proběhlo v pořádku

[17:43:49] INFO: Starting Web Terminal...
[2025/10/12 17:43:49:2492] N: ttyd 1.7.7-40e79c7 (libwebsockets 4.4.0-v4.4.1)
[2025/10/12 17:43:49:2493] N: tty configuration:
[2025/10/12 17:43:49:2493] N:   start command: tmux -u new -A -s homeassistant bash -l
[2025/10/12 17:43:49:2493] N:   close signal: SIGHUP (1)
[2025/10/12 17:43:49:2493] N:   terminal type: xterm-256color
[2025/10/12 17:43:49:2522] N:    /usr/lib/libwebsockets-evlib_uv.so
[2025/10/12 17:43:49:2526] N: lws_create_context: LWS: 4.4.0-v4.4.1, NET CLI SRV H1 H2 WS SS-JSON-POL ConMon IPV6-off
[2025/10/12 17:43:49:2530] N: elops_init_pt_uv:  Using foreign event loop...
[2025/10/12 17:43:49:2541] N: [vh|2|default||8099]: lws_socket_bind: source ads 0.0.0.0
[2025/10/12 17:43:49:2541] N:  Listening on port: 8099
s6-rc: info: service legacy-services successfully started
[2025/10/12 17:43:49:2763] N: [wsicli|0|GET/h1/connectivitycheck.android.com/([wsiSScli|0|ca]: lws_sort_dns: 2a00:1450:4014:80b::200e has no route out
[2025/10/12 17:43:49:3130] N: lws_system_cpd_set: setting CPD result OK
[17:43:49] INFO: Starting the SSH daemon...
Server listening on 0.0.0.0 port 22.
Server listening on :: port 22.

Použití webového terminálu

Webový terminál je nejjednodušší způsob, jak získat přístup k příkazové řádce Home Assistantu, bez nutnosti instalace jakéhokoli dalšího softwaru.

Přístup k webovému terminálu

Existují dva způsoby, jak otevřít webový terminál:

1. Přes info stránku addonu:

• Přejděte do Nastavení → Doplňky → Terminal & SSH
• Klikněte na tlačítko Otevřít webové rozhraní

2. Přes postranní panel (doporučeno):

• Na info stránce addonu zapněte možnost Zobrazit na postranním panelu
• V levém menu se objeví ikona terminálu pro rychlý přístup

Práce s webovým terminálem

Když otevřete webový terminál, objeví se vám plnohodnotný příkazový řádek běžící v Bash shellu.

Kopírování a vkládání textu

Webový terminál má specifický způsob kopírování a vkládání:

Kopírování textu:

1. Podržte klávesu SHIFT
2. Myší vyberte text, který chcete zkopírovat
3. Po uvolnění levého tlačítka myši se text zkopíruje do schránky

Vkládání textu:

1. Stiskněte SHIFT + INSERT

Základní orientace

Po přihlášení se nacházíte v domovském adresáři /root, odkud máte přístup k důležitým cestám přes symbolické odkazy:

• /config (alias /homeassistant) - adresář s konfigurací Home Assistantu
• /ssl - certifikáty pro HTTPS
• /addons - lokální addons
• /addon_configs - konfigurace addonů
• /backup - zálohy systému
• /share - sdílený adresář mezi addony
• /media - mediální soubory

# Zobrazení všech dostupných adresářů
ls -la ~

# Zobrazení obsahu konfiguračního adresáře
ls -la /config

# Úprava hlavního konfiguračního souboru
nano /config/configuration.yaml

# Kontrola konfigurace
ha core check

Předinstalované nástroje

Addon obsahuje základní sadu nástrojů:

• Editory: Nano, Vim
• Verzování: Git
• MQTT: Mosquitto klient
• Audio: PulseAudio utils, ALSA pluginy
• Bluetooth: BlueZ nástroje
• Ostatní: tmux (terminálový multiplexer), pwgen (generátor hesel)

Dodatečné nástroje

Pokud potřebujete další nástroje jako curl, wget, nmap, htop, jq nebo jiné, můžete je snadno nainstalovat přidáním do sekce Packages v konfiguraci addonu.

# MQTT testování
mosquitto_sub -h localhost -t '#'

# Git operace
cd /config
git status

# Použití tmux pro trvalé sessions
tmux new -s moje-prace

SSH připojení z lokálního počítače

Webový terminál je skvělý pro rychlé úkoly, ale pro pokročilejší práci nebo pro případ, že chcete používat vlastní nástroje a editory, je lepší použít SSH připojení z lokálního počítače.

Zjištění IP adresy

Pokud neznáte IP adresu vašeho Home Assistantu, můžete ji zjistit v Nastavení → Systém → Síť.

Nebo můžete použít hostname: homeassistant.local (pokud funguje mDNS ve vaší síti).

Připojení z různých systémů

macOS / Linux

Otevřete Terminál a použijte příkaz ssh:

S výchozím portem 22:

ssh [email protected]
# nebo
ssh [email protected]

S vlastním portem (např. 2222):

ssh -p 2222 [email protected]
# nebo
ssh -p 2222 [email protected]

Se specifikací SSH klíče:

ssh -i ~/.ssh/id_ed25519 [email protected]

Windows PowerShell

Windows 10/11 obsahuje vestavěný SSH klient:

S výchozím portem 22:

ssh [email protected]
# nebo
ssh [email protected]

S vlastním portem:

ssh -p 2222 [email protected]

Windows PuTTY

Stáhněte si PuTTY a:

1. Spusťte PuTTY
2. Do pole Host Name zadejte: homeassistant.local nebo IP adresu
3. Do pole Port zadejte: 22 (nebo váš vlastní port)
4. V Connection type vyberte SSH
5. (Volitelně) V Connection → SSH → Auth nastavte cestu k soukromému klíči
6. Klikněte na Open

Praktické příklady použití SSH

Rychlá editace konfigurace z lokálního editoru

Pokud máte nastavený SSH přístup, můžete namountovat vzdálený /config adresář:

Na macOS/Linux s SSHFS:

# Instalace SSHFS (macOS)
brew install macfuse
brew install gromgit/fuse/sshfs-mac

# Mountování
mkdir ~/ha-config
sshfs [email protected]:/config ~/ha-config

# Nyní můžete editovat soubory lokálně
code ~/ha-config  # VS Code
nano ~/ha-config/configuration.yaml

# Odpojení
umount ~/ha-config

Port forwarding pro přístup k databázi

Pokud máte MariaDB addon a chcete se k němu připojit z lokálního databázového klienta:

ssh -L 3306:localhost:3306 [email protected]

Nyní můžete připojit svůj databázový klient na localhost:3306.

Vzdálené sledování logů

# Připojení a sledování logů v reálném čase
ssh [email protected] "ha core logs -f"

Automatizace úloh pomocí SSH

Můžete vytvořit skripty na lokálním počítači, které vzdáleně provádějí úkoly:

#!/bin/bash
# backup-ha.sh - Skript pro vytvoření zálohy HA

ssh [email protected] << 'EOF'
  ha backups new --name "automated-backup-$(date +%Y%m%d)"
EOF

Srovnání s jinými addony

Funkce	Terminal & SSH	Advanced SSH & Web Terminal	VS Code
Webový terminál	✅	✅	✅
SSH server	✅	✅	❌
Grafický editor	❌	❌	✅
Bezpečnostní audit	✅	✅	❌
ZSH shell	✅	✅	❌
Complexity	Nízká	Střední	Vysoká
Oficiální addon	✅	❌ (Community)	✅

Alternativy

• Advanced SSH & Web Terminal - komunitní addon s ještě více funkcemi (Mosh, SFTP, více možností)
• Studio Code Server - pokud preferujete grafický editor přímo v prohlížeči
• File Editor - jednoduchý editor pro rychlé úpravy konfigurace

Shrnutí

Terminal & SSH addon je nezbytný nástroj pro každého, kdo chce mít plnou kontrolu nad svým Home Assistant systémem. Ať už potřebujete:

• Rychle upravit konfigurační soubor
• Debugovat problém v reálném čase
• Spravovat systém vzdáleně z pohodlí svého počítače
• Provádět pokročilé úkoly, které nejsou dostupné z webového rozhraní

Tento addon vám to vše umožní - bezpečně, rychle a efektivně.