To work correctly, both your website and its modules require information that is specific to your website, such as the following:

• Your website maintains a list of accounts that can access the website, along with their passwords.

• Modules have configuration information they use to connect to third-party services.

Although this information is essential for your production website, not all of the information may be necessary when you’re testing your website in your staging environment. If the information existed in both production and staging, it could represent a security or performance risk.

Site Factory uses a scrub script called /hooks/common/post-db-copy/000-acquia_required_scrub.php, which clears certain sensitive information from your databases as they are copied from production to staging.

The default scrub script runs a custom command (acsf-site-scrub) on the website’s database. This command uses the drush_sql_sanitize() function, which executes the Drush hook: hook_drush_sql_sync_sanitize() (for Drush versions 8 and earlier) to remove information relating to the website or the Site Factory Management Console.

Drush provides:

• For Drush versions 8 and earlier: an example hook implementation

• For Drush versions 9 and higher: @hook post-command sql-sanitize

The scrubbed information can include the following items:

• Website and Site Factory Management Console email addresses

• Accounts locally created on websites (does not include OpenID accounts)

• Caching information (including webforms and CDNs, if used)

• 301 website redirection settings

• Internal logging and statistics

If you have added modules or features to your codebase, you can use one of the following methods to either scrub your database or execute custom actions:

• Use hook_drush_sql_sync_sanitize() in your own, custom scrub script to remove any information that could have security or performance implications.

• Use Site Factory hooks in your code either to do additional scrubbing or to execute custom actions.

Protecting accounts during staging

When the scrub scripts process user accounts, Site Factory updates user accounts in the following ways:

• User names are changed to user[UID], replacing [UID] with the user’s account number.

• User email addresses are changed to user[UID]@[HASH].example.com, replacing [UID] with the user’s account number and [HASH] with the MD5 hash of the user’s email address.

Scrubbed users must sign in with the user[UID] username and their regular Site Factory password.

Not all user accounts are scrubbed, however. User accounts with the developer or release engineer role are not scrubbed during the staging process.

In addition, you can protect other accounts from scrubbing. If you have an account that you don’t want to be scrubbed during staging, complete the following steps:

• Sign in to your Prod environment’s Site Factory Management Console using an account with the platform admin role.

• In the admin menu, click User.

• Find the user account that you want to prevent from being scrubbed, and click its edit link.

• Click the View tab, and then click the Click to preserve this user during scrubbing link.

The account’s information will not be scrubbed during any website staging that takes place. To configure the account to once again have its username and email information scrubbed, use the same process, but instead click the Click to scrub this user during scrubbing link on the user’s View tab.

Protecting hosted website accounts during staging

As the scrub scripts process each website during the staging process, they remove specific user information from each local account, including each account’s email address. User names are changed to user[UID] (where [UID] is their user account number), and their email addresses are removed. Users whose accounts have been scrubbed therefore must log in to staged websites with the user[UID] username and their regular password for the website.

If you have one or more accounts that you don’t want to be scrubbed during staging, you must one of the following hooks in your website’s code:

• hook_acsf_staging_scrub_preserved_users_alter() - Protects local user accounts

• hook_acsf_staging_scrub_admin_roles_alter() - Protects local roles

Each of the hooks accept an array by reference of one or more user or role IDs, respectively.

When you reference the hooks, Drupal requires that you replace the hook reference in the hook with the name of the module that contains the hook. For example, if you use hook_acsf_staging_scrub_preserved_users_alter() in a module called example, you would use example_acsf_staging_scrub_preserved_users_alter().

Example

The following code example demonstrates both of the hooks in use by a module called example, protecting the account information for the account with a user ID of 16 and for all accounts with a role ID of 26:

<?php
/**
* Implements hook_acsf_staging_scrub_preserved_users_alter().
*/
function example_acsf_staging_scrub_preserved_users_alter(&$uids) {
  $uids[] = 16;
}

/**
* Implements hook_acsf_staging_scrub_admin_roles_alter().
*/
function example_acsf_staging_scrub_admin_roles_alter(&$rids) {
  $rids[] = 26;
}

Managing your scrub script

Site Factory looks for your scrub script in the /hooks/common/post-db-copy folder off of the docroot directory.

Your code distribution includes a sample scrub script called acquia-cloud-site-factory-post-db.sh that you can use as you develop your own scrub script file. The sample file (located in the acsf_init/lib/cloud_hooks/samples/ folder in the module for the current Drupal version, or the /hooks/samples folder in the Drupal 7 module) contains the following code:

#!/bin/sh
#
# Cloud Hook: post-db-copy
#
# The post-db-copy hook is run whenever you use the Workflow page to copy a
# database from one environment to another. (Note: this script is run when
# staging a site, but not when duplicating a site, because the latter
# happens on the same environment.) See ../README.md for details.
#
# Usage: post-db-copy site target-env db-role source-env
site="$1"
target_env="$2"
db_role="$3"
source_env="$4"

# You need the URI of the site factory website in order for drush to target
# that site. Without it, the drush command will fail. The uri.php file
# below will locate the URI based on the site, environment and db role
# arguments.
uri=`/usr/bin/env php /mnt/www/html/$site.$target_env/hooks/acquia/uri.php $site $target_env $db_role`

# Print a statement to the cloud log.
echo "$site.$target_env: Received copy of database from $uri ($source_env environment)."

# The websites' document root can be derived from the site/env:
docroot="/var/www/html/$site.$target_env/docroot"

# Acquia recommends the following two practices:
# 1. Hardcode the drush version.
# 2. When running drush, provide the application + url, rather than relying
#    on aliases. This can prevent some hard to trace problems.
DRUSH_CMD="drush8 --root=$docroot --uri=https://$uri"

# Retrieve the site name.
$DRUSH_CMD cget system.site name

Be sure to include all of the variables defined in the sample scrub script, because they are required for Drush to locate your specific website, which includes using the --uri=[URI] parameter, where [URI] is your website’s location. To obtain your website’s URI, in the /hooks/samples folder in your distribution’s files, run the acquia-cloud-site-factory-post-db.sh script.

As you add new modules or features to your website, be sure to edit your website’s scrub script to remove any unneeded database information relating to the new additions.

After you create your new scrub script and deploy the code to your codebase, be sure to test the operation of the scrub script by staging a website and inspecting the website to ensure that the scrubbed information doesn’t appear in the staging environment.

Scrub script command examples

Based on your website and its custom needs, use the following examples with your scrub script to accomplish different tasks.

Disabling modules for the staging environment

To disable modules for the staging environment, use the following:

drush @$site.$target_env --uri=$uri pm-disable [modules]

Running custom commands defined in a module

You can use custom commands to act on your users’ stored data, such as removing phone numbers or credit card information.

drush @$site.$target_env --uri=$uri [custom_command]

Scrubbing sensitive data from staged sites

<?php
/**
* Implements hook_acsf_staging_scrub_preserved_users_alter().
*/
function example_acsf_staging_scrub_preserved_users_alter(&$uids) {
  $uids[] = 16;
}

/**
* Implements hook_acsf_staging_scrub_admin_roles_alter().
*/
function example_acsf_staging_scrub_admin_roles_alter(&$rids) {
  $rids[] = 26;
}

#!/bin/sh
#
# Cloud Hook: post-db-copy
#
# The post-db-copy hook is run whenever you use the Workflow page to copy a
# database from one environment to another. (Note: this script is run when
# staging a site, but not when duplicating a site, because the latter
# happens on the same environment.) See ../README.md for details.
#
# Usage: post-db-copy site target-env db-role source-env
site="$1"
target_env="$2"
db_role="$3"
source_env="$4"

# You need the URI of the site factory website in order for drush to target
# that site. Without it, the drush command will fail. The uri.php file
# below will locate the URI based on the site, environment and db role
# arguments.
uri=`/usr/bin/env php /mnt/www/html/$site.$target_env/hooks/acquia/uri.php $site $target_env $db_role`

# Print a statement to the cloud log.
echo "$site.$target_env: Received copy of database from $uri ($source_env environment)."

# The websites' document root can be derived from the site/env:
docroot="/var/www/html/$site.$target_env/docroot"

# Acquia recommends the following two practices:
# 1. Hardcode the drush version.
# 2. When running drush, provide the application + url, rather than relying
#    on aliases. This can prevent some hard to trace problems.
DRUSH_CMD="drush8 --root=$docroot --uri=https://$uri"

# Retrieve the site name.
$DRUSH_CMD cget system.site name

drush @$site.$target_env --uri=$uri pm-disable [modules]

drush @$site.$target_env --uri=$uri [custom_command]