Справочник конфига

Верхний уровень

Ключ	Тип	По умолчанию	Значение
version	целое	—	Версия формата конфига. Сейчас 1. Конфиг с большей версией отвергается, а не читается наугад.
settings	словарь	см. ниже	Куда писать, куда бэкапить, что сбрасывать.
include	список строк	["zones/*.yaml", "zones/*.hosts"]	Шаблоны файлов-зон относительно каталога конфига. Без ключа берутся значения по умолчанию; пустой список не подключает ничего.
groups	список групп	[]	Группы, лежащие в основном конфиге. Группы из зон сюда не пишутся.

settings

Ключ	Тип	По умолчанию	Значение
target	путь	/etc/hosts, либо $HOSTSCTL_TARGET, если ключа нет	Файл, в который рендерится управляемый блок. --target перебивает его на один запуск. $HOSTSCTL_TARGET только подставляет значение по умолчанию, поэтому на выписанный ключ он уже не влияет — а hostsctl init его выписывает.
backup_dir	путь	/var/db/hostsctl/backups (macOS), /var/lib/hostsctl/backups (Linux)	Куда пишутся снимки.
keep_backups	целое	20	Сколько снимков хранить. 0 отключает чистку.
flush_dns	булево	true	Сбрасывать DNS-кеш после успешной записи. Попытка делается только если цель — настоящий /etc/hosts.

Группа

Ключ	Тип	По умолчанию	Значение
name	строка	—	Уникально по всем файлам, сравнение без учёта регистра.
enabled	булево	true	Выключенная группа сохраняет записи и не рендерится.
description	строка	—	Рендерится шапкой группы внутри блока.
entries	список записей	[]	Локальные записи. На практике взаимоисключающи с source.
source	словарь	—	Удалённый блоклист, см. ниже. Записи такой группы берутся из кеша, а не из entries.

Запись

Ключ	Тип	По умолчанию	Значение
ip	строка или список строк	—	Один или несколько адресов. Единственный адрес пишется обратно скаляром.
hostnames	список строк	—	Одно или несколько имён. Каждый адрес получает строку со всем набором.
enabled	булево	true	Выключенная запись остаётся в конфиге и не рендерится.
comment	строка	—	Дописывается к строке после #.

- ip: 10.0.0.7
  hostnames: [api.local, web.local]
  enabled: true
  comment: staging box

Источник

Ключ	Тип	По умолчанию	Значение
url	строка	—	http:// или https://. Обычный HTTP принимается, но с предупреждением: список можно подменить по дороге.
rewrite_ip	строка	—	Заменяет адрес у всех записей списка. Обычно 0.0.0.0.
allow	список строк	[]	Имена, выбрасываемые из скачанного списка.
last_fetch	строка	—	Пишется hostsctl после успешного обновления. Информационное поле.

Файлы-зоны

.yaml-зона принимается в трёх формах:

# 1. обёрнутая
groups:
  - name: work
    entries: []

# 2. голый список
- name: work
  entries: []

# 3. одна группа, имя из имени файла
description: Work stands
entries:
  - ip: 10.0.0.7
    hostnames: [stand.local]

Неизвестный ключ в третьей форме — ошибка, а не молча пустой файл: group: вместо groups: стоит ловить.

.hosts-зона — обычный hosts-синтаксис ровно с одной группой. Имя берётся из имени файла без ведущих цифр, дефисов и подчёркиваний (10-local.hosts → local). Строка # hostsctl: disabled в шапке помечает группу выключенной — единственное, что этот формат иначе выразить не может.

Переменные окружения

Переменная	Что делает
HOSTSCTL_CONFIG	Путь к конфигу; сильнее $XDG_CONFIG_HOME и ~/.config.
HOSTSCTL_CACHE	Каталог кеша блоклистов.
HOSTSCTL_TARGET	Целевой файл для конфига, в котором он не указан. Конфиг от hostsctl init его указывает, так что переменная полезна в основном для урезанного вручную конфига.
XDG_CONFIG_HOME, XDG_CACHE_HOME	Учитываются, кроме запуска под sudo, где указывают на окружение root.
VISUAL, EDITOR	Используются hostsctl edit в этом порядке, иначе vi.
NO_COLOR, TERM=dumb	Отключают цвет. Цвета нет и когда stdout не tty.