Usage

Examples for common use cases listed below are written in LMIShell. Where appropriate, an example for LMI metacommand is added.

Note

Examples below are written for openlmi-tools version 0.9.2.

Listing installed packages

Simple

Simple but slow way:

c = connect("host", "user", "pass")
cs = c.root.cimv2.PG_ComputerSystem.first_instance()
for identity in cs.associators(
        AssocClass="LMI_InstalledSoftwareIdentity",
        Role="System",
        ResultRole="InstalledSoftware",
        ResultClass="LMI_SoftwareIdentity"):
    print(identity.ElementName)

Note

Here we use PG_ComputerSystem as a class representing computer system.

Faster

This is much faster. Here we enumerate association class LMI_InstalledSoftwareIdentity and get information from its key properties.

c = connect("host", "user", "pass")
for iname in c.root.cimv2.LMI_InstalledSoftwareIdentity.instance_names():
    print(iname.InstalledSoftware.InstanceID
            [len("LMI:LMI_SoftwareIdentity:"):])

LMI metacommand

lmi -h $HOST sw list pkgs

Listing repositories

LMIShell

c = connect("host", "user", "pass")
for repo in c.root.cimv2.LMI_SoftwareIdentityResource.instance_names():
    print(repo.Name)

LMI metacommand

lmi -h $HOST sw list pkgs

Listing available packages

LMIShell

Enumerating of LMI_SoftwareIdentity is disabled due to a huge amount of data being generated. That’s why we enumerate them for particular repository represented by LMI_SoftwareIdentityResource:

c = connect("host", "user", "pass")
for repo in c.root.cimv2.LMI_SoftwareIdentityResource.instances():
    if repo.EnabledState != c.root.cimv2.LMI_SoftwareIdentityResource. \
            EnabledStateValues.Enabled:
        continue                  # skip disabled repositories
    print(repo.Name)
    for identity in repo.associator_names(
            AssocClass="LMI_ResourceForSoftwareIdentity",
            Role="AvailableSAP",
            ResultRole="ManagedElement",
            ResultClass="LMI_SoftwareIdentity"):
        print("  " + identity.InstanceID[len("LMI:LMI_SoftwareIdentity:"):])

Note

This is not the same as running:

yum list available

which outputs all available, not installed packages. The example above yields available packages without any regard to their installation status.

Using installation service

This method is both simpler and more effective. It also does not list installed packages.

c = connect("host", "user", "pass")
service = c.root.cimv2.LMI_SoftwareInstallationService.first_instance()
ret = service.FindIdentity(Installed=False)
for iname in ret.rparams["Matches"]:
    # we've got only references to instances
    print iname.Name[len("LMI:LMI_SoftwareIdentity:"):]

LMI metacommand

lmi -h $HOST sw list pkgs --available

Listing files of package

Let’s list files of packages openlmi-tools. Note that package must be installed on system in order to list its files.

LMIShell

We need to know exact NEVRA [1] of package we want to operate on. If we don’t, we can find out using FindIdentity() method. See example under Searching for packages.

c = connect("host", "user", "pass")
identity = c.root.cimv2.LMI_SoftwareIdentity.new_instance_name(
        {"InstanceID" : "LMI:LMI_SoftwareIdentity:openlmi-tools-0:0.5-2.fc18.noarch"})
for filecheck in identity.to_instance().associator_names(
        AssocClass="LMI_SoftwareIdentityChecks",
        Role="Element",
        ResultRole="Check",
        ResultClass="LMI_SoftwareIdentityFileCheck"):
    print("%s" % filecheck.Name)

LMI metacommand

lmi -h $HOST sw list files openlmi-tools

Searching for packages

If we know just a fraction of informations needed to identify a package, we may query package database in the following way.

LMIShell

c = connect("host", "user", "pass")
service = c.root.cimv2.LMI_SoftwareInstallationService.first_instance()
# let's find all packages with "openlmi" in Name or Summary without
# architecture specific code
ret = service.FindIdentity(Name="openlmi", Architecture="noarch")
for identity in ret.rparams["Matches"]:
    # we've got only references to instances
    print identity.Name[len("LMI:LMI_SoftwareIdentity:"):]

See also

FindIdentity() method

Please don’t use this method to get an instance of package you know precisely. If you know all the identification details, you may just construct the instance name this way:

c = connect("host", "user", "pass")
iname = c.root.cimv2.LMI_SoftwareIdentity.new_instance_name(
        {"InstanceID" : "LMI:LMI_SoftwareIdentity:openlmi-software-0:0.1.1-2.fc20.noarch"})
identity = iname.to_instance()

LMI metacommand

See help on sw command for more information on this.

lmi -h $HOST sw list pkgs openlmi

Package installation

There are two approaches to package installation. One is synchronous and the other asynchronous.

Synchronous installation

This is a very simple and straightforward approach. We install package by creating a new instance of LMI_InstalledSoftwareIdentity with a reference to some available software identity.

c = connect("host", "user", "pass")
identity = c.root.cimv2.LMI_SoftwareIdentity.new_instance_name(
    {"InstanceID" : "LMI:LMI_SoftwareIdentity:sblim-sfcb-0:1.3.16-3.fc19.x86_64"})
cs = c.root.cimv2.PG_ComputerSystem.first_instance_name()
installed_assoc = c.root.cimv2.LMI_InstalledSoftwareIdentity.create_instance(
    properties={
            "InstalledSoftware" : identity,
            "System"            : cs
})

If the package is already installed, this operation will fail with the pywbem.CIMError exception being raised initialized with CIM_ERR_ALREADY_EXISTS error code.

Downside of this approach is its slowness. It may block for a long time.

Asynchronous installation

Method InstallFromSoftwareIdentity() needs to be invoked with desired options. After the options are checked by provider, a job is returned representing installation process running at background. Please refer to Asynchronous Jobs for more details.

c = connect("host", "user", "pass")
service = c.root.cimv2.LMI_SoftwareInstallationService.first_instance()
identity = c.root.cimv2.LMI_SoftwareIdentity.new_instance_name(
        {"InstanceID" : "LMI:LMI_SoftwareIdentity:sblim-sfcb-0:1.3.16-5.fc19.x86_64"})
cs = c.root.cimv2.PG_ComputerSystem.first_instance_name()
ret = service.InstallFromSoftwareIdentity(
        Source=identity,
        Target=cs,
        # these options request to install available, not installed package
        InstallOptions=[4]     # [Install]
        # this will force installation if package is already installed
        # (possibly in different version)
        #InstallOptions=[4, 3] # [Install, Force installation]
)

The result can be checked by polling resulting job for finished status:

finished_statuses = {
      c.root.cimv2.CIM_ConcreteJob.JobState.Completed
    , c.root.cimv2.CIM_ConcreteJob.JobState.Exception
    , c.root.cimv2.CIM_ConcreteJob.JobState.Terminated
    }
job = ret.rparams["Job"].to_instance()
while job.JobStatus not in finished_statuses:
    # wait for job to complete
    time.sleep(1)
    job.refresh()
print c.root.cimv2.LMI_SoftwareJob.JobStateValues.value_name(job.JobState)
# get an associated job method result and check the return value
print "result: %s" % job.first_associator(
        AssocClass='LMI_AssociatedSoftwareJobMethodResult').__ReturnValue
# get installed software identity
installed = job.first_associator(
        Role='AffectingElement',
        ResultRole='AffectedElement',
        AssocClass="LMI_AffectedSoftwareJobElement",
        ResultClass='LMI_SoftwareIdentity')
print "installed %s at %s" % (installed.ElementName, installed.InstallDate)

You may also subscribe to indications related to LMI_SoftwareInstallationJob and listen for events instead of the polling done above

As you can see, you may force the installation allowing for reinstallation of already installed package. For more options please refer to the documentation of this method.

Combined way

We can combine both approaches by utilizing a feature of LMIShell. Method above can be called in a synchronous way (from the perspective of script’s code). It’s done like this:

# note the use of "Sync" prefix
ret = service.SyncInstallFromSoftwareIdentity(
        Source=identity,
        Target=cs,
        # these options request to install available, not installed package
        InstallOptions=[4]     # [Install]
        # this will force installation if package is already installed
        # (possibly in different version)
        #InstallOptions=[4, 3] # [Install, Force installation]
)
print "result: %s" % ret.rval

The value of .__ReturnValue of LMI_SoftwareMethodResult is placed to the ret.rval attribute. Waiting for job’s completion is taken care of by LMIShell. But we lose the reference to the job itself and we can not enumerate affected elements (that contain, among other things, installed package).

Installation from URI

This is also possible with:

c = connect("host", "user", "pass")
service = c.root.cimv2.LMI_SoftwareInstallationService.first_instance()
cs = c.root.cimv2.PG_ComputerSystem.first_instance_name()
ret = service.to_instance().InstallFromSoftwareURI(
        Source="http://someserver.com/fedora/repo/package.rpm",
        Target=cs,
        InstallOptions=[4])  # [Install]

Supported URI schemes are:

  • http
  • https
  • ftp
  • file

In the last case, the file must be located on the managed system.

See also

InstallFromURI() method

Please refer to Asynchronous installation above for the consequent procedure and how to deal with ret value.

LMI metacommand

lmi -h $HOST sw install sblim-sfcb

Package removal

Again both asynchronous and synchronous approaches are available.

Synchronous removal

The aim is achieved by issuing an opposite operation than before. The instance of LMI_InstalledSoftwareIdentity is deleted here:

c = connect("host", "user", "pass")
identity = c.root.cimv2.LMI_SoftwareIdentity.new_instance_name(
        {"InstanceID" : "LMI:LMI_SoftwareIdentity:sblim-sfcb-0:1.3.16-3.fc19.x86_64"})
installed_assocs = identity.to_instance().reference_names(
        Role="InstalledSoftware",
        ResultClass="LMI_InstalledSoftwareIdentity")
if len(installed_assocs) > 0:
    for assoc in installed_assocs:
        assoc.to_instance().delete()
        print("deleted %s" % assoc.InstalledSoftware.InstanceID)
else:
    print("no package removed")

Asynchronous removal

c = connect("host", "user", "pass")
service = c.root.cimv2.LMI_SoftwareInstallationService.first_instance()
identity = c.root.cimv2.LMI_SoftwareIdentity.new_instance_name(
        {"InstanceID" : "LMI:LMI_SoftwareIdentity:sblim-sfcb-0:1.3.16-5.fc19.x86_64"})
cs = c.root.cimv2.PG_ComputerSystem.first_instance_name()
ret = service.InstallFromSoftwareIdentity(
        Source=identity,
        Target=cs,
        InstallOptions=[9])  # [Uninstall]

Again please refer to Asynchronous installation for examples on how to deal with the ret value.

LMI metacommand

lmi -h $HOST sw remove sblim-sfcb

Package update

Only asynchronous method is provided for this purpose. But with the possibility of synchronous invocation.

LMIShell

Example below shows the synchronous invocation of asynchronous method:

c = connect("host", "user", "pass")
service = c.root.cimv2.LMI_SoftwareInstallationService.first_instance()
identity = c.root.cimv2.LMI_SoftwareIdentity.new_instance_name(
        {"InstanceID" : "LMI:LMI_SoftwareIdentity:sblim-sfcb-0:1.3.16-5.fc19.x86_64"})
cs = c.root.cimv2.PG_ComputerSystem.first_instance_name()
ret = service.SyncInstallFromSoftwareIdentity(
        Source=identity,
        Target=cs,
        InstallOptions=[5]       # [Update]
        # to force update, when installed package is same or higher version
        #InstallOptions=[4, 5]   # [Install, Update]
)
print "installation " + ("successful" if rval == 0 else "failed")

LMI metacommand

lmi -h $HOST sw update sblim-sfcb

Package verification

Installed RPM packages can be verified. Attributes of installed files are compared with those stored in particular RPM package. If some value of attribute does not match or the file does not exist, it fails the verification test. Following attributes come into play in this process:

  • File size - in case of regular file
  • User ID
  • Group ID
  • Last modification time
  • Mode
  • Device numbers - in case of device file
  • Link Target - in case the file is a symbolic link
  • Checksum - in case of regular file

LMIShell

It’s done via invocation of VerifyInstalledIdentity(). This is an asynchronous method. We can not use synchronous invocation if we want to be able to list failed files.

c = connect("host", "user", "pass")
service = c.root.cimv2.LMI_SoftwareInstallationService.first_instance()
identity = c.root.cimv2.LMI_SoftwareIdentity.new_instance_name(
        {"InstanceID" : "LMI:LMI_SoftwareIdentity:sblim-sfcb-0:1.3.16-5.fc19.x86_64"})
results = service.VerifyInstalledIdentity(
        Source=identity,
        Target=ns.PG_ComputerSystem.first_instance_name())
nevra = (    identity.ElementName if isinstance(identity, LMIInstance)
        else identity.InstanceID[len('LMI:LMI_SoftwareIdentity:'):])
if results.rval != 4096:    # asynchronous job started
    msg = 'failed to verify identity "%s (rval=%d)"' % (nevra, results.rval)
    if results.errorstr:
        msg += ': ' + results.errorstr
    raise Exception(msg)

job = results.rparams['Job'].to_instance()

# wait by polling or listening for indication
wait_for_job_finished(job)

if not LMIJob.lmi_is_job_completed(job):
    msg = 'failed to verify package "%s"' % nevra
    if job.ErrorDescription:
        msg += ': ' + job.ErrorDescription
    raise Exception(msg)

# get the failed files
failed = job.associators(
        AssocClass="LMI_AffectedSoftwareJobElement",
        Role='AffectingElement',
        ResultRole='AffectedElement',
        ResultClass='LMI_SoftwareIdentityFileCheck')
for iname in failed:
    print iname.Name    # print their paths

Polling, as a way of waiting for job completion, has been already shown in the example under Asynchronous installation.

LMI metacommand

lmi -h $HOST sw verify sblim-sfcb

Enable and disable repository

LMIShell

c = connect("host", "user", "pass")
repo = c.root.cimv2.LMI_SoftwareIdentityResource.first_instance_name(
        key="Name",
        value="fedora-updates-testing")
# disable repository
repo.to_instance().RequestStateChange(
    RequestedState=c.root.cimv2.LMI_SoftwareIdentityResource. \
        RequestedStateValues.Disabled)
repo = c.root.cimv2.LMI_SoftwareIdentityResource.first_instance_name(
        key="Name",
        value="fedora-updates")
# enable repository
repo.to_instance().RequestStateChange(
    RequestedState=c.root.cimv2.LMI_SoftwareIdentityResource. \
        RequestedStateValues.Enabled)

LMI metacommand

lmi -h $HOST sw disable fedora-updates-testing
lmi -h $HOST sw enable fedora-updates

Supported event filters

There are various events related to asynchronous job you may be interested in. All of them can be subscribed to with static filters presented below. Usage of custom query strings is not supported due to a complexity of its parsing. These filters should be already registered in CIMOM if OpenLMI-Software provider is installed. You may check them by enumerating CIM_IndicationFilter class located in root/interop namespace. All of them apply to two different software job classes you may want to subscribe to:

LMI_SoftwareInstallationJob
Represents a job requesting to install, update or remove some package.
LMI_SoftwareVerificationJob
Represents a job requesting verification of installed package.

Filters below are written for LMI_SoftwareInstallationJob only. If you deal with the other one, just replace the class name right after the ISA operator and classname in filter’s name.

Percent Updated

Indication is sent when the LMI_SoftwareJob.PercentComplete property of a job changes.

SELECT * FROM LMI_SoftwareInstModification WHERE
    SourceInstance ISA LMI_SoftwareInstallationJob AND
    SourceInstance.CIM_ConcreteJob::PercentComplete <>
    PreviousInstance.CIM_ConcreteJob::PercentComplete

Registered under filter name "LMI:LMI_SoftwareInstallationJob:PercentUpdated".

Job state change

Indication is sent when the LMI_SoftwareJob.JobState property of a job changes.

SELECT * FROM LMI_SoftwareInstModification WHERE
    SourceInstance ISA LMI_SoftwareInstallationJob AND
    SourceInstance.CIM_ConcreteJob::JobState <>
    PreviousInstance.CIM_ConcreteJob::JobState

Registered under filter name "LMI:LMI_SoftwareInstallationJob:Changed".

Job Completed

This event occurs when the state of job becomes COMPLETED/OK [2].

SELECT * FROM LMI_SoftwareInstModification WHERE
    SourceInstance ISA LMI_SoftwareInstallationJob AND
    SourceInstance.CIM_ConcreteJob::JobState = 17

Registered under filter name "LMI:LMI_SoftwareInstallationJob:Succeeded".

Error

This event occurs when the state of job becomes COMPLETED/Error [3].

SELECT * FROM LMI_SoftwareInstModification WHERE
    SourceInstance ISA LMI_SoftwareInstallationJob AND
    SourceInstance.CIM_ConcreteJob::JobState = 10

Registered under filter name "LMI:LMI_SoftwareInstallationJob:Failed".

New Job

This event occurs when the new instance of LMI_SoftwareJob is created.

SELECT * FROM LMI_SoftwareInstCreation WHERE
     SourceInstance ISA LMI_SoftwareInstallationJob

Registered under filter name "LMI:LMI_SoftwareInstallationJob:Created".


[1]

Stands for

Name, Epoch, Version, Release, Architecure.

Please refer to Identifying software identity for more details.

[2]This is a composition of values in OperationalStatus array. It corresponds to value Completed of JobState property.
[3]This is a composition of values in OperationalStatus array. It corresponds to value Exception of JobState property.