Server Host Recovery Guide
This guide is intended to assist a Server administrator with recovering a Server instance in the event of failure of an original host or hosts, when moving to a new upgraded Server, moving from an on-premises to a cloud server, and in other cases where your infrastructure changes.
A Server Recovery allows you to get a new Server running with your original users, workflows, schedules, etc., based on having the following from your original Server:
- Controller Token
- RuntimeSettings.xml from Controller node
- MongoDB backup
Affected Alteryx Server Versions:
- 2021.4.2.47792 (Patch 5)+
- 2022.1.1.42590 (Patch 3)+
- 2022.3.1.430 (GA)+
DCM connections within a MongoDB database will be unusable if that database is migrated to a new machine. See the DCM Connections fail after Host Recovery article for instructions on how to update DCM connections to allow them to work in this scenario.
Below are details for each step of the process:
Prerequisites
1 - Prepare
2 - Recover RuntimeSettings.xml
3 - Recover MongoDB
4 - Restore Other Files and Settings
5 - Start Alteryx Server
6 - Test
In Scope
- Recovery from the failure of a single, default Server installation using embedded MongoDB.
- Available backup with necessary information intact.
- The target machine(s) can be overwritten.
Out of Scope
- Multi-node Server environment or user-managed MongoDB - please contact customer support for help.
- Merging of databases of connection files.
- Back up or restoration of ODBC drivers.
- Back up or restoration of User or system DSNs.
- Back up or restoration of other aliases stored in Windows that exist outside of Alteryx.
Prerequisites
- Install all database drivers and necessary software for workflow operation before completing the steps outlined in this guide to ensure minimal downtime.
- Administrator rights on the target Server.
- Access to all credentials used for impersonation including, the service account (if not Local System), the Run As user, and any defined/used workflow credentials.
- Controller Token from the original Server.
-
On the original Server, verify the length of the Controller token. If it’s 40 characters long AND you’re recovering your Server instance on 2021.4 or 2022.1, follow the steps below before proceeding with the steps in this guide:
-
Open Alteryx System Settings > Controller > General, save the existing token, and select Regenerate to create a new token. The new token will be 64 characters long.
-
Navigate through the rest of Alteryx System Settings and select Finish. This will restart the Alteryx Service.
-
If you have a multi-node setup, use the newly regenerated Controller Token to reconnect all of your nodes to your Controller node.
-
-
Use the new 64-character Controller Token for the remainder of this Host Recovery Guide.
-
- Access to RuntimeSettings.xml from the original Server is found here: %ProgramData%\Alteryx\RuntimeSettings.xml.
- Backup of MongoDB from the original Server. Learn how to perform a backup.
- Verify the target Server is set to the same time zone as the original Server in Windows time zone settings. If not set to the same time zone, errors might occur in schedule views.
Optional
The following items might not have been leveraged in the original Server. Check if the functionality was used and complete the corresponding steps marked (Optional) in this guide.
- Service Log On user, if used.
- Run-As User details for Worker configuration:
- Domain
- Username
- Password
- SMTP server username and password for Server configuration.
- Connectors from %ProgramData%\Alteryx\Tools.
- Alteryx System-Based and In-DB Connection aliases from the original Server.
- System In-DB Data Connections see %ProgramData%\Alteryx\Engine\SystemConnections.xml
- System Data Connections see %ProgramData%\Alteryx\Engine\SystemAlias.xml
- Alteryx User-Based and In-DB Connection Aliases from the original Server – the below might be relevant for each run-as or workflow credential user account
- User Data Connections see C:\Users\[username]\AppData\Roaming\Alteryx\Engine\UserConnections.xml
- User In-DB Data Connections see C:\Users\[username]\AppData\Roaming\Alteryx\Engine\UserAlias.xml
Step 1: Prepare
| # | Step | Details |
|---|---|---|
| 1.1 | Set machine time zone | The Windows time zone of the new machine must be set to match the original machine. |
| 1.2 | Ensure access to Alteryx | Ensure the machine can contact whitelist.alteryx.com used by the Alteryx licensing system. |
| 1.3 | Install the same version of Server | Perform a clean install of the same version Server that generated the Mongo backup. Use the latest maintenance release for the quarter, for example, if your backup is from version 2022.4.2 and the 2022.4.5 maintenance release is available, use that release. If your version is not still available at http://downloads.alteryx.com, please contact fulfillment@alteryx.com. Install or Upgrade Server Test the Server UI appears in a browser, you do not need to log in. |
| 1.4 | Troubleshoot License key "in use" error |
If your license key is still tied to your old server you will need to deactivate it on that machine. If that machine is inaccessible, contact your License Administrator to release the license. |
Step 2: Recover RuntimeSettings.xml
| # | Step | Details |
|---|---|---|
| 2.1 | Open Command Prompt 1 in bin folder |
Open a Command Prompt As Administrator and navigate to the Alteryx\bin folder, enter the commands below (adjust based on your install location). c: |
| 2.2 | Stop the Service |
Enter the command net stop alteryxservice On success you should see "The Alteryx Service service was stopped successfully." |
| 2.3 | Backup existing RuntimeSettings.xml |
Enter the command c: |
| 2.4 | Restore RuntimeSettings.xml | Copy the RuntimeSettings.xml file from your original server to the current %ProgramData%\Alteryx\ directory. |
| 2.5 | Clear Controller Token |
Edit the RuntimeSettings.xml you just copied and delete everything between the <ServerSecretEncrypted> tags, leaving just the tags as shown below: Save and close the file. |
| 2.6 | Restore Controller Token |
Enter the command using your original server Controller Token |
| 2.7 | Restore Encryption Keys |
The <StorageKeysEncrypted> value might have changed when the controller token was reset in step 2.6. If so, it should be replaced with the value from the original RuntimeSettings.xml file. It is easiest to copy the tags as well to ensure that the entire value between them is copied from the original RuntimeSettings.xml file. You can leave RuntimeSettings.xml open in a text editor as you make further changes in step 3. Pro tip: Open Notepad As Administrator to save the file.
|
| 2.8 | Restore Run As User | If you had a Run As User on the original Server, enter the following command, otherwise skip this step. AlteryxService.exe setexecuteuser=NAME,DOMAIN,PASSWORD |
| 2.9 | Restore SMTP Password | If you had filled in Alteryx System Settings > Server UI > SMTP > Password (even if the SMTP checkbox was unchecked), enter the following command, otherwise skip this step. AlteryxService.exe setsmtppassword=PASSWORD |
| 2.10 | Remain on the Command Line | Step 3 assumes you are in an Administrator command line in the \Alteryx\bin folder. |
Step 3: Recover MongoDB
| # | Step | |
|---|---|---|
| 3.1 | Get MongoDB backup | Copy the Mongo backup from the original server to a MONGO_BACKUP folder on your new Server. |
| 3.2 | Restore to a new folder | Restore the Mongo database from the backup folder to a new restore folder AlteryxService.exe emongorestore="MONGO_BACKUP_FOLDER","MONGO_RESTORE_FOLDER" Example: AlteryxService.exe emongorestore="D:\db_bkp","%ProgramData%\Alteryx\Service\Persistence\Mongo_Restore" |
| 3.3 | Set Mongo path in RuntimeSettings.XML |
Edit RuntimeSettings.xml and enter the path to the MONGO_RESTORE_FOLDER in the <EmbeddedMongoDBRootPath> tag. Example:
Save and close the text editor. |
| 3.4 | Start MongoDB | Enter the command mongod ––dbpath "MONGO_RESTORE_FOLDER" ––auth ––port 27018 Example mongod ––dbpath "%ProgramData%\Alteryx\Service\Persistence\Mongo_Restore" ––auth ––port 27018 |
|
Do not close the command prompt window. |
||
| << Begin second Command Prompt section >> | ||
| 3.5 | Open second Command Prompt in bin folder |
Open a SECOND Command Prompt As Administrator and navigate to the Alteryx\bin folder, enter the commands below (adjust based on your install location). c: |
| 3.6 | Get Non-Admin Mongo password | Enter the command and copy your NON_ADMIN_MONGO_PASSWORD to Notepad AlteryxService.exe getemongopassword |
| 3.7 | Start Mongo Command Line | Enter the command mongo mongodb://SERVER:PORT/AlteryxGallery -u user -p NON_ADMIN_MONGO_PASSWORD Example mongo mongodb://localhost:27018/AlteryxGallery -u user -p CCEC***33C0 On success you should see a ">" prompt. |
| 3.8 | Delete locks set by original Server | Enter the Mongo command db.locks.remove({}) On success you should see: "writeResult({ “nRemoved” : N })", where N is a number between 0 and 3. |
| 3.9 | Quit Mongo Command Line and Command Prompt 2 | Enter the command exit Close Command_Prompt_2 |
| << End second Command Prompt section >> | ||
| 3.10 | Stop Mongo database |
In the original command prompt, enter the keyboard command ctrl-c one or more times until you exit MongoDB and return to a normal command prompt. Close the command prompt. |
Step 4: Restore Other Files and Settings
| # | Step | Details |
|---|---|---|
| 4.1 | Did you have a Service Log On User on the original Server? | Set Service Log On User on new Server. Windows Services app > right-click AlteryxService > Properties > Log On |
| 4.2 | Add data drivers and System DSNs. | Add same-version drivers and same-name System DSNs to match original Server, https://downloads.alteryx.com/. |
| Advanced issues that may not apply to your recovery: | ||
| 4.3 | In more secure environments, configure required Run As user permissions. | Ensure all credentials used to run workflows (Run As, Service Log On, or credential set when saving the workflow) have proper sufficient access, configure required run user permissions. |
| 4.4 | Restore System-based and In-DB Connection Aliases | System Data Connections: %ProgramData%\Alteryx\Engine\SystemAlias.xml System In-DB Data Connections: %ProgramData%\Alteryx\Engine\SystemConnections.xml |
| 4.5 | Restore User-Based and User In-DB Connection Aliases | User Data Connections: C:\Users\[username]\AppData\Roaming\Alteryx\Engine\UserConnections.xml User In-DB Data Connections: C:\Users\[username]\AppData\Roaming\Alteryx\Engine\UserAlias.xml |
| 4.6 | Do workflows use Connectors? |
Copy Connector folders from your original server to Contact Customer Support to enable Connectors on your new Server. |
| 4.7 | Do workflows use the Python Tool? | Re-install any Python packages that workflows had installed. See Server upgrade - Python. |
| 4.8 | Do workflows use the R Tool? | Coming soon. |
| 4.9 | Do you have a multi-node environment or user-managed Mongo? | (Coming soon) Contact your Account Executive or Customer Support. |
| 4.10 | Do you use SSL? | If you are recovering to a Sandbox Server for testing, use HTTP for testing. If you are migrating to a new Server, re-establish your SSL: Configure Server SSL/TLS Configuring Alteryx Server for SSL Obtaining and Installing Certificates (15577) |
Step 5: Start the Alteryx Server
| # | Step | Details |
|---|---|---|
| 5.1 | Review Alteryx System Settings, suspend Schedules if desired. | Run Alteryx System Settings and step through each page confirming the settings (like the Controller Token) contain the values you expect. If you do not want Schedules to run when the Service starts, uncheck: Worker > General > Allow machine to run scheduled Alteryx workflows When you select Finish, the Alteryx Service should start and the Server should be available in a browser. |
Step 6: Test
| # | Step | Details |
|---|---|---|
| 6.1 | Basic testing | Is the Alteryx Service running? Can you:
|
| 6.2 | Workflow-specific testing | Can you run workflows that contain extensions or external connections, such as
|