Глобальные параметры

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

В самом начале вашего Caddyfile может быть блок глобальных параметров. Это блок без ключей:

{
	...
}

Может быть только один, и он должен быть первым блоком в Caddyfile.

Возможные параметры (нажмите на каждый параметр, чтобы перейти к его документации):

{	# General Options
	debug
	http_port    <port>
	https_port   <port>
	default_bind <hosts...>
	order <dir1> first|last|[before|after <dir2>]
	storage <module_name> {
		<options...>
	}
	storage_clean_interval <duration>
	admin   off|<addr> {
		origins <origins...>
		enforce_origin
	}
	persist_config off
	log [name] {
		output  <writer_module> ...
		format  <encoder_module> ...
		level   <level>
		include <namespaces...>
		exclude <namespaces...>
	}
	grace_period   <duration>
	shutdown_delay <duration>
	metrics {
		per_host
	}	# TLS Options
	auto_https off|disable_redirects|ignore_loaded_certs|disable_certs
	email <yours>
	default_sni <name>
	fallback_sni <name>
	local_certs
	skip_install_trust
	acme_ca <directory_url>
	acme_ca_root <pem_file>
	acme_eab {
		key_id <key_id>
		mac_key <mac_key>
	}
	acme_dns <provider> ...
	dns <provider> ...
	ech <public_names...> {
		dns <provider> ...
	}
	on_demand_tls {
		ask        <endpoint>
		permission <module>
	}
	key_type ed25519|p256|p384|rsa2048|rsa4096
	cert_issuer <name> ...
	renew_interval <duration>
	cert_lifetime  <duration>
	ocsp_interval  <duration>
	ocsp_stapling off
	preferred_chains [smallest] {
		root_common_name <common_names...>
		any_common_name  <common_names...>
	}	# Server Options
	servers [<listener_address>] {
		name <name>
		listener_wrappers {
			<listener_wrappers...>
		}
		timeouts {
			read_body   <duration>
			read_header <duration>
			write       <duration>
			idle        <duration>
		}
		keepalive_interval <duration>
		trusted_proxies <module> ...
		client_ip_headers <headers...>
		trace
		max_header_size <size>
		enable_full_duplex
		log_credentials
		protocols [h1|h2|h2c|h3]
		strict_sni_host [on|insecure_off]
	}	# File Systems
	filesystem <name> <module> {
		<options...>
	}	# PKI Options
	pki {
		ca [<id>] {
			name                  <name>
			root_cn               <name>
			intermediate_cn       <name>
			intermediate_lifetime <duration>
			root {
				format <format>
				cert   <path>
				key    <path>
			}
			intermediate {
				format <format>
				cert   <path>
				key    <path>
			}
		}
	}	# Event options
	events {
		on <event> <handler...>
	}
}

Общие параметры

`debug`

Включает отладочный режим, который устанавливает уровень логирования на DEBUG для журналирования по умолчанию. Это раскрывает больше деталей, которые могут быть полезны при устранении неполадок (и очень подробный в рабочей среде). Мы просим вас включить это перед обращением за помощью на форумах сообщества. Например, вверху вашего Caddyfile, если у вас нет других глобальных параметров:

{
	debug
}

`http_port`

Порт, который сервер должен использовать для HTTP.

Только для внутреннего использования; не изменяет порт HTTP для клиентов. Обычно используется, если внутри вашей внутренней сети вам нужно было перенаправить порт 80 на другой порт (например, 8080) перед достижением Caddy для целей маршрутизации.

По умолчанию: 80

`https_port`

Порт, который сервер должен использовать для HTTPS.

Только для внутреннего использования; не изменяет порт HTTPS для клиентов. Обычно используется, если внутри вашей внутренней сети вам нужно было перенаправить порт 443 на другой порт (например, 8443) перед достижением Caddy для целей маршрутизации.

По умолчанию: 443

`default_bind`

Адрес(а) привязки по умолчанию, которые будут использоваться для всех сайтов, если используется директива bind на сайте. По умолчанию: пусто, что привязывается ко всем интерфейсам.

{
	default_bind 10.0.0.1
}

`order`

Назначает порядок для директив обработчика HTTP. Поскольку обработчики HTTP выполняются в последовательной цепочке, необходимо, чтобы обработчики выполнялись в правильном порядке. Стандартные директивы имеют предварительно определенный порядок, но если вы используете модули сторонних обработчиков HTTP, вам нужно будет явно определить порядок, используя этот параметр или поместив директиву в route блок. Порядок может быть описан абсолютно (first или last) или относительно (before или after) другой директивы.

Например, для использования replace-response плагина, вы захотите убедиться, что его директива упорядочена после encode, чтобы она могла выполнить замены перед кодированием ответа (потому что ответы передаются вверх по цепочке обработчика, а не вниз):

{
	order replace after encode
}

`storage`

Настраивает механизм хранения Caddy. По умолчанию используется file_system. Есть много других доступных модулей хранения, предоставляемых как плагины.

Например, чтобы изменить расположение хранилища файловой системы:

{
	storage file_system /path/to/custom/location
}

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

`storage_clean_interval`

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

Хранилище всегда будет очищено при первом запуске процесса. Затем новое очищение будет запущено через указанное время после завершения предыдущего очищения, если предыдущее очищение завершилось менее чем за половину этого интервала (в противном случае следующий запуск будет пропущен).

По умолчанию: 24h

{
	storage_clean_interval 7d
}

`admin`

Настраивает адрес API-интерфейса администрирования. Принимает заполнитель. Принимает сетевые адреса.

По умолчанию: localhost:2019, если не установлена переменная окружения CADDY_ADMIN.

Если установлено off, то адрес API-интерфейса администрирования будет отключен. При отключении изменения конфигурации будут невозможны без остановки и запуска сервера, поскольку команда caddy reload использует API-интерфейс администрирования для передачи новой конфигурации работающему серверу.

Не забудьте использовать флаг --address CLI с совместимыми командами командами, чтобы указать текущий адрес API-интерфейса администрирования, если адрес работающего сервера был изменён с значения по умолчанию.

Также поддерживает следующие подпараметры:

origins настраивает список источников, которым разрешено подключение к API.

Значение по умолчанию выбирается интеллектуально:
- если адрес прослушивания является локальным (например, localhost или локальный IP-адрес или сокет Unix), то разрешённые источники — localhost, ::1 и 127.0.0.1, соединённые с портом адреса прослушивания (например, localhost:2019 — это допустимый источник).
- если адрес прослушивания не является локальным, то разрешённый источник — тот же, что и адрес прослушивания.
Если хост адреса прослушивания не является интерфейсом с подстановкой (подстановки включают: пустую строку или 0.0.0.0 или [::]), то выполняется принуждение заголовка Host. Эффективно это означает, что по умолчанию заголовок Host проверяется на соответствие значению в origins, так как интерфейс является localhost. Но для адреса, такого как :2020, который имеет интерфейс с подстановкой, проверка заголовка Host не выполняется.
enforce_origin включает принуждение заголовка запроса Origin.

Это наиболее полезно, когда адрес прослушивания является интерфейсом с подстановкой (поскольку Host не проверяется) и API-интерфейс администрирования доступен для публичного интернета. Он включает предварительные проверки CORS и гарантирует, что заголовок Origin проверяется по отношению к списку origins. Используйте это только в том случае, если вы работаете с Caddy на своей машине разработки и вам нужно получить доступ к API-интерфейсу администрирования из веб-браузера.

Например, чтобы экспонировать API-интерфейс администрирования на другом порту, на всех интерфейсах — ⚠️ этот порт не следует экспонировать публично, в противном случае любой может управлять вашим сервером; рассмотрите возможность включения принуждения источника, если вам это нужно для публичного доступа:

{
	admin :2020
}

Чтобы отключить API-интерфейс администрирования — ⚠️ это делает перезагрузки конфигурации невозможными без остановки и запуска сервера:

{
	admin off
}

Чтобы использовать сокет Unix для API-интерфейса администрирования, позволяя управлять доступом с помощью разрешений файлов:

{
	admin unix//run/caddy-admin.sock
}

Чтобы разрешить только запросы с соответствующим заголовком Origin:

{
	admin :2019 {
		origins localhost
		enforce_origin
	}
}

`persist_config`

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

{
	persist_config off
}

`log`

Настраивает именованные логгеры.

Имя может быть передано для указания конкретного логгера, для которого нужно настроить поведение. Если имя не указано, изменяется поведение логгера default. Вы можете узнать больше о логгере default и объяснении того, как работает журналирование в Caddy.

Несколько логгеров с разными именами могут быть настроены путём многократного использования log.

Это отличается от log директивы, которая настраивает только ведение журналов HTTP-запросов (также известные как журналы доступа). Глобальный параметр log разделяет свою структуру конфигурации с директивой (за исключением include и exclude), и полная документация находится на странице директивы.

output настраивает место записи журналов.

См. log директиву для полной документации.
format описывает способ кодирования или форматирования журналов.

См. log директиву для полной документации.
level — минимальный уровень записи в журнал.

По умолчанию: INFO.

Возможные значения: DEBUG, INFO, WARN, ERROR, и очень редко PANIC, FATAL.
include указывает имена журналов, которые должны быть включены в этот логгер.

По умолчанию этот список пуст (т. е. включены все журналы).

Например, чтобы включить только журналы, выпущенные API-интерфейсом администрирования, вы должны включить admin.api.
exclude указывает имена журналов, которые должны быть исключены из этого логгера.

По умолчанию этот список пуст (т. е. нет исключений).

Например, чтобы исключить только журналы доступа HTTP, вы должны исключить http.log.access.

Имена логгеров, которые include и exclude принимают, зависят от используемых модулей, и самый простой способ их узнать — из предыдущих журналов.

Вот пример логгирования в формате json всех журналов доступа HTTP и журналов администрирования в stdout:

{
	log default {
		output stdout
		format json
		include http.log.access admin.api
	}
}

`grace_period`

Определяет период ожидания для завершения работы HTTP-серверов (например, во время изменений конфигурации или при остановке Caddy).

В период благоприятного завершения (grace period) не принимаются новые подключения, закрываются свободные подключения, а активные подключения терпеливо ждут завершения своих запросов. Если клиенты не завершат свои запросы в течение этого периода, сервер будет принудительно завершён, чтобы позволить перезагрузке завершиться и освободить ресурсы. Принимает значения продолжительности.

По умолчанию, период благоприятного завершения (grace period) вечен, что означает, что подключения никогда не закрываются принудительно.

{
	grace_period 10s
}

`shutdown_delay`

Определяет продолжительность до периода благоприятного завершения (grace period), в течение которой сервер, который будет остановлен, продолжает работать в обычном режиме, за исключением того, что {http.shutting_down} заменяется на true, а {http.time_until_shutdown} указывает время до начала периода благоприятного завершения (grace period).

Это приводит к задержке, если какой-либо сервер останавливается в рамках изменения конфигурации, и фактически планирует изменение на более позднее время. Это полезно для оповещения систем проверки работоспособности о предстоящем прекращении работы этого сервера и предоставления времени для балансировщику нагрузки для удаления его из ротации; например:

{
	shutdown_delay 30s
}
example.com {
	handle /health-check {
		@goingDown vars {http.shutting_down} true
		respond @goingDown "Bye-bye in {http.time_until_shutdown}" 503
		respond 200
	}
	handle {
		respond "Hello, world!"
	}
}

Параметры TLS

`auto_https`

Настраивает Автоматическое HTTPS, функция, которая позволяет Caddy автоматизировать управление сертификатами и перенаправления HTTP в HTTPS для ваших сайтов.

Можно выбрать несколько режимов:

off: Отключает автоматизацию сертификатов и перенаправления HTTP в HTTPS.
disable_redirects: Отключает только перенаправления HTTP в HTTPS.
disable_certs: Отключает только автоматизацию сертификатов.
ignore_loaded_certs: Автоматизировать сертификаты даже для имён, которые появляются в вручную загруженных сертификатах. Полезно, если вы указали сертификат с помощью tls директивы, которая содержит имена (или шаблоны), которые вы хотите вместо этого управлять автоматически.

Этот параметр не влияет на протокол по умолчанию Caddy, который всегда HTTPS, когда адрес сайта имеет действительное доменное имя. Это означает, что auto_https off не заставит ваш сайт работать по протоколу HTTP, а только отключит автоматическое управление сертификатами и перенаправления.

Это означает, что если вы хотите обслуживать свой сайт по протоколу HTTP, вы должны изменить адрес своего сайта так, чтобы он начинался с http:// или заканчивался на :80 (или параметр http_port).

{
	auto_https disable_redirects
}

`email`

Ваш адрес электронной почты. В основном используется при создании учётной записи ACME у вашего удостоверяющего центра и настоятельно рекомендуется в случае проблем с сертификатами.

Помните, что Let's Encrypt может отправлять вам электронные письма о приближении срока действия сертификата, но это может быть вводящим в заблуждение, так как Caddy может выбрать использование другого поставщика (например, ZeroSSL) при возобновлении. Проверьте свои журналы и/или сам сертификат (например, в вашем браузере), чтобы увидеть, какой поставщик был использован, и что его срок действия всё ещё действителен; если так, вы можете безопасно проигнорировать электронное письмо от Let's Encrypt.

{
	email admin@example.com
}

`default_sni`

Устанавливает имя сервера TLS по умолчанию для случаев, когда клиенты не используют SNI в своём сообщении ClientHello.

{
	default_sni example.com
}

`fallback_sni`

⚠️ Экспериментально

Если настроен, резервный параметр становится именем сервера TLS в сообщении ClientHello, если исходное имя сервера не соответствует никаким сертификатам в кэше.

Применение этого параметра весьма специфично; обычно, если клиент — это CDN и передает имя сервера из промежуточного обмена, но может принять сертификат с именем хоста источника вместо этого, то вы зададите это как имя хоста источника. Обратите внимание, что Caddy должен управлять сертификатом для этого имени.

{
	fallback_sni example.com
}

`local_certs`

Принудительно вызывает выпуск всех сертификатов внутри системы по умолчанию, а не через (публичный) центр сертификации ACME, такой как Let's Encrypt. Это полезно в качестве быстрого переключателя в средах разработки.

{
	local_certs
}

`skip_install_trust`

Пропускает попытки установки корневого сертификата локального центра сертификации в хранилище доверия системы, а также в хранилища доверия Java и Mozilla Firefox.

{
	skip_install_trust
}

`acme_ca`

Указывает URL каталога центра сертификации ACME. Настоятельно рекомендуется установить его на эталонный конечный пункт Let's Encrypt для тестирования или разработки. По умолчанию: ZeroSSL и производственные конечные точки Let's Encrypt.

Обратите внимание, что глобально настроенный центр сертификации ACME может не применяться ко всем сайтам; см. требования к имени хоста для использования стандартного поставщика ACME.

{
	acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

`acme_ca_root`

Указывает файл PEM, содержащий доверенный корневой сертификат для конечных точек ACME CA, если он не находится в хранилище доверия системы.

{
	acme_ca_root /path/to/ca/root.pem
}

`acme_eab`

Указывает внешнюю привязку учётных записей (External Account Binding), которую следует использовать для всех транзакций ACME.

Например, с тестовыми данными ZeroSSL:

{
	acme_eab {
		key_id GD-VvWydSVFuss_GhBwYQQ
		mac_key MjXU3MH-Z0WQ7piMAnVsCpD1shgMiWx6ggPWiTmydgUaj7dWWWfQfA
	}
}

`acme_dns`

Настраивает поставщика вызовов ACME DNS для использования во всех транзакциях ACME.

Требует пользовательской сборки Caddy с плагином для вашего поставщика DNS.

Имена поставщика, следующие за именем поставщика, настраивают поставщика так же, как если бы они были указаны в tls директиве acme поставщика.

{
	acme_dns cloudflare {env.CLOUDFLARE_API_TOKEN}
}

`dns`

Настраивает поставщика DNS по умолчанию, который используется, когда другой поставщик не указан локально в соответствующем контексте. Например, если вызов ACME DNS включён, но поставщик DNS не настроен, будет использоваться этот глобальный параметр по умолчанию. Он также применяется для публикации конфигураций Encrypted ClientHello (ECH).

Ваш бинарный файл Caddy должен быть скомпилирован с указанным модулем поставщика DNS для корректной работы.

Пример использования переменных окружения:

{
	dns cloudflare {env.CLOUDFLARE_API_TOKEN}
}

(Требуется Caddy 2.10 beta 1 или более поздняя версия.)

`ech`

Включает Encrypted ClientHello (ECH) путём использования указанных доменных имён как текста имени сервера (SNI) в рукопожатиях TLS. При соответствующих условиях ECH может помочь защитить доменные имена ваших сайтов в сети во время подключений. Caddy сгенерирует и опубликует одну конфигурацию ECH для каждого указанного публичного имени. Публикация — это способ, которым совместимые клиенты (например, правильно настроенные современные браузеры) знают, как использовать ECH для доступа к вашим сайтам.

Для правильной работы конфигурация(и) ECH должны быть опубликованы так, как ожидают клиенты. Большинство браузеров (с включённым DNS-over-HTTPS или DNS-over-TLS) ожидают, что конфигурации ECH будут опубликованы в записях DNS типа HTTPS. Caddy выполняет такую публикацию автоматически, но вам нужно указать поставщика DNS либо с подвариантом dns, либо глобально с dns глобальным параметром, и ваш бинарный файл Caddy должен быть скомпилирован с указанным модулем поставщика DNS. (Пользовательские сборки доступны на нашей странице загрузки.)

Заметки о конфиденциальности:

В целом рекомендуется максимизировать размер вашего множества анонимности. Поэтому обычно рекомендуется, чтобы большинство пользователей настраивали только одно публичное доменное имя для защиты всех ваших сайтов.
Ваш сервер должен быть авторитетным для указанных вами публичных доменных имён (т. е. они должны указывать на ваш сервер), так как Caddy получит сертификат для них. Эти сертификаты имеют важное значение для того, чтобы клиенты, соответствующие спецификациям, могли надёжно и безопасно подключаться с ECH в некоторых случаях. Они используются только для облегчения надлежащего рукопожатия ECH, а не для данных приложения (ваших сайтов — если вы не определите сайт, совпадающий с вашим публичным доменным именем).
Каждая ситуация может быть уникальной. Мы рекомендуем обратиться к экспертам для проверки вашей модели угроз, если ставки высоки, так как ECH не является универсальным решением.

Пример использования переменных окружения для публикации в имена серверов, размещённых в Cloudflare:

{
	dns cloudflare {env.CLOUDFLARE_API_TOKEN}
	ech ech.example.net
}

Это должно привести к тому, что совместимые клиенты загрузили все ваши сайты с помощью ech.example.net, а не отдельных имён сайтов, представленных в текстовом виде.

Успешная публикация требует, чтобы домены вашего сайта были размещены у настроенного поставщика DNS, и записи могли быть изменены с помощью предоставленных данных/конфигурации поставщика.

(Требуется Caddy 2.10 beta 1 или более поздняя версия.)

`on_demand_tls`

Настраивает HTTPS по запросу, где он включен, но не включает его (чтобы включить его, используйте on_demand поддирективу tls директивы). Необходимо для использования в производственных средах, чтобы предотвратить злоупотребления.

ask заставит Caddy сделать HTTP-запрос на указанный URL, спрашивая, разрешено ли домену иметь выданный сертификат.

Запрос имеет строку запроса ?domain=, содержащую значение доменного имени.

Если конечная точка возвращает код состояния 2xx, Caddy получит право получить сертификат для этого имени. Любой другой код состояния приведёт к отмене выдачи сертификата и ошибке рукопожатия TLS.

permission позволяет использовать пользовательские модули для определения, должен ли быть выдан сертификат для определенного имени. Модуль должен реализовывать caddytls.OnDemandPermission интерфейс. Включён модуль разрешений http, который используется в параметре ask и остаётся в качестве сокращения для обратной совместимости.
⚠️ interval и burst параметры ограничения скорости были доступны, но НЕ рекомендуются. Удалите их из вашей конфигурации, если они у вас всё ещё есть.

{
	on_demand_tls {
		ask http://localhost:9123/ask
	}
}
https:// {
	tls {
		on_demand
	}
}

`key_type`

Указывает тип ключа, который следует сгенерировать для TLS-сертификатов; изменяйте его только в случае необходимости в настройке.

Возможные значения: ed25519, p256, p384, rsa2048, rsa4096.

{
	key_type ed25519
}

`cert_issuer`

Определяет издателя (или источник) сертификатов TLS.

Это позволяет настроить издателей глобально, а не на уровне каждого сайта, как это делается с поддирективой tls директивы issuer.

Можно повторять, если вы хотите настроить более одного издателя для проверки. Они будут проверены в порядке их определения.

{
	cert_issuer acme {
		...
	}
	cert_issuer zerossl {
		...
	}
}

`renew_interval`

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

По умолчанию: 10m

{
	renew_interval 30m
}

`cert_lifetime`

Срок действия, который необходимо запросить у ЦС для выдачи сертификата.

Это значение используется для вычисления поля notAfter заказа ACME; поэтому система должна иметь достаточно синхронизированные часы. ПРИМЕЧАНИЕ: Не все ЦС поддерживают это. Проверьте документацию вашего ЦС по ACME, чтобы узнать, разрешено ли это и какие значения могут быть использованы.

По умолчанию: 0 (ЦС выбирает срок действия, обычно 90 дней)

⚠️ Эта функция находится в стадии эксперимента. Может быть изменена или удалена.

{
	cert_lifetime 30d
}

`ocsp_interval`

Как часто проверять необходимость обновления OCSP-стяжек.

По умолчанию: 1h

{
	ocsp_interval 2h
}

`ocsp_stapling`

Можно установить в off, чтобы отключить OCSP-стяжки. Полезно в средах, где ответчики недоступны из-за брандмауэров.

{
	ocsp_stapling off
}

`preferred_chains`

Если ваш ЦС предоставляет несколько цепочек сертификатов, вы можете использовать этот параметр, чтобы указать, какую цепочку Caddy должен предпочесть. Установите один из следующих параметров:

smallest укажет Caddy предпочесть цепочки с наименьшим объёмом.
root_common_name — список одного или нескольких общих имен; Caddy выберет первую цепочку, у которой корень соответствует хотя бы одному из указанных общих имен.
any_common_name — список одного или нескольких общих имен; Caddy выберет первую цепочку, у которой издатель соответствует хотя бы одному из указанных общих имен.

Обратите внимание, что указание preferred_chains в качестве глобального параметра повлияет на всех издателей, если нет переопределяющей конфигурации на уровне издателя.

{
	preferred_chains smallest
}

{
	preferred_chains {
		root_common_name "ISRG Root X2"
	}
}

Параметры сервера

Настраивает HTTP-серверы с настройками, которые потенциально могут распространяться на несколько сайтов и поэтому не могут быть правильно настроены в блоках сайта. Эти параметры влияют на прослушиватель/сокет или другие компоненты под уровнем HTTP.

Можно указывать несколько раз с различными значениями listener_address, чтобы настроить разные параметры для каждого сервера. Например, servers :443 будет применяться только к серверу, привязанному к адресу прослушивателя :443. Пропуск адреса прослушивателя применит параметры ко всем остальным серверам.

Например, чтобы настроить разные параметры для серверов на портах :80 и :443, вы бы указали два блока servers:

{
	servers :443 {
		listener_wrappers {
			http_redirect
			tls
		}
	}
	servers :80 {
		protocols h1 h2c
	}
}

При использовании servers, он будет только применяться к серверам, которые действительно отображаются в вашем Caddyfile (то есть, создаются блоком сайта). Помните, Автоматический HTTPS создает сервер, прослушивающий порт 80 (или параметр http_port), для обслуживания перенаправлений HTTP->HTTPS и для решения HTTP-задачи ACME; это происходит во время выполнения, т.е. после того, как адаптер Caddyfile применит servers. Иными словами, это означает, что servers не будет применяться к :80, если вы не объявите явным образом блок сайта, например http:// или :80.

Если вы используете директиву bind или глобальный параметр default_bind, listener_address ОБЯЗАТЕЛЬНО должен соответствовать адресу привязки в сочетании с портом блока сайта, иначе настройки не будут применены. Например:

{	# This will NOT match the server, bind address missing
	servers :8080 {
		name private
	}	# This will work because it's an exact match
	servers 192.168.1.2:8080 {
		name public
	}
}
:8080 {
	bind 127.0.0.1
}
:8080 {
	bind 192.168.1.2
}

`name`

Пользовательское имя для этого сервера. Обычно полезно для идентификации сервера по имени в логах и метриках. Если не установлено, Caddy определит его динамически, используя шаблон srvX, где X начинается с 0 и увеличивается в зависимости от количества серверов в конфигурации.

Обратите внимание, что настройки будут применены только к серверам, созданным блоками сайта в вашей конфигурации. Автоматический HTTPS создает сервер :80 (или http_port) во время выполнения, поэтому если вы хотите его переименовать, вам потребуется по крайней мере пустой блок сайта http://.

Например:

{
	servers :443 {
		name https
	}
	servers :80 {
		name http
	}
}
example.com {
}
http:// {
}

`listener_wrappers`

Позволяет настроить обёртки прослушивателей, которые могут изменять поведение прослушивателя сокета. Они применяются в заданном порядке.

`tls`

Обёртка прослушивателя tls — это пассивная обёртка прослушивателя, которая отмечает место, где должен находиться прослушиватель TLS в цепочке обёрток прослушивателей. Она должна использоваться только в том случае, если другая обёртка прослушивателя должна быть расположена перед рукопожатием TLS.

`http_redirect`

Обёртка http_redirect обеспечивает перенаправления HTTP->HTTPS для подключений, которые поступают на порт TLS как HTTP-запрос, определяя по первым байтам, что это не рукопожатие TLS, а HTTP-запрос. Это наиболее полезно при предоставлении HTTPS по нестандартному порту (кроме 443), так как браузеры будут пытаться использовать HTTP, если схема не указана. Она должна размещаться перед обёрткой прослушивателя tls. Вот пример:

{
	servers {
		listener_wrappers {
			http_redirect
			tls
		}
	}
}

`proxy_protocol`

Обёртка прослушивателя proxy_protocol (до версии v2.7.0 она была доступна только через плагин) позволяет парсить протокол PROXY PROXY protocol (популярный в HAProxy). Она должна использоваться перед обёрткой прослушивателя tls, так как парсит текстовые данные в начале подключения:

proxy_protocol {
	timeout <duration>
	allow <cidrs...>
	deny <cidrs...>
	fallback_policy <policy>
}

timeout указывает максимальное время ожидания заголовка PROXY. По умолчанию 5s.
allow — список CIDR-диапазонов доверенных источников, которые должны получать заголовки PROXY. Unix-сокеты доверяются по умолчанию и не входят в этот параметр.
deny — список CIDR-диапазонов доверенных источников, заголовки PROXY от которых должны отклоняться.
fallback_policy — действие, которое должно быть выполнено, если заголовок PROXY приходит от адреса, который не входит ни в один из списков allow/deny. По умолчанию политика fallback — ignore. Допустимые значения для fallback_policy:
- ignore: адрес из заголовка PROXY, но подключение принимается
- use: адрес из заголовка PROXY
- reject: подключение при отправке заголовка PROXY
- require: подключение для отправки заголовка PROXY, отклонение, если он отсутствует
- skip: принимает подключение без требования заголовка PROXY.

Например, для HTTPS-сервера (требующего обёртку прослушивателя tls), который принимает заголовки PROXY из определенного диапазона IP-адресов и отклоняет заголовки PROXY из другого диапазона, с таймаутом в 2 секунды:

{
	servers {
		listener_wrappers {
			proxy_protocol {
				timeout 2s
				allow 192.168.86.1/24 192.168.86.1/24
				deny 10.0.0.0/8
				fallback_policy reject
			}
			tls
		}
	}
}

`timeouts`

read_body — значение длительности, определяющее время ожидания чтения данных клиента. Установка короткого, ненулевого значения может смягчить атаки slowloris, но также может повлиять на клиентов с реально низкой скоростью. По умолчанию таймаут отсутствует.
read_header — значение длительности, определяющее время ожидания чтения заголовков запроса клиента. По умолчанию таймаут отсутствует.
write — значение длительности, определяющее время ожидания записи данных клиенту. Установка малого значения при передаче больших файлов может негативно сказаться на клиентах с реально низкой скоростью. По умолчанию таймаут отсутствует.
idle — значение длительности, устанавливающее максимальное время ожидания следующего запроса при включённых keep-alive. По умолчанию 5 минут, чтобы избежать исчерпания ресурсов.

{
	servers {
		timeouts {
			read_body   10s
			read_header 5s
			write       30s
			idle        10m
		}
	}
}

`keepalive_interval`

Интервал, с которым отправляются пакеты TCP keepalive для поддержания соединения на уровне TCP, когда другие данные не передаются. По умолчанию 15s.

{
	servers {
		keepalive_interval 30s
	}
}

`trusted_proxies`

Позволяет настроить диапазоны IP-адресов (CIDR) прокси-серверов, запросы с которых должны быть доверенными. По умолчанию прокси не доверяются.

Включение этого параметра заставляет доверенные запросы анализировать истинный IP-адрес клиента из заголовков HTTP (по умолчанию, X-Forwarded-For; см. client_ip_headers, чтобы настроить другие заголовки). При доверенном статусе IP-адрес клиента добавляется в логи доступа, доступен в качестве {client_ip} заполнители и позволяет использовать client_ip matcher. Если запрос не идёт с доверенного прокси, IP-адрес клиента устанавливается в адрес удалённого IP-адреса прямого входящего подключения. По умолчанию IP-адреса в заголовках анализируются слева направо. См. trusted_proxies_strict, чтобы изменить это поведение.

Некоторые matchers или обработчики могут использовать статус доверия запроса для принятия решений. Например, при доверенном статусе обработчик reverse_proxy будет проксировать и дополнять важные X-Forwarded-* заголовки запроса.

В стандартной поставке Caddy включён только модуль static источника IP, но его можно расширить плагинами для поддержания динамического списка диапазонов IP-адресов.

`static`

Принимает статический (неизменяемый) список диапазонов IP-адресов (CIDR), которым следует доверять.

В качестве сокращения можно использовать private_ranges для соответствия всем частным диапазонам IPv4 и IPv6. Это эквивалентно указанию всех этих диапазонов: 192.168.0.0/16 172.16.0.0/12 10.0.0.0/8 127.0.0.1/8 fd00::/8 ::1.

Синтаксис следующий:

trusted_proxies static [private_ranges] <ranges...>

Вот пример, в котором доверяются примерному диапазону IPv4 и диапазону IPv6:

{
	servers {
		trusted_proxies static 12.34.56.0/24 1200:ab00::/32
	}
}

`trusted_proxies_strict`

Когда trusted_proxies включено, IP-адреса в заголовках (конфигурируемых с помощью client_ip_headers) анализируются слева направо по умолчанию. Первый ненадёжный IP-адрес, который обнаружится, становится реальным адресом клиента. Начиная с версии 2.8, вы можете включить анализ этих заголовков справа налево с помощью trusted_proxies_strict. По умолчанию этот параметр отключен для обеспечения обратной совместимости.

Прокси-серверы вышестоящего уровня, такие как HAProxy, CloudFlare, AWS ALB, CloudFront и т.д., будут добавлять каждый новый соединяемый удалённый адрес справа от X-Forwarded-For. Рекомендуется включать trusted_proxies_strict при работе с ними, так как самый левый IP-адрес может быть подделан клиентом.

{
	servers {
		trusted_proxies static private_ranges
		trusted_proxies_strict
	}
}

`client_ip_headers`

В паре с trusted_proxies можно настроить, какие заголовки использовать для определения IP-адреса клиента. По умолчанию учитывается только X-Forwarded-For. Можно указать несколько полей заголовков, в этом случае используется первое непустое значение заголовка.

{
	servers {
		trusted_proxies static private_ranges
		client_ip_headers X-Forwarded-For X-Real-IP
	}
}

`metrics`

Включает сборку метрик Prometheus; необходимо перед сканированием метрик. Обратите внимание, что метрики снижают производительность на очень загруженных серверах. (Наша команда работает над улучшением этого. Присоединяйтесь!)

{
	metrics
}

Вы можете добавить per_host параметр для маркировки метрик именем хоста метрики.

{
	metrics {
		per_host
	}
}

`trace`

Записывать каждый вызываемый обработчик. Требуется, чтобы запись логов осуществлялась на уровне DEBUG (это можно сделать с помощью debug глобального параметра).

ПРИМЕЧАНИЕ: это может записать конфигурацию ваших модулей обработки HTTP-запросов; не включайте этот параметр в небезопасных контекстах, когда в конфигурации есть конфиденциальные данные.

⚠️ Эта функция находится в стадии разработки. Она может быть изменена или удалена.

{
	servers {
		trace
	}
}

`max_header_size`

Максимальный размер для анализа заголовков HTTP-запроса клиента. Если предел превышен, сервер ответит кодом состояния HTTP 431 Request Header Fields Too Large. Поддерживает все форматы, поддерживаемые go-humanize. По умолчанию лимит равен 1MB.

{
	servers {
		max_header_size 5MB
	}
}

`enable_full_duplex`

Включить полнодуплексную коммуникацию для запросов HTTP/1. Действует только, если Caddy был скомпилирован с Go 1.21 или более поздней версией.

Для запросов HTTP/1 сервер Go по умолчанию потребляет любую непрочитанную часть тела запроса перед началом записи ответа, препятствуя обработчикам одновременного чтения из запроса и записи ответа. Включение этого параметра отключает это поведение и позволяет обработчикам продолжать чтение из запроса, одновременно записывая ответ.

Для запросов HTTP/2+ сервер Go всегда позволяет одновременное чтение и ответы, поэтому этот параметр не оказывает влияния.

Тщательно протестируйте с вашими HTTP-клиентами, так как некоторые старые клиенты могут не поддерживать полнодуплексный HTTP/1, что может привести к тупику. Подробнее см. golang/go#57786.

⚠️ Эта функция находится в стадии разработки. Она может быть изменена или удалена.

{
	servers {
		enable_full_duplex
	}
}

`log_credentials`

По умолчанию в журналы доступа (включённые с помощью log директивы) с заголовками, которые содержат потенциально конфиденциальную информацию (Cookie, Set-Cookie, Authorization и Proxy-Authorization), будут записываться как REDACTED.

Если вы хотите, чтобы эти заголовки не заменялись, вы можете включить параметр log_credentials.

{
	servers {
		log_credentials
	}
}

`protocols`

Список HTTP-протоколов через пробел, которые нужно поддерживать.

По умолчанию: h1 h2 h3

Допустимые значения:

h1 для HTTP/1.1
h2 для HTTP/2
h2c для HTTP/2 через открытый текст
h3 для HTTP/3

В настоящее время включение HTTP/2 (включая H2C) неизбежно подразумевает включение HTTP/1.1, потому что стандартная библиотека Go не позволяет отключить HTTP/1.1 при использовании её HTTP-сервера. Однако HTTP/1.1 или HTTP/3 можно включить независимо.

Обратите внимание, что H2C («HTTP/2 через открытый текст» или «H2 через TCP») и HTTP/3 не реализованы стандартной библиотекой Go, поэтому некоторые функции или возможности могут быть ограничены. Мы рекомендуем не включать H2C, если это не абсолютно необходимо для вашего приложения.

{
	servers :80 {
		protocols h1 h2c
	}
}

`strict_sni_host`

Включение этого параметра требует, чтобы заголовок запроса Host соответствовал значению ServerName, отправленному клиентом TLS ClientHello, что является необходимой мерой предосторожности при использовании TLS-аутентификации клиента. В случае несоответствия клиенту отправляется HTTP-ответ со статусом 421 Misdirected Request.

Этот параметр автоматически включится, если настроена аутентификация клиента client authentication. Это предотвращает обход TLS-аутентификации клиента (domain fronting), который можно использовать, отправив незащищённое значение SNI во время рукопожатия TLS, а затем поместив защищённый домен в заголовок Host после установления соединения. Это поведение является безопасным по умолчанию, но вы можете явно отключить его с помощью insecure_off, например, в случае работы прокси, где желательно domain fronting и доступ не ограничен на основе имени хоста.

{
	servers {
		strict_sni_host on
	}
}

Файловые системы

Глобальный параметр filesystem позволяет объявлять одну или несколько файловых систем, которые можно использовать для ввода-вывода файлов.

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

Файловые системы объявляются с именем для идентификации. Это означает, что вы можете подключиться к нескольким файловым системам одного типа, если это необходимо.

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

Пример

Используя воображаемый custom модуль файловой системы, вы могли бы объявить две файловые системы:

{
	filesystem foo custom {
		...
	}
	filesystem bar custom {
		...
	}
}
foo.example.com {
	fs foo
	file_server
}
foo.example.com {
	fs bar
	file_server
}

Параметры PKI

Приложение PKI (Public Key Infrastructure) является основой для функций Caddy Local HTTPS и ACME-сервера. Приложение определяет центры сертификации (ЦС), которые способны подписывать сертификаты.

Идентификатор ЦС по умолчанию - local. Если идентификатор опущен при конфигурации ca, предполагается local.

`name`

Пользовательское имя центра сертификации.

По умолчанию: Caddy Local Authority

{
	pki {
		ca local {
			name "My Local CA"
		}
	}
}

`root_cn`

Имя, которое нужно поместить в поле CommonName корневого сертификата.

По умолчанию: {pki.ca.name} - {time.now.year} ECC Root

{
	pki {
		ca local {
			root_cn "My Local CA - 2024 ECC Root"
		}
	}
}

`intermediate_cn`

Имя, которое нужно поместить в поле CommonName промежуточных сертификатов.

По умолчанию: {pki.ca.name} - ECC Intermediate

{
	pki {
		ca local {
			intermediate_cn "My Local CA - ECC Intermediate"
		}
	}
}

`intermediate_lifetime`

Срок действия промежуточных сертификатов. Это значение должно быть меньше срока действия корневого сертификата (3600d или 10 лет).

По умолчанию: 7d. Изменять его не рекомендуется, если это не абсолютно необходимо.

{
	pki {
		ca local {
			intermediate_lifetime 30d
		}
	}
}

`root`

Пара ключей (сертификат и закрытый ключ), которые нужно использовать в качестве корня ЦС. Если не указано, будет сгенерирован и автоматически управляется.

format - формат, в котором предоставляются сертификат и закрытый ключ. В настоящее время поддерживается только pem_file, что является значением по умолчанию, поэтому это поле необязательно.
cert - сертификат. Должен быть путём к файлу PEM, если используется формат pem_file.
key - закрытый ключ. Должен быть путём к файлу PEM, если используется формат pem_file.

`intermediate`

Пара ключей (сертификат и закрытый ключ), которые нужно использовать в качестве промежуточного звена ЦС. Если не указано, будет сгенерирован и автоматически управляется.

format - формат, в котором предоставляются сертификат и закрытый ключ. В настоящее время поддерживается только pem_file, что является значением по умолчанию, поэтому это поле необязательно.
cert - сертификат. Должен быть путём к файлу PEM, если используется формат pem_file.
key - закрытый ключ. Должен быть путём к файлу PEM, если используется формат pem_file.

{
	pki {
		ca local {
			root {
				format pem_file
				cert /path/to/root.pem
				key /path/to/root.key
			}
			intermediate {
				format pem_file
				cert /path/to/intermediate.pem
				key /path/to/intermediate.key
			}
		}
	}
}

Параметры событий

Модули Caddy генерируют события, когда происходят (или вот-вот произойдут) интересные вещи.

События, как правило, включают метаданные. Лучший способ узнать о событиях и их содержании - это документация каждого модуля, но вы также можете увидеть события и их данные, включив debug глобальный параметр и прочитав логи.

`on`

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

Например, чтобы выполнить команду после получения сертификата (плагин стороннего разработчика требуется), используя часть данных события в скрипте с помощью заглушки:

{
	events {
		on cert_obtained exec ./my-script.sh {event.data.certificate_path}
	}
}

События

Эти стандартные события генерирует Caddy:

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

© 2015-2025 Matthew Holt and The Caddy Authors
Licensed under the Apache License 2.0.
Caddy is a registered trademark of Stack Holdings GmbH.
https://caddyserver.com/docs/caddyfile/options