Manage a Semarchy xDM instance in Azure

You can perform the main administrative tasks needed for your Semarchy using the Bash scripts listed below.
Other tasks, such as resizing the instances or databases or configuring the firewall rules, are performed as regular Azure tasks.

Download the scripts from the Semarchy Azure Templates Github repository, and install them in your environment or your Azure Cloud Shell.

Configure the Azure resources

You can configure the resources deployed in the instance, for example:

To scale the instance, you can change the size of the virtual machine, of the scale set virtual machines, or of the databases. You can also modify the scale set configuration to add more VMs.
To configure network rules or reinforce security, you can modify the application gateway configuration.

Refer to the Azure documentation for more information about these tasks and the configuration options of the deployed resources.

Add a new database

The az-xdm-instance-add-database script creates a new database/schema - for example, for a new data location - and then automatically configures and restarts the Semarchy instance to take into account this new database.

az-xdm-instance-add-database.sh
    [--resource-group=resource-group-name]
    [--admin-password=admin-password]
    [--db-server-password=database-server-password]
    --db-name=<database-name>
    [--db-password=database-password]

Parameters

--db-name: The name of the new database. This value is used for the name of the database created, for the user created for this database, as well as for the name of the datasource configured in the application server to connect this database.

Optional parameters

--resource-group: The resource group into which the instance is deployed. The resource group specified in the $XDM_RESOURCE_GROUP environment variable is used by default.
--admin-password: The password of the instance administrator. The password specified in the $XDM_ADMIN_PASSWORD environment variable is used by default.
--db-admin-password: The password of the database server administrator. The password specified in the $XDM_DB_SERVER_PASSWORD environment variable is used by default.
--db-password: The password of the new database user to create. The password specified in the $XDM_DB_PASSWORD environment variable is used by default.

Configure the application server

The virtual machine and the scale set run Semarchy xDM in a Tomcat application server. This server reads its configuration from the file share in the storage account.

The file share, hosting the configuration and files used by all the Semarchy active and passive nodes, is organized as shown below:

/xdm-assets
- /conf
  This folder contains the Semarchy configuration files, including:
  - semarchy.xml: This file contains configuration elements of the Semarchy xDM application in Tomcat. See Tomcat configuration file for more information.
  - logging.properties: This file contains the logging configuration of the Tomcat server.
  - config.properties: Contains the Semarchy xDM startup configuration, shared by the Active Virtual Machine and the Scale Set VMs. This configuration contains for example the repository connection information. Note that this file is copied in all the virtual machines, in the /etc/xdm/config.properties location.
  - local.keystore: Contains the default local keystore used to encrypt secrets in the repository. It may be replaced by a user-defined key. See Secrets management for more information. Note that this file is copied in all virtual machines and is referenced in config.properties at its target location in the VMs (/etc/xdm/local.keystore).
- /lib
  This folder contains additional libraries. These libraries will be copied in the active and passive VM’s, in Tomcat’s lib folder.
- /bin
  This folder contains the startup configuration for the tomcat server running on the active and passive nodes.
  - setenv.sh: tomcat startup options for all nodes node, including java system properties. Note that this file references the startup configuration file at its target location in the VMs (/etc/xdm/config.properties).
  - setenv-active.sh: specific options for the active node. This file does not exist by default. If it exists, it is used instead of setenv.sh for the active node.

You can use the content of the file share to configure the active and passive nodes. For example:

To modify the Semarchy xDM startup configuration in conf/config.properties.
To add new Tomcat startup parameters using the bin/setenv.sh file.
To add new libraries in the /lib/ folder.

When you change the content of the file share, you must restart the instance to refresh the instance with these changes.

To configure the application server:

Download the configuration file that you want to modify, update it and re-upload it at the same location in the file share.
Upload additional libraries to the /lib/ folder.
Restart the instance.

Restart the instance

The az-xdm-instance-restart script restarts the Semarchy instance, for example after modifying its configuration.

az-xdm-instance-restart.sh
    [--resource-group=resource-group-name]
    [--admin-password=admin-password]

Example

Example 1. Restart the instance in the xdm-production resource group.

az-xdm-instance-restart.sh --resource-group=xdm-production

Optional parameters

--resource-group: The resource group into which the instance is deployed. The resource group specified in the $XDM_RESOURCE_GROUP environment variable is used by default.
--admin-password: The password of the instance administrator. The password specified in the $XDM_ADMIN_PASSWORD environment variable is used by default.

Upgrade the instance

The az-xdm-instance-upgrade script upgrades the Semarchy instance to a given version.

az-xdm-instance-upgrade.sh
    --resource-group=resource-group-name
    --xdm-version=version
    [--admin-password=admin-password]
    [--db-server-password=db-server-password]
    [--repo-ro-password=repo-ro-password]
    [--backup-suffix=backup-suffix]
    [--backup]

Supported upgrade methods

This script supports:

In-place upgrades, executed on a running instance.

For an in-place upgrade, it is recommended to backup the existing resources by using the --backup parameter.
Out-of-place upgrades, executed on a cloned instance. This method is recommended for major updates (for instance from 5.2.x to 5.3) on production environments. To perform such an upgrade, proceed with the following steps:
1. Clone the current instance in another resource group by executing the az-xdm-instance-clone.sh script (see clone the instance for details).
2. Execute the az-xdm-instance-upgrade.sh script (see details below) on the cloned instance.
3. Test the new instance.
4. Change settings on your DNS server: Assign the new public (active) IP address to the existing DNS name of the Semarchy server.

It is recommended to perform major and minor upgrades either on a cloned instance (out-of-place upgrade) by running the az-xdm-instance-clone script prior to az-xdm-instance-upgrade.
For patch upgrades, in-place upgrade is acceptable, with the --backup option.

For more details about the in-place and out-of-place upgrade methods, see Upgrade Semarchy xDM.

Upgrade operations performed

The operations performed by this script depend on the type of upgrade:

For major upgrades (from 5.1.x or 5.2.x to 5.3.y), the script performs the following operations:
- Create backup resources if requested using the --backup parameter and --backup-suffix parameters.
- Create a new active virtual machine.
- Set the startup configuration, based on the provided parameters and the repository connection information from the previously used semarchy.xml file.
- Generate a local JKS key for secrets encryption (see Secrets management for details).
- Run the repository upgrade on the new active virtual machine.
- Create datasources on the upgraded instance based on the content of the previously used semarchy.xml file
- Create a new Scale Set and deploy the new Semarchy passive war file.
For minor upgrades, the script performs the following operations:
- Create backup resources if requested using the --backup and --backup-suffix parameters.
- Create a new active virtual machine.
- Deploy the new Semarchy active war file on the new active virtual machine.
- Reimage the existing Scale Set to use the new version and deploy the new Semarchy passive war file.

Examples

Example 2. Upgrade the instance in the xdm-production resource group to the latest 5.3 patch and create backup resources.

az-xdm-instance-upgrade.sh
    --resource-group=xdm-production
    --xdm-version=5.3
    --backup

Example 3. Upgrade the instance in the xdm-production resource group to version 5.2.3.

az-xdm-instance-upgrade.sh
    --resource-group=xdm-production
    --xdm-version=5.2.3

Example 4. Upgrade the instance in the xdm-production resource group to the latest 5.1 patch.

az-xdm-instance-upgrade.sh
    --resource-group=xdm-production
    --xdm-version=5.1

Parameters

--resource-group

The resource group into which the instance is deployed. The resource group specified in the $XDM_RESOURCE_GROUP environment variable is used by default.

--xdm-version

The Semarchy version to which you want to upgrade. This version may be provided in the following format:

A 2 digits minor version of Semarchy (e.g., 5.2): In that case, the template upgrades the latest patch of the minor version specified.
A 3 digits patch version of Semarchy (e.g., 5.2.1). In that case, the template upgrades to that product version.

Optional parameters

--admin-password: The password of the instance administrator. The password specified in the XDM_ADMIN_PASSWORD environment variable is used by default.
--db-server-password: The password of the database administrator. The password specified in the XDM_DB_SERVER_PASSWORD environment variable is used by default.
--repo-ro-password: The password of the repository read-only user (only applicable to version 5.3 and higher). The password specified in the XDM_RO_USER_PASSWORD environment variable is used by default.
--backup: Use this option to backup databases, virtual machines, and scale set resources. The backup is disabled by default.
--backup-suffix: Use this option to define the suffix added to name of the backup resources created by the --backup flag. Resources cannot be renamed, so make sure to set a suffix that you can keep if you need to use the backups. If you do not specify the suffix, a random value is generated.

The script uses the following environment variables for commonly used values if not available in the command: XDM_RESOURCE_GROUP, XDM_ADMIN_PASSWORD, XDM_DB_SERVER_PASSWORD and XDM_RO_USER_PASSWORD.
The script prompts for passwords if they are not passed on the command line and the environments variables are not set.

Clone the instance

The az-xdm-instance-clone script clones a Semarchy instance in a separate resource group.

az-xdm-instance-clone.sh
    --origin-resource-group=origin-resource-group-name
    --destination-resource-group=destination-resource-group-name
    --instance-name=instance-name
    [--admin-password=admin-password]
    [--db-server-password=db-server-password]

Example

az-xdm-instance-clone.sh
    --origin-resource-group=xdm-production
    --destination-resource-group=xdm-production-clone
    --instance-name=xdm1

Parameters

--origin-resource-group: The resource group from which the instance is cloned. The resource group specified in the XDM_ORIGIN_RESOURCE_GROUP environment variable is used by default.
--destination-resource-group: The resource group where the instance is cloned. The resource group specified in the XDM_DESTINATION_RESOURCE_GROUP environment variable is used by default. If the provided resource group exists, it is used, otherwise, it is created by the script (Note that the user who runs the script should have sufficient privileges to create resource groups).
--instance-name: The prefix for all the resources in the cloned instance. The instance name specified in the XDM_INSTANCE_NAME environment variable is used by default.

Optional parameters

--admin-password: The password of the instance administrator. The password specified in the XDM_ADMIN_PASSWORD environment variable is used by default.
--db-server-password: The password of the database administrator. The password specified in the XDM_DB_SERVER_PASSWORD environment variable is used by default.

The script uses the following environment variables for commonly used values if not available in the command: XDM_ORIGIN_RESOURCE_GROUP, XDM_DESTINATION_RESOURCE_GROUP, XDM_INSTANCE_NAME, XDM_ADMIN_PASSWORD, XDM_DB_SERVER_PASSWORD.
The script prompts for passwords when they are not passed on the command line and the environments variables are not set.
The script generates a unique string as a suffix for database name and storage account name. If the script fails due to an already existing database name or storage account name, relaunch the script to generate a new suffix.

Change the instance admin password

The az-xdm-instance-reset-admin script changes the admin password of the Semarchy instance.

az-xdm-instance-reset-admin.sh
    [--resource-group=resource-group-name]
    [--admin-password=new-admin-password]

Example

    az-xdm-instance-reset-admin.sh --resource-group=xdm-production

Optional parameters

--resource-group: The resource group into which the instance is deployed. The resource group specified in the XDM_RESOURCE_GROUP environment variable is used by default.
--admin-password: The new password of the instance administrator. The password specified in the XDM_ADMIN_PASSWORD environment variable is used by default.

The script uses the following environment variables for commonly used values if not available in the command: XDM_RESOURCE_GROUP and XDM_ADMIN_PASSWORD.
The script prompts for passwords when they are not passed on the command line and the environment variables are not set.

This script changes the password of the instance administrator but does not change the password of the first Semarchy xDM administrator user created during the deployment.