Using and understanding variables

Using Baseline Variables
Due to the fact that AMS baseline files are read-only and immutable there are features that can be toggled off and on as well as being configured by editing the variables they consume.

Baseline Variables

Here is a sample of the contents of the file /etc/httpd/conf.d/variables/ams_default.vars

Define DISP_LOG_LEVEL info

Define AUTHOR_WHITELIST_ENABLED 0

Define PUBLISH_WHITELIST_ENABLED 0

Define AUTHOR_FORCE_SSL 1

Define PUBLISH_FORCE_SSL 0

Example 1 - Force SSL

The variables shown above AUTHOR_FORCE_SSL, or PUBLISH_FORCE_SSL can be set to 1 to engage rewrite rules that force end users when coming in on http request to be redirected to https.

Here is the configuration file syntax that allows this toggle to work:

<VirtualHost *:80>

  <IfModule mod_rewrite.c>

    ReWriteEngine    on

    <If "${PUBLISH_FORCE_SSL} == 1">

      Include /etc/httpd/conf.d/rewrites/forcessl_rewrite.rules

    </If>

  </IfModule>

</VirtualHost>

As you can see the rewrite rules include is what has the code to redirect the end users browser, but the variable being set to 1 is what allows the file to be used or not.

Example 2 - Logging Level

The variables DISP_LOG_LEVEL can be used to set what you want to have for the log level that’s actually used in the running configuration.

Here is the syntax example that exists in the ams baseline configuration files:

<IfModule disp_apache2.c>

  DispatcherLog    logs/dispatcher.log

  DispatcherLogLevel ${DISP_LOG_LEVEL}

</IfModule>

If you need to increase the dispatcher logging level just update the ams_default.vars variable DISP_LOG_LEVEL to the level you’d like.

Example values can be an integer or the word:

Example 3 - Whitelists

The variables AUTHOR_WHITELIST_ENABLED and PUBLISH_WHITELIST_ENABLED can be set to 1 to engage rewrite rules that include rules to allow or disallow end user traffic based on IP address. Toggling this feature ON needs to be combined with creating a whitelist rules file as well for it to include.

Here is a few syntax examples of how the variable enables the includes of the whitelist files and a whitelist file example:

sample.vhost:

<VirtualHost *:80>

  <Directory />

    <If "${AUTHOR_WHITELIST_ENABLED} == 1">

        Include /etc/httpd/conf.d/whitelists/*_whitelist.rules

    </If>

  </Directory>

</VirtualHost>

sample_whitelist.rules:

<RequireAny>

  Require ip 10.43.0.10/24

</RequireAny>

As you can see the sample_whitelist.rules enforces the IP restriction but toggling the variable allows it to be included in the sample.vhost

Where to place the Variables?
Web Server Start Up Arguments

AMS will put global variables in the startup arguments of the apache process inside the file /etc/sysconfig/httpd

This file has variables pre-defined like shown here:

AUTHOR_IP="10.43.0.59"
AUTHOR_PORT="4502"
AUTHOR_DOCROOT='/mnt/var/www/author'
PUBLISH_IP="10.43.0.20"
PUBLISH_PORT="4503"
PUBLISH_DOCROOT='/mnt/var/www/html'
ENV_TYPE='dev'
RUNMODE='dev'

These isn’t something you can change but is good to leverage in your configuration files.

Note - Due to the fact that this file only gets included when the service starts up. A restart of the service is required to pick up changes. Meaning a reload isn’t enough but a restart instead is needed.

Variables Files (.vars)

Custom variables provided by your code should live in .vars files inside the directory /etc/httpd/conf.d/variables/

These files can have any custom variables you’d like. Here are some syntax examples for the following sample files:

When creating your own variables files name them according to their content and to follow the naming standards provided in the manual here. In the above example you can see that the variables file hosts the different DNS entries as variables to use in the configuration files.

/etc/httpd/conf.d/variables/sample-domain_domains_dev.vars:

Define SAMPLE_DOMAIN dev.sample-domain.com
    Define SAMPLE_ALT_DOMAIN dev.sample-domain.net

/etc/httpd/conf.d/variables/sample-domain_domains_stage.vars:

Define SAMPLE_DOMAIN stage.sample-domain.com
    Define SAMPLE_ALT_DOMAIN stage.sample-domain.net

/etc/httpd/conf.d/variables/sample-domain_domains_prod.vars:

Define SAMPLE_DOMAIN www.sample-domain.com
    Define SAMPLE_ALT_DOMAIN www.sample-domain.net

Using Variables
Now that you’ve defined your variables inside your variables files you’ll want to know how to use them properly inside your other configuration files.

We’ll use the example .vars files from above to illustrate a proper use case.

We want to include all the environment based variables globally we’ll create the file /etc/httpd/conf.d/000_load_env_vars.conf

Include /etc/httpd/conf.d/variables/*_${ENV_TYPE}.vars
Include /etc/httpd/conf.d/variables/*_${RUNMODE}.vars

We know that when the httpd service starts up it pulls in the variables set by AMS in /etc/sysconfig/httpd and has the variable set of ENV_TYPE and RUNMODE

When this global .conf file gets pulled in it will be pulled in early because the include order of files in conf.d is alpha numeric load order mean 000 in the filename will assure that it loads before the other files in the directory.

The include statement is also using a variable in the filename. This can change which file it will actually loads based on what value is in the ENV_TYPE and RUNMODE variables.

If the ENV_TYPE value is dev then the file that gets used is:

/etc/httpd/conf.d/variables/sample-domain_domains_dev.vars

If the ENV_TYPE value is stage then the file that gets used is:

/etc/httpd/conf.d/variables/sample-domain_domains_stage.vars

If the RUNMODE value is preview then the file that gets used is:

/etc/httpd/conf.d/variables/sample-domain_domains_preview.vars

When that file gets included it will allow us to use the variable names that were stored inside.

In our /etc/httpd/conf.d/available_vhosts/sample-domain.vhost file we can swap out the normal syntax that only worked for dev:

<VirtualHost *:80>

  ServerName    dev.sample-domain.com

  ServerAlias    dev.sample-domain.net

With newer syntax that uses the power of variables to work for dev, stage, and prod:

<VirtualHost *:80>

  ServerName    ${SAMPLE_DOMAIN}

  ServerAlias    ${SAMPLE_ALT_DOMAIN}

In our /etc/httpd/conf.dispatcher.d/vhosts/sample-domain_vhosts.any file we can swap out the normal syntax that only worked for dev:

"dev.sample-domain.com"
"dev.sample-domain.net"

With newer syntax that uses the power of variables to work for dev, stage, and prod:

"${SAMPLE_DOMAIN}"
"${SAMPLE_ALT_DOMAIN}"

These variables have a huge amount of re-use to individualize running settings without having to have different deployed files per environment. You essentially templatize your configuration files with the use of variables and include files based on variables.