bitmessage/README.ru-RU.md at 68eb019e59485045d557d8b3f589f0f9f1889f62

private/bitmessage

Fork 0

Files

T

bitdeals 68eb019e59

Build docker image and push to registry.bitdeals.org / main-build-job (push) Successful in 2m21s

Details

refactor: no root in this container at all

The chown at startup was the only thing that ever needed root here, and it
served a case this project does not have: keys.dat arriving from a bind mount
owned by somebody else. Every deployment uses a named volume, which takes its
ownership from the image. So the chown goes, and everything that existed to
survive it goes with it.

USER bitmessage in the Dockerfile, from PID 1 onwards. drop_privs.py is
deleted, the supervisor no longer re-executes itself with a trimmed bounding
set, run.sh has no privileged prologue and no wrapper around the eight
commands that used to run through one. What is left of run.sh differs from
the version before any of this by eleven lines: two chowns gone, seven `gosu
bitmessage` prefixes gone, one comment reworded.

keys.dat gets its mode 600 at build time instead of on every start, because
on every start there is now no root to set it. Its mode and ownership reach a
fresh volume from the image, and every volume in service already carries them
-- checked on all four live nodes: nothing under /home/bitmessage is owned by
anyone but 2000.

The setuid strip stays. It is two lines and it closes the one way a taken-over
daemon could still have climbed.

What the caller sets changes too, and in the right direction: `cap_drop: ALL`
with nothing added back, where the previous commit needed seven capabilities
handed in. Confinement that used to be split between the image and the caller
now sits in one place. The image gives up defending itself when run with no
options at all, which is the trade named in the README along with the bind
mount it costs.

2026-09-09 13:23:28 +00:00

182 lines

17 KiB

Markdown

Raw Blame History

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

 # Общие сведения
 > English version: [README.md](README.md)
 [PyBitmessage](https://bitmessage.org/) — клиент P2P-протокола обмена сообщениями Bitmessage, служащий для отправки шифрованных сообщений как одному адресату, так и множеству подписчиков.
 Клиент PyBitmessage, работающий демоном в docker-контейнере с включённым XML-RPC API.
 Репозиторий описывает только развёртывание в docker.
 # Использование
 Контейнер создаёт детерминированные адреса Bitmessage на основе переменной `BITMESSAGE_SEED_PHRASE`.
 Ниже — примеры, с которых удобно начать создание контейнера.
 У контейнера два порта, и они не взаимозаменяемы. **8442** — XML-RPC API: он
 полностью управляет демоном и не имеет TLS, поэтому задайте свои учётные данные
 и оставьте его на loopback. **8444** — P2P-порт Bitmessage: опубликуйте его,
 чтобы к узлу могли подключаться другие, или не публикуйте, и тогда узел работает
 только на исходящих. Внутри контейнера демон слушает оба в любом случае.
 ## docker-compose
 ```yaml
 services:
   pybitmessage:
     build:
       context: https://git.bitdeals.org/private/bitmessage.git
       dockerfile: ./docker/Dockerfile
     image: registry.bitdeals.org/bitmessage
     environment:
       - BITMESSAGE_API_USER=CHANGE_ME
       - BITMESSAGE_API_PASSWORD=CHANGE_ME
       - BITMESSAGE_SEED_PHRASE=bitmessage_seed_phrase
       - BITMESSAGE_SEED_ADDRESSES=1
       - BITMESSAGE_TTL=172800
       - BITMESSAGE_STOPRESENDINGAFTERXDAYS=60
       - BITMESSAGE_MAXTOTALCONNECTIONS=40
     ports:
       - 127.0.0.1:8442:8442   # API — только loopback
       - 8444:8444             # P2P — уберите строку, чтобы остаться на исходящих
     volumes:
       - bitmessage:/home/bitmessage
 volumes:
   bitmessage:
 ```
 ## docker cli
 ```sh
 docker run -d \
   -e BITMESSAGE_API_USER=CHANGE_ME \
   -e BITMESSAGE_API_PASSWORD=CHANGE_ME \
   -e BITMESSAGE_SEED_PHRASE=bitmessage_seed_phrase \
   -e BITMESSAGE_SEED_ADDRESSES=1 \
   -e BITMESSAGE_TTL=172800 \
   -e BITMESSAGE_STOPRESENDINGAFTERXDAYS=60 \
   -e BITMESSAGE_MAXTOTALCONNECTIONS=40 \
   -p 127.0.0.1:8442:8442 \
   -p 8444:8444 \
   -v bitmessage:/home/bitmessage \
   registry.bitdeals.org/bitmessage
 ```
 # Параметры
 Образы контейнера настраиваются параметрами, передаваемыми при запуске.
 |Параметр|Назначение|
 |:--------|:-------|
 |-p 127.0.0.1:8442|Порт API. Внутри контейнера демон всегда слушает `0.0.0.0`, поэтому доступность определяет то, что опубликовано|
 |-p 8444|P2P-порт Bitmessage. Необязательный: без него узел всё равно подключается к пирам сам, просто к нему подключиться нельзя. Публиковать только как `8444:8444` — см. «Замечания»|
 |-v /home/bitmessage|Каталог данных: `keys.dat` (личность, настройки) и `messages.dat`. Без него после каждого обновления это новый узел|
 |-e BITMESSAGE_API_USER|Пользователь XML-RPC API. По умолчанию: `bitmessage_api_user` — измените|
 |-e BITMESSAGE_API_PASSWORD|Пароль XML-RPC API. По умолчанию: `bitmessage_api_password` — измените, см. «Замечания»|
 |-e BITMESSAGE_SEED_PHRASE|Парольная фраза для создания детерминированных адресов. По умолчанию: генерируется заново при каждом старте, то есть адреса каждый раз другие. Используется только при `BITMESSAGE_SEED_ADDRESSES` больше `0`|
 |-e BITMESSAGE_SEED_ADDRESSES|Количество создаваемых детерминированных адресов. По умолчанию: `0`|
 |-e BITMESSAGE_TTL|Срок жизни вновь отправляемых сообщений, в секундах. По умолчанию: `172800`|
 |-e BITMESSAGE_STOPRESENDINGAFTERXDAYS|Прекратить повторную отправку недоставленного сообщения через X дней. По умолчанию: `30`|
 |-e BITMESSAGE_APIVARIANT|Предоставляемый API: xml или json-RPC. По умолчанию: `legacy`|
 |-e BITMESSAGE_MAXTOTALCONNECTIONS|Предел одновременных соединений, входящих и исходящих вместе (`maxoutboundconnections` равен 8, то есть это значение минус 8 — запас на входящие). По умолчанию: `200`, штатное значение PyBitmessage — снижайте, если P2P-порт опубликован|
 |-e BITMESSAGE_TRUSTED_PEER|`host:port` единственного пира, к которому узел подключается наружу; больше ни к кому. По умолчанию: пусто — узел выбирает пиров сам. См. «Замечания»|
 |-e BITMESSAGE_SEND_OUTGOING|Подключается ли узел наружу вообще: `True` или `False`. По умолчанию: `True`. При `False` получается узел, который только принимает входящие, — центр приватного контура|
 |-e BITMESSAGE_KNOWN_NODES|Список `host:port` через запятую; записывается в `knownnodes.dat` при каждом старте вместо того, что там было. По умолчанию: пусто — файл не трогается. Заодно выключает бутстрап по DNS, см. «Замечания»|
 |-e BITMESSAGE_WATCHDOG|Перезапускать ли демона, потерявшего всех пиров: `True` или `False`. По умолчанию: `True`. См. «Замечания»|
 |-e BITMESSAGE_WATCHDOG_PERIOD|Секунд между проверками числа пиров. По умолчанию: `60`|
 |-e BITMESSAGE_WATCHDOG_AFTER|Сколько проверок подряд без пиров нужно, чтобы вмешаться. По умолчанию: `5` — то есть пять минут при периоде по умолчанию|
 |-e BITMESSAGE_WATCHDOG_COOLDOWN|Минимальный промежуток между двумя перезапусками, в секундах. По умолчанию: `900`. `0` снимает ограничение|
 # Замечания
 - `%` в пароле API использовать нельзя: он ломает собственный чтец конфигурации
   PyBitmessage, и любой вызов API отвечает `500`, притом что `keys.dat`
   выглядит правильным. Остальные символы допустимы, контейнер их экранирует.
 - Клиенты обязаны кодировать учётные данные — они попадают в
   `http://user:password@host:port/`, где `@`, `#`, `/` и `:` меняют разбор URL.
   Скрипты этого образа кодируют, ваш клиент должен тоже.
 - Контейнер становится здоровым, когда у демона появилось сетевое соединение,
   — на новом узле это несколько минут. Начальный период ожидания заодно
   покрывает стартовый `VACUUM` файла `messages.dat`.
 - **Демона без пиров перезапускаем, молчащего — нет.** Демон, потерявший всех
   пиров, сам обратно дорогу не находит: он может простоять на нуле соединений
   сколько угодно, — а только что запущенный ищет пиров напористо и находит.
   Поэтому контейнер присматривает за собственным демоном: раз в
   `BITMESSAGE_WATCHDOG_PERIOD` спрашивает у API число соединений и после
   `BITMESSAGE_WATCHDOG_AFTER` нулей подряд останавливает демона через его же API
   и поднимает заново. *Контейнер* при этом не пересоздаётся и никто снаружи не
   участвует, так что соседний узел сохраняет адреса и видит лишь моргнувший API.
   Демона, у которого API не отвечает вовсе, сторож не трогает намеренно. Это
   узел, застрявший на стартовом `VACUUM`, которого он не может закончить;
   перезапуск его не лечит, а лишь обрывает следующий `VACUUM` на середине.
   Проверка здоровья показывает `unhealthy` в обоих случаях, но вмешиваться стоит
   только в первый, а во втором нужен человек.
   **Задайте контейнеру `stop_grace_period: 90s`** (compose) или
   `--stop-timeout 90` (`docker run`). Корректное закрытие `messages.dat` не
   укладывается в десять секунд, отпущенные Docker по умолчанию, — замерено около
   тринадцати на небольшой базе, и растёт вместе с файлом, — так что без этого
   демона убьёт SIGKILL на середине записи, ровно то, ради предотвращения чего
   супервизор и заведён. Сам образ это задать не может, только вызывающая сторона.
   `BITMESSAGE_WATCHDOG=False` выключает правило о пирах. Супервизор остаётся в
   любом случае: он же корректно останавливает демона по `docker stop` и
   поднимает того, кто умер сам, вместо контейнера, стоящего вокруг трупа.
 - **P2P-порт публикуется только как `8444:8444`.** Пирам демон сообщает порт из
   собственной конфигурации (`port` в `keys.dat`), а не тот, в который вы его
   отобразили, поэтому `8555:8444` объявляет сети порт, где никого нет. Для
   другого порта на хосте нужен `extport` в `keys.dat`, а его этот контейнер не
   подставляет.
 - **Свой адрес нигде не указывается.** В version-сообщении демон шлёт
   захардкоженный `127.0.0.1`, который каждый пир отбрасывает и берёт вместо него
   IP, увиденный на сокете, а порт — из того же сообщения. Поэтому узел с
   опубликованным 8444 сеть находит сама, как только он подключится наружу:
   ни IP, ни DNS-имя хоста задавать негде. Единственное исключение — скрытый
   сервис Tor, которому нужен явный `onionhostname`.
 - **Приватному контуру нужны назначенные пиры и звезда, в которую их назначать.**
   PyBitmessage отвергает кандидата, чья сетевая группа (для IPv4 — /16) уже
   представлена среди его исходящих соединений. Все контейнеры одного
   compose-проекта живут в одной /16, поэтому каждый узел удерживает ровно одно
   исходящее соединение — со случайно выбранным пиром, и контур чаще всего
   распадается на компоненты. Задайте одному узлу
   `BITMESSAGE_SEND_OUTGOING=False`, и он станет хабом, который только принимает
   (проверка смотрит лишь на исходящие, входящие она не ограничивает), остальные
   направьте на него через `BITMESSAGE_TRUSTED_PEER=<ip-хаба>:8444` — объекты
   пойдут спица → хаб → спицы. Адреса задавайте IP, а не именами сервисов:
   проверка разбирает хост как IP, да и обмен `addr` между узлами оперирует IP.
 - **`BITMESSAGE_KNOWN_NODES` — то, что делает приватный контур приватным.** Узел,
   у которого в `knownnodes.dat` есть пир не из встроенного списка PyBitmessage,
   перестаёт спрашивать адреса у `bootstrap8080.bitmessage.org`; без этого даже
   узел с назначенным пиром при каждом старте резолвит публичный бутстрап-хост.
   Файл переписывается на каждом старте, поэтому во что узел верит при загрузке,
   определяет переменная, а не история контейнера.
 - **Публикация 8444 — осознанный компромисс по безопасности.** Демон работает на
   Python 2 и уже разбирает недоверенные данные от своих исходящих пиров, так что
   открытый порт эту поверхность не создаёт — он меняет то, *кто* может
   подключиться, *когда* и *сколько их*. Разбор до рукопожатия становится доступен
   кому угодно, а реальный риск — исчерпание ресурсов, а не выполнение кода.
   Держите `BITMESSAGE_MAXTOTALCONNECTIONS` низким и ограничьте контейнер по
   памяти и CPU.
 - **Root'а в этом контейнере нет.** Он стартует под uid 2000 и остаётся под ним,
   включая PID 1: `run.sh` работает только с файлами этого пользователя, а два,
   которые заводит сам демон — `knownnodes.dat` и `messages.dat`, — он заводит в
   своём домашнем каталоге. Ничего не понижается на старте, потому что повышенных
   прав изначально нет. Ни на одном файле образа нет бита setuid или setgid, так
   что захваченному демону не по чему подниматься.
   Плата за это — bind-монтирование. Каталог `/home/bitmessage`, приехавший с
   хоста, должен принадлежать uid 2000: сменить владельца на входе контейнер
   больше не может. Именованный том, ради которого образ и сделан, наследует
   владельца и режимы от образа, и делать с ним ничего не надо.
   Три вещи может задать только вызывающая сторона, и все три стоит задать.
   `cap_drop: ALL`, ничего не возвращая: образу не нужна ни одна capability, и
   этот же набор получают healthcheck и `docker exec`, а сузить его сам контейнер
   не может. `read_only: true` с `tmpfs` под `/tmp` и `/run`: демон пишет только в
   свой домашний каталог. И `pids_limit` — рядом с ограничениями по памяти и CPU,
   о которых просит предыдущее замечание. Заодно `no-new-privileges:true`: без
   единого setuid-файла в образе кусать ему почти нечего, но и стоит он ничего.

182 lines 17 KiB Markdown Raw Blame History Unescape Escape

182 lines

17 KiB

Markdown

Raw Blame History