Модуль Apache mod_macro

Общие сведения

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

Использование

Макросы определяются с помощью блоков <Macro>, содержащих часть конфигурации, которую необходимо повторять, вместе с переменными для тех частей, которые нужно заменить.

Например, можно использовать макрос для определения блока <VirtualHost>, чтобы задать несколько похожих виртуальных хостов:

<Macro VHost $name $domain>
<VirtualHost *:80>
    ServerName $domain
    ServerAlias www.$domain

    DocumentRoot "/var/www/vhosts/$name"
    ErrorLog "/var/log/httpd/$name.error_log"
    CustomLog "/var/log/httpd/$name.access_log" combined
</VirtualHost>
</Macro>

Имена макросов не чувствительны к регистру, как и директивы конфигурации httpd. Однако имена переменных чувствительны к регистру.

Затем можно вызвать этот макрос несколько раз, чтобы создать виртуальные хосты:

Use VHost example example.com
Use VHost myhost hostname.org
Use VHost apache apache.org

UndefMacro VHost

При запуске сервера каждый из этих вызовов Use будет раскрыт в полноценный виртуальный хост, определённый в <Macro>.

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

Более подробный вариант этого примера приведён ниже в разделе «Примеры».

Советы

Имена параметров должны начинаться со специального символа, например $, % или @, чтобы их было легко распознать, а также чтобы упростить взаимодействие с другими директивами, например с базовой директивой Define. В противном случае будет выдано предупреждение. Тем не менее рекомендуется хорошо знать всю конфигурацию сервера, чтобы не использовать одни и те же переменные повторно в разных областях видимости, что может привести к путанице.

Параметры с префиксом $ или % не экранируются. Параметры с префиксом @ экранируются в кавычках.

Не используйте параметр, имя которого начинается с имени другого параметра (например, $win и $winter), поскольку это может привести к путанице при вычислении выражения. Если возникнет такая неоднозначность, будет использовано самое длинное из возможных имён параметра.

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

<Macro DocRoot ${docroot}>
    DocumentRoot "/var/www/${docroot}/htdocs"
</Macro>

Примеры

Определение виртуального хоста

Распространённый способ применения mod_macro — создание виртуальных хостов, генерируемых динамически.

## Define a VHost Macro for repetitive configurations

<Macro VHost $host $port $dir>
  Listen $port
  <VirtualHost *:$port>

    ServerName $host
    DocumentRoot "$dir"

    # Public document root
    <Directory "$dir">
        Require all granted
    </Directory>

    # limit access to intranet subdir.
    <Directory "$dir/intranet">
      Require ip 10.0.0.0/8
    </Directory>
  </VirtualHost>
</Macro>

## Use of VHost with different arguments.

Use VHost www.apache.org 80 /vhosts/apache/htdocs
Use VHost example.org 8080 /vhosts/example/htdocs
Use VHost www.example.fr 1234 /vhosts/example.fr/htdocs

Удаление определения макроса

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

<Macro DirGroup $dir $group>
  <Directory "$dir">
    Require group $group
  </Directory>
</Macro>

Use DirGroup /www/apache/private private
Use DirGroup /www/apache/server  admin

UndefMacro DirGroup

<Macro name [par1 .. parN]> ... </Macro>

<Macro LocalAccessPolicy>
    Require ip 10.2.16.0/24
</Macro>

<Macro RestrictedAccessPolicy $ipnumbers>
    Require ip $ipnumbers
</Macro>

UndefMacro name

UndefMacro LocalAccessPolicy
UndefMacro RestrictedAccessPolicy

Use name [value1 ... valueN]

Use LocalAccessPolicy
...
Use RestrictedAccessPolicy "192.54.172.0/24 192.54.148.0/24"

Require ip 10.2.16.0/24
...
Require ip 192.54.172.0/24 192.54.148.0/24