HowTo Yggdrasil - gemini_protocol

Agate

anonymous@undisclosed.example.com (Anonymous) — Sun, 05 Apr 2026 12:02:13 +0000

Agate

Agate - проверенный временем сервер статики для Gemini, написанный на языке Rust. В отличии от gmid, в виду особенностей реализации rustls (и ограничений RFC 6066 в частности) не имел поддержки «сырых» адресов IPv6 и требовал наличия Alfis DNS или meshname.

С недавних пор, в рамках PR#433 появилась экспериментальная ветка, которая реализует fallback SNI: то есть, позволяет указывать общий сертификат-заглушку, применимую для меш-сетей, например Yggdrasil и/или Mycelium. Ниже рассмотрен пример её установки и использования.

Установка

Изменения частично приняты в master. Сборка с форка - имеет свои отличия реализации, но в целом обе версии должны работать одинаково.

git clone https://github.com/YGGverse/agate.git
cd agate
git checkout fallback-sni
cargo build --release
sudo install target/release/agate /usr/local/bin

Сервер Agate имеет ряд особенностей при работе в мульти-хост режиме. Наиболее простой вариант запуска для наших целей - автоматическое создание в первую очередь сертификатов для хостов .ygg, .i2p и т.д., если предусмотрено их использование. Для этого, сначала следует выполнить инициальный запуск с терминала, указав аргумент(ы) --hostname:

agate --addr [::1]:1965 --hostname domain.ygg --hostname domain.i2p --certs /path/to/.certificates

Один из сертификатов копируем в корень /path/to/.certificates - он будет использоваться по-умолчанию. Запись CN (Canonical Name) в данном случае не имеет значения, т.к. наиболее популярный браузер Lagrange это поддерживает (пример тому - сертификат BBS); также можно создать сертификат вручную, указав IPv6 в качестве значения.

Далее создадим сервис, в котором из Exec убираем --hostname и указываем бинд на реальные интерфейсы. В данном примере, используются сети Yggdrasil и Mycelium, но может быть и общий «::»

/etc/systemd/system/agate.service

[Unit]
After=network-online.target
Wants=network-online.target

[Service]
Type=simple

User=agate
Group=agate

WorkingDirectory=/home/agate
ExecStart=/usr/local/bin/agate --content /home/agate/public \
                               --certs /path/to/.certificates \
                               --addr [202:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx]:1965 \
                               --addr [505:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx]:1965

StandardOutput=file:///home/agate/debug.log
StandardError=file:///home/agate/error.log

[Install]
WantedBy=multi-user.target

Таким образом, сервис будет доступен на адресах:

gemini://[202:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx]
gemini://[505:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx]
gemini://domain.ygg
gemini://domain.i2p
и так далее…

β-Doku

anonymous@undisclosed.example.com (Anonymous) — Wed, 22 Oct 2025 08:13:17 +0000

β-Doku

Проект с открытым кодом для организации зеркала DokuWiki для протокола Gemini.

Написан на языке PHP 8, в качестве основы использует:

gemini-php - для конвертации базы данных и безопасной работы с файловой системой
titan-II - форк сервера с поддержкой IPv6
cache-php - оболочка для кеширования скомпилированных страниц посредством Memcached
manticore - для полнотекстового поиска

Установка

Проект находится в процессе разработки, актуальная инструкция доступна в README

Синхронизация

Ресурс «betahowto» для всех инстансов использует автоматический дамп в качестве источника.

Также, по совместительству отправляет историю правок в репозиторий howto-db, откуда можно также получить актуальную версию базы данных:

git clone http://[316:c51a:62a3:8b9::4]/YGGverse/howto-db.git

* при использовании базы из репозитория, следует учитывать наличие директории .git в корне (в прочем, корневая директория не используется, а скрытые файлы игнорируются индексатором gemini-php)

Обновление осуществляется скриптом по расписанию crontab, где общая директория «data» расположена в корне «howto-db» (на которую ведут символические ссылки всех хостов):

/home/bdoku/crontab/update.sh

cd /home/bdoku

wget http://[222:a8e4:50cd:55c:788e:b0a5:4e2f:a92c]/howto-wiki_$(date -d "$date -1 days" +"%F")-23-30.tar.gz
tar -xvf howto-wiki_$(date -d "$date -1 days" +"%F")-23-30.tar.gz -C howto-db
rm howto-wiki_$(date -d "$date -1 days" +"%F")-23-30.tar.gz

Обновление β-Doku:

/home/bdoku/crontab/update.sh

cd /home/bdoku/bdoku

git pull
composer update

Если администрируется контрольный репозиторий:

/home/bdoku/crontab/update.sh

cd /home/bdoku/howto-db

git add .
git commit -m "$(date -d "$date -1 days" +"%F")-23-30"
git push

От пользователя bdoku:

crontab -e

0 0 * * * /home/bdoku/crontab/update.sh >> /home/bdoku/crontab/log/update-`/bin/date +\%F`.log 2>&1

От пользователя root:

crontab -e

5 0 * * * service betahowto restart
5 0 * * * service betahowto.ygg restart
5 0 * * * service betahowto.duckdns.org restart

Для синхронизации важно правильно установить часовой пояс, например GMT:

unlink /etc/localtime
ln -s /usr/share/zoneinfo/GMT /etc/localtime
date

Ссылки

β-Doku на GitHub
howtools - скрипты авто-обновлений

Gmid

anonymous@undisclosed.example.com (Anonymous) — Wed, 22 Oct 2025 08:13:17 +0000

Gmid

Многофункциональный сервер для протокола Gemini, с поддержкой виртуальных хостов и реверсивного проксирования.

Установка

Кроме типичных пакетов для сборки программ с make, потребуется также:

apt install bison byacc

Как и в большинстве случаев, удобным будет создать отдельного пользователя:

useradd -m gmid

Логинимся и забираем последнюю версию из репозитория (есть зеркало на GitHub) и осуществляем сборку командами:

git clone https://github.com/omar-polo/gmid.git
cd gmid
./configure
make

Проксирование

Для сертификатов виртуальных хостов можно создать отдельные директории, там же можно расположить конфигурации.

Можно создать общий файл конфигурации для запуска в рамках одного юнита / процесса.

Пример проксирования общего IPv4 Clearnet на два IPv6 Yggdrasil:

/home/gmid/gmid.conf

server "betahowto.duckdns.org" {

	listen on 94.140.114.89 port 1965
	
	cert "/home/gmid/host/betahowto.duckdns.org/cert.pem"
	key "/home/gmid/host/betahowto.duckdns.org/key.rsa"

	proxy {
		sni "betahowto.duckdns.org"
		relay-to 301:5eb5:f061:678e::b port 1965
		verifyname off
	}
}

server "kevachat.duckdns.org" {

	listen on 94.140.114.89 port 1965
	
	cert "/home/gmid/host/kevachat.duckdns.org/cert.pem"
	key "/home/gmid/host/kevachat.duckdns.org/key.rsa"

	proxy {
		sni "kevachat.duckdns.org"
		relay-to 201:23b4:991a:634d:8359:4521:5576:15b7 port 1965
		verifyname off
	}
}

Юнит в этом случае будет таким:

/etc/systemd/system/gmid.service

[Unit]
Description=gmid
After=network.target

[Service]
Type=simple
User=gmid
Group=gmid
WorkingDirectory=/home/gmid/
ExecStart=/home/gmid/gmid/gmid -c /home/gmid/gmid.conf -f -v
StandardOutput=file:/home/gmid/output.log
StandardError=file:/home/gmid/debug.log
Restart=on-failure

[Install]
WantedBy=multi-user.target

-f указывает на «foreground», иначе процесс будет стартовать в фоновом режиме
-v verbose, отладка

Проверить работу сервера можно выполнив от пользователя gmid:

netstat -tulpn | grep LISTEN

Ссылки

Домашняя страница

Nex (протокол)

anonymous@undisclosed.example.com (Anonymous) — Sun, 12 Apr 2026 14:19:23 +0000

Nex (протокол)

Минималистичный сетевой протокол семейства Gopher / Gemini для обмена преимущественно текстовыми файлами.

От последнего отличается отсутствием:

внешних и внутренних редиректов
статус-кодов и других заголовков - MIME тип документа определяется расширением файла (по-умолчанию text/plain)
разметки, за исключением кликабельных ссылок, в формате => url/uri [alt]
обязательной сертификации TLS, следовательно - привязки к домену посредством CN/SNI, что выгодно при использовании классической адресации 0200::/7 в Yggdrasil, где передаваемый трафик уже зашифрован а DNS - зачастую не используется

Спецификация

NEX

Сервер принимает подключения посредством TCP на порту 1900 и в зависимости от наличия слеша в конце пути запроса, возвращает либо директорию либо текстовый или бинарный файл.

Пример запроса:

telnet nightfall.city 1900
nex

Подробнее:

nex://nightfall.city/nex/info/specification.txt

NPS

Протокол отправки данных по типу Titan для Gemini, по-умолчанию используется порт 1915.

Целостность отправляемого пакета обеспечивается точкой в последней строке сообщения, после чего пакет считается отправленным и соединение с сервером прекращается.
Формат взаимодействия с сервером может отличаться, обычно документация прилагается отдельно взятым ресурсом, но в целом принцип следующий

Пример запроса:

nc nightfall.city 1915
classifieds
YOUR MESSAGE GOES HERE
.

где строки:

установка соединения посредством синтаксиса netcat
целевой ресурс на сервере - в данном случае, аргумент указывает URI classifieds
тело сообщения, можно указать несколько строк
единственная точка в новой строке - завершает отправку, в содержимое сообщения данным сервером не добавляется

Текст из файла

file.txt

classifieds
╦ ╦╔═╗╔═╗╔╦╗╦═╗╔═╗╔═╗╦╦  
╚╦╝║ ╦║ ╦ ║║╠╦╝╠═╣╚═╗║║  
 ╩ ╚═╝╚═╝═╩╝╩╚═╩ ╩╚═╝╩╩═╝
.

cat file.txt | nc nightfall.city 1915

Посмотреть отправленное сообщение можно по адресу:

nex://nightfall.city/classifieds/

Также появился внутрисетевой сервер отправки сообщений KevaChat, работает подобным образом:

nc 201:23b4:991a:634d:8359:4521:5576:15b7 1915

В некоторых дистрибутивах для поддержки IPv6 в nc может потребоваться установка пакета netcat-openbsd
IPv6 также поддерживается утилитами telnet и ncat (вместо nc), ncat лучше работает с кириллицей
Для работы с кириллицей в терминале (на что собственно и ориентирован протокол), важно также убедиться в наличии поддержки окружением кодировки ввода UTF-8 (установить можно командой stty iutf8 в ~/.bashrc)

Спецификация:

nex://nightfall.city/nps/info/specification.txt

Программное обеспечение

Клиент

GUI

Lagrange (C) - браузер для различных smallnet протоколов, включая nex

CLI

gelim (Go)
pynex (Python)

Сервер

nexd - очень простой сервер на Go для публикации статики на 1900 порту, по-умолчанию открывает файлы с названием «index» (репозиторий mercurial)
- форк сервера nexd - включает пакет nex-pfm и модифицированный для Linux / amd64 makefile
next - сервер на PHP с множеством настроек
kinex - проксирующий сервер на Go для публикации статики на 8080 порту, также добавляет разметку HTML
nexy (Rust) - сервер для публикации статики с гибкими настройками и расширенной поддержкой кириллицы в названиях файлов (v0.6+)

Библиотеки

nex-php, nps-php - PHP 8 / Composer библиотеки для разработки веб-приложений
Ratchet - универсальная библиотека PHP 8 / Composer для разработки асинхронных серверов

Проксирование

В виду простоты протокола, передаваемые данные легко проксируются любым сервером, поддерживающим маршрутизацию потоков TCP, например Nginx.

Внутрисетевые ресурсы

nex://[202:68d0:f0d5:b88d:1d1a:555e:2f6b:3148]/ - сервер YGGverse

Ссылки

https://nightfall.city (nex://nightfall.city) - домашняя страница - документация, полезные ссылки и ресурсы сообщества
https://hg.sr.ht/~m15o/ - тематические проекты с открытым кодом
Справочный материал по вариантам netcat (en)
Сравнение протоколов gemini, spartan, scroll, nex

Twins

anonymous@undisclosed.example.com (Anonymous) — Wed, 22 Oct 2025 08:13:17 +0000

Twins

При использовании в качестве прокси, данный сервер «срезает» часть контента (#18)

Решение не найдено, если требуется реверсивное проксирование, то лучше сразу использовать сервер gmid

Многозадачный сервер для протокола Gemini с поддержкой кеширования, реверсивного проксирования и других функций. Написанный на языке Go.

Установка

go install code.rocketnine.space/tslocum/twins@latest

Пример маршрутизации общего IPv4 адреса доменов first.host.org и second.host.org на разные ресурсы Yggdrasil:

/home/twins/config.yaml

listen: "xx.xx.xx.xx:1965"
hosts:
  first.host.org:
    cert: /home/twins/first.host.org/cert.pem
    key: /home/twins/first.host.org/key.rsa
    paths:
      -
        path: /
        proxy: gemini-insecure://[xxx:xxxx:xxxx:xxxx::xxxx]:1965
  second.host.org:
    cert: /home/twins/second.host.org/cert.pem
    key: /home/twins/second.host.org/key.rsa
    paths:
      -
        path: /
        proxy: gemini-insecure://[xxx:xxxx:xxxx:xxxx::xxxx]:1966

По такому же принципу можно запустить службы на свободных локальных адресах IPv4 или использовать разный порт для каждого сервера.
На целевых (публичных) ресурсах Yggdrasil вместо разных портов, достаточно настроить Адрес из подсети 300::/64.

Сертификаты в данном примере должны быть сконфигурированы на соответствующий домен, например для first.host.org:

openssl req -x509 -newkey rsa:4096 -keyout key.rsa -out cert.pem -days 365 -nodes -subj "/CN=first.host.org"

* если запись для IPv6 - квадратные скобки в CN не используются

Для запуска указываем путь к бинарному файлу twins и вторым аргументом - путь к файлу конфигурации:

/home/twins/go/bin/twins -config /home/twins/config.yaml

Можно создать сервис:

/etc/systemd/system/twins.service

[Unit]
Description=twins
After=network.target

[Service]
Type=simple
User=twins
Group=twins
WorkingDirectory=/home/twins/
ExecStart=/home/twins/go/bin/twins -config /home/twins/config.yaml
StandardOutput=file:/home/twins/debug.log
StandardError=file:/home/twins/error.log
Restart=on-failure

[Install]
WantedBy=multi-user.target

А также добавить автозапуск:

systemctl daemon-reload
systemctl enable twins
systemctl start twins

Заметки

У сервера twins иногда бывают проблемы с кодировкой кириллических ресурсов, поэтому целевые хосты должны отдавать кодировку в заголовке:

text/gemini; charset=utf-8

Как указано в readme, важно также указать размер контента (size)

Чтобы отключить проверку сертификата, можно использовать псевдо-протокол gemini-insecure://

Ссылки

Домашняя страница проекта