Porta On Prem VM Setup Guide

The setup_vm.ps1 powershell script will guide you through the set-up of a new VM automatically. Periodic interaction will be required, but overall this script will:

• Detect and disable Hyper-V if it is enabled.
• Import a new Porta VM image or use an existing VM.
• Configure the VM’s network settings.
• Enable the OpenSSH Windows feature.
• Generate an SSH key and set up SSH access to the VM.
• Optionally add rules to Windows firewall.
• Optionally reset the VM’s identity.
• Configure a static IP address for the VM.

Prerequisites

Before beginning the setup process, ensure your physical machine meets the prerequisite criteria:

• A copy of the latest Porta On Prem Virtual Machine release as a zip file.
  • This zip contains the setup_vm.ps1 script and the.ova VM image file.
  • The image is an.ova file, which is a virtual machine image that can be imported into VirtualBox.
  • The image is a pre-configured Ubuntu image with Docker and Porta Manager already installed.
• VirtualBox 7.1.8 installed.
• Latest copy of the Porta On Prem application as a zip file.
• Minimum of 3 physical machines if running database replication.

Component	Specification
Operating System	Windows 11 64-bit
Hypervisor	VirtualBox 7.1.8
CPU	Intel i7 4th Generation (required: CPU with AVX2 support)
Memory	8GB RAM
Storage	100+GB free disk space

Setup

Note

• Any prompts for username should be entered asportavm.
• Any prompts for password should be entered as the Porta VM password provided to you by Disguise.

1. Beginning the Setup

   1. Extract the latest Porta On Prem VM zip file on the Windows machine for which it will be installed.
   2. Right-click on Windows Powershell or Windows Terminal and choose “Run as administrator”.
   3. In the window that opens, run the following command:

      Note

      Replace Path\to\setup_vm.ps1 with the path to the location of your extracted setup_vm.ps1 script.

      Powershell -ExecutionPolicy ByPass -NoExit -File "\Path\to\setup_vm.ps1"

      Example:

      Powershell -ExecutionPolicy ByPass -NoExit -File "C:\Users\user.name\Desktop\setup_vm.ps1"

2. Running the Script

   • The script will begin running and prompt for the Porta VM password.
   • Enter the Porta VM password provided to you by Disguise and press Enter.

3. Hyper-V Check

   In order to set up and run Porta VM, Hyper-V must not be enabled. The status of Hyper-V will be automatically checked.

   • If Hyper-V is already disabled, the script will proceed automatically.
   • If Hyper-V is enabled, you’ll need to disable it by typing y and hitting Enter.
     1. If you choose to disable it now, you’ll need to reboot your computer.
        • To reboot now, enter y and press Enter
     2. After rebooting, run the setup_vm.ps1 script again and begin from Step 1.

4. VirtualBox Check

   The script will check if VirtualBox is installed:

   • If VirtualBox is already installed, the script will proceed automatically and you may proceed to the next step.
   • If VirtualBox is not installed, you will be prompted to install it.
     1. If you choose to install it, enter y and press Enter.
     2. The script will download and install VirtualBox automatically.
     3. After installation, you may need to reboot your computer
        • To reboot now, enter y and press Enter
     4. After rebooting, run the setup_vm.ps1 script again

   Caution

   If you decline the VirtualBox installation, you will need to install it manually yourself and then run the setup_vm.ps1 script again.

5. VM Selection

   You’ll be presented with options to import a new VM, or use an existing one.

   1. Type 1 and hit Enter to choose to import a new VM.
   2. In the file explorer window that opens, navigate to the folder where you extracted the VM zip and select the.ova file.
   3. ClickOpen to import this file.
   4. The image will begin importing. Wait for it to finish, this may take several minutes.
      • There will be a lot of output in the terminal, but you can ignore it.
   5. Once the import is complete, the script will print “Successfully imported the appliance.” and proceed automatically to the next step.

   Tip

   After completing the VM import step, if at any time during set up you need to stop and restart the setup process, such as if you mis-entered a selection, you can do so by stopping and re-running the setup_vm.ps1 script.

   When you reach the VM Selection step again, type 2 and press Enter, then select the existing VM you just imported instead of re-importing it.

   You may then continue with the setup from here.

6. VM Network Configuration

   1. Select the network adapter you want the VM to use by entering the number corresponding to the listed adapter and pressing Enter.

      • If you’re unsure which adapter to choose, select the one that reads as (Status: Up ...)
      • If your machine contains a more complex networking setup, you may need to try different adapters until you find one that works, or ask your network administrator for help.

   2. The virtual machine will now power on and begin booting.

      • This will open another terminal window that may briefly display a lot of output.
      • While waiting for hte VM to boot, your Powershell window will display “Waiting for VM to start…” periodically until the VM is fully booted.

   3. In the Powershell window, you will see the detected IP address of the VM, which will be used to access Porta later.

      • For example: VM is running with IP: 10.221.113.136

      Tip

      If the IP is 127.0.0.1, please see the Troubleshooting section for more information.

   4. You will be warned that the authenticity of the host can't be established and asked if you want to continue connecting.

   5. Typeyes and press Enter (the “yes” will not appear in the terminal, but it is still being entered)

   6. The terminal will display “SSH connection established successfully”.

      Caution

      If you encounter a “Failed to establish SSH connection” error, AND your IP address is displayed as 127.0.0.1, please see the VM IP Address is 127.0.0.1 troubleshooting section for more information.

      If you encounter a “Failed to establish SSH connection” error with a different IP, you will need to manually reset the identity and/or set up the static IP after VM setup has completed. Please see the Resetting Identity and Manual Static IP Setup guides for instructions.

   7. Setting up firewall rules is optional, and you can decline to set them up by typing n and pressing Enter.

7. Resetting Identity

   Note

   If you are only running one virtual machine, you may decline to reset the identity by entering n and pressing Enter, then proceeding to the next step, “Setting Static IP Address”.

   1. If you are running multiple virtual machines, enter y and press Enter.
   2. Enter a new hostname or simply press Enter to use the default suggested hostname.
   3. You will be prompted for the password again a couple of times, then the VM will reboot.
      • After about 30 seconds, the VM will be back online.
      • It’s not uncommon to encounter a timeout error when the VM is rebooting, see the Timed out waiting for VM to come online section if this happens. 4.The script will then get a new IP address for the VM and print it to the terminal.
      • You may be prompted for password several more times.

8. Setting Static IP Address

   The script will automatically proceed to set up a static IP for the VM.

   1. The script will perform a network scan to find available IP addresses on your network.

      Caution

      If the network scan fails to complete or doesn’t find any available IPs, you’ll be asked “Would you like to manually enter an IP address?”

      • To be prompted to enter a custom IP address of your choosing, type y and press Enter.
      • To decline and set up the static IP manually later, type n and press Enter.
        • The script will skip the static IP setup and proceed to the completion step.
        • After the setup completes, you’ll need to manually configure the static IP on the VM. Please see the VM Static IP Setup guide for instructions.
   2. Select an IP address for the virtual machine by typing the number corresponding to one of the listed available IPs and pressing Enter.
      • If you choose to enter a custom IP address:
        • Enter the full IP address (e.g., 192.168.1.100)
        • If the IP appears to be in use, you’ll be asked to confirm by typing y and pressing Enter
   3. Next, select the machine role (also known as its type) by entering the number corresponding to one of the following options and pressing Enter:
      1. main
      2. backup
      3. arbiter

      Note

      If you’re only using one machine for Porta, select 1 formain

   4. The script will then proceed to configure the VM with the selected static IP address and machine role.
      • You will see a lot of output in the terminal, including password prompts, but you can ignore it.
   5. When IP configuration is complete, the script will print “Static IP setup completed successfully! VM is now accessible at IP:” and list the new static IP address.

   Caution

   IMPORTANT NOTE: If you are setting up multiple Porta VMs, their IP addresses should be sequential (e.g., 10.100.100.10, 10.100.100.11, 10.100.100.12).

   Otherwise you must manually configure the hosts file of each VM correctly after setup has completed. Please see the Manual Static IP Setup guide’s Manually configuring the hosts file section for instructions.

9. Completed

   Once the setup has finished, your VM is ready to use!

   • Access the Porta Manager (installer wizard) in the browser at the VM’s IP address and port88: http://VM-IP:88.
   • Porta Manager’s login credentials are:
     • Email address: superadmin@disguise.one
     • Password: The Porta VM password
   • After signing in, you can click the “Begin” button on the dashboard to use the installer wizard to install Porta.
     • Make sure you have downloaded the latest Porta On Prem bundle and have it ready to upload when prompted by the installer wizard.

Warning

If static IP address setup, or SSH connection, failed or was skipped during the VM setup, don’t forget to manually set up the static IP.

---

Troubleshooting common issues during VM setup

ACPI Shutdown is taking longer than 3 minutes

Force the machine to stop:

• In the VM’s terminal window, File > Close > Power Off Machine.

Once the VM terminal window has closed, in VirtualBox, start it again by double-clicking the VM in the sidebar, or selecting it and clicking the Start button in the header.

Timed out waiting for VM to come online / VM takes too long at any given step

The error “Timed out waiting for VM to come online” is not uncommon during IP setup or resetting identity. Try the following steps:

1. First, we will try to gracefully shut down the machine.
   • In the VM’s terminal window, File > Close > ACPI Shutdown
2. If this does not begin printing new output to the window, or is taking more than a minute or two to complete, you can force the machine to stop:
   • In the VM’s terminal window, File > Close > Power Off Machine.
3. Return to your initial Powershell window and enter Ctrl+C to stop the VM setup script.
4. Re-run the setup_vm.ps1 script by hitting the Up arrow on your keyboard so that the setup_vm.ps1 command from the beginning of this guide appears, and then hitting Enter.
5. Continue as before until the VM Selection step.
6. When prompted to import a new Porta VM or use and existing one, type 2 and press Enter.
7. You’ll see a list of available VMs with their current status (running or stopped).
8. Select the VM you previously imported by typing its listed number and hitting Enter.
9. If the VM is not already running, the script will start it.
10. Continue with the steps from Network Configuration above.

Failed to establish SSH connection

If you encounter this error during the Network Configuration step, AND your IP was listed as 127.0.0.1, see VM IP Address is 127.0.0.1 below.

If you encounter this error during the Resetting Identity step, then after VM setup has completed you will need to manually reset the VM’s identity and manually set up a static IP for the machine. Please see the Manually Resetting Identity and VM Static IP Setup guides for instructions.

If you encounter this error during the Setting Static IP Address step, you will need to manually set up the static IP after VM setup has completed. Please see the VM Static IP Setup guide for instructions.

VM IP address is 127.0.0.1

VirtualBox is probably not connected to the correct network adapter, or DHCP is not working. Take these steps to try to resolve the issue:

1. Shutdown the VM if it is running.
2. Open Powershell in Windows and run ipconfig /all to list all adapters and their names.
3. Open VirtualBox and navigate to the VM’s Settings -> Network Settings.
4. Ensure the Vm’s “Attached to” is set to “Bridged Adapter” and the selected “Name” matches the name of the adapter you want to use, as listed in theipconfig results.
5. Start the VM and try again.

”No available IPs found”

Sometimes the network scan fails to complete or doesn’t find any available IPs. There are a few scenarios in which this can occur, and the solution depends on which.

• If this issue occurs during the Resetting Identity step, you will need to manually reset the identity and/or set up the static IP after VM setup has completed. Please see the Manually Resetting Identity and Manual Static IP Setup guides for instructions.
• If this issue occurs during the Setting Static IP Address step, you’ll need to configure an IP manually after VM setup has completed. Please see the VM Static IP Setup guide for instructions.

VirtualBox error when importing appliance: E_INVALIDARG 0X80070057

Likely a disk space issue. Make sure the default location for the VM is on a drive with enough space.

• In VirtualBox, go to File > Preferences > General and change the Default Machine Folder if needed.

VM booting is stuck on “Begin: Loading essential drivers”

Shut down the VM and go into the VM’s VirtualBox Settings -> Storage. Make sure these are set as expected. Checking the Solid State box for the SATA hard disk resolved the issue when last seen.

rcu: detected stalls on CPUs/tasks or other similar errors in the VM terminal

This indicates the VM is struggling with resources. Normally restarting the VM will resolve the issues. Gracefully shut down the VM by navigating to the VM’s terminal window and clicking File > Close > ACPI Shutdown.

If this does not begin printing new output to the window, or is taking more than a minute or two to complete, you can force the machine to stop by navigating to the VM’s terminal window, and clicking File > Close > Power Off Machine.

If this error becomes a common occurrence, please make confirm that your physical machine meets the VM requirements, and, if so, contact Disguise support.

systemd-networkd.service: Watchdog timeout message / array-index-out-of-bounds message in the VM terminal

This message can appear during setup, and is usually not a problem. If the setup completes successfully, you can ignore this message.

VM Disk Space Issues

If you encounter disk space issues on the VM (not Windows itself), check Docker’s filesystem by running this command in the VM’s terminal:

docker system df

Here is an example of what you may see:

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          12        4         13.77GB   10.3GB (74%)
Containers      4         4         360MB     0B (0%)
Local Volumes   7         3         6.55GB    6.334GB (96%)
Build Cache     0         0         0B        0B

If the Images “Reclaimable” space is significant, you can free it up by connecting to the VM and running:

docker image prune -af

If you still need more space, please contact Disguise support for assistance.