A Practical Approach to WBEM[s]CIM Management

The mof Language

General

mof is a textual language used, like UML, to describe CIM models. It generally contains more details than the equivalent UML diagram, but is less easy for a human to read. Some tools are available to assist in the preparation of mof and I discuss these starting on page 273.

The mof language itself is defined in the Common Information Model (CIM) Specification (Document DSP0004 available from the DMTF Web site ( http://www.dmtf.org ). and I make no attempt here to describe the whole language. Instead I give a few pointers to the general syntax of the language and describe how:

• Instances are named: see page 66.

• Qualifiers are defined to specify the format and use of a property or class (e.g., this property has a maximum value of 42): page 69.

• Classes are defined: page 74.

• Association classes are defined: page 77.

• Indication classes are defined: page 78.

• Instances of classes are defined: page 79.

The best examples of mof code are probably the DMTF's core and common models themselves ; you should download these from the DMTF Web site and study them. In general, the following rules apply to mof programs:

• Comments take the C++ and C forms:

  // this is a comment /* and so is this */

• Names are case insensitive (i.e. Disk, DISK and dISk all represent the same object, although it may not be sensible to rely on all implementations following this rule).

• The basic numeric datatypes are better defined than those of C/C++, being signed and unsigned 8, 16, 32 and 64-bit integers, and 4 and 8-byte floating point numbers . Additionally mof supports Booleans, strings, and datetimes as basic datatypes. These are straightforward with the possible exceptions of string and datetime, which I describe in Appendix D.

• There is a number of compiler directives supported through the use of the #pragma construction (a pragma is basically a way of expressing concepts outside the language). These include

  • #pragma namespace() . This pragma specifies the namespace of the following mof code. The concept of a namespace is discussed more fully starting on page 197.

  • #pragma locale() . This pragma specifies the language and country of the system. As I describe later, it is possible for some descriptive text in the mof to be specified in different languages. This pragma defines the actual locale of the management system and thereby allows a particular language to be selected. The format of the pragma is

    #pragma locale("ll_cc")

    where ll is a language code taken from ISO/IEC 639 and cc is a country code taken from ISO/IEC 3166. If no pragma locale is given, then it is assumed to be en_us : i.e. English as spoken in the United States of America. A useful explanation of this coding is given in RFC1766

    Having described this excellent structure for making CIM models international, I must confess that the DMTF core and common models are documented internally only in en_us. There is also a problem associated with locale ”what if a French-speaking operator in Germany is managing a device installed in Croatia? What locale should be used?

    See page 145 for more discussion of locale and international character sets and languages.

  • #pragma include() . As with the C or C++ precompiler, this pragma simply allows another mof file to be included as though it were typed at that point.

• As with C++, constant strings can be continued over a line by closing the quotation marks and re-opening them at the beginning of the next line. Thus

  "I met a " "traveller from " "an antique land"

  is a single string constant comprising

  "I met a traveller from an antique land"

• Enumerations (the equivalent of a C++ enum ) are defined in two parts : a list of the keys, known as a ValueMap, and a list of the associated values, known as Values. This is illustrated in the following definition, taken from the DMTF's model of the class CIM_ProductProductDependency:

  [Description ( "The nature of the Product dependency. This " "property describes that the associated " "Product must be installed (value=2) or " "must be absent (value=3) in order for " "the Product to function."), ValueMap {"0", "1", "2", "3"}, Values {"Unknown", "Other", "Product Must Be Installed", "Product Must Not Be Installed"} ] ] uintl6 TypeOfDependency;

  In this example, TypeOfDependency is an enumerated property which can take the values Unknown, Other, Product Must Be Installed, or Product Must Not Be Installed. These correspond to actual integer values 0, 1, 2, and 3. Note that this example also uses the string-continued-on-next-line convention described earlier.

The Naming of Parts

It must be possible to identify any particular instance of a class uniquely. In the domestic dog example illustrated in Figure 5.3, for example, we need to distinguish Fido (the dog) and Joe (the owner). To do this, we specify that some of Fido's properties (defined on his class or one of his superclasses) have the qualifier KEY . The combination of his namespace, class name , and the values of all keys forms a unique identifier for Fido.

Assume, for example, that the Name property in the DomesticDog class is Fido's only KEY . Then Fido might be identified informally as

root/acne:Dachshund.Name="Fido"

and Joe might be identified by

root/acne:DogOwner.Name="Joe Smith"

In each of these cases, the word "root/acne" is a namespace (presumably registered by the Acne Manufacturing Company for its components ). By the way, although this name contains a slash and a slash is often used in operating systems to represent some form of hierarchy, this namespace is not hierarchical ”it consists of one word containing the symbols r, o, o, t, /, a, c, n, and e.

If you are familiar with C++, then you already understand CIM namespaces. If not, then consider a namespace to be a domain (or container) within which names are unique. Thus you may have a class called Dachshund referring to a new car being developed and I may have a class called Dachshund referring to the type of dog, but as long as they exist in different namespaces, they remain unrelated.

The namespace is followed by the class name and then by a list of key values identifying the particular instance.

More formally , objects (either classes or instances of classes) are uniquely identified by a name known as an Object Path or Object Name. This name is effectively equivalent to a URL and has the following structure:

<namespacePath>:<modelPath>

where the two components also have structure as follows :

• Namespace Path

  • Namespace Type. This specifies the access protocol or API set that must be used to access the instance and any address necessary for reaching the instance. An example of a Namespace Type might be http. ^[6]

  • Namespace Handle. This specifies the namespace within which the instance has been created.

  http://47.2.34.2/root/cimv2 is an example of a Namespace Path.

• Model Path. This part of the name identifies the particular instance within the namespace. It takes the form

  <class>.<key>=<value>,....,<key>=<value>

  An example of a Model Path is ^[7]

  CIM_BGPCluster.ClusterID=74

The full name of a CIM_BGPCluster instance might therefore be

http://47.2.34.2/root/cimv2:CIM_BGPCluster.ClusterID=74

This is the full name (Object Path) of an instance. The same format is used to identify a class but the "key=value" clauses are naturally omitted:

http://47.2.34.2/root/cimv2:CIM_BGPCluster

Weak Associations

I deferred discussion of weak associations until this point because you needed more background information. You are now equipped to dive into the following description.

A weak association is used to name an instance of one class in the context of an instance of another class. For example, the user cwlh may be logged on to several computers at the same time. A particular instance could always be named uniquely by including the particular computer as a property of the user, but this could mean unnecessarily duplicating a significant amount of information. Because there is likely to be an association between the user and the computer already in existence, it would be better to name the user by a combination of the user name (e.g., cwlh ) and the computer name (e.g., mercury ), provided that there is a weak association between the two.

A more realistic example of a weak association is given in Figure 5.12 where a CIM_MPLSService ^[8] is weakly associated with a router, modelled as a CIM_ComputerSystem. The full name of the CIM_MPLS-Service is

Figure 5.12: A Weak Association

CIM_MPLSService.CreationClassName="CIM_MPLSService", Name="MPLSService12", SystemCreationClassName="CIM_ComputerSystem", SystemName="Router6635"

As you can see, a CIM_MPLSService has four keys, all inherited from CIM_Service:

1. CreationClassName: The name of the subclass of CIM_Service to which this instance belongs.

2. Name: The name of this actual MPLS service.

3. SystemCreationClassName: The name of the subclass of CIM_System associated with this MPLS service. The SystemCreationClassName property has a qualifier to say that it is propagated from the CIM_System class property CreationClassName.

4. SystemName: The name of the instance of the CIM_System associated with MPLS service. Again, this property is propagated from CIM_System.

Specifying Qualifiers

Qualifiers give additional information about classes, associations, properties, etc. They may specify the maximum length of a string property, the maximum value of a numeric property, whether a particular property may be modified (written) or only read. The CIM specification defines many qualifiers, some of which I explain here but you can also define your own for conditions specific to your system: "this property must be an IP address."

There is some confusion about whether an instance may have qualifiers. This could mean, for instance, that whereas a string property could be defined at the class level to have a maximum length of 10 characters, a particular instance of the class could have a qualifier saying that the maximum length of the string was only 8 characters . Whether or not this is legal is somewhat ambiguous at the moment and is being resolved in the DMTF ”probably by making instance qualifiers illegal.

Some of the more important qualifiers predefined by the CIM standard include:

• WRITE to indicate that a property may be changed by an operator.

• READ to indicate that a property may be accessed by an operator.

• KEY to indicate that the value of a property (or reference) forms part or all of the key of an instance, allowing the instance to be uniquely identified as described above. Thus, for example, in the definition of a CIM_BGPCluster in the network model, the ClusterID property is defined with the qualifier KEY as follows:

  [Key, Description ( "If a cluster has more than one route reflector, " "all of the route reflectors in the cluster need " "to be configured with a 4-byte cluster ID. This " "allows route reflectors to recognize updates " "from other route reflectors in the same cluster.") ] uint32 ClusterID;

  This means that a particular instance of a CIM_BGPCluster is identified by having a unique ClusterID. In general a class can have several keys and it is the combination of key values that makes each instance unique.

• ABSTRACT to indicate that a class has been defined only to be a superclass for other classes. It is not possible to create an instance of a class which has the ABSTRACT qualifier. If you are familiar with the C++ language, this terminology will not be new ”a C++ class which can only act as a superclass for other classes is called an abstract class. Sometimes italic text is used for the class name on the UML diagram to indicate that the class is abstract.

• TERMINAL to indicate almost the opposite of ABSTRACT ”this class may not be subclassed. Naturally, a class may not be both ABSTRACT and TERMINAL .

• MAXVALUE to define the maximum value a property, method, or parameter may have.

• REQUIRED to indicate that a property must have a genuine (non-NULL) value.

• DESCRIPTION to allow a full textual description of a class, property, association, or parameter to be included in the mof in such a way that it is stored in the repository and made available at run time for enquiries. See Figure 5.14 on page 77 for a good example of the use of the DESCRIPTION qualifier.

• VERSION to allow a version number to be associated with every class, association, or indication. As with the DESCRIPTION qualifier (or, indeed, any qualifier), you can read the value associated with the VERSION qualifier from the repository with a query. See Figure 5.14 on page 77 for an example of the VERSION qualifier.

• PROPAGATED to allow a key property in one instance to be associated through a so-called weak association (see page 68) with a key property on another instance, allowing the number of keys to be reduced. I give an example of the use of the PROPAGATED qualifier on page 68.

• DEPRECATED to discourage the use of a class. This qualifier is used in the DMTF's models where a class has been superseded by a different class, but the old class has been retained for backwards compatibility ”the qualifier effectively means that you should not use the class for new models, but that it will remain for use in your existing models. Whenever the qualifier is used, it should point to the new, nondeprecated class.

• MAPPINGSTRINGS to allow a particular property (or class) to be defined as equivalent to a particular property in another model. This is a particularly important concept during migration from a legacy management system to WBEM, and I give a slightly extended description in Appendix E.

• MIN and MAX to specify the way in which an association may or must be used. These qualifiers can be confusing because they appear at first glance to refer to the "wrong end" of the association and a few examples may be in order. Assume that an association links an instance of class A (antecedent) with an instance of class B (dependent). The following conditions may occur depending on the application:

  • Any number (including zero) of B instances may be associated with an instance of A. In this case no MIN and MAX qualifiers are needed.

  • At least one instance of an A is required for each instance of a B. This is represented by mof of the form

    [Min(1)] A REF antecedent; B REF dependent;

  • At most six instances of an A are permitted for each instance of a B. This is represented by mof of the form

    [Max(6)] A REF antecedent; B REF dependent;

  • Exactly one, two, or three instances of an A are permitted for each instance of a B. This is represented by mof of the form

    [Max(3),Min(1)] A REF antecedent; B REF dependent;

  MAX and MIN qualifiers are illustrated in Figure 6.3 on page 98, where they are used to specify that precisely one (not zero, not two) instance of CIM_ManagedElement must be associated with each instance of CIM_StatisticalData. This means that whenever an instance of CIM_StatisticalData is created, an instance of CIM_ElementStatisticalData must be created to associate it with exactly one CIM_ManagedElement.

These are a very small selection from a wide range of predefined qualifiers. You may also specify your own qualifiers. Assume, for example, that you require a qualifier on properties which requires that the property have a genuine (non-NULL) value on Tuesdays. This could be declared in the mof as follows:

qualifier RequiredOnTuesdays : Boolean = false, scope (property), flavor (DisableOverride);

(note the en_us spelling of "flavour"). This declaration defines a new qualifier called RequiredOnTuesdays , which can take the values true and false (i.e., it is a Boolean) and defaults to the value false . It can be applied to a property (but not, for example, to a class or association) and it may not be overridden in a subclass.

As the RequiredOnTuesdays example shows, qualifiers may have flavours. A flavour typically specifies whether a qualifier on a class should be inherited by subclasses and, if so, whether the subclasses may override it. In the RequiredOnTuesdays example, the qualifier is inherited by the properties in all subclasses of the class to which it is applied and may not be overridden there.

Be aware that if you do create your own qualifiers, then there is the possibility that the name you choose ( RequiredOnTuesdays in this example) will clash with a name chosen in the future by the DMTF. The CIM specification includes a complete list of the current qualifier names and some names reserved for future use ”obviously, you should avoid these, but it would probably be safer if you prepended your company's registered name to any qualifier names you choose (ACNERequiredOnTuesdays).

Another important flavor of a qualifier is Translatable . Consider, for example, the definition of the qualifier Description as given in the standard mof :

Qualifier Description : string = null, Scope(any), Flavor(Translatable);

This defines the qualifier Description as being a string which may be applied to any mof entity: property, class, etc. A description may also be translated into different languages, identified in the class or property definition by a pseudo-qualifier of the form Description_ll_cc where 11 is the language code (from ISO/IEC 639) and cc the country code (from ISO/IEC 3166) of the language. Consider, for example, the dog-owning hierarchy illustrated in Figure 5.3 on page 54. The description of a (male) dog owner might be

Description_en_gb ("Chap who has a dog"), Description_en_us ("Guy who has a dog"), Description_fr_fr ("Mec qui a un chien"), Description_fr_ca ("Gars qui a un chien"), Description_de_de ("Bursche, der einen Hund hat"), Description_de_at ("Mannaz, der einen Hund hat")

Another qualifier which has the Translatable flavor is Values: see page 66. This allows the Values associated with a value map to be written in several languages:

Valuemap {"1", "2", "3"}, Values_en_gb {"Dog", "Elephant", "Cat" }, Values_fr_fr {"Chien", "Elephant", "Chat"}, Values_de_de {"Hund", "Elefant", "Katze" }

For more details of some of the more nonintuitive standard qualifiers, see page 189. That section covers, in particular, the OVERRIDE qualifier which can be awkward to use correctly.

Specifying Classes

Apart from the inclusion of qualifiers in square brackets, the syntax for specifying a class in mof will be familiar to any C++ programmer:

[ <Qualifiers> ] class <class name> : <superclass name> { <property or method>; <property or method>; ..... <property or method>; };

Each property has the format:

[ <qualifiers> ] <type> <name> { = <default> };

and each method has the format:

[ <qualifiers> ] <return type> <method name>(<parameter>, ... <parameter>);

where, again, a parameter consists of a list of qualifiers in square brackets, followed by a type, followed by the parameter name. A simple property and method might therefore be coded in mof as follows (both taken from the CIM_LogicalDevice class):

[Deprecated { "CIM_PoweredStatisticalData.TotalPowerOnHours"}, Description ( "The total number of hours that this Device has been " "powered."), Units ( "Hours"), Counter ] uint64 TotalPowerOnHours; [Description ( "Requests a reset of the LogicalDevice. The return value " "should be 0 if the request was successfully executed, 1 " "if the request is not supported and some other value if " "an error occurred. In a subclass, the set of possible " "return codes could be specified, using a ValueMap " "qualifier on the method. The strings to which the " "ValueMap contents are 'translated' may also be specified " "in the subclass as a Values array qualifier.") ] uint32 Reset();

In addition to being able to specify a single property, mof can also specify that a property is an array of any of the basic types ”integers, strings, Booleans, dates, and floating point numbers ”but not of references (i.e., pointers to other objects). The syntax is again very similar to C/C++: square brackets after the property name, possibly enclosing a constant which specifies the array size . Thus Figure 5.13 defines an array of uint16s called LabelStack as one of the properties of the class CIM_MPLSCrossConnect, which is a CIM_Service. Note the use of the qualifier Ordered in this definition; mof allows three types of array to be specified:

1. A bag ”an unordered array which allows duplicate entries. The array index has no significance for the items in a bag other than a guarantee that if all the possible indices are accessed then all items in the bag will have been accessed. There is no concept of ordinality for the items in a bag. If no qualifier is given, then an array is assumed to be a bag.

2. An ordered list (as in Figure 5.13) ”like a bag, an ordered list allows entries to be duplicated , but the index now specifies an order for the entries when they are accessed.

3. An indexed array ”like an Ordered List but where items can be overwritten but not deleted. The index starts at 0 and has no gaps.

class CIM_MPLSCrossConnect : CIM_Service { ..... snip ..... [Description ( "Identifies a stack of labels to be pushed beneath " "the top label. Note that the top label identified " "in an instance of OutSegment ensures that all the " "components of a multipoint-to-point connection " "have the same outgoing label. This array is " "'Ordered' to maintain the sequence of entries."), ArrayType ("Ordered") ] uintl6 LabelStack[]; ..... snip ..... };

An example of a class definition, taken from the Network Common Model, is given by Figure 5.14. This defines the class CIM_BGPCluster as a subclass of CIM_CollectionOfMSEs. Notice the following points about this definition:

• The extensive use of the DESCRIPTION qualifier. This qualifier allows a textual description of any type of object (class, method, property, etc.) to be included in the repository. Because this makes it accessible for querying, using this qualifier is preferable to using comments in the mof code.

• ClusterID is a key for a CIM_BGPCluster.

• The version number of the class is included as a qualifier: again allowing it to be accessed by an operator.

// ======================================================== // BGPCluster // ======================================================== [Version ("2.6.0"), Description ( "The BGP speakers in an AS are required to be " "fully meshed. This can lead to a huge number " "of TCP connections per router. One way to reduce " "the peering requirements is to use a route " "reflector. This is based on specifying one or " "more routers to act as focal points for IBGP " "sessions.\n\n" "The route reflector as a whole is called a cluster. " "It is logically divided into three types of routers: " "reflectors, clients of the route reflector(s), and " "non-clients of the route reflector. There can be " "more than one route reflector in a cluster, and " "there can be more than one cluster in an AS.") ] class CIM_BGPCluster : CIM_CollectionOfMSEs { [Key, Description ( "If a cluster has more than one route reflector, " "all of the route reflectors in the cluster need " "to be configured with a 4-byte cluster ID. This " "allows route reflectors to recognize updates from " "other route reflectors in the same cluster.") ] uint32 ClusterID; };

Specifying Associations

Syntactically, associations look much like classes (not unreasonably ”they are classes). A class becomes an association by the inclusion of the qualifier ASSOCIATION as illustrated in Figure 5.15.

// ========================================================== // RangesOfConfiguration // ========================================================== [Association, Experimental, Version ("2.7.0"), Description ( "This association connects address ranges to the " "OSPF area " "......much description cut for simplicity.......... " "to allow or disallow advertisements in the range.") ] class CIM_RangesOfConfiguration : CIM_Dependency { [Override ("Antecedent"), Description ( "The address range that is in the OSPF area " "configuration.") ] CIM_RangeOfIPAddresses REF Antecedent; [Override ("Dependent"), Description ( "The OSPF area config that contains the range.") ] CIM_OSPFAreaConfiguration REF Dependent; [Description ( "The address range is advertised (TRUE) or not " "(FALSE), see C.2 in RFC 2328.") ] boolean EnableAdvertise; };

The following points can be noted in this example:

• The class CIM_RangesOfConfiguration is a subclass of the class CIM_Dependency from which it inherits and overrides the properties Antecedent and Dependent.

• The keyword REF is used to define a "pointer" to the objects linked by this association. Note that all REFs must be keys.

• This association contains a property, EnableAdvertise , which is not a reference to another object. This is an example of an association with an additional property.

In the example shown in Figure 5.15 there are only two REFs ”i.e., two objects are being associated. This is normally the case but, in principle, an association can relate any number (greater than 1) of objects.

Specifying Indications

Indications are just classes which inherit, directly or indirectly, from CIM_Indication. They have no special format.

Specifying Instances

In addition to defining classes, the mof language can be used to specify instances of classes. This feature is used for instances where, for some reason (e.g. the instance is completely static) the instance does not depend on the run-time environment; it can be specified in advance. As the mof is compiled, any providers handling the creation of instances will be invoked as if the instance had been created by an operator. The format is as follows:

instance of <class name> { [ <property qualifiers> ] <property name> = <value>; ..... [ <property qualifiers> ] <property name> = <value>; };

For example, an instance of a CIM_BGPCluster as defined in Figure 5.14 could be specified in mof as follows:

instance of CIM_BGPCluster { clusterID = 73; };

To create an instance of an association, you must be able to specify the instances which it associates . An instance of CIM_RangesOfConfigur-ation as defined in Figure 5.15 could be coded as follows:

// definition of antecedent and dependent // earlier in the mof instance of CIM_RangeOfIPAddresses as $LHS { ... definition ... }; instance of CIM_OSPFAreaConfiguration as $RHS { ... definition ... }; // definition of the association instance instance of CIM_RangesOfConfiguration { Antecedent = $LHS; Dependent = $RHS; EnableAdvertise = true; };

Note that, in this case, the Antecedent and Dependent have been set to point to other instances created earlier in the file by using the technique known as aliasing ”specifying an alias for an instance when it is specified so that it can be referenced elsewhere (forward references and even circular references are allowed). Without this technique, it would have been necessary to specify the full Object Path of the instance (see page 64 above).

Models form abstractions useful to different operators managing a device or service. These models abstract away the actual hardware and software implementations and present a common picture to operators, independent of the particular device or service implementation. In CIM such models may be expressed graphically in UML or textually in mof.

^[6] Hypertext Transfer Protocol: a generic, stateless, object-oriented protocol described in RFC1945.

^[7] BGP is a protocol used by two IP routers owned by different companies to exchange reachability information ”see Glossary.

^[8] MPLS: Multi-Protocol Label Switching: A layer 2.5 connection-oriented communications protocol ”see Glossary.