Deploy Scanner Instance Using Command-line virt-install

You can deploy a Scanner Instance using the command line virt-install.

Log into your KVM server and run the following commands to launch a scanner instance using the qCOW2 disk image:

Method 1: Deploy and Personalize the Scanner using User Data (Recommended)

This is the preferred method because it allows you to deploy and personalize the scanner with a single command. This method supports deploying single- and split-network configurations, as well as UEFI-boot scanners.

1. Extract the qVSA QCOW2 image and upload it to your KVM server, see section Step 2: Configuration of Virtual Scanner.
2. Prepare a userdata text file:
   • PERSCODE=706xxxxxxxxxx
   • PROXY_URL=user:password@proxyhost:443 (This is an optional Parameter)
   • Enable_WAN_Interface=True (Optional Parameter for enabling split network)
3. Run the virt-install command to launch and personalize the scanner with the provided user data file.

    Command

   virt-install --name $VM_NAME \ 
     --memory $RAM_in_MB \ 
     --vcpus $Num_CPUs \ 
     --network $Guest_Network \    # LAN 
     --network $Guest_Network \    # If enabling split network, add second --network    
     --cloud-init user-data=$PATH_to_UserData_File 
     --disk $PATH_to_disk_image \
     --graphics vnc \ 
     --noautoconsole \ 
     --osinfo detect=on,require=off \
     --check disk_size=off \ 
     --import       
   

   Example for Deploying a Single Network Scanner.

   virt-install --name $VM_NAME \ 
     --memory 4096 \ 
     --vcpus 2 \ 
     --network bridge=bridge0,model=virtio \     
     --cloud-init user-data=userdata.txt 
     --disk qVSA.x86_64-4.2.xx-x.qcow2 \
     --graphics vnc \ 
     --noautoconsole \
     --osinfo detect=on,require=off \
     --check disk_size=off \ 
     --import       
   

   Ensure in userdata.txt that the 'Enable_WAN_Interface' parameter is omitted.

   Example for Deploying Split Network Scanner

   virt-install --name $VM_NAME \ 
     --memory 4096 \ 
     --vcpus 2 \ 
     --network bridge=bridge0,model=virtio \    # LAN 
     --network bridge=bridge1,model=virtio \    # WAN      
     --cloud-init user-data=userdata.txt 
     --disk qVSA.x86_64-4.2.xx-x.qcow2 \
     --graphics vnc \ 
     --noautoconsole \
     --osinfo detect=on,require=off \
     --check disk_size=off \ 
     --import       
    

   Ensure in userdata.txt that 'Enable_WAN_Interface=True' is included and add second --network parameter to the command.

   Example for Deploying Scanner in UEFI Boot Mode

   virt-install --name $VM_NAME \ 
     --memory 4096 \ 
     --vcpus 2 \ 
     --network bridge=bridge0,model=virtio \     
     --cloud-init user-data=userdata.txt 
     --disk qVSA.x86_64-4.2.xx-x.qcow2 \
     --boot uefi \
     --graphics vnc \ 
     --noautoconsole \ 
     --osinfo detect=on,require=off \
     --check disk_size=off \ 
     --import       
   

   Ensure the edk2-ovmf package is installed on the KVM server and add '--boot uefi' parameter to the command.

Method 2: Deploy Scanner by Injecting Custom Data and Modifying XML

Scanner VM XML template can be used to inject custom user data. The user data includes a Personalization code. Optionally, Proxy details can also be included in user data. 
The custom user data needs to be in base64 encoded format.

Follow these steps to inject custom user data into the Scanner VM XML template:

1. Deploy KVM scanner VM.

    Do not power on the Scanner VM before completing all steps.

2. Create base64 encoded user data.
3. On the Linux machine, run this command to encode user data: <<<$'PERSCODE=xxxxxxxxxx' gzip -c | openssl base64 -A

   This will generate base64 encoded data.

   Optional:

   With Proxy details included: <<<$'PERSCODE=xxxxxxxxxx\nPROXY_URL=user:pwd@proxyip:port' gzip -c | openssl base64 -A)

   Log in to the KVM host terminal and run - virsh edit <vm name> to edit the XML template.

   In the XML template, you can view this section

   <os>
   <type arch='x86_64' machine='pc-i440fx-rhel7.6.0'>hvm</type>
   <boot dev='hd'/>
   </os>      
       

   Edit this section with the following:
   After <boot dev='hd'/>,

   add

   <smbios mode='sysinfo'/>
   Add new section after </os>:
   <sysinfo type='smbios'>
   <system>
   <entry name='serial'>CONFIG:<base64 encoded data></entry>
   </system>
   </sysinfo>      
       
   

   For element entry name='serial', add the encoded user-data generated in here.

   The updated XML is

   <os>
    <type arch='x86_64' machine='pc-i440fx-rhel7.6.0'>hvm</type>
    <boot dev='hd'/>
    <smbios mode='sysinfo'/>
   </os>
   <sysinfo type='smbios'>
     <system>
    <entry name='serial'>CONFIG:<base64 encoded data></entry>
    </system>
   </sysinfo>      
       
   

4. Power on the Scanner VM.

Method 3: Deploy Scanner with NoCloud datasource and CIDATA.iso

You can inject user data into a KVM virtual machine by using cloud-init with the NoCloud datasource. The user data is usually provided through an ISO image or a configuration drive. When the virtual machine starts for the first time, cloud-init reads this data and automatically applies the configuration to the guest operating system.

To inject user data, perform the following steps: 

1. Prepare User-Data:

   Create a user-data file containing the desired scanner’s configuration. 

   Example

   cat user-data: 
   PERSONALIZATION_CODE=1234567890123 
   PROXY_URL=proxy_user:[email protected]:3128       

   Create an ISO Image (or Configuration Drive): 

   Use a tool like genisoimage to create an ISO image containing the user-data file. The volume label of this ISO image must be named "CIDATA.iso"  for cloud-init to recognize it as a NoCloud datasource. 

   Example: 
   genisoimage -output cidata.iso -volid cidata -joliet -rock user-data 

2. Attach the ISO to the scanner VM:

   When creating or editing the KVM virtual machine, attach the CIDATA.iso to the VM scanner using the virsh-install command. 

   Command

   virt-install --name qualys-scanner \ 
     --memory 4096 \ 
     --vcpus 2 \ 
     --network bridge=bridge0,model=virtio \ # VM with LAN interface only 
     --disk qVSA.x86_64-4.1.82-1.qcow2 \ 
     --disk CIDATA.iso \ 
     --graphics vnc \ 
     --check disk_size=off \ 
     --import       

Alternative Method to Add Second Network Interface to Existing Scanner

 This step is not needed if you used Method 1 to deploy the Split network scanner via the CLI and a user data file.

When deploying the scanner through the KVM Cockpit Web Console, you are limited to attaching a single network interface during the initial VM setup. The Cockpit UI does not provide an option to add a second network interface (the scanner’s WAN) at that stage.

You can add a second (WAN) interface to an existing scanner VM by manually editing its XML configuration.

To edit the XML, run this command:

virsh edit < INSTANCE NAME >

Example

virsh edit qVSA-X.X.XX-X

Add second interface configuration:

Ensure the source bridge network is present on the KVM Hypervisor host machine.

<interface type='bridge'>
     <mac address='<MAC address>'/>
      <source bridge='<name of the bridge network>'/>
     <model type='<model type>'/>
     <link state='up'/>
     <address type='pci' domain='0x0000' bus='0x01' slot='0x04' function='0x0'/>
</interface>      

 Example

<interface type='bridge'>
     <mac address='xx:xx:xx:xx:xx:xx'/>
     <source bridge='bridge1'/>
     <model type='e1000'/>
     <link state='up'/>
     <address type='pci' domain='0x0000' bus='0x01' slot='0x04' function='0x0'/>
</interface>