Правила

Экосистема Caddy придерживается нескольких правил, чтобы обеспечить согласованность и интуитивность работы на всей платформе.

• Сетевые адреса
• Заменители
• Расположение файлов
  • Директория данных
  • Директория конфигурации
• Длительности

Сетевые адреса

При указании сетевого адреса для подключения или привязки Caddy принимает строку в следующем формате:

network/address

Часть сети является необязательной (по умолчанию tcp), и представляет собой все, что распознает функция Go's net.Dial. Если сеть указана, одиночный слеш / должен отделять части сети и адреса.

Сеть может быть любой из следующих; те, что оканчиваются на 4 или 6, соответственно, поддерживают только IPv4 или IPv6:

• TCP: tcp, tcp4, tcp6
• UDP: udp, udp4, udp6
• IP: ip, ip4, ip6
• Unix: unix, unixgram, unixpacket

Часть адреса может иметь любой из этих форматов:

• host
• host:port
• :port
• [ipv6%zone]:port
• /path/to/unix/socket
• /path/to/unix/socket|0200

Хост может быть любым именем хоста, разрешаемым доменным именем или IP-адресом.

В случае IPv6-адресов адрес должен быть заключён в квадратные скобки []. Идентификатор зоны (начинающийся с %) является необязательным (часто используется для адресов link-local).

Порт может быть одиночным значением (:8080) или диапазоном (:8080-8085). Диапазон портов будет преобразован в отдельные адреса. Не все поля конфигурации принимают диапазоны портов. Специальный порт :0 означает любой доступный порт.

Путь unix-соккета допустим только при использовании типа сети unix*. Слэш, разделяющий сеть и адрес, не считается частью пути.

При использовании unix-соккета в качестве адреса привязки можно необязательно указать режим разрешений файла после пути, разделив их символом pipe |. По умолчанию используется 0200 (восьмеричный), т.е. u=w,g=,o= (символьный). Ведущий 0 является необязательным.

Применимые примеры:

:8080
127.0.0.1:8080
localhost:8080
localhost:8080-8085
tcp/localhost:8080
tcp/localhost:8080-8085
udp/localhost:9005
[::1]:8080
tcp6/[fe80::1%eth0]:8080
unix//path/to/socket
unix//path/to/socket|0200

Заменители

Конфигурация Caddy поддерживает использование заменителей. Использование замен — простой способ внедрения динамических значений в статическую конфигурацию.

Заменители ограничены с обеих сторон фигурными скобками { } и содержат идентификатор внутри, например: {foo.bar}. Открывающая скобка замены может быть экранирована \{like.this}, чтобы предотвратить замену. Идентификаторы замен обычно имеют пространство имён с точками, чтобы избежать конфликтов между модулями.

Доступные заменители зависят от контекста. Не все заменители доступны во всех частях конфигурации. Например, приложение HTTP задаёт заменители, которые доступны только в областях конфигурации, связанных с обработкой HTTP-запросов.

Следующие заменители всегда доступны (глобальные):

Не все поля конфигурации поддерживают заменители, но большинство поддерживают их там, где ожидается. Поддержка заменителей должна быть явно добавлена в эти поля. Разработчики плагинов могут прочитать эту статью, чтобы узнать, как добавить поддержку замен в свои модули.

Расположение файлов

Этот раздел содержит информацию о расположении различных файлов. Пути к файлам и каталогам, описанные здесь, являются в лучшем случае значениями по умолчанию; некоторые из них могут быть переопределены.

Ваши файлы конфигурации

Нет единого, стандартного места для размещения файлов конфигурации.

Дистрибутивы, поставляемые с файлом конфигурации по умолчанию, должны документировать расположение этого файла, даже если это очевидно для разработчиков пакета/дистрибутива. В большинстве систем Linux файл Caddyfile будет находиться в /etc/caddy/Caddyfile.

Директория данных

Caddy хранит сертификаты TLS и другие важные ресурсы в каталоге данных, который поддерживается модулем хранения, настроенным в XDG_DATA_HOME (по умолчанию: локальная файловая система).

Если переменная среды XDG_DATA_HOME установлена, она $XDG_DATA_HOME/caddy.

В противном случае её путь зависит от платформы и соответствует соглашениям ОС:

Все остальные ОС используют путь каталога Linux/BSD.

Каталог данных не должен рассматриваться как кеш. Его содержимое не является временным или предназначено только для повышения производительности. Caddy хранит сертификаты TLS, приватные ключи, OCSP-стаплеры и другую необходимую информацию в каталоге данных. Его не следует очищать без понимания последствий.

Этот каталог должен быть постоянным и доступным для записи Caddy.

Директория конфигурации

Здесь Caddy может хранить определённую конфигурацию на диске. В частности, он сохраняет последнюю активную конфигурацию (по умолчанию) в эту папку для удобства возобновления работы позже с помощью caddy run --resume.

Если переменная среды XDG_CONFIG_HOME установлена, она $XDG_CONFIG_HOME/caddy.

В противном случае её путь зависит от платформы и соответствует соглашениям ОС:

Все остальные ОС используют путь каталога Linux/BSD.

Этот каталог должен быть постоянным и доступным для записи Caddy.

Длительности

Строки длительности широко используются в конфигурации Caddy. Они имеют тот же формат, что и синтаксис Go's time.ParseDuration, за исключением того, что вы также можете использовать d для дня (мы предполагаем, что 1 день = 24 часа для упрощения). Допустимые единицы:

• ns (наносекунда)
• us/µs (микросекунда)
• ms (миллисекунда)
• s (секунда)
• m (минута)
• h (час)
• d (день)

Примеры:

• 250ms
• 5s
• 1.5h
• 2h45m
• 90d

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