Caddy

Web-сервер caddy

Что такое caddy?

Caddy — это веб-сервер с открытым исходным кодом с автоматическим HTTPS из коробки.

Среди основных особенностей можно выделить:

• Простота настройки;
• Автоматическое обновление сертификатов TLS;
• Поддержка мультиядерности/мультипроцессорности;
• Поддержка HTTP/1.1, HTTP/2, и HTTP/3 по умолчанию;
• Возможность изменения конфигурации через API.

Установка caddy в ОС Альт

Стандартная установка

Предпочтительным способом установки является установка пакета caddy из репозитория:

$ su -
# apt-get update && apt-get install caddy

Продвинутая установка

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

Для сборки необходим Go версии 1.19 или новее. Установим его:

$ su -
# apt-get update && apt-get install go
# exit

Для удобной сборки, когда требуется добавить какие-то плагины, можно воспользоваться утилитой xcaddy. Установить xcaddy можно данной командой:

$ GOBIN=$HOME/bin go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest

Сборка происходит с помощью команды xcaddy build, а плагины перечисляются с помощью --with. Соберём caddy с двумя плагинами на адаптеры конфигурации: nginx и yaml.

$ xcaddy build \
    --with github.com/caddyserver/nginx-adapter \
    --with github.com/abiosoft/caddy-yaml

После этого, в текущей директории появится бинарный файл caddy.

$ ./caddy version
v2.6.4 h1:2hwYqiRwk1tf3VruhMpLcYTg+11fCdr8S3jhNAdnPy8=

Далее сделаем такой трюк: установим пакет caddy, удалим его из базы rpm и заменим исполняемый файл /usr/bin/caddy на собранный только что. Эта процедура позволит воспользоваться преимуществами конфигурации по умолчанию, служебными файлами systemd и bash-комплектацией из официального пакета.

$ su -
# apt-get install caddy
# rpm -e --justdb caddy
# chmod --reference /usr/bin/caddy /home/sysadmin/caddy
# chown --reference=/usr/bin/caddy /home/sysadmin/caddy
# rm /usr/bin/caddy && cp /home/sysadmin/caddy /usr/bin/

В данном случае, собранный исполняемый файл находится по пути /home/sysadmin/caddy.

Проверим работоспособность caddy и убедимся, что нужные адаптеры конфигурации добавлены:

$ caddy list-modules | grep adapters
caddy.adapters.caddyfile
caddy.adapters.nginx
caddy.adapters.yaml

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

# cat <<EOF | tee /etc/apt/preferences.d/forbid-caddy
Package: caddy
Pin: origin ""
Pin-Priority: 1001
EOF

После этого, пакет caddy не будет устанавливаться, т.к. "пустой" источник будет более приоритетным:

# apt-get install caddy
Чтение списков пакетов... Завершено
Построение дерева зависимостей... Завершено
Пакет caddy присутствует в базе данных, но не имеет доступной версии.
Как правило это означает, что хотя пакет упоминается в списке зависимостей,
он отсутствует в репозитории, был вытеснен, либо в sources.list нет адреса
репози�E: Для пакета caddy не найдено подходящего кандидата для установки

Управление службой

С использованием systemd

Пакет caddy в ОС Альт предоставляет две systemd службы:

• caddy.service — если вы настроите Caddy с Caddyfile. Если вы предпочитаете использовать другой адаптер конфигурации или файл конфигурации JSON, вы можете переопределить команды ExecStart и ExecReload.
• caddy-api.service — если вы настраиваете Caddy исключительно через его API. Эта служба использует параметр --resume, который запускает Caddy с использованием файла autosave.json, который сохраняется по умолчанию.

Управление данными службами возможно через стандартные команды systemctl.

Например, чтобы добавить caddy в автозагрузку и запустить прямо сейчас можно воспользоваться данной командой:

# systemctl enable --now caddy

Если вам нужно переключаться между службами, вам следует отключить и остановить предыдущую, прежде чем включать и запускать другую. Например, чтобы переключиться с сервиса caddy на сервис caddy-api:

# systemctl disable --now caddy
# systemctl enable --now caddy-api

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

# journalctl -eu caddy.service

• -e - немедленно перейдите к концу журнал
• -u - показывать логи только выбранного юнита

Без использования systemd

Также возможно использование caddy без systemd.

Для запуска сервера воспользуйтесь командой caddy run. Для запуска с стандартной конфигурацией, предоставляемой пакетом caddy добавьте --сonfig /etc/caddy/Caddyfile:

# caddy run --config /etc/caddy/Caddyfile

Данная команда запустит сервер в текущем терминале. Если необходимо запустить в фоне, можно воспользоваться командой caddy start.

Для выключения сервера воспользуйтесь командой caddy stop.

По остальным командам можно почитать в:

• caddy help и caddy help [command]
• официальной документации .

Настройка caddy

В ОС Альт конфигурация caddy расположена в /etc/caddy/Caddyfile.

По умолчанию главный файл конфигурации содержит строку import Caddyfile.d/*.caddyfile. Эта строка указывает на то, что caddy импортирует все файлы с расширением .caddyfile из директории /etc/caddy/Caddyfile.d/. Данная функциональность позволяет разделять конфигурации на отдельные файлы и упрощает организацию и поддержку конфигурации сервера.

Настройка через Caddyfile

HTTPS

По умолчанию Caddy обслуживает все сайты по HTTPS.

• Caddy обслуживает IP-адреса и локальные/внутренние имена хостов по HTTPS, используя самоподписанные сертификаты. Примеры: localhost, 127.0.0.1.
• Caddy обслуживает публичные DNS-имена по HTTPS, используя сертификаты от публичного ACME CA, такого как Let's Encrypt или ZeroSSL. Примеры: example.com, sub.example.com, *.example.com.

Caddy обновляет все управляемые сертификаты и автоматически перенаправляет HTTP (порт 80 по умолчанию) на HTTPS (порт 443 по умолчанию).

Локальный

Чтобы обслуживать непубличные сайты по HTTPS, Caddy создает свой собственный центр сертификации (ЦС) и использует его для подписи сертификатов. Цепочка доверия состоит из корневого и промежуточного сертификата. Листовые сертификаты подписываются промежуточным. В ОС Альт они хранятся в /var/lib/caddy/.local/share/caddy/pki/authorities/local.

Локальный HTTPS не использует ACME и не выполняет проверку DNS. Он работает только на локальной машине и доверяется только там, где установлен корневой сертификат CA.

Публичный

Получение публично доверенного сертификата TLS требует подтверждения от публично доверенного стороннего органа. В настоящее время этот процесс проверки автоматизирован с помощью протокола ACME и может быть выполнен одним из трех способов:

• HTTP challenge;
• TLS-ALPN challenge;
• DNS challenge.

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

Чтобы настроить или выключить глобально автоматический https, необходимо воспользоваться опцией auto_https:

{
  auto_https off
}
 
example.com {
  ...
}

localhost {
  ...
}

Также можно выключить для конкретного сайта, указав протокол http:// или порт :80:

http://example.com {
  ...
}

localhost:80 {
  ...
}

Статический файловый сервер

Для создания статического файлового сервера необходимо использовать директиву file_server.

Пример минимальной конфигурации:

example.com {
    root * /var/www/html
    file_server
}

При этом будут обслуживаться все файлы в корневом каталоге. Если не используется index файл, то для просмотра списка файлов потребуется указать file_server browse.

Если необходимо скрыть какие-то файлы, то можно воспользоваться директивой hide:

example.com {
    root * /var/www/html
    file_server {
        hide .git
    }
}

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

Если необходимо скрыть какие-то файлы конкретные файлы, то можно использовать переменную http.vars.root:

example.com {
   root * /var/www/html
   file_server {
      hide {http.vars.root}/file
   }
}

Данная конфигурация скрывает файл /var/www/html/file.

Reverse proxy

Для создания обратного прокси-сервера (reverse proxy) необходимо использовать директиву reverse_proxy.

Пример минимальной конфигурации:

example.com {
    reverse_proxy localhost:5000
}

Пример конфигурации, которая проксирует запросы, начинающиеся с /api/, и обеспечивает обслуживание статических файлов:

example.com {
    root * /var/www/html
    reverse_proxy /api/* localhost:5000
    file_server
}

C помощью обратного прокси-сервера, например, можно запустить Python приложение, если использовать такие сервера gunicorn и uwsgi (с протоколом http).

PHP

Для настройки PHP можно воспользоваться директивой php_fastcgi. Это директива, которая проксирует запросы на сервер PHP FastCGI, например php-fpm.

Пример минимальной конфигурации, которая подойдет большинству современных PHP приложений:

example.com {
   root * /var/www/html
   php_fastcgi unix//var/run/php8.2-fpm/php8.2-fpm.sock
   file_server
}

Запросы к файлам, существующим на диске (CSS, JS и пр.), будут обслуживаться с помощью file_server, а все остальное будет направляться в index.php для обработки PHP-приложением.

Для сайта PHP, который не использует index.php в качестве точки входа, вы можете использовать try_files, чтобы изменить поведение по умолчанию:

 php_fastcgi unix//var/run/php8.2-fpm/php8.2-fpm.sock {
   try_files {path} {path}/index.php =404
 }

Директива php_fastcgi на самом деле является просто сокращением для некоторой части конфигурации, которая использует reverse_proxy c transport fastcgi.

Редирект с www. субдомена

Для редиректа в сервере caddy используется директива redir.

Пример конфигурации для редиректа с www. субдомена:

www.example.com {
    redir https://example.com{uri}
}

example.com {
}

Если необходимо сделать редирект для нескольких доменов, то можно воспользоваться переменными {labels.*}:

www.example-one.com, www.example-two.com {
    redir https://{labels.1}.{labels.0}{uri}
}

example-one.com, example-two.com {
}

Массив labels хранит части имени хоста, индексируемые с 0 с права (0=com, 1=example-one, 2=www).

Адаптер конфигурации

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

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

1. Caddyfile
   Caddyfile является основным и наиболее распространенным способом конфигурации Caddy. Он основан на простом текстовом формате и позволяет определить веб-сервер и его параметры в удобном для чтения виде. Пример Caddyfile:

   localhost:80 {
       root * /var/www/html
       file_server
   }
   

2. JSON
   Родным языком конфигурации Caddy является JSON, но написание JSON вручную может быть утомительным и подверженным ошибкам. Однако, если вы предпочитаете работать с JSON-файлами или если ваши инструменты автоматизации используют JSON-формат, можно использовать данный вариант конфигурации. Пример JSON-конфигурации:

   {
     "apps": {
       "http": {
         "servers": {
           "srv0": {
             "listen": [
               ":80"
             ],
             "routes": [
               {
                 "match": [
                   {
                     "host": [
                       "localhost"
                     ]
                   }
                 ],
                 "handle": [
                   {
                     "handler": "vars",
                     "root": "/var/www/html"
                   },
                   {
                     "handler": "file_server"
                   }
                 ]
               }
             ]
           }
         }
       }
     }
   }
   

3. YAML
   Caddy также поддерживает конфигурацию в формате YAML. YAML обеспечивает более читаемую и структурированную форму конфигурации. Чтобы использовать данный адаптер конфигурации, необходимо собрать caddy с плагином abiosoft/caddy-yaml. Пример YAML-конфигурации:

   apps:
     http:
       servers:
         srv0:
           listen:
             - ':80'
           routes:
             - match:
                 - host:
                     - localhost
               handle:
                 - handler: vars
                   root: /var/www/html
                 - handler: file_server
   

4. Nginx
   Caddy также может импортировать конфигурации из Nginx. Это очень удобно, если у вас уже есть настроенные конфигурации Nginx, и вы хотите перейти на Caddy. Чтобы использовать данный адаптер конфигурации, необходимо собрать caddy с плагином caddyserver/nginx-adapter. Пример конфигурации Nginx:

   http {
       server {
           listen 80;
           server_name localhost;
           
           location / {
               root /var/www/html;
               try_files $uri $uri/ =404;
           }
       }
   }
   

Использовать адаптер конфигурации можно, указав его в командной строке с помощью флага --adapter в большинстве подкоманд, принимающих конфигурацию:

$ caddy run --config caddy.yaml --adapter yaml

Если используется systemd сервис, то нужно изменить его:

# systemctl edit caddy

[Service]
ExecStartPre=
ExecStartPre=/usr/bin/caddy validate --config /etc/caddy/caddy.yaml --adapter yaml
ExecStart=
ExecStart=/usr/bin/caddy run --environ --config /etc/caddy/caddy.yaml --adapter yaml
ExecReload=
ExecReload=/usr/bin/caddy reload --config /etc/caddy/caddy.yaml --adapter yaml

Чтобы проверить работу адаптера конфигурации, можно воспользоваться командой caddy adapt:

$ caddy adapt --config /etc/caddy/caddy.yaml --adapter yaml

Данная команда выводит JSON конфигурацию без запуска сервера.

Настройка через API

Редактирование конфигурации Caddy возможно через конечную точку администрирования, доступ к которой можно получить через HTTP с помощью REST API. Адрес по умолчанию: localhost:2019.

Пример запроса для загрузки конфигурации (POST /load):

$ curl localhost:2019/load \
    -H "Content-Type: application/json" \
    -d @- << EOF
    {
        "apps": {
            "http": {
                "servers": {
                    "hello": {
                        "listen": [":2015"],
                        "routes": [
                            {
                                "handle": [{
                                    "handler": "static_response",
                                    "body": "Hello, world!"
                                }]
                            }
                        ]
                    }
                }
            }
        }
    }
EOF

Данная конфигурация возвращает строку Hello, world! при запросе на localhost:2015:

$ curl localhost:2015
Hello, world!

Подробнее про API можно прочесть в официальной документации.

Чтобы отключить API, можно воспользоваться глобальной опцией admin в Caddyfile:

{
  admin off
}

Если API отключено, изменение конфигурации будет невозможно без остановки и запуска сервера.

Решение типовых проблем

listen tcp 127.0.0.1:2019: bind: address already in use

Пример сообщения об ошибке:

starting caddy administration endpoint: listen tcp 127.0.0.1:2019: bind: address already in use

Ошибка означает, что адрес 127.0.0.1:2019 (порт 2019) уже занят.

Для того, чтобы определить, какое приложение использует данный порт можно воспользоваться утилитой lsof:

# lsof -i :2019
COMMAND   PID    USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
ahttpd  38108 _ahttpd   16u  IPv6  64156      0t0  TCP *:2019 (LISTEN)

• -i - позволяет вывести сведения о файлах, интернет-адреса которых соответствуют заданному адресу;
• :2019 - необходимый порт.

В данном случае, необходимо остановить службу ahttpd:

# systemctl stop ahttpd.service

Error: decoding config

Пример сообщения об ошибке:

Error: decoding config: invalid character 'a' looking for beginning of value

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

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

WARN nginx server: unrecognized or unsupported nginx directive

Пример возникновения ошибки:

# cat /etc/caddy/caddy-nginx.conf 
server {
    listen 80;
    server_name localhost;
    
    location / {
        root /var/www/html;
        try_files $uri $uri/ =404;
    }
}
# caddy adapt --config /etc/caddy/caddy-nginx.conf --adapter nginx
{"apps":{"http":{}}}
2023/06/23 03:11:54.620	WARN	nginx	server: unrecognized or unsupported nginx directive	{"file": "/etc/caddy/caddy-nginx.conf", "line": 1}

Данная ошибка решается тем, что директиву server необходимо поместить внутрь http:

# cat /etc/caddy/caddy-nginx.conf 
http { 
    server {
        listen 80;
        server_name localhost;
    
        location / {
            root /var/www/html;
            try_files $uri $uri/ =404;
        }
    }
}
# caddy adapt --config /etc/caddy/caddy-nginx.conf --adapter nginx
{"apps":{"http":{"servers":{"server_0":{"listen":[":80"],"routes":[{"match":[{"host":["localhost"]},{"path":["/*"]}],"handle":[{"handler":"subroute","routes":[{"handle":[{"handler":"file_server","root":"/var/www/html"}],"match":[{"path":["/*"]}]}]}]}]}}}}}

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

• Страница проекта на GitHub
• Ошибки в ALT Linux Bugzilla

Список использованных источников

• Официальная документация Caddy;
• Викистраница Caddy на wiki.archlinux.org;
• Хостинг веб-сайта с Caddy в Ubuntu 18.04 (Digitalocean Tutorials);
• Man-страница lsof;
• Serving Django with Caddy.