Chapter 12 Using the XML Interface With the Logical Domains Manager

This chapter explains the Extensible Markup Language (XML) communication mechanism through which external user programs can interface with Logical Domains software. These basic topics are covered:

• XML Transport

• XML Protocol

• Event Messages

• Logical Domains Manager Actions

• Logical Domains Manager Resources and Properties

For various schemas to use with the Logical Domains Manager, see Appendix A, XML Schemas.

XML Transport

External programs can use the Extensible Messaging and Presence Protocol (XMPP – RFC 3920) to communicate with the Logical Domains Manager. XMPP is supported for both local and remote connections and is on by default. To shut off a remote connection, set the ldmd/xmpp_enabled SMF property to false and restart the Logical Domains Manager.

# svccfg -s ldom/ldmd setprop ldmd/xmpp_enabled=false
# svcadm refresh ldmd
# svcadm restart ldmd

XMPP Server

The Logical Domains Manager implements an XMPP server which can communicate with numerous available XMPP client applications and libraries. The LDoms Manager uses the following security mechanisms:

• Transport Layer Security (TLS) to secure the communication channel between the client and itself.

• Simple Authentication and Security Layer (SASL) for authentication. PLAIN is the only SASL mechanism supported. You must send in a user name and password to the server, so it can authorize you before allowing monitoring or management operations.

Local Connections

The LDoms Manager detects whether user clients are running on the same domain as itself and, if so, does a minimal XMPP handshake with that client. Specifically, the SASL authentication step after the setup of a secure channel through TLS is skipped. Authentication and authorization are done based on the credentials of the process implementing the client interface.

Clients can choose to implement a full XMPP client or to simply run a streaming XML parser, such as the libxml2 Simple API for XML (SAX) parser. Either way the client has to handle an XMPP handshake to the point of TLS negotiation. Refer to the XMPP specification for the sequence needed.

XML Protocol

After communication initialization is complete, LDoms-defined XML messages are sent next. There are two general types of XML messages:

• Request and response messages use the <LDM_interface> tag. This type of XML message is used for communicating commands and getting results back from the LDoms Manager, analogous to executing commands using the command-line interface (CLI). This tag is also used for event registration and unregistration.

• Event messages use the <LDM_event> tag. This type of XML message is used to asynchronously report events posted by the LDoms Manager.

Request and Response Messages

The XML interface into LDoms has two different formats:

• One format for sending commands into the LDoms Manager

• Another format for LDoms Manager to respond on the status of the incoming message and the actions requested within that message.

The two formats share many common XML structures, but are separated in this discussion for a better understanding of the differences between them. This document also contains an XML Schema which details the combined incoming and outgoing XML (See LDM_Event XML Schema).

Request Messages

An incoming XML request to the LDoms Manager at its most basic level includes a description of a single command, operating on a single object. More complicated requests can handle multiple commands and multiple objects per command. Following is the structure of a basic XML command.

Example 12–1 Format of a Single Command Operating on a Single Object

<LDM_interface version="1.0">
  <cmd>
    <action>Place command here</action>
    <option>Place options for certain commands here</option>
    <data version="3.0">
      <Envelope>
        <References/>
        <!-- Note a <Section> section can be here instead of <Content> -->
        <Content xsi:type="ovf:VirtualSystem_Type" id="Domain name">
          <Section xsi:type="ovf:ResourceAllocationSection_type">
            <Item>
              <rasd:OtherResourceType>LDom Resource Type</rasd:OtherResourceType>
              <gprop:GenericProperty
              key="Property name">Property Value</gprop:GenericProperty>
            </Item>
          </Section>
          <!-- Note: More Sections sections can be placed here -->
        </Content>
      </Envelope>
    </data>
    <!-- Note: More Data sections can be placed here -->
  </cmd>
  <!-- Note: More Commands sections can be placed here -->
</LDM_interface>

The <LDM_interface> Tag

All commands sent to the LDoms Manager must start with the <LDM_interface> tag. Any document sent into the LDoms Manager must have only one <LDM_interface> tag contained within it. The <LDM_interface> tag must include a version attribute as shown in Example 12–1.

The <cmd> Tag

Within the <LDM_interface> tag, the document must include at least one <cmd> tag. Each <cmd> section must have only one <action> tag. Use the <action> tag to describe the command to run. Each <cmd> tag must include at least one <data> tag to describe the objects on which the command is to operate.

The <cmd> tag can also have an <option> tag, which is used for options and flags that are associated with some commands. The following commands use options:

• The remove-domain command can use the -a option.

• The stop-domain command can use the -f option.

• The cancel-operation command can use the migration or reconf option.

• The add-spconfig command can use the -r autosave-name option.

• The remove-spconfig command can use the -r option.

• The list-spconfig command can use the -r [autosave-name] option.

The <data> Tag

Each <data> section contains a description of an object pertinent to the command specified. The format of the data section is based on the XML schema portion of the Open Virtualization Format (OVF) draft specification. That schema defines an <Envelope> section which contains a <References> tag (unused by LDoms) and <Content> and <Section> sections.

For LDoms, the <Content> section is used to identify and describe a particular domain. The domain name in the id= attribute of the <Content> node identifies the domain. Within the <Content> section are one or more <Section> sections describing resources of the domain as needed by the particular command.

If you only need to identify a domain name, then you do not need to use any <Section> tags. Conversely, if no domain identifier is needed for the command, then you do need to provide a <Section> section, describing the resources needed for the command, outside of a <Content> section, but still within the <Envelope> section.

A <data> section does not need to contain an <Envelope> tag in cases where the object information can be inferred. This situation mainly applies to requests for monitoring all objects applicable to an action, and event registration and unregistration requests.

To allow use of the OVF specification's schema to properly define all types of objects, two additional OVF types have been defined:

• <gprop:GenericProperty> tag (See The GenericProperty XML Schema.)

• <Binding> tag (See Binding_Type XML Schema.)

The <gprop:GenericProperty> tag was defined to handle any object's property for which the OVF specification does not have a definition. The property name is defined in the key= attribute of the node and the value of the property is the contents of the node. The <binding> tag is used in the list-bindings subcommand output to define resources that are bound to other resources.

Response Messages

An outgoing XML response closely matches the structure of the incoming request in terms of the commands and objects included, with the addition of a <Response> section for each object and command specified, as well as an overall <Response> section for the request. The <Response> sections provide status and message information as described in Example 12–2. Following is the structure of a response to a basic XML request.

Example 12–2 Format of a Response to a Single Command Operating on a Single Object

<LDM_interface version="1.0">
  <cmd>
    <action>Place command here</action>
    <data version="3.0">
      <Envelope>
        <References/>
        <!-- Note a <Section> section can be here instead of <Content> -->
        <Content xsi:type="ovf:VirtualSystem_Type" id="Domain name">
          <Section xsi:type="ovf:ResourceAllocationSection_type">
            <Item>
              <rasd:OtherResourceType>
                LDom Resource Type
              </rasd:OtherResourceType>
              <gprop:GenericProperty
              key="Property name">
                Property Value
            </gprop:GenericProperty>
            </Item>
          </Section>
          <!-- Note: More <Section> sections can be placed here -->
        </Content>
      </Envelope>
      <response>
        <status>success or failure</status>
        <resp_msg>Reason for failure</resp_msg>
      </response>
    </data>
    <!-- Note: More Data sections can be placed here -->
    <response>
      <status>success or failure</status>
      <resp_msg>Reason for failure</resp_msg>
    </response>
  </cmd>
  <!-- Note: More Command sections can be placed here -->
  <response>
    <status>success or failure</status>
    <resp_msg>Reason for failure</resp_msg>
  </response>
</LDM_interface>

Overall Response

This <response> section, which is the direct child of the <LDM_interface> section, indicates overall success or failure of the entire request. Unless the incoming XML document is malformed, the <response> section includes only a <status> tag. If this response status indicates success, all commands on all objects have succeeded. If this response status is a failure and there is no <resp_msg> tag, then one of the commands included in the original request failed. The <resp_msg> tag is used only to describe some problem with the XML document itself.

Command Response

The <response> section under the <cmd> section alerts the user to success or failure of that particular command. The <status> tag shows if that command succeeds or fails. As with the overall response, if the command fails, the <response> section includes only a <resp_msg> tag if the contents of the <cmd> section of the request is malformed. Otherwise, the failed status means one of the objects the command ran against caused a failure.

Object Response

Finally, each <data> section in a <cmd> section also has a <response> section. This shows if the command being run on this particular object passes or fails. If the status of the response is SUCCESS, there is no <resp_msg> tag in the <response> section. If the status is FAILURE, there are one or more <resp_msg> tags in the <response> field, depending on the errors encountered when running the command against that object. Object errors can result from problems found when running the command, or a malformed or unknown object.

In addition to the <response> section, the <data> section can contain other information. This information is in the same format as an incoming <data> field, describing the object that caused a failure. See The <data> Tag. This additional information is especially useful in the following cases:

• When a command fails against a particular <data> section but passes for any additional <data> sections

• When an empty <data> section is passed into a command and fails for some domains but passes for others

Event Messages

In lieu of polling, you can subscribe to receive event notifications of certain state changes that occur. There are three types of events to which you can subscribe, individually or collectively. See Event Types for complete details.

Registration and Unregistration

Use an <LDM_interface> message to register for events. See The <LDM_interface> Tag. The action tag details the type of event for which to register or unregister and the <data> section is left empty.

Example 12–3 Example Event Registration Request Message

<LDM_interface version="1.0">
  <cmd>
    <action>reg-domain-events</action>
    <data version="3.0"/>
  </cmd>
</LDM_interface>

The Logical Domains Manager responds with an <LDM_interface> response message stating whether the registration or unregistration was successful.

Example 12–4 Example Event Registration Response Message

<LDM_interface version="1.0">
  <cmd>
    <action>reg-domain-events</action>
    <data version="3.0"/>
      <response>
        <status>success</status>
      </response>
    </data>
    <response>
      <status>success</status>
    </response>
  </cmd>
  <response>
    <status>success</status>
  </response>
</LDM_interface>

The action string for each type of event is listed in the events subsection.

The <LDM_event> Messages

Event messages have the same format as an incoming <LDM_interface> message with the exception that the start tag for the message is <LDM_event>. The action tag of the message is the action that was performed to trigger the event. The data section of the message describes the object associated with the event; the details depend on the type of event that occurred.

Example 12–5 Example <LDM_event> Notification

<LDM_event version='1.0'>
  <cmd>
    <action>Event command here</action>
    <data version='3.0'>
      <Envelope
        <References/>
        <Content xsi:type='ovf:VirtualSystem_Type' ovf:id='ldg1'/>
          <Section xsi:type="ovf:ResourceAllocationSection_type"> 
            <Item>
              <rasd:OtherResourceType>LDom Resource Type</rasd:OtherResourceType>
              <gprop:GenericProperty
              key="Property name">Property Value</gprop:GenericProperty>
            </Item>
          </Section>
      </Envelope>
    </data>
  </cmd>
</LDM_event>

Event Types

Following are the event types to which you can subscribe:

• Domain events

• Hardware events

• Progress events

• Resource events

All the events correspond to Logical Domains Manager (ldm) subcommands.

Domain Events

Domain events describe what actions can be performed directly to a domain. The following table shows the domain events which can be listed in the <action> tag in the <LDM_event> message.

These events always contain only a <Content> tag in the OVF data section that describes to which domain the event happened. To register for the domain events, send an <LDM_interface> message with the <action> tag set to reg-domain-events. Unregistering for these events requires an <LDM_interface> message with the action tag set to unreg-domain-events.

Hardware Events

Hardware events pertain to changing the physical system hardware. In the case of LDoms software, the only hardware changes that can be made are those to the service processor (SP) when a user adds, removes, or sets an SP configuration. Currently, the only three events of this type are:

• add-spconfig

• set-spconfig

• remove-spconfig

The hardware events always contain only a <Section> tag in the OVF data section which describes which SP configuration to which the event is happening. To register for these events, send an <LDM_interface> message with the <action> tag set to reg-hardware-events. Unregistering for these events requires an <LDM_interface> message with the <action> tag set to unreg-hardware-events.

Progress Events

Progress events are issued for long-running commands, such as a domain migration. These events report the amount of progress that has been made during the life of the command. At this time, only the migration-process event is reported.

Progress events always contain only a <Section> tag in the OVF data section that describes the SP configuration affected by the event. To register for these events, send an <LDM_interface> message with the <action> tag set to reg-hardware-events. Unregistering for these events requires an <LDM_interface> message with the <action> tag set to unreg-hardware-events.

The <data> section of a progress event consists of a <content> section that describes the affected domain. This <content> section uses an ldom_info <Section> tag to update progress. The following generic properties are shown in the ldom_info section:

• --progress – Percentage of the progress made by the command

• --status – Command status, which can be one of ongoing, failed, or done

• --source – Machine that is reporting the progress

Resource Events

Resource events occur when resources are added, removed, or changed in any domain. The data section for some of these events contains the <Content> tag with a <Section> tag giving a service name in the OVF data section. The following table shows events which can be listed in the <action> tag in the <LDM_event> message.

The remaining resource events always contain only the <Content> tag in the OVF data section that describes to which domain the event happened.

To register for the resource events, send an <LDM_interface> message with the <action> tag set to reg-resource-events. Unregistering for these events requires an <LDM_interface> message with the <action> tag set to unreg-resource-events.

All Events

You can also register to listen for all three type of events without having to register for each one individually. To register for all three types of events simultaneously, send an <LDM_interface> message with the <action> tag set to reg-all-events. Unregistering for these events require an <LDM_interface> message with the <action> tag set to unreg-all-events.

Logical Domains Manager Actions

The commands specified in the <action> tag, with the exception of *-*-events commands, correspond to those of the LDoms command-line interface. For details about Logical Domains Manager (ldm) subcommands, see the ldm(1M) man page.

The XML interface does not support the verb or command aliases supported by the Logical Domains Manager CLI.

The supported strings in the <action> tag are as follows:

Logical Domains Manager Resources and Properties

Following are the Logical Domains Manager resources and the properties that can be defined for each of those resources. The resources and properties are shown in bold type in the XML examples. These examples show resources, not binding output. The constraint output can be used to create input for the Logical Domains Manager actions. The exception to this is domain migration output. See Domain Migration. Each resource is defined in a <Section> OVF section and is specified by a <rasd:OtherResourceType> tag.

Logical Domain Information (ldom_info) Resource

Example 12–6 Example ldom_info XML Output

<Envelope>
  <References/>
  <Content xsi:type="ovf:VirtualSystem_Type" id="primary">
    <Section xsi:type="ovf:ResourceAllocationSection_type">
      <Item>
        <rasd:OtherResourceType>ldom_info</rasd:OtherResourceType>
        <rasd:Address>00:03:ba:d8:ba:f6</rasd:Address>
        <gprop:GenericPropertykey="hostid">83d8baf6</gprop:GenericProperty>
        <gprop:GenericProperty key="master">plum</gprop:GenericProperty>
        <gprop:GenericProperty key="failure-policy">reset</gprop:GenericProperty>
        <gprop:GenericProperty key="progress">45%</gprop:GenericProperty>
        <gprop:GenericProperty key="status">ongoing</gprop:GenericProperty>
        <gprop:GenericProperty key="source">dt90-319</gprop:GenericProperty>
      </Item>
    </Section>
  </Content>
</Envelope>

The ldom_info resource is always contained within a <Content> section. The following properties within the ldom_info resource are optional properties:

• <rasd:Address> tag, which specifies the MAC address to be assigned to a domain.

• <gprop:GenericPropertykey="failure-policy"> tag, which specifies how slave domains should behave should the master domain fail. The default value is ignore. Following are the valid property values:

  • ignore ignores failures of the master domain (slave domains are unaffected).

  • panic panics any slave domains when the master domain fails.

  • reset resets any slave domains when the master domain fails.

  • stop stops any slave domains when the master domain fails.

• <gprop:GenericPropertykey="hostid"> tag, which specifies the host ID to be assigned to the domain.

• <gprop:GenericPropertykey="master"> tag, which specifies up to four comma-separated master domain names.

• <gprop:GenericPropertykey="progress"> tag, which specifies the percentage of progress made by the command.

• <gprop:GenericPropertykey="source"> tag, which specifies the machine reporting on the progress of the command.

• <gprop:GenericPropertykey="status"> tag, which specifies the status of the command (done, failed, or ongoing).

CPU (cpu) Resource

Example 12–7 Example cpu XML

<Envelope>
  <References/>
  <Content xsi:type="ovf:VirtualSystem_Type" id="ldg1">
    <Section xsi:type="ovf:VirtualHardwareSection_Type">
      <Item>
        <rasd:OtherResourceType>cpu</rasd:OtherResourceType>
        <rasd:AllocationUnits>4</rasd:AllocationUnits>
      </Item>
    </Section>
  </Content>
</Envelope>

A cpu resource is always contained within a <Content> section. The only property is the <rasd:AllocationUnits> tag, which specifies the number of virtual CPUs.

MAU (mau) Resource

The mau resource is any LDoms-supported cryptographic unit on an LDoms-supported server. Currently, the two cryptographic units supported are the Modular Arithmetic Unit (MAU) and the Control Word Queue (CWQ).

Example 12–8 Example mau XML

<Envelope>
  <References/>
  <Content xsi:type="ovf:VirtualSystem_Type" id="ldg1">
    <Section xsi:type="ovf:VirtualHardwareSection_Type">
      <Item>
        <rasd:OtherResourceType>mau</rasd:OtherResourceType>
        <rasd:AllocationUnits>1</rasd:AllocationUnits>
      </Item>
    </Section>
  </Content>
</Envelope>

A mau resource is always contained within a <Content> section. The only property is the <rasd:AllocationUnits> tag, which signifies the number of MAUs or other cryptographic units.

Memory (memory) Resource

Example 12–9 Example memory XML

<Envelope>
  <References/>
  <Content xsi:type="ovf:VirtualSystem_Type" id="ldg1">
    <Section xsi:type="ovf:VirtualHardwareSection_Type">
      <Item>
        <rasd:OtherResourceType>memory</rasd:OtherResourceType>
        <rasd:AllocationUnits>4G</rasd:AllocationUnits>
      </Item>
    </Section>
  </Content>
</Envelope>

A memory resource is always contained within a <Content> section. The only property is the <rasd:AllocationUnits> tag, which signifies the amount of memory.

Virtual Disk Server (vds) Resource

Example 12–10 Example vds XML

<Envelope>
  <References/>
  <Content xsi:type="ovf:VirtualSystem_Type" id="ldg1">
    <Section xsi:type="ovf:VirtualHardwareSection_Type">
      <Item>
        <rasd:OtherResourceType>vds</rasd:OtherResourceType>
        <gprop:GenericProperty
          key="service_name">vdstmp</gprop:GenericProperty>
      </Item>
    </Section>
  </Content>
</Envelope>

A virtual disk server (vds) resource can be in a <Content> section as part of a domain description, or it can appear on its own in an <Envelope> section. The only property is the <gprop:GenericProperty> tag with a key of service_name and which contains the name of the vds resource being described.

Virtual Disk Server Volume (vds_volume) Resource

Example 12–11 Example vds_volume XML

<Envelope>
  <References/>
    <Section xsi:type="ovf:VirtualHardwareSection_Type">
      <Item>
        <rasd:OtherResourceType>vds_volume</rasd:OtherResourceType>
        <gprop:GenericProperty key="vol_name">vdsdev0</gprop:GenericProperty>
        <gprop:GenericProperty key="service_name">primary-vds0</gprop:GenericProperty>
        <gprop:GenericProperty key="block_dev">
          opt/SUNWldm/domain_disks/testdisk1</gprop:GenericProperty>
        <gprop:GenericProperty key="vol_opts">ro</gprop:GenericProperty>
        <gprop:GenericProperty key="mpgroup">mpgroup-name</gprop:GenericProperty>
      </Item>
    </Section>
</Envelope>

A vds_volume resource can be in a <Content> section as part of a domain description, or it can appear on its own in an <Envelope> section. It must have <gprop:GenericProperty> tags with the following keys:

• vol_name – Name of the volume

• service_name – Name of the virtual disk server to which this volume is to be bound

• block_dev – File or device name to be associated with this volume

Optionally, a vds_volume resource can also have the following properties:

• vol_opts – One or more of the following, comma-separated, within one string: {ro,slice,excl}

• mpgroup – Name of the multipath (failover) group

Disk (disk) Resource

Example 12–12 Example disk XML

<Envelope>
  <References/>
  <Content xsi:type="ovf:VirtualSystem_Type" id="ldg1">
    <Section xsi:type="ovf:VirtualHardwareSection_Type">
      <Item>
        <rasd:OtherResourceType>disk</rasd:OtherResourceType>
        <gprop:GenericProperty key="vdisk_name">vdisk0</gprop:GenericProperty>
        <gprop:GenericProperty
          key="service_name">primary-vds0</gprop:GenericProperty>
        <gprop:GenericProperty key="vol_name">vdsdev0</gprop:GenericProperty>
        <gprop:GenericProperty key="timeout">60</gprop:GenericProperty>
      </Item>
    </Section>
  </Content>
</Envelope>

A disk resource is always contained within a <Content> section. It must have <gprop:GenericProperty> tags with the following keys:

• vdisk_name – Name of the virtual disk

• service_name – Name of the virtual disk server to which this virtual disk is to be bound

• vol_name – Virtual disk service device with which this virtual disk is to be associated

Optionally, the disk resource can also have the timeout property, which is the timeout value in seconds for establishing a connection between a virtual disk client (vdc) and a virtual disk server (vds). If there are multiple virtual disk (vdisk) paths, then the vdc can try to connect to a different vds, and the timeout ensures that a connection to any vds is established within the specified amount of time.

Virtual Switch (vsw) Resource

Example 12–13 Example vsw XML

<Envelope>
  <References/>
  <Content xsi:type="ovf:VirtualSystem_Type" id="ldg1">
    <Section xsi:type="ovf:VirtualHardwareSection_Type">
      <Item>
        <rasd:OtherResourceType>vsw</rasd:OtherResourceType>
        <gprop:GenericProperty key="service_name">vsw1-ldg1</gprop:GenericProperty>
        <gprop:GenericProperty key="dev_path">bge0</gprop:GenericProperty>
        <gprop:GenericProperty key="linkprop">phys-state</gprop:GenericProperty>
        <rasd:Address>00:14:4f:fc:00:01</rasd:Address>
        <gprop:GenericProperty key="mode">sc</gprop:GenericProperty>
        <gprop:GenericProperty key="pvid">12345678</gprop:GenericProperty>
        <gprop:GenericProperty key="vid">87654321</gprop:GenericProperty>
      </Item>
    </Section>
  </Content>
</Envelope>

A vsw resource can be either in a <Content> section as part of a domain description, or it can appear on its own in an <Envelope> section. It must have <gprop:GenericProperty> tags with the following keys:

• service_name – Name to be assigned to the virtual switch.

• linkprop – Specifies whether the virtual device should get physical link state updates. When the value is phys-state, the virtual device gets physical link state updates. When the value is blank, the virtual device does not get physical link state updates. By default, the virtual device does not get physical link state updates.

• dev_path – Path of the network device to be associated with this virtual switch

Optionally, the vsw resource can also have the following properties:

• <rasd:Address> – Assigns a MAC address to the virtual switch

• pvid – Port virtual local area network (VLAN) identifier (ID) indicates the VLAN of which the virtual network needs to be a member, in untagged mode.

• vid – Virtual local area network (VLAN) identifier (ID) indicates the VLAN of which a virtual network and virtual switch need to be a member, in tagged mode.

• mode – sc for SunCluster heartbeat support.

Network (network) Resource

Example 12–14 Example network XML

<Envelope>
  <References/>
  <Content xsi:type="ovf:VirtualSystem_Type" id="ldg1">
    <Section xsi:type="ovf:VirtualHardwareSection_Type">
      <Item>
        <rasd:OtherResourceType>network</rasd:OtherResourceType>
        <gprop:GenericProperty key="linkprop">phys-state</gprop:GenericProperty>
        <gprop:GenericProperty key="vnet_name">ldg1-vnet0</gprop:GenericProperty>
        <gprop:GenericProperty
          key="service_name">primary-vsw0</gprop:GenericProperty>
        <rasd:Address>00:14:4f:fc:00:01</rasd:Address>
      </Item>
    </Section>
  </Content>
</Envelope>

A network resource is always contained within a <Content> section. It must have <gprop:GenericProperty> tags with the following keys:

• linkprop – Specifies whether the virtual device should get physical link state updates. When the value is phys-state, the virtual device gets physical link state updates. When the value is blank, the virtual device does not get physical link state updates. By default, the virtual device does not get physical link state updates.

• vnet_name – Name of the virtual network (vnet)

• service_name – Name of the virtual switch (vswitch) to which this virtual network is to be bound

Optionally, the network resource can also have the following properties:

• <rasd:Address> – Assigns a MAC address to the virtual switch

• pvid – Port virtual local area network (VLAN) identifier (ID) indicates the VLAN of which the virtual network needs to be a member, in untagged mode.

• vid – Virtual local area network (VLAN) identifier (ID) indicates the VLAN of which a virtual network and virtual switch need to be a member, in tagged mode.

• mode – hybrid to enable hybrid I/O for that virtual network.

Virtual Console Concentrator (vcc) Resource

Example 12–15 Example vcc XML

<Envelope>
  <References/>
  <Content xsi:type="ovf:VirtualSystem_Type" id="ldg1">
    <Section xsi:type="ovf:VirtualHardwareSection_Type">
      <Item>
        <rasd:OtherResourceType>vcc</rasd:OtherResourceType>
        <gprop:GenericProperty key="service_name">vcc1</gprop:GenericProperty>
        <gprop:GenericProperty key="min_port">6000</gprop:GenericProperty>
        <gprop:GenericProperty key="max_port">6100</gprop:GenericProperty>
      </Item>
    </Section>
  </Content>
</Envelope>

A vcc resource can be either in a <Content> section as part of a domain description, or it can appear on its own in an <Envelope> section. It can have <gprop:GenericProperty> tags with the following keys:

• service_name – Name to be assigned to the virtual console concentrator service

• min_port – Minimum port number to be associated with this vcc

• max_port – Maximum port number to be associated with this vcc

Variable (var) Resource

Example 12–16 Example var XML

<Envelope>
  <References/>
  <Content xsi:type="ovf:VirtualSystem_Type" id="ldg1">
    <Section xsi:type="ovf:VirtualHardwareSection_Type">
      <Item>
        <rasd:OtherResourceType>var</rasd:OtherResourceType>
        <gprop:GenericProperty key="name">test_var</gprop:GenericProperty>
        <gprop:GenericProperty key="value">test1</gprop:GenericProperty>
      </Item>
    </Section>
  </Content>
</Envelope>

A var resource is always contained within a <Content> section. It can have <gprop:GenericProperty> tags with the following keys:

• name – Name of the variable

• value – Value of the variable

Physical I/O Device (physio_device) Resource

Example 12–17 Example physio_device XML

<Envelope>
  <References/>
  <Content xsi:type="ovf:VirtualSystem_Type" id="ldg1">
    <Section xsi:type="ovf:VirtualHardwareSection_Type">
      <Item>
        <rasd:OtherResourceType>physio_device</rasd:OtherResourceType>
        <gprop:GenericProperty key="name">pci@780</gprop:GenericProperty>
      </Item>
    </Section>
  </Content>
</Envelope>

A physio_device resource is always contained within a <Content> section. The only property is the <gprop:GenericProperty> tag with the name key property value, which is the name of the I/O device being described.

SP Configuration (spconfig) Resource

Example 12–18 Example spconfig XML

<Envelope>
    <Section xsi:type="ovf:ResourceAllocationSection_type">
      <Item>
        <rasd:OtherResourceType>spconfig</rasd:OtherResourceType>
        <gprop:GenericProperty
          key="spconfig_name">primary</gprop:GenericProperty>
        <gprop:GenericProperty
          key="spconfig_status">current</gprop:GenericProperty>
      </Item>
    </Section>
</Envelope>

A service processor (SP) configuration (spconfig) resource always appears on its own in an <Envelope> section. It can have <gprop:GenericProperty> tags with the following keys

• spconfig_name – Name of a configuration to be stored on the SP

• spconfig_status – The current status of a particular SP configuration. This property is used in the output of an ldm list-spconfig command.

Virtual Data Plane Channel Service (vdpcs) Resource

Example 12–19 Example vdpcs XML

<Envelope>
  <References/>
  <Content xsi:type="ovf:VirtualSystem_Type" id="ldg1">
    <Section xsi:type="ovf:VirtualHardwareSection_Type">
      <Item>
        <rasd:OtherResourceType>vdpcs</rasd:OtherResourceType>
        <gprop:GenericProperty key="service_name">dg1-vdpcs</gprop:GenericProperty>
      </Item>
    </Section>
  </Content>
</Envelope>

This resource is only of interest in a Netra DPS environment. A vdpcs resource can be either in a <Content> section as part of a domain description, or it can appear on its own in an <Envelope> section. The only property is the <gprop:GenericProperty> tag with the service_name key property value, which is the name of the virtual data plane channel service (vdpcs) resource being described.

Virtual Data Plane Channel Client (vdpcc) Resource

Example 12–20 Example vdpcc XML

<Envelope>
  <References/>
  <Content xsi:type="ovf:VirtualSystem_Type" id="ldg1">
    <Section xsi:type="ovf:VirtualHardwareSection_Type">
      <Item>
        <rasd:OtherResourceType>vdpcc</rasd:OtherResourceType>
        <gprop:GenericProperty key="vdpcc_name">vdpcc</gprop:GenericProperty>
        <gprop:GenericProperty
          key="service_name">ldg1-vdpcs</gprop:GenericProperty>
      </Item>
    </Section>
  </Content>
</Envelope>

This resource is only of interest in a Netra DPS environment. A virtual data plane channel client resource is always contained within a <Content> section. It can have <gprop:GenericProperty> tags with the following keys:

• vdpcc_name – Name of the virtual data plane channel client (vdpcc)

• service_name – Name of the virtual data plane channel service vdpcs to which this vdpcc is to be bound

Console (console) Resource

Example 12–21 Example console XML

<Envelope>
  <References/>
  <Content xsi:type="ovf:VirtualSystem_Type" id="ldg1">
    <Section xsi:type="ovf:VirtualHardwareSection_Type">
      <Item>
        <rasd:OtherResourceType>console</rasd:OtherResourceType>
        <gprop:GenericProperty key="port">6000</gprop:GenericProperty>
        <gprop:GenericProperty key="service_name">vcc2</gprop:GenericProperty>
        <gprop:GenericProperty key="group">group-name</gprop:GenericProperty>
      </Item>
    </Section>
  </Content>
</Envelope>

A console resource is always contained within a <Content> section. It can have <gprop:GenericProperty> tags with the following keys:

• port – Port to which to change this virtual console (console)

• service_name – Virtual console concentrator (vcc) service to which to bind this console

• group – Name of the group to which to bind this console

Domain Migration

This example shows what is contained in the <data> section for a migrate-domain subcommand.

Example 12–22 Example migrate-domain <data> Section

<Envelope>
  <References/>
  <Content xsi:type="ovf:VirtualSystem_Type" ovf:id="ldg1"/>
  <Content xsi:type="ovf:VirtualSystem_Type" ovf:id="ldg1"/>
    <Section xsi:type="ovf:ResourceAllocationSection_Type">
      <Item>
        <rasd:OtherResourceType>ldom_info</rasd:OtherResourceType>
        <gprop:GenericProperty key="target">target-host</gprop:GenericProperty>
        <gprop:GenericProperty key="username">user-name</gprop:GenericProperty>
        <gprop:GenericProperty key="password">password</gprop:GenericProperty>
      <Item>
    </Section>
  </Content>
</Envelope>

Where:

• First <Content> node (without an <ldom_info> section) is the source domain to migrate.

• Second <Content> node (with an <ldom_info> section) is the target domain to which to migrate. The source and target domain names can be the same.

• The <ldom_info> section for the target domain describes the machine to which to migrate and the details needed to migrate to that machine:

  • target-host is the target machine to which to migrate.

  • user-name is the login user name for the target machine. Must be SASL 64-bit encoded.

  • password is the password to use for logging into the target machine. Must be SASL 64-bit encoded.

The Logical Domains Manager uses sasl_decode64() to decode the target user name and password and uses sasl_encode64() to encode these values. SASL 64 encoding is equivalent to base64 encoding.