Installing ManageIQ

ManageIQ is able to be installed and ready to configure in a few quick steps. After downloading ManageIQ as a virtual machine image template from the Red Hat Customer Portal, the installation process takes you through the steps of uploading the appliance to a supported virtualization or cloud provider.

After installing the ManageIQ appliance, you must configure the database for ManageIQ. See Configuring a Database for ManageIQ.

Obtaining the appliance

  1. In a browser, navigate to manageiq.org/download.

  2. Select Red Hat Enterprise Virtualization from the --Choose your platform-- list.

  3. Select Stable (darga-2) from the --Choose a release-- list.

  4. Follow the instructions to download the appliance.

Uploading the Appliance on Red Hat Enterprise Virtualization Manager

Uploading the ManageIQ appliance file onto Red Hat Enterprise Virtualization Management systems has the following requirements:

  • 44 GB of storage space on both the export domain and the local partition where /tmp resides since the OVF archive is locally expanded into that directory.

  • 8 GB RAM.

  • 4 VCPUs.

  • Install the rhevm-image-uploader package containing the engine-image-uploader script to your local machine.

    # yum install rhevm-image-uploader

    It is recommended to use -v (verbose logging) when using the engine-image-uploader script to see the progression of the upload.

  • Depending on your infrastructure, allow approximately 90 minutes for the upload.

  • Once the OVF is uploaded and imported as a template, add a network adapter to the template itself.

Using the Image Uploader Tool

The engine-image-uploader command allows you to list export storage domains and upload virtual machine images in OVF format to an export storage domain and have them automatically recognized in the Red Hat Enterprise Virtualization Manager.

The image uploader only supports gzip-compressed OVF files created by Red Hat Enterprise Virtualization.

The archive contains images and master directories in the following format:

|-- images
|   |-- [Image Group UUID]
|        |--- [Image UUID (this is the disk image)]
|        |--- [Image UUID (this is the disk image)].meta
|-- master
|   |---vms
|       |--- [UUID]
|             |--- [UUID].ovf

The basic syntax for the image uploader command is:

engine-image-uploader [options] listengine-image-uploader [options] upload [file].[file]...[file]

The image uploader command supports two actions: list, and upload.

  • The list action lists the export storage domains to which images can be uploaded.

  • The upload action uploads images to the specified export storage domain.

You must specify one of the above actions when you use the engine-image-uploader command. Moreover, you must specify at least one local file to use the upload action.

There are several parameters to further refine the engine-image-uploader command. You can set defaults for any of these parameters in the /etc/ovirt-engine/imageuploader.conf file.

General Options

-h, --help

Displays information on how to use the image uploader command.

--conf-file=[PATH]

Sets [PATH] as the configuration file the command will use. The default is /etc/ovirt-engine/imageuploader.conf.

--log-file=[PATH]

Sets [PATH] as the specific file name the command will use to write log output. The default is /var/log/ovirt-engine/ovirt-image-uploader/ovirt-image-uploader-[date].log.

--cert-file=[PATH]

Sets [PATH] as the certificate for validating the engine. The default is /etc/pki/ovirt-engine/ca.pem.

-i, --insecure

Specifies that no attempt will be made to verify the engine.

--quiet

Sets quiet mode, reducing console output to a minimum.

--verbose

Sets verbose mode, providing more console output.

-f, --force

Specifies that no attempt will be made to verify the engine.

Force mode is necessary when the source file being uploaded has the same file name as an existing file in the destination export domain. This option forces the existing file to be overwritten.

Red Hat Enterprise Virtualization Manager Options

-u [USER], --user=[USER]

Specifies the user whose credentials will be used to execute the command. The [USER] is specified in the format [username]@[domain]. The user must exist in the specified domain and be known to the Red Hat Enterprise Virtualization Manager.

-r [FQDN], --engine=[FQDN]

Specifies the IP address or fully qualified domain name of the Red Hat Enterprise Virtualization Manager from which the images will be uploaded. It is assumed that the image uploader is being run from the same machine on which the Red Hat Enterprise Virtualization Manager is installed. The default value is localhost:443.

Export Storage Domain Options

The following options specify the export domain to which the images will be uploaded. These options cannot be used together; you must use either the -e option or the -n option.

-e [EXPORT_DOMAIN], --export-domain=[EXPORT_DOMAIN]

Sets the storage domain EXPORT_DOMAIN as the destination for uploads.

-n [NFSSERVER], --nfs-server=[NFSSERVER]

Sets the NFS path [NFSSERVER] as the destination for uploads.

Import Options

The following options allow you to customize which attributes of the images being uploaded are included when the image is uploaded to the export domain.

-i, --ovf-id

Specifies that the UUID of the image will not be updated. By default, the command generates a new UUID for images that are uploaded. This ensures there is no conflict between the ID of the image being uploaded and the images already in the environment.

-d, --disk-instance-id

Specifies that the instance ID for each disk in the image will not be renamed. By default, the command generates new UUIDs for disks in images that are uploaded. This ensures there are no conflicts between the disks on the image being uploaded and the disks already in the environment.

-m, --mac-address

Specifies that network components in the image will not be removed from the image. By default, the command removes network interface cards from image being uploaded to prevent conflicts with network cards on other virtual machines already in the environment. If you do not use this option, you can use the Administration Portal to add network interface cards to newly imported images and the Manager will ensure there are no MAC address conflicts.

-N [NEW_IMAGE_NAME], --name=[NEW_IMAGE_NAME]

Specifies a new name for the image being uploaded.

Uploading the Appliance with the Image Uploader

The following procedure uploads the ManageIQ appliance using the Image Uploader tool.

  1. Change to the directory containing the ManageIQ appliance.

  2. Run the following command:

    # engine-image-uploader -N `newimagename` -e `myexportdomain` -v -m upload cfme-rhevm-5.3-15.x86_64.rhevm.ova

    Substitute newimagename with your chosen name for the image, and substitute myexportdomain with your chosen export storage domain.

  3. Enter the password of the default administrative user for your Red Hat Enterprise Virtualization Manager when prompted.

    Please provide the REST API password for the admin@internal oVirt Engine user (CTRL+D to abort): **********

    Ensure your Red Hat Enterprise Virtualization Manager has administrator access to the chosen export storage domain.

It takes approximately 90 minutes to upload the ManageIQ appliance file to the Red Hat Enterprise Virtualization Manager.

Uploading the Appliance Manually

The following procedure provides manual upload instructions if the Image Uploader tool is not available or fails to upload.

  1. Log into a host in your Red Hat Enterprise Virtualization with a mount to the Export storage domain.

  2. Change to the Export storage domain’s directory.

  3. Copy the ManageIQ appliance OVF archive to this directory.

  4. Extract the OVF file using the tar command:

    $ tar xvf cfme-rhevm-5.3-15.x86_64.rhevm.ova
  5. Set the following permissions:

    chown -R 36:36 images/
    chown -R 36:36 master/

Running ManageIQ

After uploading the appliance to the export storage domain, import it as a template and create a virtual machine. Use the following procedure as a guide.

  1. Import the appliance image from the export storage domain as a template in a Red Hat Enterprise Virtualization data storage domain. Use the newimagename you specified when you uploaded the image to find the image to import as a template. Once the import is complete, check the template for a network interface (NIC). If the template does not include one, create a NIC for it.

  2. Create a new virtual machine using the ManageIQ appliance template as a basis. See the Red Hat Enterprise Virtualization Administrator Guide for instructions.

  3. Add a database disk if you are hosting the database on the same machine as the appliance.

  4. Start the newly created ManageIQ appliance virtual machine.

Your Red Hat Enterprise Virtualization environment now contains a running ManageIQ appliance.

Configuring ManageIQ

Although the ManageIQ appliance comes configured to be integrated immediately into your environment, you can make some changes to its configuration.

The ManageIQ appliance is intended to have minimal configuration options.

Changing Configuration Settings

The procedure describes how to make changes to the configuration settings on the ManageIQ appliance.

  1. After starting the appliance, log in with a user name of root and the default password of smartvm. This displays the Bash prompt for the root user.

  2. Enter the appliance_console command. The ManageIQ appliance summary screen displays.

  3. Press Enter to manually configure settings.

  4. Press the number for the item you want to change, and press Enter. The options for your selection are displayed.

  5. Follow the prompts to make the changes.

  6. Press Enter to accept a setting where applicable.

The ManageIQ appliance console automatically logs out after five minutes of inactivity.

Advanced Configuration Settings

After logging in, you can use the following menu items for advanced configuration of the appliance:

  • Use Set DHCP Network Configuration to use DHCP to obtain the IP address and network configuration for your ManageIQ appliance. The appliance is initially configured as a DHCP client with bridged networking.

  • Use Set Static Network Configuration if you have a specific IP address and network settings you need to use for the ManageIQ appliance.

  • Use Test Network Configuration to check that name resolution is working correctly.

  • Use Set Hostname to specify a hostname for the ManageIQ appliance.

    A valid fully qualified hostname for the ManageIQ appliance is required for SmartState analysis to work correctly,

  • Use Set Timezone, Date, and Time to configure the time zone, date, and time for the ManageIQ appliance.

  • Use Restore Database from Backup to restore the VMDB database from a previous backup.

  • Use Setup Database Region to create regions for VMDB replication.

  • Use Configure Database to configure the VMDB database. Use this option to configure the database for the appliance after installing and running it for the first time.

  • Use Extend Temporary Storage to add temporary storage to the appliance. The appliance formats an unpartitioned disk attached to the appliance host and mounts it at /var/www/miq_tmp. The appliance uses this temporary storage directory to perform certain image download functions.

  • Use Configure External Authentication (httpd) to configure authentication through an IPA server.

  • Use Generate Custom Encryption Key to regenerate the encryption key used to encode plain text password.

  • Use Harden Appliance Using SCAP Configuration to apply Security Content Automation Protocol (SCAP) standards to the appliance. You can view these SCAP rules in the /var/www/miq/lib/appliance_console/config/scap_rules.yml file.

  • Use Stop Server Processes to stop all server processes. You may need to do this to perform maintenance.

  • Use Start Server Processes to start the server. You may need to do this after performing maintenance.

  • Use Restart Appliance to restart the ManageIQ appliance. You can either restart the appliance and clear the logs or just restart the appliance.

  • Use Shut Down Appliance to power down the appliance and exit all processes.

  • Use Summary Information to go back to the network summary screen for the ManageIQ appliance.

  • Use Quit to leave the ManageIQ appliance console.

Configuring a Database for ManageIQ

Before using ManageIQ, configure the database options for it. ManageIQ provides two options for database configuration:

  • Install an internal PostgreSQL database to the appliance

  • Configure the appliance to use an external PostgreSQL database

Configuring an Internal Database

Before installing an internal database, add a disk to the infrastructure hosting your appliance. See the documentation specific to your infrastructure for instructions on how to add a disk. As a storage disk usually cannot be added while a virtual machine is running, Red Hat recommends adding the disk before starting the appliance. Red Hat CloudForms only supports installing of an internal VMDB on blank disks. The installation will fail if the disks are not blank.

  1. Start the appliance and open a terminal from your virtualization or cloud provider.

  2. After starting the appliance, log in with a user name of root and the default password of smartvm. This displays the Bash prompt for the root user.

  3. Enter the appliance_console command. The ManageIQ appliance summary screen displays.

  4. Press Enter to manually configure settings.

  5. Select 8) Configure Database from the menu.

  6. You are prompted to create or fetch an encryption key.

    • If this is the first ManageIQ appliance, choose 1) Create key.

    • If this is not the first ManageIQ appliance, choose 2) Fetch key from remote machine to fetch the key from the first ManageIQ appliance. All ManageIQ appliances in a multi-region deployment must use the same key.

  7. Choose 1) Internal for the database location.

  8. Choose a disk for the database. For example:

    1)  /dev/vdb: 20480
    
    Choose disk:

    Enter 1 to choose /dev/vdb for the database location.

  9. When prompted, enter a unique three digit region ID to create a new region.

    Creating a new region destroys any existing data on the chosen database.

  10. Confirm the configuration when prompted.

ManageIQ configures the internal database.

Configuring an External Database

The postgresql.conf file used with ManageIQ databases requires specific settings for correct operation. For example, it must correctly reclaim table space, control session timeouts, and format the PostgreSQL server log for improved system support. Due to these requirements, Red Hat recommends that external ManageIQ databases use a postgresql.conf file based on the standard file used by the ManageIQ appliance.

Ensure you configure the settings in the postgresql.conf to suit your system. For example, customize the shared_buffers setting according to the amount of real storage available in the external system hosting the PostgreSQL instance. In addition, depending on the aggregate number of appliances expected to connect to the PostgreSQL instance, it may be necessary to alter the max_connections setting.

Because the postgresql.conf file controls the operation of all databases managed by a single instance of PostgreSQL, do not mix ManageIQ databases with other types of databases in a single PostgreSQL instance.

ManageIQ 4.x requires PostgreSQL version 9.4.

  1. Start the appliance and open a terminal console from your virtualization or cloud provider.

  2. After starting the appliance, log in with a user name of root and the default password of smartvm. This displays the Bash prompt for the root user.

  3. Enter the appliance_console command. The ManageIQ appliance summary screen displays.

  4. Press Enter to manually configure settings.

  5. Select 8) Configure Database from the menu.

  6. You are prompted to create or fetch a security key.

    • If this is the first ManageIQ appliance, select the option to create a key.

    • If this is not the first ManageIQ appliance, select the option to fetch the key from the first ManageIQ appliance. All ManageIQ appliances in a multi-region deployment must use the same key.

  7. Choose 2) External for the database location.

  8. Enter the database hostname or IP address when prompted.

  9. Enter the database name or leave blank for the default (vmdb_production).

  10. Enter the database username or leave blank for the default (root).

  11. Enter the chosen database user’s password.

  12. Confirm the configuration if prompted.

ManageIQ will then configure the external database.

Configuring a Worker Appliance

You can configure a worker appliance through the terminal. These steps demonstrate how to join a worker appliance to an appliance that already has a region configured with a database.

  1. Start the appliance and open a terminal from your virtualization or cloud provider.

  2. After starting the appliance, log in with a user name of root and the default password of smartvm. This displays the Bash prompt for the root user.

  3. Enter the appliance_console command. The ManageIQ appliance summary screen displays.

  4. Press Enter to manually configure settings.

  5. Select 8) Configure Database from the menu.

  6. You are prompted to create or fetch a security key. Select the option to fetch the key from the first ManageIQ appliance. All ManageIQ appliances in a multi-region deployment must use the same key.

  7. Choose 2) External for the database location.

  8. Enter the database hostname or IP address when prompted.

  9. Enter the database name or leave blank for the default (vmdb_production).

  10. Enter the database username or leave blank for the default (root).

  11. Enter the chosen database user’s password.

  12. Confirm the configuration if prompted.

Logging In After Installing ManageIQ

Once ManageIQ is installed, you can log in and perform administration tasks.

Log into ManageIQ for the first time after installing by:

  1. Navigate to the URL for the login screen. (https://xx.xx.xx.xx on the virtual machine instance)

  2. Enter the default credentials (Username: admin | Password: smartvm) for the initial login.

  3. Click Login.

Changing the Default Login Password

Change your password to ensure more private and secure access to ManageIQ.

  1. Navigate to the URL for the login screen. (https://xx.xx.xx.xx on the virtual machine instance)

  2. Click Update Password beneath the Username and Password text fields.

  3. Enter your current Username and Password in the text fields.

  4. Input a new password in the New Password field.

  5. Repeat your new password in the Verify Password field.

  6. Click Login.