Manpage of esxupdate (VMware ESX 3.5)
ESXUPDATE(8) VMware ESX Server Manual ESXUPDATE(8)
NAME
esxupdate - VMware ESX Server software maintenance tool
SYNOPSIS
esxupdate <Bundle Spec> [OPTIONS] update
esxupdate <Bundle Spec> [–explain] scan
esxupdate [-l] query
esxupdate [-l] info bundleID [bundleID2..]
esxupdate [-l] <Bundle Spec> info
COPYRIGHT
VMware ESX Server is Copyright 2007 VMware, Inc. All rights reserved.
DESCRIPTION
You can maintain your ESX Server host using the esxupdate tool. The tool can help administrators perform patch selection and risk analysis,
bring the ESX Server up to date in different ways, and track installed
software. The tool runs on the ESX Server service console. Only the
root user can invoke the tool.
The esxupdate tool works with bundles and depots.
bundle a single unit of installation. There are two types - regular
bundles containing a single patch, and a roll-up bundle (with a
name ending in RG) which defines a convenient grouping of
released bundles. The bundle name contains the product, version
(x.y.z), year, numeric month, a serial ID, and type codes. The
format is as follows: ESXvvv-yyyymmsss-cc
depot a folder containing a subset of bundles for the current ESX
Server release, plus a contents.xml file. Depots may be located
on an NFS, FTP, or HTTP server.
The use of a depot allows esxupdate to resolve dependencies and work
with collections of software updates, instead of just one at a time.
Depot and bundle metadata is locally cached on the ESX Server root par-
tition for HTTP and FTP based depots. To create a depot, define a
directory and extract the contents.zip package and the bundle .zip
packages into it. The contents file contains depot metadata.
Depots and bundles contain digital signatures for authentication.
There are four modes of operation. In scan mode, you scan depots for
applicable updates. In update mode, you install bundles. In test mode,
you can test an update transaction without modifying the system. In
inquiry mode, you retrieve information about installed bundles and
packages, and about bundles in depots.
Invoking esxupdate with no arguments causes a brief help screen to be
printed.
<Bundle Spec>: Specifying bundles to work with
There are multiple ways to specify single or multiple bundles for use
with the update, scan, and info commands.
-d, --depot depot-URL
Select all the bundles in the depot located at depot-URL.
file://, http://, ftp:// are the supported URL types.
-d, --depot depot-URL -b bundleID [-b bundleID ...]
Select specific bundles in the depot located at depot-URL. Each
bundleID value may refer to a specific bundle, or it may contain
Unix shell-style wildcards to match multiple bundles.
-b bundleID [-b bundleID ...]
Select specific bundles in the depot located at the current
directory.
No arguments
If neither -r nor -d/-b are specified, and the current directory
is a depot, all the bundles in this depot will be selected. If
the current directory is a bundle, only that bundle is selected,
akin to using -r.
-r, --repo bundle-URL
Select the single bundle at bundle-URL. For the update command,
the use of this syntax results in the loss of depot awareness,
so dependency resolution will not happen. This syntax is mainly
provided for compatibility with ESX 3.0.x customer scripts.
file://, http://, ftp:// are the supported URL types.
The following can be used in the bundle ID for wildcard matching:
* Matches everything
? Matches any single character
[seq] Matches any character in seq
[!seq] Matches any character not in seq
Scanning the depot
The scan command prints out a concise summary of the bundles in a depot and offers administrators a quick way to select bundles and perform risk and downtime analysis. It also offers a quick way of checking the depot for errors. In general, you should scan the entire depot. One
line is printed for each bundle with the following fields:
* The bundle ID
* An 8-character appFlags field, summarizing why a bundle is not
applicable
* A 40-character summary of the bundle
* A 3-character iFlags field for host system dependencies
A line of dashes for the appFlags field indicates that the bundle is
applicable. This field can be used to quickly check for any errors and
to see which bundles are already installed or will be skipped. A
breakdown of the appFlags field:
irmcoNdv
|||||||+-> v: The host is not in maintenance mode and it needs to be
||||||+--> d: This flag is currently unused
|||||+---> N: One or more signatures could not be authenticated
||||+----> o: This bundle is obsolete and will be skipped
|||+-----> c: This bundle conflicts with another bundle
||+------> m: A dependency is missing from the depot or bundle spec
|+-------> r: A dependency is not applicable for some reason
+--------> i: This bundle is already installed and will be skipped
iFlags helps with downtime analysis by identifying which bundles will
cause downtime for VMs or the ESX server itself. A breakdown of the
iFlags field:
rmh
||+-> h: Host agent will be restarted
|+--> m: Maintenance mode required; VMs must be shut off or VMotioned
+---> r: Reboot of the ESX Server host is required
Scan options:
--explain
Display detailed explanations for why a bundle is not applica-
ble.
Updating ESX Server
Use Cases
In order to update your ESX Server host to all of the latest patches,
extract the latest roll-up into a depot directory and use the are no
longer needed are not installed.
Updating your ESX Server to a subset of patches is also easy.
* Specify the ID of a roll-up, which is a predefined set of bundles
* Use a wildcard to install only patches from specific months
-b "*-200711*" specifies all patches from 2007 November.
* Use a wildcard to install only particular types of patches
-b "*-SG" specifies all security fixes
* Do a scan and use individual -b options to specify each bundle
Another strategy is to define a custom depot to contain the subset of
bundles that a group of ESX Servers should contain.
1. Create a depot directory.
2. Unpack the latest contents.zip into the directory.
3. Only unpack the bundles that make up the desired subset.
4. Run a scan to verify that the depot has no errors.
To bring a group of ESX Servers up to the baseline defined by this cus-
tom depot, simply log into each ESX Server and type
esxupdate -d customDepotURL update
Installation Behavior
esxupdate requires a minimum of 24MB free on /tmp, 24MB free on /boot,
and 50MB on /, but a safe rule of thumb is to have twice the space
taken up by the bundles to be installed. If the ESX server does not
have sufficient disk space, esxupdate will exit with an error message
prior to installing or removing any packages.
esxupdate skips over bundles that are not applicable for any reason
(see the Scan section for particular reasons) or if bundles are miss-
ing, and installs the remainder of the bundles. If none of the bundles
are applicable or can be found, error messages will be printed and esx-
update will exit. For a preview of exactly which bundles will be
installed, use test mode.
esxupdate attempts to automatically pull in the dependencies of a bun-
dle from the depot. If any of the dependencies of a bundle are not
applicable for any reason, that bundle is also not applicable.
If any bundle requires maintenance mode, it will be enforced before
installation starts. If any bundle requires a reboot, then a reboot is
done at the end of the entire transaction. It is possible that an
update may require more than one reboot. Esxupdate attempts to install
as many bundles as it can before doing the reboot, but any bundles that
can only be installed after the reboot, will be marked not applicable,
and esxupdate must be restarted after the reboot to complete the trans-
action. Multi-session updates should be rare.
If a set of bundles contains multiple versions of an RPM, only the lat-
est version will be installed.
The installation process consists of:
* Checking for dependencies and system state
* Downloading RPMs from the bundles
* Authenticating bundle contents
* Running a test RPM transaction, checking for disk space
* Updating to a newer version of esxupdate, if available
* Removing obsolete RPMs as necessary
* Installing RPM packages
* Kernel and driver configuration
* Restarting host agent and/or rebooting, if required
Installation is non-interactive, and if the software update calls for a
reboot, it will be initiated after a successful installation.
Installation options:
-x, --exclude package
Do not install the rpm named package. This is commonly used to
preserve the version of a package due to be upgraded, or to work
around dependency problems. This option may be repeated. Leave
out the version and release info from the package name, ex,
'kudzu', not 'kudzu-0.6.3-18.1'
-n, --noreboot
Do not reboot the system after installing a bundle that requires
a reboot. This may be used to install a whole series of bundles
without rebooting, as long as the reboot happens later.
--test Enables test mode. Analyses dependencies, sorts bundles, down-
loads RPMs, runs a test transaction, exits with code 0 and
prints a report.
--nosigcheck
Disable digital signature checking. VMware recommends that this
option never be used, as it may allow malicious software to be
installed.
-f, --force
Force the install of older and existing packages, plus those
with dependency conflicts. By default, esxupdate will skip the
installation of older and existing packages. VMware recommends
that this option not be used, as it may cause versioning issues
between packages and unintentionally de-stabilize your system.
If you are trying to write a script to install a sequence of
bundles, this option is not needed, as esxupdate will ignore
older packages as necessary.
Test Mode
It might be helpful to use --test to preview an update.
First, this lets you see exactly which bundles will be installed and
skipped, and why, as well as which RPMs will be installed and skipped.
It actually downloads the RPMs, runs through a test transaction, and
checks for disk space, but stops before any RPMs are removed or
installed. A report is printed at the end, and esxupdate exits with
code 0.
Secondly, for HTTP and FTP-based depots, test mode fills the local
depot cache, so that subsequent updates can be faster.
Inquiry Mode
Describing the installed software
The query command lists all the installed bundles on the system, in
order of installation time. If a bundle obsoletes an earlier bundle,
only the later one will be displayed. The first column lists the bundle
ID, which can be used with the info command to obtain a detailed list-
ing of each bundle and the packages installed with it. The installa-
tion time and a 40-character summary follows. The version, build num-
ber, and installation time of the last ESX Server full release is also
displayed, usually as the first line.
-l, --listrpms
Estimate the packages that have been installed, removed, or
upgraded outside of using esxupdate. Very useful for determining
custom software configurations. If an RPM package installed in
the system is not of the right version, "should be" followed by
the right version will be printed after the package name. If
there are multiple versions of a package installed, the extrane-
ous versions along with "duplicate of" of the right version will
be printed after the package name. Useful for auditing.
Describing a bundle in detail
The info command lists the summary, description, build and install
timestamps, dependency details, and optionally a versioned list of
packages for a depot bundle, an installed bundle, or the last ESX full
release.
To retrieve information on uninstalled bundles, run the info command
and sepcify the bundle or depot URL. To retrieve information on
installed bundles, run the info command and list one or more installed
bundle IDs on the command line.
-l, --listrpms
Provide a list of the bundle's installed and not installed (or
skipped) RPM packages, and their version numbers. Also, if any
RPMs were removed by the package, list the RPM names.
Universal Options
--flushcache
Force a flush of the local depot cache
-v, --verbose loglevel
Sets the verbosity of standard output. The default is 20, but
it can be changed to 10 to include debug output, or raised to 30
to silence output except for warnings and 40 for errors only.
The verbosity of the log file is not affected and is always at
level 10.
Exit Codes
0 Update completed successfully, no further actions required
80 Update completed, but a reboot is required
11-12 Download error, or bundle cannot be found
40-43 Bundle dependency error
For a detailed list, please see the Patch Management Guide.
EXAMPLES
To scan depot for applicable bundles and risks:
esxupdate -d http://zebra16/pub/patches scan
To detail bundle ESX-1001 in depot http://zebra16/pub/patches/:
esxupdate -d http://zebra16/pub/patches -b ESX-1001 -l info
To install the same bundle, but skip the openssh package:
esxupdate -d http://zebra16/pub/patches -b ESX-1001 -x openssh update
Now, review all installed bundles:
esxupdate query
To install all security patches in the depot:
esxupdate -d http://zebra16/pub/patches -b ‘*-SG’ update
To see a list of the RPMs installed with the CD (The build number below
is just an example):
esxupdate -l info 3.5.0-1234
FILES
/etc/vmware/patchdb
The patch database directory.
/var/log/vmware/esxupdate.log
Log file with verbose output. To see a summary of the installa-
tion history, 'grep summary' on this file.
ESX 3.5 Oct 17, 2007 ESXUPDATE(8)
Short Help
To install ESX patches and updates: esxupdate [options] update -b <bundle ID> : Install this bundle. May be a wildcard.May be repeated. Defaults to ‘*’.
-r/–repo <url> : Install bundle at url; default is cwd
–test : Download RPMs and run test transaction only
-n/–noreboot : Do not reboot after install
–nosigcheck : Do not check signatures of the depot files
-x/–exclude <pkg> : Exclude pkg during install; use one -x per pkg.
-f/–force : Force install of older and existing packages
To scan for available updates in a depot:
esxupdate -d <depotURL> [-b <bundlespec>][options] scan
–explain : Explain in detail why a bundle is not applicable
To query installed update bundles:
esxupdate [-l] query
esxupdate [-l] info <bundleID1> [<bundleID2> …]
-l/–listrpms : (info) List every rpm in patch
(query) Diff RPMDB against installed updates
To query update bundle(s) at URL or in a depot:
esxupdate [-r <URL> | -d <depotURL> [-b <bundleID>] …] [-l] info
Universal options:
-d <depot URL> : Depot containing contents.xml file is here
–flushcache : Force a flush of the local depot cache
-v/–verbose <level> : Set output verbosity (default=20)
10=debug / 20=info / 30=warning / 40=error
A reboot will occur after an install finishes by default, unless
no bundles require a reboot or the –noreboot option is passed.
Recent Comments