Sysprep Image Configuration

 1 ===========================
   2 Sysprep Image Configuration
   3 ===========================
   4
   5 This document describes configuring instances using the
   6 ``sysprep`` configuration strategy, which allows passing
   7 a customized unattend.xml to an instance using
   8 Microsoft Windows System Preparation (Sysprep).
   9 Sysprep allows customizing many aspects of a Windows system
  10 as it boots.
  11
  12 This implementation of Sysprep passes the configuration options in
  13 an unattend.xml file in a CD-ROM device presented to the guest system.
  14 It's expected that the image is ready for Sysprep,
  15 and that it will run Sysprep to read the unattend.xml,
  16 and apply the customization
  17 when an instance using the image boots.
  18
  19 The ``sysprep`` configuration strategy described in this document
  20 is an example of a pluggable configuration strategy,
  21 as described in pluggable_config_strategies.rst.
  22
  23
  24 Overview
  25 ========
  26
  27 Sysprep configuration in OpenStack requires that the administrator
  28 set the ``configuration_strategy`` image metadata to a JSON document
  29 that contains a template unattend.xml file and a mapping of configuration
  30 property key names to elements or attributes in the template.
  31 The image metadata is described in the `Image metadata` section.
  32
  33 When nova-compute is booting the new instance
  34 it generates a configuration property map.
  35 The configuration property map contains properties
  36 that OpenStack picks for the instance (for example, the IP address) and
  37 properties that the user can set for the instance
  38 (provided as metadata on the boot request).
  39 The configuration properties are described in the
  40 `Configuration properties` section.
  41
  42 Next, using the mapping from the image metadata,
  43 nova-compute maps the configuration properties to
  44 unattend.xml elements or attributes and
  45 generates an unattend.xml file that is presented to the guest
  46 as a cdrom.
  47 The property mapping is described in the `Property mapping` section.
  48
  49 Users will have to know the extra metadata options that
  50 they can set for the image when they use it to create a new instance.
  51 When the user creates an instance,
  52 they specify extra metadata on the boot request
  53 (this is the ``--meta`` option on the nova command line).
  54
  55
  56 Image metadata
  57 ==============
  58
  59 In order to cause the Sysprep configuration strategy to be active for
  60 an image, the image metadata must be set as described in this section.
  61
  62 The ``configuration_strategy`` metadata item for the image must be
  63 set to a JSON object that contains the template unattend.xml and the
  64 mapping from the configuration properties to the entities or attributes.
  65 Configuration properties are described in the next section.
  66
  67 The format for the ``configuration_strategy`` metadata item is like::
  68
  69  {
  70    "type": "sysprep",
  71    "properties": {
  72        "metadata_template": "--template-unattend--",
  73        "mapping": [
  74            {
  75              "source": "--configuration-property-key-name--",
  76              "target": "--path-to-element-or-attribute--"
  77            }, ...
  78          ]
  79      }
  80  }
  81
  82 Notes:
  83
  84 * The type must be ``sysprep`` otherwise the configuration strategy is ignored.
  85 * The ``metadata_template`` is set to a template unattend.xml.
  86   It's an XML document.
  87 * Mapping contains an array of objects, where the object has a
  88   ``source`` member that is the configuration property key,
  89   and the ``target`` is the path to an element or attribute
  90   which will be set to that configuration property's value.
  91   See the `Path to Element or Attribute Format` section for the
  92   format of the ``target`` value.
  93
  94 Here's an example, with the template unattend.xml elided for brevity::
  95
  96  {
  97    "type": "sysprep",
  98    "properties": {
  99        "metadata_template": "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n <unattend xmlns=\"urn:schemas-microsoft-com:unattend\">...</unattend>",
 100        "mapping": [
 101          {
 102            "source": "server.metadata.colorDepth",
 103            "target": ".//{urn:schemas-microsoft-com:unattend}Display/{urn:schemas-microsoft-com:unattend}ColorDepth"
 104          }
 105        ]
 106      }
 107  }
 108
 109
 110 Path to Element or Attribute Format
 111 -----------------------------------
 112
 113 The format of the ``target`` values in the mapping is as follows:
 114
 115 * To identify an element, the format is an XPATH.
 116   In this case, the contents of the element are replaced with the
 117   value of the source configuration property.
 118 * To identify an attribute, the format is like ``XPATH@attribute-name``.
 119   In this case, the attribute in the element is set to the
 120   value of the source configuration property.
 121
 122 For documentation on the XPATH format, see the python documentation:
 123 http://docs.python.org/2/library/xml.etree.elementtree.html#xpath-support
 124
 125 Note that if the path identifies more than one element,
 126 only one of the elements will be the target element.
 127 If the path doesn't identify an element in the template
 128 the boot of the instance will fail with an error.
 129
 130 The following examples assume this template is used::
 131
 132  <?xml version="1.0" encoding="utf-8"?>
 133  <unattend xmlns="urn:schemas-microsoft-com:unattend">
 134      <settings pass="oobeSystem">
 135          <component name="Microsoft-Windows-Shell-Setup" processorArchitecture="amd64" xmlns:wcm="http://schemas.microsoft.com/WMIConfig/2002/State">
 136              <Display>
 137                  <ColorDepth>16</ColorDepth>
 138                  <HorizontalResolution>1024</HorizontalResolution>
 139                  <RefreshRate>60</RefreshRate>
 140                  <VerticalResolution>768</VerticalResolution>
 141              </Display>
 142              <RegisteredOrganization>OpenStack</RegisteredOrganization>
 143              <OOBE>
 144                  <HideEULAPage>true</HideEULAPage>
 145                  <NetworkLocation>Cluster</NetworkLocation>
 146                  <ProtectYourPC>1</ProtectYourPC>
 147                  <SkipMachineOOBE>true</SkipMachineOOBE>
 148                  <SkipUserOOBE>true</SkipUserOOBE>
 149              </OOBE>
 150          </component>
 151      </settings>
 152  </unattend>
 153
 154 The following path identifies the ColorDepth element::
 155
 156  .//{urn:schemas-microsoft-com:unattend}Display/{urn:schemas-microsoft-com:unattend}ColorDepth
 157
 158 The following path identifies the `processorArchitecture` attribute in the
 159 component element::
 160
 161  .//{urn:schemas-microsoft-com:unattend}component[@name='Microsoft-Windows-Shell-Setup']@processorArchitecture
 162
 163
 164 Utility
 165 -------
 166
 167 A utility is provided to make it easier to generate the metadata for an image
 168 for the sysprep configuration strategy. To run the utility, run
 169 ``python $NOVA_PREFIX/nova/compute/configuration_strategy_sysprep.py``
 170 (replacing ``$NOVA_PREFIX`` with the location of your Nova install).
 171
 172 Following is the help text::
 173
 174  $ python $NOVA_PREFIX/nova/compute/configuration_strategy_sysprep.py -h
 175  usage: configuration_strategy_sysprep.py [-h] --unattend FILENAME
 176                                           [--mapping TARGET=SOURCE]
 177                                           [--auth_token FILENAME]
 178                                           [--image_id ID] [--replace]
 179
 180  optional arguments:
 181    -h, --help            show this help message and exit
 182    --unattend FILENAME   The unattend.xml file
 183    --mapping TARGET=SOURCE
 184                          A property mapping
 185    --auth_token FILENAME
 186                          File containing authentication token
 187    --image_id ID         Image ID
 188    --replace             Replace existing attribute
 189
 190 Tip:
 191 To generate the ``auth_token`` file run ``keystone token-get``
 192 and then create a file containing just the token with
 193 ``echo -n "..." > auth_token``.
 194
 195
 196 Here's an example running the utility::
 197
 198  $ python /opt/stack/nova/nova/compute/configuration_strategy_sysprep.py \
 199      --unattend unattend.xml \
 200      --mapping ".//{urn:schemas-microsoft-com:unattend}AdministratorPassword/{urn:schemas-microsoft-com:unattend}Value=server.metadata.admin_password" \
 201      --auth_token auth_token \
 202      --image_id 237d6175-00b8-4983-b488-9648da71c250
 203
 204 The utility prints out the HTTP result code for the operation.
 205 ``200 OK`` is printed for success.
 206 If the result is ``409 Conflict``
 207 the ``configuration_strategy`` already exists;
 208 use the ``--replace`` option to overwrite the current value.
 209
 210
 211 Configuration properties
 212 ========================
 213
 214 The names of the configuration properties are the values used
 215 in the ``source`` attributes in the ``mapping`` in the
 216 ``configuration_strategy`` in the image metadata.
 217 The configuration properties come from 2 sources:
 218
 219 A) Properties provided by OpenStack (network info, etc., as described below)
 220 B) Properties provided by the user on the boot
 221
 222 The following table describes the properties provided by OpenStack:
 223
 224 ==================================  ==================================
 225 Name                                Description
 226 ==================================  ==================================
 227 server.admin_password               Random administrator password generated by OpenStack.
 228 server.hostname                     The hostname for this instance.
 229 server.domainname                   Domain name, usually like novalocal,
 230                                     from the dhcp_domain configuration option.
 231 server.dns-client.pri_dns           Primary DNS server IP address.
 232 server.network.[n].mac              Mac address for network interface number n.
 233 server.network.[n].slotnumber       Slot number for network interface number n.
 234 server.network.[n].[v4|v6].address  IPv4 or IPv6 address for network interface number n.
 235 server.network.[n].[v4|v6].netmask  IPv4 or IPv6 netmask for network interface number n.
 236 server.network.[n].[v4|v6].gateway  IPv4 or IPv6 gateway for network interface number n.
 237 server.network.[n].v4.use_dhcp      ``true`` if the network uses DHCP.
 238 ==================================  ==================================
 239
 240 Slot number is defined as the decimal value of the last two digits of the mac address.
 241
 242 In addition to the OpenStack properties, the metadata provided by the user
 243 on the boot are prefixed with 'server.metadata.'.
 244
 245 Example
 246 -------
 247
 248 The following table is an example set of configuration properties that would
 249 be available to the mapping,
 250 given the following assumptions:
 251
 252 1) The instance is booted with the following command,
 253 where 07900b0a-c137-41d0-b9cc-4171dbbcb28a is an image with sysprep metadata:
 254
 255 ::
 256
 257  nova boot appliance-1 \
 258    --image "07900b0a-c137-41d0-b9cc-4171dbbcb28a" \
 259    --flavor 1 \
 260    --meta=system.password='somepassword'
 261
 262 2) OpenStack picks the following values:
 263
 264 * Administrator password is DC3b7thv9i3G
 265 * Hostname is appliance-1
 266 * The configured domain name is novalocal
 267 * The primary DNS server is 10.10.0.1
 268 * A single IPv4 interface with IP address 10.0.0.2, netmask 255.255.255.0, and gateway 10.0.0.1.
 269
 270 Following are the configuration property names and values that would result:
 271
 272 =====================================================  ===============
 273 Name                                                   Value
 274 =====================================================  ===============
 275 server.admin_password                                  DC3b7thv9i3G
 276 server.hostname                                        appliance-1
 277 server.domainname                                      novalocal
 278 server.dns-client.pri_dns                              10.10.0.1
 279 server.network.1.v4.address                            10.0.0.2
 280 server.network.1.v4.netmask                            255.255.255.0
 281 server.network.1.v4.gateway                            10.0.0.1
 282 server.metadata.system.password                        somepassword
 283 =====================================================  ===============
 284
 285
 286 Property mapping
 287 ================
 288
 289 When an instance boots and the sysprep image metadata is present,
 290 an unattend.xml file is created that is modified by
 291 looking up the element or attribute associated with
 292 each target path specified in the mapping and replacing the
 293 contents with the configuration property value.
 294
 295 When the image owner sets the properties for the image,
 296 they specify which values the user can override when
 297 booting the image by using properties with a name starting
 298 with ``server.metadata.``.
 299 Users set the value by specifying the metadata as the ``--meta``
 300 value when they boot the image.
 301
 302
 303 Setting customization options on the boot
 304 =========================================
 305
 306 When booting an image with sysprep metadata,
 307 the user can pass in metadata to set configuration options.
 308 The user must know which properties to set.
 309 The properties are specified as the ``source`` values that start with ``server.metadata``
 310 in the ``mapping`` section
 311 in the ``configuration_properties`` value
 312 in the image metadata.
 313
 314 For example, if the ``configuration_properties`` in the image metadata has::
 315
 316  {
 317    "type": "sysprep",
 318    "properties": {
 319        "metadata_template": "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n <unattend xmlns=\"urn:schemas-microsoft-com:unattend\">...</unattend>",
 320        "mapping": [
 321          {
 322            "source": "server.metadata.colorDepth",
 323            "target": ".//{urn:schemas-microsoft-com:unattend}Display/{urn:schemas-microsoft-com:unattend}ColorDepth"
 324          }
 325        ]
 326      }
 327  }
 328
 329 Then users can set the ``server.metadata.colorDepth`` option on boot using the ``--meta`` option,
 330 like this::
 331
 332  nova boot --image myimage1 --meta=colorDepth=24