Using a pre-installed DataMiner Virtual Hard Disk

You can download a virtual hard disk with DataMiner pre-installed to immediately get started. The virtual hard disk is available in VHD, VHDX, and VMDK format. The pre-installed DataMiner VM is hardened out-of-the box for improved security.

When you configure this setup, you will be able to choose between different data storage setups:

• STaaS, i.e. the recommended setup.

• Self-managed dedicated clustered storage: A setup where you host and manage the Cassandra and OpenSearch clusters required by DataMiner yourself on dedicated servers (not recommended). If you choose this setup, you will need to make sure these database clusters are fully installed before you run the procedures below, so that DataMiner will be able to connect to them.

• A development setup where both Cassandra and OpenSearch run locally on Windows Subsystem for Linux (WSL). Such a setup should only be used for single-Agent development environments, and this will also require additional resources on the local machine. To convert such a setup to a staging or production setup, you will need to either migrate to Storage as a Service (STaaS) or switch to using Cassandra and OpenSearch clusters on separate servers (not recommended), and then decommission WSL.

Once you have downloaded the pre-installed virtual hard disk from DataMiner Dojo, you will need to follow the steps below to use it:

1. Create the VM.
2. Connect and start the VM.
3. Configure DataMiner.
4. Optionally, switch from subscription mode to a perpetual-license setup.

Note

• If you are not familiar with virtualization, we suggest installing DataMiner using the DataMiner Installer instead.
• The VMDK hard disk is compatible with desktop hypervisors such as VMWare Workstation. If you use the hard disk in a VMware vSphere ESXi environment, an error mentioning Unsupported and/or invalid disk type can be shown. For information on how to resolve this issue, refer to A virtual machine fails to power on with the error: Unsupported and/or invalid disk type.

Creating the VM

When you have downloaded the virtual hard disk, you can start to create a VM in your chosen virtualization environment. Below you can find the steps to follow in Hyper-V:

1. Start creating your VM by following the official Hyper-V guide.

2. Specify a name for your VM and store the machine in a location of your own choice, making sure your disk has enough space.

3. Choose Virtual Machine Generation 2.

4. Assign (at least) 8192 MB startup memory.

   Optionally, you can choose to use dynamic memory.

   Important

   If you intend to run the databases locally on the same server using WSL, assign at least 12288 MB RAM, as the WSL storage container will take about 4 GB to run.

5. Connect to a virtual switch that has internet access (either the default switch or a custom one).

   Note

   If you choose the default virtual switch, you will only be able to use remote access through dataminer.services to access the system outside of the virtual machine environment.

6. Connect the virtual hard disk that you have just downloaded.

Important

If you intend to use the locally hosted Cassandra and OpenSearch clusters running on WSL, make sure to enable nested virtualization on your host PC for the VM you created before starting the VM. To do so, run the following command on your host PC in an elevated Powershell prompt:

Set-VMProcessor -VMName <VMName> -ExposeVirtualizationExtensions $true

Connecting and starting the VM

1. When you have created the VM, double-click the entry and then click Start to boot the VM.

   You will see that the VM will boot in the OOBE setup screen.

2. Choose the region and keyboard settings and select a strong password for the built-in Administrator account.

   When you have set the password, the VM will restart.

3. When the login screen is shown, log in to the VM.

4. Verify in the network configuration that the network interface uses a static IP instead of DHCP, because DataMiner requires a static IP.

   For more details, refer to Change TCP/IP Settings under Essential Network Settings and Tasks in Windows.

Configuring DataMiner

As soon as you log in to the VM, a window will be shown where you can configure your DataMiner System.

Important

• The configuration wizard takes care of the automatic license and data storage configuration; however, this requires a connection to the internet. If you need to install DataMiner offline, you will not be able to use this wizard. Instead, the license and data storage configuration will need to be done manually:
  • For the license, see Permanent license.
  • For the data storage configuration, please refer to Configuring dedicated clustered storage.
• If you intend to restore a backup coming from another machine because of e.g. a hardware migration or during disaster recovery, skip the configuration below and follow the steps under Restoring a backup onto the virtual hard disk.
• If you are installing a Failover Agent, skip the configuration below, and follow the steps under Configuring the new DataMiner Agent as a new Agent in a Failover pair.

Note

If you have accidentally closed the configuration window, you can run it manually from C:\Skyline DataMiner\Tools\FirstStartupChoice\FirstStartupChoice.ps1. Make sure to run it with administrator privileges.

Follow the below steps to configure your DataMiner Agent:

1. Click Start to get started.

2. Select the desired database type, and click Next.

   These are the available database types:

   • Storage as a Service (STaaS) (recommended).

   • Self-hosted - External Storage: A regular dedicated clustered storage setup. If you select this option, you will also need to fill in the connection details for both Cassandra and OpenSearch.

     Note

     Make sure these clusters are active and reachable from the VM you are setting up. You are responsible for the management of these external database clusters.

   • Self-hosted - Local storage: A clustered storage setup where both Cassandra and OpenSearch run locally on WSL.

     Important

     This option should only be used for testing and staging environments. Do not select this option for production systems. Furthermore, make sure the necessary resources will be available for the WSL storage container. See Creating the VM.

3. Fill in the required details to connect your DataMiner Agent to dataminer.services and click Next:

   • Organization API Key: Provide an organization key that has the necessary permissions to add DataMiner Systems in your organization. For more information on how you can add a new organization key to your organization on dataminer.services, see Managing dataminer.services keys.
   • System Name: This name will be used to identify the DataMiner System in various dataminer.services applications.
   • System URL: This URL will grant you remote access to your DataMiner System web applications. You can choose to either disable or enable this remote access feature at any time.
   • Admin Email: This email address must be associated with a dataminer.services account that is a member of your organization. It will become the owner of the DMS on dataminer.services.
   • STaaS Region: If you have selected to use STaaS for data storage, select the region where your data should be hosted.

4. Verify the selected configuration and click Configure

5. When the configuration is complete, click Finish

   DataMiner will automatically start up, get licensed, and connect to dataminer.services. DataMiner Cube will also be installed, so you can connect to DataMiner locally.

6. Log in to DataMiner Cube using the previously configured Administrator account.

   Logging in automatically with the built-in Administrator account is not possible, so you will need to fill in the username and password.

Important

For security reasons, we strongly recommend creating a second user and disabling the built-in administrator account once the setup is complete. See Managing users.

WSL management

If you selected the option Self-hosted - Local storage, which is not recommended and should only be done for testing and staging environments, that means you are running a WSL container for your storage.

If you want to manage the configuration of Cassandra or OpenSearch for this setup, you should connect to the container. To do so, you will need to open a command prompt using the user account used for the installation (by default the Administrator account) and run the wsl command. This way, you should automatically be logged in and connected to the WSL container.

Note

WSL always runs under a specific user. It is not possible to reach a WSL container from another user account.

Cassandra

Cassandra is installed with the following default credentials:

• cassandra
• DataMiner123!

When Cassandra is running, you can change the password as follows:

1. Use the following command: cqlsh -u cassandra -p DataMiner123!

2. Enter the following query: alter role cassandra with password = 'MyNewPassword123!';

3. Exit cqlsh using the exit command.

OpenSearch

The OpenSearch admin user has the following default credentials:

• admin
• DataMiner123!

You can change the admin password by following these steps:

1. First go to the correct directory with this command: cd /usr/share/opensearch/plugins/opensearch-security/tools

2. Run the following command: OPENSEARCH_JAVA_HOME=/usr/share/opensearch/jdk ./hash.sh

3. Specify a (strong) password and confirm with ENTER.

   A hashed password will be generated. You can copy your <HashedPassword>.

4. Update the user account file: sudo vi /etc/opensearch/opensearch-security/internal_users.yml

5. Update the hash in the admin user account with your hashed password.

Restoring a backup onto the virtual hard disk

If you want to restore a backup coming from another machine because of e.g. a hardware migration or during disaster recovery, after you have created and connected the VM, instead of the configuration steps detailed above, follow the steps below:

1. Restore the backup in the same way as for a regular DataMiner Agent. See Restoring a DataMiner Agent using the DataMiner Taskbar Utility.

2. Stop the DMA using the DataMiner Taskbar Utility.

3. Open the C:\Skyline DataMiner\ folder.

4. Remove all *.lic files, if any.

5. Start the DMA using the DataMiner Taskbar Utility.

6. After a short while, a Request.lic file should appear in the C:\Skyline DataMiner\ folder.

7. Contact dataminer.licensing@skyline.be and provide them with the Request.lic file.

8. Wait until you receive a dataminer.lic file from Skyline.

9. When you have the dataminer.lic file, copy it to the C:\Skyline DataMiner\ folder.

10. Restart the DMA using the DataMiner Taskbar Utility.

Configuring the new DataMiner Agent as a new Agent in a Failover pair

If the new Agent will be paired with an existing Agent in a Failover setup, after you have created and connected the VM, instead of the configuration steps detailed above:

1. Make sure both the existing and new DMA are prepared and the necessary prerequisites are met, as detailed under Preparing the two DataMiner Agents.

   Important

   Do not start DataMiner on the new DMA before this preparation is fully done.

2. Start the DMA using the DataMiner Taskbar Utility.

3. After a short while, a Request.lic file should appear in the C:\Skyline DataMiner\ folder.

4. Contact dataminer.licensing@skyline.be and provide them with the ID of the existing DMA and the Request.lic file.

   In your email, mention that it concerns a Failover Agent for an existing Agent.

5. Wait until you receive either a dataminer.lic or response.lic file from Skyline.

6. When you have the dataminer.lic or response.lic file, copy it to the C:\Skyline DataMiner\ folder.

7. Restart the DMA using the DataMiner Taskbar Utility.

Once the new DMA is running, continue with the Failover configuration in Cube.

Switching from subscription mode to perpetual license

When you deploy a DataMiner Agent using the pre-installed DataMiner Virtual Hard Disk, your system will run in subscription mode and get licensed automatically. Part of this process involves getting a DataMiner ID, which uniquely identifies your DataMiner Agent.

If you have purchased a permanent license, follow the steps below to convert your subscription installation to a perpetual-license one:

1. Stop the DMA using the DataMiner Taskbar Utility.

2. Open the C:\Skyline DataMiner\ folder.

3. Remove all *.lic files, if any.

4. Open the DataMiner.xml file.

5. Find the <DataMiner> tag and locate the id attribute.

6. Note down the value in the id attribute.

7. Start the DMA using the DataMiner Taskbar Utility.

8. After a short while, a Request.lic file should appear in the C:\Skyline DataMiner\ folder.

9. Contact dataminer.licensing@skyline.be and provide them with the ID and the Request.lic file.

   In your email, mention that it concerns a conversion from a subscription to a perpetual license.

10. Wait until you receive a dataminer.lic file from Skyline.

11. When you have the dataminer.lic file, copy it to the C:\Skyline DataMiner\ folder.

12. Restart the DMA using the DataMiner Taskbar Utility.

Switching from subscription mode to an offline demo license

When you deploy a DataMiner Agent using the pre-installed DataMiner Virtual Hard Disk, your system will automatically be licensed and run in subscription mode. A DataMiner Agent running in subscription mode has to remain connected to dataminer.services to keep it licensed. If for some reason you cannot keep your Agent connected to dataminer.services, it will automatically shut down after 1 month.

If after this period you want to extend the usage of the system, you can convert your subscription installation to an offline demo installation:

1. Stop the DMA using the DataMiner Taskbar Utility.

2. Open the C:\Skyline DataMiner\ folder.

3. Remove all *.lic files, if any.

4. Start the DMA using the DataMiner Taskbar Utility.

5. After a short while, a Request.lic file should appear in the C:\Skyline DataMiner\ folder.

6. Contact dataminer.licensing@skyline.be and provide them with the Request.lic file.

   In your email, mention that it concerns a conversion from a subscription to a demo license.

7. Wait until you receive a Response.lic file from Skyline.

8. When you have the Response.lic file, copy it to the C:\Skyline DataMiner\ folder.

9. Restart the DMA using the DataMiner Taskbar Utility.