Atomia SSL Redirect agent

This manual covers the installation and configuration of the Atomia SSL Redirect Agent to enable your customers to enforce SSL for their websites.

Overview

The SSL Redirect agent is used for enabling and disabling SSL redirection (SSL enforce) for a specific hostname. It can also be used for an SSL check of the specific hostname (whether that hostname can be reached via HTTPS protocol).

At the moment this agent only works with HAproxy. It enables/disables SSL redirection by adding/removing hostnames into a specific file (see configuration example below).

Before you begin

The Atomia SSL Redirect Agent is part of the Atomia agents package. You should start by reading the general package overview and instructions here.

Pre-installation actions

The agent doesn’t require anything special before the installation.

Good to know

The SSL Redirect agent is usually installed on the same server where File system agent is installed.

Post-installation actions

In order to properly function, the agent must use root Linux user. So, the first thing to change is the default agent user in the /etc/atomia/config. Open the file and replace atomia-agent with root.

Keep in mind

The default agent user change will force usage of the root Linux user for all agents installed on the server.

HAProxy needs to be properly configured. The ssl-redirects.lst file from the configuration below needs to be properly synced with the HAProxy file. This file synchronization should be done periodically.

One more thing to do is to create and set up the agent’s configuration file. Start by copying the example config file:

sudo cp /etc/atomia/sslredirect-agent.json.example /etc/atomia/sslredirect-agent.json

Edit new copy and change some default properties if needed.

Example file and what each option means:

{
    "auth": {
        "username":"someauthusername",
        "password":"someauthpassword"
    },
    "port": 6046,
    "host": "127.0.0.1",
    "log_path": "/var/log/atomia/sslredirect-agent.log",
    "ssl_domain_file_path": "/storage/configuration/ssl-redirects.lst"
}

Option	Meaning
auth	Basic access authentication (username and password) for the atomia SSL Redirects agent.
port	Port of the SSL Redirects Agent REST API.
host	The IP address of the machine which gonna be used for listening by the SSL Redirects agent.
log_path	The file where should SSL Redirects agent log info and error messages.
ssl_domain_file_path	The file where HTTPS enabled hostnames are stored. Make sure that the file exists and has the correct name and enough privileges so that it can be properly synced with the HAProxy file.

Changes in the Automation Server

In order to connect the SSL Redirect agent with the Atomia provisioning module, Resource and ProvisioningDescription transformation files should be added to the server where Atomia Automation Server is installed.

Resource description transformation file

Place the following transformation file on the Automation server inside the folder: C:\Program Files (x86)\Atomia\AutomationServer\Common\Transformation Files:

<?xml version="1.0"?>
<resourceDescription xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <bindings xdt:Locator="XPath(//bindings[moduleList/module/@name='Atomia.Provisioning.Modules.SslRedirect.SslRedirect'])">
        <resourceList>
            <resource name="SslRedirectAgent" xdt:Transform="Insert">
            <property name="URL">URL</property>
            <property name="Username">someauthusername</property>
            <property name="Password">someauthpassword</property>
            </resource>
        </resourceList>
    </bindings>
</resourceDescription>

In the transformation file example above, the URL property should match exactly the host and port properties in the sslredirect-agent.json file (as defined in the example at the beginning of this section). Also, the Username and Password properties should be equivalent to the corresponding fields in the auth section of the same config file.

Provisioning description transformation file

Place the following transformation file on the Automation server inside the folder: C:\Program Files (x86)\Atomia\AutomationServer\Common\ProvisioningDescriptions\Transformation Files

<?xml version="1.0" encoding="utf-8"?>

<provisioningDescription xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <simpleService name="SslRedirect" friendlyName="Ssl redirect" providingModule="Atomia.Provisioning.Modules.SslRedirect.SslRedirect" xdt:Transform="Insert" xdt:Locator="XPath(//simpleServiceList)">
    <propertyList>
      <property name="Domain" friendlyName="SSL redirect domain name" key="true" />
      <property name="Status" friendlyName="SSL redirect status" defaultValue="enabled" />
    </propertyList>
    <operationList>
      <operation name="IsAvailable" />
    </operationList>
  </simpleService>

  <partService name="SslRedirect" min="1" max="1" xdt:Transform="InsertBefore(//complexService[@name='CsLinuxWebsite']//partServiceInstance[@name='CsExchangeMailSupport'])">
    <propertyTransformation>
      <simpleTransformer>
        <serviceProperty name="Domain">
          <expression>$CsLinuxWebsite::Hostname</expression>
        </serviceProperty>
      </simpleTransformer>
    </propertyTransformation>
  </partService>

  <add partName="SslRedirect" xdt:Transform="Insert" xdt:Locator="XPath(//complexService[@name='CsLinuxWebsite']//init)" />

  <partService name="SslRedirect" min="1" max="1" xdt:Transform="InsertBefore(//complexService[@name='CsWindowsWebsite']//partServiceInstance[@name='CsExchangeMailSupport'])">
    <propertyTransformation>
      <simpleTransformer>
        <serviceProperty name="Domain">
          <expression>$CsWindowsWebsite::Hostname</expression>
        </serviceProperty>
      </simpleTransformer>
    </propertyTransformation>
  </partService>

  <add partName="SslRedirect" xdt:Transform="Insert" xdt:Locator="XPath(//complexService[@name='CsWindowsWebsite']//init)" />

</provisioningDescription>

The transformation file above will allow the SSL redirection option for the Linux and Windows websites only.

Changes in the Hosting control panel

In order to allow end-users to activate/deactivate SSL redirection for their websites, a transformation file should be added to the server where Atomia Hosting Control Panel is installed.

Hosting control panel transformation file

Place the following transformation file on the Hosting Control Panel server inside the folder: C:\Program Files (x86)\Atomia\HostingControlPanel\App_Data\Transformation Files:

<?xml version="1.0" encoding="utf-8"?>
<appConfig xmlns="Atomia.Web.Base.Configs" xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <globalSettingsList>
        <globalSetting name="SSLRedirectFeatureEnabled" value="true" xdt:Locator="Match(name)" xdt:Transform="SetAttributes(value)" />
        <globalSetting name="SslRedirectIgnoreAvailabilityCheck" value="true" xdt:Locator="Match(name)" xdt:Transform="SetAttributes(value)" />
    </globalSettingsList>
</appConfig>

Running the service

systemctl start atomia-sslredirect-agent

Atomia Agents