Server Host Recovery Guide

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.

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: cd \Program Files\Alteryx\bin

2.2

Stop the Service

Enter the command

net stop alteryxservice

On success you should see "The AlteryxService service was stopped successfully."

2.3

Backup existing RuntimeSettings.xml

Enter the command

c: cd \ProgramData\Alteryx ren RuntimeSettings.xml RuntimeSettings_BACKUP.xml

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

AlteryxService.exe setserversecret=CONTROLLER_TOKEN_FROM_ORIGINAL_SERVER

Troubleshooting:

Version 2021.3+ can error on this step with: "Set server secret failed: Error in CryptImportKey(3): Bad Data. (-2146893819)". To correct this, see the previous step to ensure the value was removed from between the tags.

2.7

Restore Storage Keys Encrypted

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. If needed, open ProgramData%\Alteryx\RuntimeSettings.xml on your original machine to get the needed value. 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

Save RuntimeSettings.xml

Save the RuntimeSettings.xml file.

2.11

Transfer Encryption Key

This functionality is only available on the following versions:

The steps in Encryption Key Transfer Process will allow you to transfer the encryption key from your existing controller to your new one.

2.12

Remain on the Command Line

Step 3 assumes you are in an Administrator command line in the \Alteryx\bin folder.

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. The final parameter, ,10, ensures lower memory usage by MongoDB during the restore. This reduces the chance of out-of-memory errors but might increase the time to restore. Leaving off the ,10 might lead to faster restores. In either case, review mongoRestore.log as described below to ensure the restore was successful.

AlteryxService.exe emongorestore="MONGO_BACKUP_FOLDER","MONGO_RESTORE_FOLDER",10

Example:

AlteryxService.exe emongorestore="D:\db_bkp","%ProgramData%\Alteryx\Service\Persistence\Mongo_Restore",10

3.3

Confirm the restore was successful

Confirm the restore was successful.

Caution

This is a necessary step as a restore failure will not be reported in the previous step and can lead to missing data on your Server. To do so, review the mongoRestore.log file in the MongoDB folder where the data was restored. Open mongoRestore.log and follow these steps:

If the recovery has failed, or if you find any results when searching the key words listed above, please contact Support with all the information you have gathered.

Do not proceed if the MongoDB restore failed.

3.4

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.5

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.

If you close the window from the previous step, none of the subsequent steps will work.

<< Begin second Command Prompt section >>

3.6

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: cd \Program Files\Alteryx\bin

3.7

Get Non-Admin Mongo password

Enter the command and copy your NON_ADMIN_MONGO_PASSWORD to Notepad

AlteryxService.exe getemongopassword

3.8

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.9

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.10

Quit Mongo Command Line and Command Prompt 2

Enter the command

exit

Close Command_Prompt_2

<< End second Command Prompt section >>

3.11

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.

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

%ProgramData%\Alteryx\Tools

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 Tool Environment Checklist.

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)

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 AlteryxService should start and the Server should be available in a browser.

6.1

Basic testing

Is the AlteryxService running?

Can you:

6.2

Workflow-specific testing

Can you run workflows that contain extensions or external connections, such as