The vCloud Director installer verifies that the target server meets all upgrade prerequisites and upgrades the vCloud Director software on the server.

About this task

vCloud Director software is distributed as a digitally signed Linux executable file with a name of the form vmware-vcloud-director-distribution-v.v.v-nnnnnn.bin, where v.v.v represents the product version and nnnnnn the build number. For example: vmware-vcloud-director-distribution-8.10.0-3698331.bin. Running this executable installs or upgrades vCloud Director.

Important:

After you upgrade the first member of a server group, you must run a tool that upgrades the group's vCloud Director database before you restart vCloud Director services on the upgraded server. After the database has been upgraded, you can upgrade and re-start other members of the server group.

Prerequisites

  • Verify that you have superuser credentials for the target server.

  • To have the installer verify the digital signature of the installation file, download and install the VMware public key on the target server. If you already verified the digital signature of the installation file, you do not need to verify it again during installation. See Download and Install the VMware Public Key.

  • Verify that you have a valid license key to use the version of the vCloud Director software to which you are upgrading.

Procedure

  1. Log in to the target server as root.
  2. Download the installation file to the target server.

    If you purchased the software on media, copy the installation file to a location that is accessible to the target server.

  3. Verify that the checksum of the download matches the one posted on the download page.

    Values for MD5 and SHA1 checksums are posted on the download page. Use the appropriate tool to verify that the checksum of the downloaded installation file matches the one shown on the download page. A Linux command of the following form displays the checksum for installation-file.

    [root@cell1 /tmp]# md5sum installation-file
    checksum-value installation-file 

    Compare the checksum-value produced by this command with the MD5 checksum copied from the download page.

  4. Ensure that the installation file is executable.

    The installation file requires execute permission. To be sure that it has this permission, open a console, shell, or terminal window and run the following Linux command, where installation-file is the full pathname to the vCloud Director installation file.

    [root@cell1 /tmp]# chmod u+x installation-file
  5. In a console, shell, or terminal window, run the installation file.

    To run the installation file, type its full pathname, for example ./installation-file. The file includes an installation script and an embedded RPM package.

    Note:

    You cannot run the installation file from a directory whose pathname includes any embedded space characters.

    If the installer detects a version of vCloud Director installed on this server that is equal to or later than the version in the installation file, it displays an error message and exits. Otherwise, it prompts you to confirm that you are ready to proceed to upgrade this server.

    Checking free disk space...done
    Checking for a supported Linux distribution...
    done
    Checking for necessary RPM prerequisites...done
    Extracting VMware vCloud Director. Please wait...
    done
    Verifying RPM signatures...done
    
    An older version of VMware vCloud Director has been detected and will be
    upgraded to 8.20.0.
    
    If you choose to proceed, the installer will stop the vmware-vcd service,
    back up any configuration files from the previous release and migrate the
    product configuration as necessary.
    
    Are you sure you want to continue with the upgrade? (y/n)?
  6. Respond to the upgrade prompt.

    Option

    Action

    Continue the upgrade.

    Type y.

    Exit to the shell without making any changes in the current installation.

    Type n.

    After you confirm that you are ready to upgrade the server, the installer initiates the upgrade workflow.

    1. It verifies that the host meets all requirements.

    2. It unpacks the vCloud Director RPM package.

    3. It quiesces activity on the cell.

    4. After all active vCloud Director jobs on the cell have completed, it stops vCloud Director services on the server and upgrades the installed vCloud Director software.

    Upgrading VMware vCloud Director...
    
    Waiting indefinitely for all active jobs on this cell to complete, if you
    would like to limit how long this process will wait you can cancel this at
    any time via CTRL+C and re-run providing the --abort-tasks-after-minutes
    flag indicating the maximum number of minutes to wait for jobs to complete.
    
    Successfully entered maintenance mode.
    Stopping vmware-vcd-watchdog:                              [  OK  ]
    Stopping vmware-vcd-cell:                                  [  OK  ]
    Installing the VMware vCloud Director RPM...
    
    Preparing...
    .
    .
    .
    Upgrade installation complete.
    Next steps:
    
    You will need to upgrade the database schema before starting the
    vmware-vcd service.  The product upgrade tool should be run only once per
    vCloud Director group. The tool may be run with the following command:
    /opt/vmware/vcloud-director/bin/upgrade

    During the upgrade, the installer might display warnings:

    • It displays a warning of the following form if you did not install the VMware public key on the target server.

      warning:installation-file.rpm: Header V3 RSA/SHA1 signature: NOKEY, key ID 66fd4949

    • It displays a warning of the following form when it makes changes to the existing global.properties file on the target server.

      warning: /opt/vmware/vcloud-director/etc/global.properties created as /opt/vmware/vcloud-director/etc/global.properties.rpmnew

      Most upgrades require this sort of change, and display this warning. If you have made any changes to the existing global.properties file, you can retrieve them from global.properties.rpmnew.

  7. (Optional) : Update logging properties.

    After an upgrade, new logging properties are written to the file /opt/vmware/vcloud-director/etc/log4j.properties.rpmnew.

    Option

    Action

    If you did not change existing logging properties

    Copy this file to /opt/vmware/vcloud-director/etc/log4j.properties.

    If you changed logging properties

    Merge /opt/vmware/vcloud-director/etc/log4j.properties.rpmnew file with the existing /opt/vmware/vcloud-director/etc/log4j.properties. Merging these files preserves your changes.

Results

When the vCloud Director software upgrade is complete, the installer displays a message indicating where the old configuration files are stored, then reminds you to run the database upgrade tool.

What to do next

  • If you have not already done so, upgrade the vCloud Director database that this server uses.

  • If you already upgraded the vCloud Director database that this server group uses, you can restart the upgraded server. See Start or Stop vCloud Director Services.