Web Stack Migration to Virtual Appliance

Moving to the Virtual Appliance from Web Stack is both an upgrade and a migration. It’s an upgrade to a new on-prem version of PrinterLogic, but it is also a migration to a different platform. Web Stack runs on a Windows server and the Virtual Appliance comes as a pre-installed Virtual Appliance running on Ubuntu server utilizing Docker containers and microservices. The MySQL database gets migrated during the process, which includes the configuration, printer drivers and reporting data.

Prerequisites and Requirements

Minimum System Requirements

Authorization codes are required on the Virtual Appliance. This will ensure communication and security between the client and Virtual Appliance.

Readiness Checklist

1. Web Stack instance must be at version 19.1 Service Pack 3.
2. MySQL must be version 8 or higher. Contact PrinterLogic support for instructions to upgrade MySQL.

   If an update needs to be made, as a best practice, make sure to make a backup of the printer_installer database before performing the MySQL update.

3. MySQL configured to allow external access.
   1. Locate your root password. This is found in c:\inetpub\wwwroot\config\settings.php

   2. Open a MySQL command prompt from the Web Stack server and run the following query (all on one line):

      use mysql; update user set host='%' where user='root' and host='localhost'; flush privileges;

   Opening a MySQL command prompt
   • On the server hosting Web Stack, open the Start Menu.
   • Select MySQL from the menu items.
   • Select the MySQL 8.0 Command Line Client option.
   Copy Code

   use mysql; update user set host='%' where user='root' and host='localhost'; flush privileges;

   3. When you are prompted for a password, enter the root password obtained in step a.

4. DNS configured properly.
   1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
   2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
   3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
5. SSL certificates created and available.
   1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
6. Verify if your current Web Stack instance is configured to use authorization codes and if the clients were installed with authorization codes. This will help determine the type of cut-over performed.
   1. Check the OAUTH_ENABLED and ALWAYS_GRANT_READ_INSTANCE_SCOPE in the C:\inetpub\wwwroot\.env file.
      1. If ALWAYS_GRANT_READ_INSTANCE_SCOPE=false and OAUTH_ENABLED=true, this indicates that Auth Codes are being used. You can then check to see if you have a non-expiring Auth Code by going to Tools > Authorized Devices in the Admin Console. If so, then Auth Codes won’t be an issue if a DNS cut-over is desired.
      2. If ALWAYS_GRANT_READ_INSTANCE_SCOPE=true and OAUTH_ENABLED=true, this indicates that Auth codes aren’t being used, but the handshake has been authorized. Therefore, a DNS cut-over can still be successful. If it is not, it would require a reinstallation of clients. A Client Cut-over is the recommended option in this case.
      3. If ALWAYS_GRANT_READ_INSTANCE_SCOPE=true and OAUTH_ENABLED=false, this indicates Auth Codes are not required and are not being used. A DNS cut-over would require a client to reinstall during the cut-over, which will be challenging to do if all workstations are not accessible during cut-over. A Client Cut-over is the recommended option in this case.
7. Open ports for DB access from your machine:
   1. TCP 3306 - MySQL
   2. TCP 80 - HTTP
   3. TCP 443 - HTTPS
   4. TCP 8000 - Configuration API
   5. TCP 8080 - Configuration UI
   6. TCP 445 - SMB

Migration Stages

1. Ensure the readiness checklist is complete.
2. Decide on type of cut-over desired (DNS cut-over vs. Client cut-over). Note the requirements above for DNS cut-over.
3. Deploy the Virtual Appliance using a supported hypervisor:
   1. Hyper-V
   2. Workstation Pro
   3. ESXi
   4. Google Cloud Platform
   5. New Install: Virtual Machine Manager

   (Hypervisor deployment steps are also included in Step 6 of each cutover option below)

4. Perform the migration from Web Stack to the newly configured Virtual Appliance.
   1. DNS Cut-over
   2. Client Cut-over
   
   

Option 1 – Client Cut-over

With this method, you will end up with a different FQDN than the current prod environment. It also requires a re-install of the client, which gets it re-homed and updated. The advantage of this method is that you can do more testing of the Virtual Appliance environment and you don’t have the downtime of a single all-at-once cut-over. Another advantage is you don’t have to create two sets of license files, DNS records and cert files.

A potential downside of this method is you have to re-install all the clients to achieve the cut-over and you have to choose a different FQDN.

Client Cut-over Steps

This example will use printers.company.org as the production FQDN running on Web Stack. The Web Stack server’s host name is server1.company.org and is also listed in the license file. The FQDN for the Virtual Appliance will be printers2.company.org. After the cut-over, the production FQDN will be printers2.company.org.

1. If Web Stack is not running on version 19.1 SP3, perform an upgrade to 19.1 SP3.
2. If the version of MySQL is 5.5, upgrade MySQL to version 8 or higher.
   • Contact PrinterLogic support for instructions to upgrade MySQL at support@printerlogic.com.
3. Create a DNS A record for the FQDN of the Virtual Appliance (printers2.company.org) and a wildcard CNAME record for the wildcard underneath the FQDN of the Virtual Appliance (*.printers2.company.org) which points to the FQDN of the Virtual Appliance (printers2.company.org).
4. [Optional] If you plan on using any features that require HTTPS, create both:
   • A SAN certificate (following the Virtual Appliance SSL Certificates) for the FQDN of the Virtual Appliance (printers2.company.org)
   • And the wildcard underneath the FQDN of the Virtual Appliance (*.printers2.company.org),
5. Download the latest Virtual Appliance image. Release Notes 2024.
   • Links are also included in the drop-downs below.
6. Deploy the image to your hypervisor.
   • ESXi Prerequisites and Hypervisor Steps

     Prerequisites

     1. Download the Virtual Appliance ova file.
     2. DNS configured properly.
        1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
        2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
        3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
     3. SSL certificates created and available.
        1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
     4. Open ports for DB access from your machine:
        1. TCP 3306 - MySQL
        2. TCP 80 - HTTP
        3. TCP 443 - HTTPS
        4. TCP 8000 - Configuration API
        5. TCP 8080 - Configuration UI
        6. TCP 445 - SMB

     5. (Optional) If you are using advanced features requiring a Service Client, you must ensure the Service Client gets appropriately configured. See Set up a service client for more information.

     Configure Virtual Machine

     1. Connect to your ESXi web management interface.

        

     2. From the Virtual Machines object, choose the action Create/Register VM.

        

     3. Choose Deploy a virtual machine from an OVF or OVA file, and click Next.

        

     4. Enter the name for the VM and then Click to select files, and select the OVA file you downloaded earlier.

        

     5. With the OVA file selected, click Next, and allow time for the OVA file to be extracted.

        

     6. Select the storage to be used for the VM and click Next.

        

     7. Select the Network mapping for the VM, select whether you want Thin or Thick Disk provisioning, and un-check the Power on automatically option so you can configure other settings prior to powering on. Click on Next.

        

     8. Review your settings summary and then click Finish. Wait for upload to complete.

        

     9. Select the newly created VM and then click Edit.

        

     10. Increase the memory to 16 GB minimum.

         PrinterLogic recommends 16GB RAM for up to 15,000 users (add 8GB for every additional 15,000 users)

         

     11. Click Add hard disk, then select New standard hard disk.

         

     12. Select the new hard disk and adjust to the recommended minimum size of 50 GB.

         

         PrinterLogic recommends a minimum of 50 GB free persistent hard disk space (add 4 GB for every 100 printers).

     13. Click the drop-down arrow next to the New Hard Disk and adjust the location, Disk Provisioning and other settings as needed. Click on Save.

         

     14. Power on the VM and open a console to it.

         

     15. Click on Console.

         

     16. After VM starts, document the displayed IP address given.

     17. Copy down the displayed login and password displayed to be able to access the network settings. This will be needed if you choose to configure static IP settings or make adjustments to IP address ranges.

         

         If you will be using a fully qualified domain name for accessing your Virtual Appliance, you should configure it in DNS and assign it the IP address shown on this console. You would also need to have the license file that PrinterLogic provides to contain the same FQDN for the licensed URL. When you are done with configuration from the above URL, the system will redirect you to the FQDN/URL you have in your license. If you are just testing and don’t need to manage more than 5 printers, you can continue to access the server via IP.

   • HyperV Prerequisites and Hypervisor Steps

     Prerequisites

     1. Download the latest Virtual Appliance vhd.xz file.
     2. After downloading the vhd.xz file, you will need to extract the VHD from the vhd.xz file. The extracted VHD file should then be placed in your Hyper-V server folder.
     3. DNS configured properly.
        1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
        2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
        3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
     4. SSL certificates created and available.
        1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
     5. Open ports for DB access from your machine:
        1. TCP 3306 - MySQL
        2. TCP 80 - HTTP
        3. TCP 443 - HTTPS
        4. TCP 8000 - Configuration API
        5. TCP 8080 - Configuration UI
        6. TCP 445 - SMB
     6. (Optional) If you are using advanced features requiring a Service Client, you must ensure the Service Client gets appropriately configured. See Set up a service client for more information.

     Configure Virtual Machine

     1. Open up your Hyper-V Manager Console.

        

     2. Right click on your server, hover your pointer over New, then click on Virtual Machine.

        

     3. Click on Next.

        

     4. Specify the new Virtual Machines Name, then click Next.

        

     5. Select Generation 1 and click Next.

        

     6. Change the memory to 16000 MB and click Next.

        PrinterLogic recommends 16GB RAM for up to 15,000 users (add 4GB for every additional 15,000 users)

        

     7. Select the Virtual Switch you have configured in Hyper-V and click Next.

        

     8. Select the option to Use an existing virtual hard disk, and browse to the downloaded PrinterLogic VHD file. Select the file, and click on Next.

        

     9. Click Finish at the bottom of the summary screen.

        

     10. In the Actions pane to the right, under the virtual machine you just created, click on Settings.

         

     11. With Add Hardware selected in the left pane and SCSI Controller selected in the right pick list, click on Add.

         

     12. Select Hard Drive, and click Add.

         

     13. Select New.

         

     14. Click Next.

     15. Keep the default VHDX selected and click on Next.

         

     16. Select the appropriate disk type for your environment and click Next.

         

     17. Name the disk, and click Next.

         

     18. Select the new hard disk and adjust to the recommended minimum size of 50 GB and click Next.

         PrinterLogic recommends 50GB free persistent hard disk space (add 4GB for every 100 printers).

         

     19. Review the summary page and then click Finish.

         

     20. After the wizard finishes building you will be returned to the Settings dialog.

     21. Select Processor from the left pane and increase to a minimum of 4 processors.

         PrinterLogic recommends four 3.5-4.0 GHz processors. Add two 3.5 GHz processors for each additional 15,000 users.

         

     22. Click on OK.

     23. In the VM's action pane click on Start.

         

     24. After the VM starts, open the VM screen and annotate the provided IP address.

     25. Log in using the displayed login and password to configure the network settings. This allows you to configure a static IP, default gateway, search domain, subnet IP address ranges, and the DNS servers.

         

         If you will be using a fully qualified domain name for accessing your Virtual Appliance, you should configure it in DNS and assign it the IP address shown on this console. You would also need to have the license file that PrinterLogic provides to contain the same FQDN for the licensed URL. When you are done with configuration from the above URL, the system will redirect you to the FQDN/URL you have in your license. If you are just testing and don’t need to manage more than 5 printers, you can continue to access the server via IP.

   • VM Workstation Pro Prerequisites and Hypervisor Steps

     Prerequisites

     1. Download the Virtual Appliance ova file.
     2. DNS configured properly.
        1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
        2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
        3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
     3. SSL certificates created and available.
        1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
     4. Open ports for DB access from your machine:
        1. TCP 3306 - MySQL
        2. TCP 80 - HTTP
        3. TCP 443 - HTTPS
        4. TCP 8000 - Configuration API
        5. TCP 8080 - Configuration UI
        6. TCP 445 - SMB
     5. (Optional) If you are using advanced features requiring a Service Client, you must ensure the Service Client gets appropriately configured. See Set up a service client for more information.

     Configure Virtual Machine

     Virtual Appliance should be able to work on any supported version of VM Workstation Pro, but it has been successfully tested on versions 12 and 15.

     1. Open VMWare Workstation Pro.

     2. Click Open a Virtual Machine.

        

     3. Navigate to the .ova file you downloaded.

        

     4. Click Open.

     5. Click Edit virtual machine settings.

        

     6. Click Network Adapter.

        

     7. Select Bridged: Connected directly to the physical network (if it is not already selected).

        

     8. Click Add.

        

     9. Select Hard Disk and click Next.

        

     10. Keep SCSI selected and click Next.

         

     11. Keep Create a new virtual disk selected and click Next.

         

     12. Adjust the disk size to the minimum recommended setting of 50 GB and click Next.

         PrinterLogic recommends 50GB free persistent hard disk space (add 4GB for every 100 printers).

         

     13. Click Finish.

         

     14. Click OK.

     15. Click Power on this virtual machine.

         

     16. When the virtual machine loads, you will see the following message.

         

     17. The IP address will be specific to your PrinterLogic Virtual Appliance. You will want to note it for a following step.

     18. Copy down the displayed login and password displayed to be able to access the network settings. This will be needed if you choose to configure static IP settings..

         

         If you will be using a fully qualified domain name for accessing your Virtual Appliance, you should configure it in DNS and assign it the IP address shown on this console. You would also need to have the license file that PrinterLogic provides to contain the same FQDN for the licensed URL. When you are done with configuration from the above URL, the system will redirect you to the FQDN/URL you have in your license. If you are just testing and don’t need to manage more than 5 printers, you can continue to access the server via IP.

   • Google Cloud Platform Prerequisites and Steps

     Prerequisites

     1. Download the Virtual Appliance vmdk file.
     2. DNS configured properly.
        1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
        2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
        3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
     3. SSL certificates created and available.
        1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
     4. Open ports for DB access from your machine:
        1. TCP 3306 - MySQL
        2. TCP 80 - HTTP
        3. TCP 443 - HTTPS
        4. TCP 8000 - Configuration API
        5. TCP 8080 - Configuration UI
        6. TCP 445 - SMB
     5. (Optional) If you are using advanced features requiring a Service Client, you must ensure the Service Client gets appropriately configured. See Set up a service client for more information.

     Initial Configuration

     1. Log into Google Cloud Platform.

     2. Select Storage from the menu on the left.

        

     3. Either create a new storage bucket or select an existing storage bucket.

        

     4. After creating or selecting a storage bucket, select Upload Files.

        

     5. Upload the Virtual Machine Disk file (.vmdk) that was downloaded in the prerequisites.

        It is recommended that this step be done from a PC with an internet connection that supports high upload speeds due to the large file size.

     Convert the VMDK

     This process can take up to 40mn.

     1. Back on the Google Cloud Platform home screen, select Compute Engine from the left side menu.

        

     2. From the new menu displayed on the left, select Images.

        

     3. From the top menu, select Create Image.

        

     4. On the Create Image screen:
        1. Give it a name.
        2. Select Virtual disk (VMDK, VHD) as the source to be used.
        3. Select the Cloud Storage File
        4. In the Operating system on virtual disk section, Select Ubuntu 18.04 Bionic.
        5. Ensure that the Install guest packages box is checked.

        6. Click on Create.

           

     Configure the Image

     1. Back on the Google Cloud Platform home screen, select Compute Engine from the left side menu.

        

     2. From the new menu displayed on the left, select Images.

        

     3. Click on the newly created image name, then select Create Instance at the top.

        

     4. Give the instance a name, select appropriate Region and Zone, and select the Machine Type that meets the recommended system requirements of:

        2. Four 3.5-4.0 GHz processors. Add two 3.5 GHz processors for each additional 15,000 users.
        3. 16GB RAM for up to 15,000 users.
           • Add 2 CPUs / 8GB RAM for each additional 15,000 users.
           • Add a minimum of 2 CPUs and 4GB RAM if using the Internal Service Client.
           • Add 2 CPUs and 4GB RAM per 500 CPA/Simple Badge Release installations.
        4. 150GB free hard disk space for the host disk.
        5. There should be 50GB of free hard disk space on the persistent storage disk (add 4GB for every 100 printers).

        

        Port 8080, 8000, 3306 and 443 must be open to complete the setup phase.

     5. Scroll down to the Firewall section and select the appropriate settings to allow your workstation to communicate with the Virtual Appliance.

        

     6. Select Disks, and then scroll down and select the Add new disk button.

        

     7. Give the new disk a name and set a size (50 GB is recommended).

        

     8. Scroll down and select Done on the bottom left.

     9. Click Create on the bottom left.

        

     10. Start the newly created VM instance.

     11. Locate the IP of the newly created virtual machine and copy it.

         

         If you will be using a fully qualified domain name for accessing your Virtual Appliance, you should configure it in DNS and assign it the IP address shown on this console. You would also need to have the license file that PrinterLogic provides to contain the same FQDN for the licensed URL. When you are done with configuration from the above URL, the system will redirect you to the FQDN/URL you have in your license. If you are just testing and don’t need to manage more than 5 printers, you can continue to access the server via IP.

   • AWS Prerequisites and Steps

     Prerequisites

     1. Contact your PrinterLogic sales representative to provide you with access to the Virtual Appliance AMI.

        Only a PrinterLogic representative can provide the Virtual Appliance AMI. It is not available as a Public AMI.

     2. DNS configured properly.
        1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
        2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
        3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
     3. SSL certificates created and available.
        1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
     4. Open ports for DB access from your machine:
        1. TCP 3306 - MySQL
        2. TCP 80 - HTTP
        3. TCP 443 - HTTPS
        4. TCP 8000 - Configuration API
        5. TCP 8080 - Configuration UI
        6. TCP 445 - SMB
     5. (Optional) If you are using advanced features requiring a Service Client, you must ensure the Service Client gets appropriately configured. See Set up a service client for more information.

     Setup

     AWS is a supported platform to run the PrinterLogic Virtual Appliance. Currently, a PrinterLogic sales representative will need to assist you with getting access to the AMI.

     Please be prepared to provide the PrinterLogic sales representative with your AWS Account number so they can share the most current AMI to your account. You can find your account number in your AWS console by clicking on the drop-down next to your login name.

     

     Copy the AMI

     1. In your AWS EC2 Dashboard, in the Images drop-down, select AMIs.

        

     2. Set your AWS region to the region provided by your PrinterLogic representative.

        

     3. On the AMI list screen, select Private Images.

        

     4. Locate the AMI that was provided to you in the list.
     5. Right click the image and select Copy AMI.

     6. On the Copy AMI screen, select your Destination Region and click Copy AMI.

        The copy process can take several minutes to complete.

     7. Back on the AMI screen, select the region you copied the AMI to.

     8. Locate the AMI you just copied from the list.

        The copied AMI will display a different AMI ID now that it is in your region. However, the AMI name will stay the same.

     9. Rename or tag the AMI as needed for your use.

     Launch the AMI

     1. Right click on the AMI and select Launch Instance from AMI.
     2. Provide the Virtual Appliance instance a name.
     3. Scroll down and select the Instance type ensuring you are meeting the Web Stack Migration to Virtual Appliance.
     4. Scroll down and select the Key Pair (login) you want to use.
     5. Scroll down to the Network settings section and select the VPC you want the instance installed in.
     6. Select the Subnet you want the instance deployed to.

     

     7. In the Firewall (security groups) section, select your Existing security group if you have configured a Virtual Appliance in the past. If this is your first deployment in AWS, it will be necessary to create a security group following the steps in the drop-down option below:

        Create a Security Group for PrinterLogic Virtual Appliance

        1. In the Firewall (security group) section, select Create Security Group.
        2. Enter a Security Group Name.
        3. Enter a Description for the security group.

        4. Enter the following security group rules:

           Security Group Rules

           Type	Protocol	Port	Source
           MySQL/Aurora	TCP	3306	Anywhere
           HTTP	TCP	80	Anywhere
           HTTPS	TCP	443	Anywhere
           Custom TCP	TCP	8000	Anywhere
           Custom TCP	TCP	8080	Anywhere
           SMB	TCP	445	Anywhere
           Custom ICMP - IPv4	Echo Request	8	Anywhere

     8. The Advance Network Configuration section is optional for the following scenario:
        1. If a Static IP address for the Virtual Appliance is desired:
           1. Create a Network Interface and assign it the desired IP address.
           2. Attach that network interface in these settings.
        2. If DHCP will be used, nothing needs to be done with these settings.

     9. Scroll down to the Configure Storage section and ensure there's a minimum of 80 GB. We also suggest that an SSD (gp3) gets used to offer the ability to specify IOPS for the volume.

        Do not add the additional data volume at this time. You will add that in a later step..

     10. Scroll down to the Advanced Details section and expand it.

     11. Scroll to the bottom and paste the following code into the User Data field.

         Set the DOCKER_NETWORK IP address to the desired private TCP/IP network with a /20 or lower.

         Copy Code

         #!/bin/bash -x
         DOCKER_NETWORK="172.16.0.0/16"
         echo "*** cloud-init script begin ***"
         # Wait for Docker to become available
         until systemctl is-active docker >/dev/null 2>&1
         do
           echo "Waiting for Docker to become available..."
           sleep 5
         done
         echo "Setting Docker network to $DOCKER_NETWORK..."
         set-network "$DOCKER_NETWORK"
         echo "*** cloud-init script end ***"

     12. Select Launch Instance.
     13. Select View All Instances.
     14. Wait for the Virtual Appliance instance to completely launch.

     Attach Data Volume

     1. Select Volumes under the Elastic Block Store section of the menu.

        

     2. Click on Create Volume.
     3. Select the Volume Type. It is suggested that an SSD (gp3) be used to give the ability to specify IOPS for the volume.

     4. Select the Volume Size.

        PrinterLogic recommends a minimum of 50 GB of free persistent hard disk space (add 4 GB for every 100 additional printers).

     5. Select the Availability Zone, ensuring it is in the same zone as your Virtual Appliance instance.

        

     6. (Optional) Select the Encryption checkbox and your desired master key if you want drive encryption.

     7. Click on Click to add a Name tag, and give your volume a name.

        

     8. Click on Create Volume.
     9. The Volume Created Successfully message will display, click on Close to return to your list of volumes.

     10. Locate the newly created volume, right-click on it, and select Attach Volume.

         

     11. In the instance field, select the Virtual Appliance you just created.

     12. In the Device field, enter /dev/sdp.

         

     13. Click on Attach.
     14. Return to your Virtual Appliance instance by clicking on Instances.
     15. Locate and select your Virtual Appliance instance.

     16. Copy the IP Address of your Virtual Appliance.

         

7. If not already started, start the Virtual Appliance.
8. For VM Workstation Pro, HyperV, and ESXi hypervisors ONLY. (For AWS and Google Cloud Platform skip to Step 9.)
   • Launch the remote VM console of your hypervisor and login to the Virtual Appliance Console with the network user credentials specified. Configure TCP/IP settings as applicable (use either manual settings or DHCP reservation).
   • The Virtual Appliance starts as a DHCP client. It’s possible to leave it that way and configure the TCP/IP settings via DHCP Reservation. Otherwise, use the steps below to configure a static IP and to optionally change the private IP range that the Virtual Appliance uses by default so that it doesn’t conflict with existing subnets in the environment.
   • Login to the Virtual Appliance Console and Configure Network Settings

     1. In the hypervisor where the Virtual Appliance runs, open the web console to access the Virtual Appliance Linux terminal interface.
     2. Login with the credentials supplied in the terminal banner for the network user.

        

     3. Enter "Y" to change the network settings.
     4. Enter "Y" to change the network mode.

     5. Enter the TCP/IP settings.

        The image below is just an example. Ensure you use the settings specific to your network.

        

     6. If the existing address pool does not conflict with any subnets in the environment, enter “N”. Otherwise, enter “Y” to set a different address range.

        

        If needing to adjust IP addresses, be sure to read and understand the network range options you are presented with. Any range used must have a netmask < 20.

        

     7. If needing to adjust the IP address ranges, configure the address range.

        The image below is just an example. Ensure you use the settings specific to your network.

        

     8. Press any key to exit.

9. Run the Virtual Appliance Configuration UI by navigating to http://VA_IP_Address:8080 .

   

10. On the Configure Storage page, select VM-Attached Virtual Disk for the Storage Type and click Format Attached Storage.

    

11. Choose the Upgrade my Current Instance option.

    

12. On the Migrate Database page, enter the FQDN of the production Web Stack instance (printers.company.org) in the Host field.

    

13. Enter in your Username and Password.

    

14. Enter the APP_KEY from your Web Stack instance.

    Where can I find my Web Stack APP_KEY?

    1. Browse to your Web Stack .ENV file.
       1. Default path is: C:\intetpub\wwwroot\.env

    2. Open the file with a text editor and locate the APP_KEY and copy it.

       

    

By default, the Web Stack MySQL instance is configured to only allow local connections. If the MySQL Connection Test fails on this step, this restriction can be lifted so that the Virtual Appliance Migration can access the production MySQL database.

Run the following command at a MySQL Command Prompt on the production Web Stack server (the MySQL root password can be found inside the c:\inetpub\wwwroot\config\settings.php file on the production Web Stack instance):

use mysql; update user set host='%' where user='root' and host='localhost'; flush privileges;

Copy Code

use mysql; update user set host='%' where user='root' and host='localhost'; flush privileges;

To revert this setting, run the following command at a MySQL Command Prompt on the production Web Stack server:

use mysql; update user set host='localhost' where user='root' and host='%'; flush privileges;

Copy Code

use mysql; update user set host='localhost' where user='root' and host='%'; flush privileges;

15. On the General Settings page, enter the FQDN of the Virtual Appliance (printers2.company.org) in the Domain Name field. Keep the suggested Shared Storage Password or set it to something else, and click Continue. Ensure you document the password!

    

16. Request that your PrinterLogic representative give you your Virtual Appliance license that will match your Web Stack license capabilities, except use the new FQDN of the Virtual Appliance (printers2.company.org).

    

17. [Optional] If you created a SSL certificate for the Virtual Appliance, upload the certificate and key here, and click Continue.

    

18. Select Continue on the Setup Database page.

19. Click the final Finish Upgrade button and wait for it to complete.

    

    A large database could take a couple hours to complete.

20. Perform any testing with clients that are re-homed to printers2.company.org.

21. After successful testing, setup the uninstall/reinstall script and start pushing it out.

    1. To uninstall/reinstall the client follow these steps:
       1. In Apps and Features, uninstall the Printer Installer Client.
       2. Delete the following directory on the workstation: C:\Program Files (X86)\Printer Properties Pro
       3. Install new client with new URL and Auth Code.

    Further information on Installing and Uninstalling the Client can be found in the PrinterLogic Client section.

22. New clients will start pointing to the Virtual Appliance and old clients will continue to point to Web Stack until they are updated.
23. After all the clients are converted, have your PrinterLogic representative update the prod license file to reflect the new single URL .
24. Copy the license file to the /pi/storage folder on the shared drive.

Option 2 – DNS Cut-over

This method eliminates the need to re-install the clients during cut-over. However, you will still want to update the clients after migration, since the latest client provided by Web Stack does not support every new feature in the Virtual Appliance. The clients can be updated after the migration using the auto-update settings in the Admin Console.

You will use a different (temporary) FQDN during the migration so that you can access both the Virtual Appliance and the Web Stack server while testing. This will require a temporary DNS A/CNAME record and license file as well. When you are ready to cut-over, shut down Web Stack, change the FQDN of the Virtual Appliance, the DNS A/CNAME records, and the license file to the production FQDN. The next time the clients check in, they will be accessing the Virtual Appliance instead of Web Stack.

A potential downside of this method is that you can’t test the Virtual Appliance with the production FQDN prior to cut-over (unless you are able to change DNS temporarily during off-hours). Because the Virtual Appliance leverages DNS to communicate with the individual microservices internally, it's not possible to simply change the hosts file on a workstation to test connectivity to the Virtual Appliance using a different IP for the FQDN. The Virtual Appliance will still be pointing to the company's DNS servers, which will not include these temporary DNS settings -- the production FQDN will still resolve to the Web Stack instance, and the Virtual Appliance microservices will fail on name resolution. The FQDN of the Virtual Appliance must be changed in the secrets.env file at the same time DNS is changed.

When editing the secrets.env file, an editor like Notepad ++, Sublime Text, or Visual Studio Code must be used to ensure the file uses Unix line endings (LF only) and is saved in UTF-8 format with no byte-order mark.

DNS Cut-over Steps

This example will use printers.company.org as the production FQDN running on Web Stack. The Web Stack server’s host name is server1.company.org and is also listed in the license file. The temporary FQDN for the Virtual Appliance will be va.company.org. After the cut-over, the Virtual Appliance will be using printers.company.org.

1. If Web Stack is not running on version 19.1 SP3, perform an upgrade to 19.1 SP3.
2. If the version of MySQL is 5.5, upgrade MySQL to version 8 or higher.
   • Contact PrinterLogic support for instructions to upgrade MySQL at support@printerlogic.com.
3. Create a DNS A record for the temporary FQDN of the Virtual Appliance (va.company.org) and a wildcard CNAME record for the wildcard underneath the temporary FQDN of the Virtual Appliance (*.va.company.org) which points to the temporary FQDN of the Virtual Appliance (va.company.org).
4. [Optional] If you plan on using any features that require HTTPS, create both:
   • A temporary SAN certificate (following the Virtual Appliance SSL Certificates) for the temporary FQDN of the Virtual Appliance (va.company.org).
   • And the wildcard underneath the temporary FQDN of the Virtual Appliance (*.va.company.org).
5. Download the latest Virtual Appliance image. Release Notes 2024.
   • Links are also included in the drop-downs below.
6. Deploy the image to your hypervisor.
   • ESXi Prerequisites and Hypervisor Steps

     Prerequisites

     1. Download the Virtual Appliance ova file.
     2. DNS configured properly.
        1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
        2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
        3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
     3. SSL certificates created and available.
        1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
     4. Open ports for DB access from your machine:
        1. TCP 3306 - MySQL
        2. TCP 80 - HTTP
        3. TCP 443 - HTTPS
        4. TCP 8000 - Configuration API
        5. TCP 8080 - Configuration UI
        6. TCP 445 - SMB

     5. (Optional) If you are using advanced features requiring a Service Client, you must ensure the Service Client gets appropriately configured. See Set up a service client for more information.

     Configure Virtual Machine

     1. Connect to your ESXi web management interface.

        

     2. From the Virtual Machines object, choose the action Create/Register VM.

        

     3. Choose Deploy a virtual machine from an OVF or OVA file, and click Next.

        

     4. Enter the name for the VM and then Click to select files, and select the OVA file you downloaded earlier.

        

     5. With the OVA file selected, click Next, and allow time for the OVA file to be extracted.

        

     6. Select the storage to be used for the VM and click Next.

        

     7. Select the Network mapping for the VM, select whether you want Thin or Thick Disk provisioning, and un-check the Power on automatically option so you can configure other settings prior to powering on. Click on Next.

        

     8. Review your settings summary and then click Finish. Wait for upload to complete.

        

     9. Select the newly created VM and then click Edit.

        

     10. Increase the memory to 16 GB minimum.

         PrinterLogic recommends 16GB RAM for up to 15,000 users (add 8GB for every additional 15,000 users)

         

     11. Click Add hard disk, then select New standard hard disk.

         

     12. Select the new hard disk and adjust to the recommended minimum size of 50 GB.

         

         PrinterLogic recommends a minimum of 50 GB free persistent hard disk space (add 4 GB for every 100 printers).

     13. Click the drop-down arrow next to the New Hard Disk and adjust the location, Disk Provisioning and other settings as needed. Click on Save.

         

     14. Power on the VM and open a console to it.

         

     15. Click on Console.

         

     16. After VM starts, document the displayed IP address given.

     17. Copy down the displayed login and password displayed to be able to access the network settings. This will be needed if you choose to configure static IP settings or make adjustments to IP address ranges.

         

         If you will be using a fully qualified domain name for accessing your Virtual Appliance, you should configure it in DNS and assign it the IP address shown on this console. You would also need to have the license file that PrinterLogic provides to contain the same FQDN for the licensed URL. When you are done with configuration from the above URL, the system will redirect you to the FQDN/URL you have in your license. If you are just testing and don’t need to manage more than 5 printers, you can continue to access the server via IP.

   • HyperV Prerequisites and Hypervisor Steps

     Prerequisites

     1. Download the latest Virtual Appliance vhd.xz file.
     2. After downloading the vhd.xz file, you will need to extract the VHD from the vhd.xz file. The extracted VHD file should then be placed in your Hyper-V server folder.
     3. DNS configured properly.
        1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
        2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
        3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
     4. SSL certificates created and available.
        1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
     5. Open ports for DB access from your machine:
        1. TCP 3306 - MySQL
        2. TCP 80 - HTTP
        3. TCP 443 - HTTPS
        4. TCP 8000 - Configuration API
        5. TCP 8080 - Configuration UI
        6. TCP 445 - SMB
     6. (Optional) If you are using advanced features requiring a Service Client, you must ensure the Service Client gets appropriately configured. See Set up a service client for more information.

     Configure Virtual Machine

     1. Open up your Hyper-V Manager Console.

        

     2. Right click on your server, hover your pointer over New, then click on Virtual Machine.

        

     3. Click on Next.

        

     4. Specify the new Virtual Machines Name, then click Next.

        

     5. Select Generation 1 and click Next.

        

     6. Change the memory to 16000 MB and click Next.

        PrinterLogic recommends 16GB RAM for up to 15,000 users (add 4GB for every additional 15,000 users)

        

     7. Select the Virtual Switch you have configured in Hyper-V and click Next.

        

     8. Select the option to Use an existing virtual hard disk, and browse to the downloaded PrinterLogic VHD file. Select the file, and click on Next.

        

     9. Click Finish at the bottom of the summary screen.

        

     10. In the Actions pane to the right, under the virtual machine you just created, click on Settings.

         

     11. With Add Hardware selected in the left pane and SCSI Controller selected in the right pick list, click on Add.

         

     12. Select Hard Drive, and click Add.

         

     13. Select New.

         

     14. Click Next.

     15. Keep the default VHDX selected and click on Next.

         

     16. Select the appropriate disk type for your environment and click Next.

         

     17. Name the disk, and click Next.

         

     18. Select the new hard disk and adjust to the recommended minimum size of 50 GB and click Next.

         PrinterLogic recommends 50GB free persistent hard disk space (add 4GB for every 100 printers).

         

     19. Review the summary page and then click Finish.

         

     20. After the wizard finishes building you will be returned to the Settings dialog.

     21. Select Processor from the left pane and increase to a minimum of 4 processors.

         PrinterLogic recommends four 3.5-4.0 GHz processors. Add two 3.5 GHz processors for each additional 15,000 users.

         

     22. Click on OK.

     23. In the VM's action pane click on Start.

         

     24. After the VM starts, open the VM screen and annotate the provided IP address.

     25. Log in using the displayed login and password to configure the network settings. This allows you to configure a static IP, default gateway, search domain, subnet IP address ranges, and the DNS servers.

         

         If you will be using a fully qualified domain name for accessing your Virtual Appliance, you should configure it in DNS and assign it the IP address shown on this console. You would also need to have the license file that PrinterLogic provides to contain the same FQDN for the licensed URL. When you are done with configuration from the above URL, the system will redirect you to the FQDN/URL you have in your license. If you are just testing and don’t need to manage more than 5 printers, you can continue to access the server via IP.

   • VM Workstation Pro Prerequisites and Hypervisor Steps

     Prerequisites

     1. Download the Virtual Appliance ova file.
     2. DNS configured properly.
        1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
        2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
        3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
     3. SSL certificates created and available.
        1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
     4. Open ports for DB access from your machine:
        1. TCP 3306 - MySQL
        2. TCP 80 - HTTP
        3. TCP 443 - HTTPS
        4. TCP 8000 - Configuration API
        5. TCP 8080 - Configuration UI
        6. TCP 445 - SMB
     5. (Optional) If you are using advanced features requiring a Service Client, you must ensure the Service Client gets appropriately configured. See Set up a service client for more information.

     Configure Virtual Machine

     Virtual Appliance should be able to work on any supported version of VM Workstation Pro, but it has been successfully tested on versions 12 and 15.

     1. Open VMWare Workstation Pro.

     2. Click Open a Virtual Machine.

        

     3. Navigate to the .ova file you downloaded.

        

     4. Click Open.

     5. Click Edit virtual machine settings.

        

     6. Click Network Adapter.

        

     7. Select Bridged: Connected directly to the physical network (if it is not already selected).

        

     8. Click Add.

        

     9. Select Hard Disk and click Next.

        

     10. Keep SCSI selected and click Next.

         

     11. Keep Create a new virtual disk selected and click Next.

         

     12. Adjust the disk size to the minimum recommended setting of 50 GB and click Next.

         PrinterLogic recommends 50GB free persistent hard disk space (add 4GB for every 100 printers).

         

     13. Click Finish.

         

     14. Click OK.

     15. Click Power on this virtual machine.

         

     16. When the virtual machine loads, you will see the following message.

         

     17. The IP address will be specific to your PrinterLogic Virtual Appliance. You will want to note it for a following step.

     18. Copy down the displayed login and password displayed to be able to access the network settings. This will be needed if you choose to configure static IP settings..

         

         If you will be using a fully qualified domain name for accessing your Virtual Appliance, you should configure it in DNS and assign it the IP address shown on this console. You would also need to have the license file that PrinterLogic provides to contain the same FQDN for the licensed URL. When you are done with configuration from the above URL, the system will redirect you to the FQDN/URL you have in your license. If you are just testing and don’t need to manage more than 5 printers, you can continue to access the server via IP.

   • Google Cloud Platform Prerequisites and Steps

     Prerequisites

     1. Download the Virtual Appliance vmdk file.
     2. DNS configured properly.
        1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
        2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
        3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
     3. SSL certificates created and available.
        1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
     4. Open ports for DB access from your machine:
        1. TCP 3306 - MySQL
        2. TCP 80 - HTTP
        3. TCP 443 - HTTPS
        4. TCP 8000 - Configuration API
        5. TCP 8080 - Configuration UI
        6. TCP 445 - SMB
     5. (Optional) If you are using advanced features requiring a Service Client, you must ensure the Service Client gets appropriately configured. See Set up a service client for more information.

     Initial Configuration

     1. Log into Google Cloud Platform.

     2. Select Storage from the menu on the left.

        

     3. Either create a new storage bucket or select an existing storage bucket.

        

     4. After creating or selecting a storage bucket, select Upload Files.

        

     5. Upload the Virtual Machine Disk file (.vmdk) that was downloaded in the prerequisites.

        It is recommended that this step be done from a PC with an internet connection that supports high upload speeds due to the large file size.

     Convert the VMDK

     This process can take up to 40mn.

     1. Back on the Google Cloud Platform home screen, select Compute Engine from the left side menu.

        

     2. From the new menu displayed on the left, select Images.

        

     3. From the top menu, select Create Image.

        

     4. On the Create Image screen:
        1. Give it a name.
        2. Select Virtual disk (VMDK, VHD) as the source to be used.
        3. Select the Cloud Storage File
        4. In the Operating system on virtual disk section, Select Ubuntu 18.04 Bionic.
        5. Ensure that the Install guest packages box is checked.

        6. Click on Create.

           

     Configure the Image

     1. Back on the Google Cloud Platform home screen, select Compute Engine from the left side menu.

        

     2. From the new menu displayed on the left, select Images.

        

     3. Click on the newly created image name, then select Create Instance at the top.

        

     4. Give the instance a name, select appropriate Region and Zone, and select the Machine Type that meets the recommended system requirements of:

        2. Four 3.5-4.0 GHz processors. Add two 3.5 GHz processors for each additional 15,000 users.
        3. 16GB RAM for up to 15,000 users.
           • Add 2 CPUs / 8GB RAM for each additional 15,000 users.
           • Add a minimum of 2 CPUs and 4GB RAM if using the Internal Service Client.
           • Add 2 CPUs and 4GB RAM per 500 CPA/Simple Badge Release installations.
        4. 150GB free hard disk space for the host disk.
        5. There should be 50GB of free hard disk space on the persistent storage disk (add 4GB for every 100 printers).

        

        Port 8080, 8000, 3306 and 443 must be open to complete the setup phase.

     5. Scroll down to the Firewall section and select the appropriate settings to allow your workstation to communicate with the Virtual Appliance.

        

     6. Select Disks, and then scroll down and select the Add new disk button.

        

     7. Give the new disk a name and set a size (50 GB is recommended).

        

     8. Scroll down and select Done on the bottom left.

     9. Click Create on the bottom left.

        

     10. Start the newly created VM instance.

     11. Locate the IP of the newly created virtual machine and copy it.

         

         If you will be using a fully qualified domain name for accessing your Virtual Appliance, you should configure it in DNS and assign it the IP address shown on this console. You would also need to have the license file that PrinterLogic provides to contain the same FQDN for the licensed URL. When you are done with configuration from the above URL, the system will redirect you to the FQDN/URL you have in your license. If you are just testing and don’t need to manage more than 5 printers, you can continue to access the server via IP.

   • AWS Prerequisites and Steps

     Prerequisites

     1. Contact your PrinterLogic sales representative to provide you with access to the Virtual Appliance AMI.

        Only a PrinterLogic representative can provide the Virtual Appliance AMI. It is not available as a Public AMI.

     2. DNS configured properly.
        1. Identify a FQDN to use for the PrinterLogic Virtual Appliance (i.e., printerlogic.mycompany.com).
        2. Create an A record in DNS (i.e., printerlogic.mycompany.com) that points to the IP address of the Virtual Appliance.
        3. Create a CNAME record in DNS (i.e., *.printerlogic.mycompany.com) that points to the A record above (i.e., printerlogic.mycompany.com)
     3. SSL certificates created and available.
        1. The SubjectAlternativeName extension must list the two DNS entries above (i.e., printerlogic.mycompany.com and *.printerlogic.mycompany.com). In depth information can be found in the Virtual Appliance SSL Certificates document.
     4. Open ports for DB access from your machine:
        1. TCP 3306 - MySQL
        2. TCP 80 - HTTP
        3. TCP 443 - HTTPS
        4. TCP 8000 - Configuration API
        5. TCP 8080 - Configuration UI
        6. TCP 445 - SMB
     5. (Optional) If you are using advanced features requiring a Service Client, you must ensure the Service Client gets appropriately configured. See Set up a service client for more information.

     Setup

     AWS is a supported platform to run the PrinterLogic Virtual Appliance. Currently, a PrinterLogic sales representative will need to assist you with getting access to the AMI.

     Please be prepared to provide the PrinterLogic sales representative with your AWS Account number so they can share the most current AMI to your account. You can find your account number in your AWS console by clicking on the drop-down next to your login name.

     

     Copy the AMI

     1. In your AWS EC2 Dashboard, in the Images drop-down, select AMIs.

        

     2. Set your AWS region to the region provided by your PrinterLogic representative.

        

     3. On the AMI list screen, select Private Images.

        

     4. Locate the AMI that was provided to you in the list.
     5. Right click the image and select Copy AMI.

     6. On the Copy AMI screen, select your Destination Region and click Copy AMI.

        The copy process can take several minutes to complete.

     7. Back on the AMI screen, select the region you copied the AMI to.

     8. Locate the AMI you just copied from the list.

        The copied AMI will display a different AMI ID now that it is in your region. However, the AMI name will stay the same.

     9. Rename or tag the AMI as needed for your use.

     Launch the AMI

     1. Right click on the AMI and select Launch Instance from AMI.
     2. Provide the Virtual Appliance instance a name.
     3. Scroll down and select the Instance type ensuring you are meeting the Web Stack Migration to Virtual Appliance.
     4. Scroll down and select the Key Pair (login) you want to use.
     5. Scroll down to the Network settings section and select the VPC you want the instance installed in.
     6. Select the Subnet you want the instance deployed to.

     

     7. In the Firewall (security groups) section, select your Existing security group if you have configured a Virtual Appliance in the past. If this is your first deployment in AWS, it will be necessary to create a security group following the steps in the drop-down option below:

        Create a Security Group for PrinterLogic Virtual Appliance

        1. In the Firewall (security group) section, select Create Security Group.
        2. Enter a Security Group Name.
        3. Enter a Description for the security group.

        4. Enter the following security group rules:

           Security Group Rules

           Type	Protocol	Port	Source
           MySQL/Aurora	TCP	3306	Anywhere
           HTTP	TCP	80	Anywhere
           HTTPS	TCP	443	Anywhere
           Custom TCP	TCP	8000	Anywhere
           Custom TCP	TCP	8080	Anywhere
           SMB	TCP	445	Anywhere
           Custom ICMP - IPv4	Echo Request	8	Anywhere

     8. The Advance Network Configuration section is optional for the following scenario:
        1. If a Static IP address for the Virtual Appliance is desired:
           1. Create a Network Interface and assign it the desired IP address.
           2. Attach that network interface in these settings.
        2. If DHCP will be used, nothing needs to be done with these settings.

     9. Scroll down to the Configure Storage section and ensure there's a minimum of 80 GB. We also suggest that an SSD (gp3) gets used to offer the ability to specify IOPS for the volume.

        Do not add the additional data volume at this time. You will add that in a later step..

     10. Scroll down to the Advanced Details section and expand it.

     11. Scroll to the bottom and paste the following code into the User Data field.

         Set the DOCKER_NETWORK IP address to the desired private TCP/IP network with a /20 or lower.

         Copy Code

         #!/bin/bash -x
         DOCKER_NETWORK="172.16.0.0/16"
         echo "*** cloud-init script begin ***"
         # Wait for Docker to become available
         until systemctl is-active docker >/dev/null 2>&1
         do
           echo "Waiting for Docker to become available..."
           sleep 5
         done
         echo "Setting Docker network to $DOCKER_NETWORK..."
         set-network "$DOCKER_NETWORK"
         echo "*** cloud-init script end ***"

     12. Select Launch Instance.
     13. Select View All Instances.
     14. Wait for the Virtual Appliance instance to completely launch.

     Attach Data Volume

     1. Select Volumes under the Elastic Block Store section of the menu.

        

     2. Click on Create Volume.
     3. Select the Volume Type. It is suggested that an SSD (gp3) be used to give the ability to specify IOPS for the volume.

     4. Select the Volume Size.

        PrinterLogic recommends a minimum of 50 GB of free persistent hard disk space (add 4 GB for every 100 additional printers).

     5. Select the Availability Zone, ensuring it is in the same zone as your Virtual Appliance instance.

        

     6. (Optional) Select the Encryption checkbox and your desired master key if you want drive encryption.

     7. Click on Click to add a Name tag, and give your volume a name.

        

     8. Click on Create Volume.
     9. The Volume Created Successfully message will display, click on Close to return to your list of volumes.

     10. Locate the newly created volume, right-click on it, and select Attach Volume.

         

     11. In the instance field, select the Virtual Appliance you just created.

     12. In the Device field, enter /dev/sdp.

         

     13. Click on Attach.
     14. Return to your Virtual Appliance instance by clicking on Instances.
     15. Locate and select your Virtual Appliance instance.

     16. Copy the IP Address of your Virtual Appliance.

         

7. If not already started, start the Virtual Appliance.
8. For VM Workstation Pro, HyperV, and ESXi hypervisors ONLY. (For AWS and Google Cloud Platform skip to Step 9.)
   • Launch the remote VM console of your hypervisor and login to the Virtual Appliance Console with the network user credentials specified. Configure TCP/IP settings as applicable (use either manual settings or DHCP reservation).
   • The Virtual Appliance starts as a DHCP client. It’s possible to leave it that way and configure the TCP/IP settings via DHCP Reservation. Otherwise, use the steps below to configure a static IP and to optionally change the private IP range that the Virtual Appliance uses by default so that it doesn’t conflict with existing subnets in the environment.
   • Login to the Virtual Appliance Console and Configure Network Settings

     1. In the hypervisor where the Virtual Appliance runs, open the web console to access the Virtual Appliance Linux terminal interface.
     2. Login with the credentials supplied in the terminal banner for the network user.

        

     3. Enter "Y" to change the network settings.
     4. Enter "Y" to change the network mode.

     5. Enter the TCP/IP settings.

        The image below is just an example. Ensure you use the settings specific to your network.

        

     6. If the existing address pool does not conflict with any subnets in the environment, enter “N”. Otherwise, enter “Y” to set a different address range.

        

        If needing to adjust IP addresses, be sure to read and understand the network range options you are presented with. Any range used must have a netmask < 20.

        

     7. If needing to adjust the IP address ranges, configure the address range.

        The image below is just an example. Ensure you use the settings specific to your network.

        

     8. Press any key to exit.

9. Run the Virtual Appliance Configuration UI by navigating to http://VA_IP_Address:8080

   

10. Choose the Upgrade my Current Instance option.

    

11. On the Configure Storage page, select VM-Attached Virtual Disk for the Storage Type and click Format Attached Storage.

    

12. On the Migrate Database page, enter the IP Address of the production Web Stack instance (printers.company.org) in the Host field.

    

13. Enter in your Username and Password.

    

14. Enter the APP_KEY from your Web Stack instance.

    Where can I find my Web Stack APP_KEY?

    1. Browse to your Web Stack .ENV file.
       1. Default path is: C:\intetpub\wwwroot\.env

    2. Open the file with a text editor and locate the APP_KEY and copy it.

       

    

By default, the Web Stack MySQL instance is configured to only allow local connections. If the MySQL Connection Test fails on this step, this restriction can be lifted so that the Virtual Appliance Migration can access the production MySQL database.

Run the following command at a MySQL Command Prompt on the production Web Stack server (the MySQL root password can be found inside the c:\inetpub\wwwroot\config\settings.php file on the production Web Stack instance):

use mysql; update user set host='%' where user='root' and host='localhost'; flush privileges;

Copy Code

use mysql; update user set host='%' where user='root' and host='localhost'; flush privileges;

To revert this setting, run the following command at a MySQL Command Prompt on the production Web Stack server:

use mysql; update user set host='localhost' where user='root' and host='%'; flush privileges;

Copy Code

use mysql; update user set host='localhost' where user='root' and host='%'; flush privileges;

15. On the General Settings page, enter the temporary FQDN of the Virtual Appliance (va.company.org example used in image) in the Domain Name field. Keep the suggested Shared Storage Password or set it to something else, and click Continue. Ensure you document the password!

    Ensure that the entire FQDN is used and not just the domain name in the Domain field.
    Ensure you document and save the Shared Storage Password so you can access the Data Drive later as needed.

    

16. Request that your PrinterLogic representative create a trial license that will match your production license capabilities, except use the temporary FQDN of the Virtual Appliance (va.company.org).

    

17. [Optional] If you created a temporary SSL certificate for the Virtual Appliance, upload the certificate and key here, and click Continue.

    

18. Select Continue on the Setup Database page.

19. Click the final Finish Upgrade button and wait for it to complete.

    

    A large database could take a couple hours to complete.

20. Perform any testing with one or more clients that have been updated to point to the temporary FQDN of the Virtual Appliance (va.company.org).
21. Schedule cut-over to the Virtual Appliance in production.

22. Cut-over steps:

    1. [Optional] Install the updated PrinterLogic Client on end-user workstations (this can be done automatically after cut-over in the Virtual Appliance Admin Console by configuring client automatic updates.
    2. Shutdown the Web Stack server.
    3. Copy the production license file to the /pi/storage folder on the Virtual Appliance appliance-storage share, overwriting the existing.
    4. [Optional] Copy the new production Virtual Appliance certificate files (referenced above in the requirements section) to the certs folder on the Virtual Appliance appliance-storage share, overwriting the existing files. The SSL certificate files need to be named ssl.crt and ssl.key.

    5. Edit the secrets.env file at the root of the Virtual Appliance appliance-storage share and change the PRINTERCLOUD_DOMAIN variable to the production FQDN (printers.company.org).

       When editing the secrets.env file, an editor like Notepad ++, Sublime Text, or Visual Studio Code must be used to ensure the file uses Unix line endings (LF only) and is saved in UTF-8 format with no byte-order mark.

    6. Modify the existing DNS A record for the production FQDN (printers.company.org) to point to the IP address of the Virtual Appliance.
    7. Create a DNS CNAME record for the wildcard underneath the production FQDN (*.printers.company.org) and point it to the production FQDN (printers.company.org).
    8. Reboot the Virtual Appliance. Once the Virtual Appliance is in a “Running” state, clients should be able to connect.