tuna ❤️ NanoKVM

NanoKVM — это компактное IP-KVM устройство от Sipeed на базе RISC-V (Cube/PCIe) или ARM64 (Pro) или ARMv7 (GxxKVM/JxxKVM). Оно позволяет удалённо управлять компьютером: видеть экран, управлять клавиатурой и мышью, монтировать образы дисков — всё через веб-интерфейс в браузере.

По умолчанию NanoKVM доступен только в локальной сети. С помощью Tuna вы можете открыть доступ к нему через интернет — без «белого» IP, без VPN, без проброса портов на роутере.

к сведению

Мы тестировали данную инструкцию только на NanoKVM Cube, но вероятнее всего это будет работать на всех устройствах линейки NanoKVM.

---

Подготовка

Помимо установи инструкция по настройке разделена на 2 типа, в зависимости от наличия платной подписки Tuna.

1. На бесплатном тарифе
2. С платной подпиской

Что потребуется

• NanoKVM, подключённый к локальной сети и доступный по SSH или терминал в веб интерфейсе
• Аккаунт на tuna.am (бесплатный или с подпиской)
• Токен авторизации со страницы токена

Структура хранилища NanoKVM

NanoKVM имеет три раздела:

Раздел	Точка монтирования	Назначение
/dev/mmcblk0p1	/boot	Загрузчик, ядро
/dev/mmcblk0p2	/	Корневая ФС (Buildroot)
/dev/mmcblk0p3	/data	Данные, ISO-образы

Раздел /data сохраняется при обновлениях приложения и remote rsync, поэтому мы будем хранить tuna именно там.

Установка tuna на NanoKVM

Подключитесь к NanoKVM по SSH и установите бинарник:

ssh root@<IP-адрес-NanoKVM>

Или откройте терминал в веб интерфейсе:

Установите tuna с помощью скрипта, указав /data/tuna в качестве директории установки:

curl

mkdir -p /data/tuna
INSTALL_DIR=/data/tuna sh -c "$(curl -sSLf https://releases.tuna.am/tuna/get.sh)"

wget

mkdir -p /data/tuna
INSTALL_DIR=/data/tuna sh -c "$(wget -qO- https://releases.tuna.am/tuna/get.sh)"

подсказка

Раздел /data смонтирован как exFAT с fmask=0022, файлы автоматически получают права 0755 — бинарник можно запускать сразу после копирования. Кроме того, /data сохраняется при обновлениях, поэтому tuna не придётся переустанавливать.

Сохраните токен авторизации:

/data/tuna/tuna --config=/data/tuna/.tuna.yml config save-token <ВАШ_ТОКЕН>

подсказка

Рекомендуем создать дополнительный токен для устройства.

---

Тип 1. Бесплатный тариф — HTTP-туннель

На бесплатном тарифе доступен HTTP-туннель с динамическим адресом. Этого достаточно, чтобы открыть веб-интерфейс NanoKVM в интернет и управлять компьютером через браузер.

Ограничения бесплатного тарифа

• Адрес туннеля меняется каждые 30 минут
• Нельзя задать фиксированный поддомен
• Текущий адрес всегда можно посмотреть в личном кабинете

Создание скрипта запуска

cat << 'EOF' > /data/tuna/tuna-http.sh
#!/bin/sh

# Ждём сеть
while ! ip route | grep -q default; do
    sleep 1
done

exec /data/tuna/tuna \
    --config=/data/tuna/.tuna.yml \
    --log=/tmp/tuna-http.log \
    http \
    --inspect=false \
    --basic-auth=tuna:SecurePasswd \
    --https-redirect \
    80
EOF
chmod +x /data/tuna/tuna-http.sh

Пояснение флагов

Флаг	Обязательный	Описание
--inspect=false	Нет	Отключает инспектор трафика (не нужен для KVM), чтобы не расходовать RAM
--basic-auth=admin:ВашПароль	Нет	Дополнительная HTTP-авторизация (подробнее)
--https-redirect	Нет	Перенаправляет HTTP на HTTPS
80	Да	Порт веб-интерфейса NanoKVM

Также можно ограничить доступ по IP-подсетям.

Настройка автозапуска

Добавьте строку в /etc/inittab, чтобы init автоматически запускал и перезапускал туннель:

cat << 'EOF' >> /etc/inittab

# Tuna HTTP tunnel (respawn = auto-restart)
tweb::respawn:/data/tuna/tuna-http.sh
EOF

Применить без перезагрузки:

kill -HUP 1

Проверка

Убедитесь, что процесс запущен:

ps -ef | grep tuna

В выводе должна быть строка с /data/tuna/tuna ... http .... Если процесса нет — смотрите раздел Диагностика неполадок.

В логах вы увидите URL вашего туннеля:

cat /tmp/tuna-http.log

Также текущий адрес доступен в личном кабинете.

---

Тип 2. Подписка — SSH и HTTP туннели

С подпиской вы получаете:

• Фиксированный поддомен для HTTP-туннеля — адрес не меняется
• SSH-туннель — прямой доступ к консоли NanoKVM из любой точки мира

Ну и в целом особо ограничений нет, можете ещё несколько туннелей запустить и прокинуть доступ например к web интерфейсу роутера, SSH или RDP управляемого или любого другого компьютера в локальной сети.

HTTP-туннель с фиксированным адресом

cat << 'EOF' > /data/tuna/tuna-http.sh
#!/bin/sh

# Ждём сеть
while ! ip route | grep -q default; do
    sleep 1
done

exec /data/tuna/tuna \
    --config=/data/tuna/.tuna.yml \
    --log=/tmp/tuna-http.log \
    http \
    --subdomain=nanokvm \
    --inspect=false \
    --basic-auth=admin:ВашПароль \
    --https-redirect \
    80
EOF
chmod +x /data/tuna/tuna-http.sh

Отличие от бесплатной версии — флаг --subdomain=nanokvm, который закрепляет за вами постоянный адрес. После перезапуска туннеля URL останется прежним.

к сведению

Поддомен из примера уже занят. Зарезервируйте свой поддомен заранее в личном кабинете, затем используйте его в флаге --subdomain=ваш-поддомен.

Пояснение флагов HTTP-туннеля

Флаг	Обязательный	Описание
--subdomain=nanokvm	Нет	Фиксирует постоянный адрес туннеля (только с подпиской)
--inspect=false	Нет	Отключает инспектор трафика (не нужен для KVM), чтобы не расходовать RAM
--basic-auth=admin:ВашПароль	Нет	Дополнительная HTTP-авторизация (подробнее)
--https-redirect	Нет	Перенаправляет HTTP на HTTPS
80	Да	Порт веб-интерфейса NanoKVM

Также можно ограничить доступ по IP-подсетям.

SSH-туннель

SSH-туннель позволяет подключаться к консоли NanoKVM через интернет. Это удобно для администрирования, обновления прошивки и диагностики.

cat << 'EOF' > /data/tuna/tuna-ssh.sh
#!/bin/sh

# Ждём сеть
while ! ip route | grep -q default; do
    sleep 1
done

exec /data/tuna/tuna \
    --config=/data/tuna/.tuna.yml \
    --log=/tmp/tuna-ssh.log \
    ssh \
    --port=nanokvm-ssh \
    --record-session=false \
    --password-auth=false
EOF
chmod +x /data/tuna/tuna-ssh.sh

Пояснение флагов SSH-туннеля

Флаг	Обязательный	Описание
--port=nanokvm-ssh	Нет	Фиксирует порт SSH-туннеля. Без этого флага порт будет назначаться случайно при каждом запуске. Алиас для порта нужно зарезервировать заранее перед запуском.
--record-session=false	Нет	Отключает запись SSH-сессий на диск. На embedded устройствах с ограниченным хранилищем рекомендуется отключать, чтобы не занимать место.
--password-auth=false	Нет	Запрещает подключение по паролю — доступ только по SSH-ключам (подробнее)

Также можно задать статичный логин и пароль или ограничить доступ по IP-подсетям.

Настройка автозапуска обоих туннелей

Добавьте строки в /etc/inittab:

cat << 'EOF' >> /etc/inittab

# Tuna tunnels (respawn = auto-restart)
tssh::respawn:/data/tuna/tuna-ssh.sh
tweb::respawn:/data/tuna/tuna-http.sh
EOF

Применить без перезагрузки:

kill -HUP 1

Проверка туннелей

Убедитесь, что оба процесса запущены:

ps -ef | grep tuna

В выводе должны быть две строки — с http и ssh. Если какого-то процесса нет — смотрите раздел Диагностика неполадок.

Посмотрите логи:

cat /tmp/tuna-http.log
cat /tmp/tuna-ssh.log

В логах HTTP-туннеля будет URL, а в логах SSH-туннеля — инструкция для подключения с указанием адреса и порта.

---

Управление туннелями

С inittab respawn процесс tuna автоматически перезапускается при падении. Для управления используйте следующие команды:

Проверка статуса

ps -ef | grep tuna

Остановка туннеля

Нельзя просто завершить процесс — init тут же его перезапустит. Сначала закомментируйте строку в /etc/inittab:

# Остановить HTTP-туннель
sed -i 's/^tweb:/#tweb:/' /etc/inittab && kill -HUP 1

# Остановить SSH-туннель
sed -i 's/^tssh:/#tssh:/' /etc/inittab && kill -HUP 1

Запуск туннеля

Раскомментируйте строку обратно:

# Запустить HTTP-туннель
sed -i 's/^#tweb:/tweb:/' /etc/inittab && kill -HUP 1

# Запустить SSH-туннель
sed -i 's/^#tssh:/tssh:/' /etc/inittab && kill -HUP 1

---

Восстановление после перепрошивки

Бинарник и скрипты в /data/tuna/ сохраняются при обновлении приложения через веб-интерфейс и при remote rsync. После полной перепрошивки (Etcher) потребуется заново скопировать бинарник и создать скрипты.

При remote rsync нужно восстановить только строки в /etc/inittab:

cat << 'EOF' >> /etc/inittab

# Tuna tunnels (respawn = auto-restart)
tssh::respawn:/data/tuna/tuna-ssh.sh
tweb::respawn:/data/tuna/tuna-http.sh
EOF
kill -HUP 1

к сведению

Если вы также используете мониторинг доступности, не забудьте восстановить соответствующую строку в /etc/inittab.

---

Дополнительные настройки безопасности

Зачем нужен --basic-auth

У NanoKVM есть собственная авторизация в веб-интерфейсе. Однако, учитывая историю уязвимостей в IoT-устройствах, мы настоятельно рекомендуем добавить дополнительный уровень защиты. При открытии доступа через интернет лучше перестраховаться — флаг --basic-auth добавит стандартную HTTP-авторизацию (логин и пароль в браузере) ещё до того, как запрос дойдёт до NanoKVM.

--basic-auth=mylogin:MyStr0ngP@ss

Важно

Задайте свои логин и пароль. Не используйте значения из примеров.

Аутентификация в SSH-туннеле

Вариант 1. По SSH-ключам (рекомендуется)

Флаг --password-auth=false отключает вход по паролю. Для подключения потребуется предварительно добавить публичный SSH-ключ в личном кабинете.

Подробная инструкция: Настройка SSH-ключей

warning

Туннельные ноды имеют публичный адрес. Злоумышленники могут просканировать порты и начать подбор пароля. Для долгоживущих SSH-туннелей настоятельно рекомендуем отключить парольную аутентификацию.

Вариант 2. Статичный логин и пароль

Если SSH-ключи не подходят, можно задать фиксированные учётные данные:

--auth=user:pass

Замените user и pass на свои значения.

Ограничение по IP-подсетям

Для HTTP и SSH туннелей можно ограничить доступ по IP-адресам.

Разрешить доступ только с определённых подсетей:

--cidr-allow="203.0.113.0/24"

Запретить доступ из определённых подсетей:

--cidr-deny="198.51.100.0/24"

Можно комбинировать — разрешить подсеть, но исключить отдельные адреса:

--cidr-allow="10.0.0.0/24" --cidr-deny="10.0.0.33/32"

Осторожно

Используйте фильтрацию по IP с осторожностью. Если вы ошибётесь с подсетью или ваш IP-адрес изменится — вы потеряете удалённый доступ к NanoKVM. Убедитесь, что у вас есть альтернативный способ управления устройством (например, локальный доступ).

---

Диагностика неполадок

Процесс tuna не запускается

Проверьте, что процесс присутствует в списке:

ps -ef | grep tuna

Если в выводе нет строк с /data/tuna/tuna — убедитесь, что записи в /etc/inittab не закомментированы:

grep tuna /etc/inittab

Строки должны начинаться с tssh:: или tweb::, а не с #. Если они закомментированы — раскомментируйте и перечитайте конфигурацию:

kill -HUP 1

Просмотр логов

Логи туннелей записываются в /tmp/ и доступны до перезагрузки устройства:

# Логи HTTP-туннеля
cat /tmp/tuna-http.log

# Логи SSH-туннеля
cat /tmp/tuna-ssh.log

Для наблюдения за логами в реальном времени:

tail -f /tmp/tuna-http.log

Типичные ошибки в логах

Ошибка	Причина	Решение
token is invalid	Неверный или просроченный токен	Повторите config save-token с актуальным токеном со страницы
Domain already reserved	Поддомен занят другим пользователем	Выберите другое имя через --subdomain=
port alias not found	Алиас порта не зарезервирован	Зарезервируйте алиас в личном кабинете
connection refused	Нет доступа к интернету	Проверьте сеть: ping -c 3 8.8.8.8

Нет доступа к интернету

Проверьте, что NanoKVM имеет сетевое подключение:

# Проверить наличие IP-адреса
ip addr

# Проверить маршрут по умолчанию
ip route

# Проверить доступ в интернет
ping -c 3 8.8.8.8

Логи пропали после перезагрузки

Логи хранятся в /tmp/, который очищается при перезагрузке. Это нормальное поведение. Если нужно сохранять логи между перезагрузками, измените путь в скриптах запуска на /data/tuna/:

--log=/data/tuna/tuna-http.log

warning

На NanoKVM раздел /data — exFAT, частая запись логов может сократить ресурс SD-карты. Используйте это только для временной отладки.

Туннель работал и перестал

1. Проверьте, не обновлялась ли прошивка — после remote rsync нужно восстановить записи в /etc/inittab (см. Восстановление после перепрошивки)
2. Проверьте логи на наличие ошибок
3. Убедитесь, что токен всё ещё действителен в личном кабинете

---

Ссылки

• NanoKVM — официальная документация
• NanoKVM — репозиторий на GitHub
• Обновление NanoKVM
• Перепрошивка NanoKVM
• HTTP-туннель — все флаги
• SSH-туннель — все флаги
• Настройка SSH-ключей
• Запуск tuna как сервис

---

Мониторинг доступности

Помимо туннелей для удалённого доступа, вы можете настроить мониторинг доступности NanoKVM. Heartbeat-мониторинг будет отправлять вам уведомления, если устройство потеряет связь с интернетом или перестанет отвечать.

Полная инструкция: Мониторинг доступности NanoKVM