Capture Role

 

The Capture Role operation creates a copy of the operating system virtual hard disk (VHD) that is associated with the Virtual Machine, saves the VHD copy in the same storage location as the operating system VHD, and registers the copy as an image the image repository. You must prepare the Virtual Machine by running the Sysprep command and you must shut down the Virtual Machine before you can capture an image from it.

Request

The Capture Role request may be specified as follows. Replace <subscription-id> with the subscription ID, <cloudservice-name> with the name of the cloud service, <deployment-name> with the name of the deployment, and <role-name> with the name of the Virtual Machine.

Method

Request URI

POST

https://management.core.windows.net/<subscription-id>/services/hostedservices/<cloudservice-name>/deployments/<deployment-name>/roleinstances/<role-name>/Operations

URI Parameters

None.

Request Headers

The following table describes the request headers.

Request Header

Description

x-ms-version

Required. Specifies the version of the operation to use for this request. This header should be set to 2012-03-01 or higher.

Request Body

The following example shows the format of the request body:

<CaptureRoleOperation xmlns="https://schemas.microsoft.com/windowsazure" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <OperationType>CaptureRoleOperation</OperationType>
  <PostCaptureAction>recreate-virtual-machine</PostCaptureAction>
  <ProvisioningConfiguration> 
    <ConfigurationSetType>WindowsProvisioningConfiguration</ConfigurationSetType>
    <ComputerName>name-of-virtual-machine</ComputerName>
    <AdminPassword>administrator-password-for-virtual-machine</AdminPassword> 
    <EnableAutomaticUpdates>enable-updates</EnableAutomaticUpdates>  
    <TimeZone>time-zone</TimeZone>
    <DomainJoin>
      <Credentials>
        <Domain>domain-to-join</Domain>
        <Username>user-name-in-the-domain</Username>
        <Password>password-for-the-user-name</Password>
      </Credentials>
      <JoinDomain>domain-to-join</JoinDomain>
      <MachineObjectOU>distinguished-name-of-the-ou</MachineObjectOU>
    </DomainJoin>
    <StoredCertificateSettings>
      <CertificateSetting>
        <StoreLocation>LocalMachine</StoreLocation>
        <StoreName>name-of-store-on-the-machine</StoreName>
        <Thumbprint>certificate-thumbprint</Thumbprint>
      </CertificateSetting>
    </StoredCertificateSettings>
    <WinRM>
      <Listeners>
        <Listener>
          <Protocol>protocol-of-listener</Type>
        </Listener>
        <Listener>
          <CertificateThumbprint>certificate-thumbprint</CertificateThumbprint>
          <Protocol>protocol-of-listener</Protocol>
        </Listener>
      </Listeners>
    </WinRm>
    <AdminUsername>name-of-administrator-account</AdminUsername>
    <CustomData>base-64-encoded-data</CustomData>
    <AdditionalUnattendContent>
      <Passes>
        <UnattendPass>
          <PassName>name-of-pass</PassName>
          <Components>
            <ComponentName>name-of-component</ComponentName>
            <ComponentSettings>
              <ComponentSetting>
                <SettingName>name-of-setting</SettingName>
                <Content>base-64-encoded-XML-content</Content>
              </ComponentSetting>
            </ComponentSettings>
          </Components>
        </UnattendedPass>
      </Passes>
    </AdditionalUnattendedContent>
  </ProvisioningConfiguration> 
  <TargetImageLabel>label-of-image</TargetImageLabel>
  <TargetImageName>name-of-image</TargetImageName>
</CaptureRoleOperation>

The following example shows the format of the request body to capture a Linux Virtual Machine:

<CaptureRoleOperation xmlns="https://schemas.microsoft.com/windowsazure" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <OperationType>CaptureRoleOperation</OperationType>
  <PostCaptureAction>Delete|Reprovision</PostCaptureAction>
  <ProvisioningConfiguration>
    <ConfigurationSetType>LinuxProvisioningConfiguration</ConfigurationSetType>
    <HostName>host-name-for-the-vm</HostName>
    <UserName>new-user-name</UserName> 
    <UserPassword>password-for-the-new-user</UserPassword> 
    <DisableSshPasswordAuthentication>enable-authentication</DisableSshPasswordAuthentication>           
    <SSH>
      <PublicKeys>
        <PublicKey>
          <Fingerprint>certificate-fingerprint</Fingerprint>
          <Path>SSH-public-key-storage-location</Path>     
        </PublicKey>
      </PublicKeys>
      <KeyPairs>
        <KeyPair>
          <Fingerprint>certificate-fingerprint</Fingerprint>
          <Path>SSH-public-key-storage-location</Path>
        </KeyPair>
      </KeyPairs>
    </SSH>
    <CustomData>base-64-encoded-data</CustomData>
  </ProvisioningConfiguration>
  <TargetImageLabel>label-of-image</TargetImageLabel>
  <TargetImageName>name-of-image</TargetImageName>
</CaptureRoleOperation>

The following table describes the elements of the request body.

Element name

Description

OperationType

Required. Must be set to CaptureRoleOperation.

PostCaptureAction

Required. Specifies the action that is performed after the capture operation finishes.

Possible values are:

  • Delete – this value causes the virtual machine to be deleted after the image has been captured.

  • Reprovision – this value causes the virtual machine to be redeployed after the image is captured by using the specified information in ProvisioningConfiguration.

ProvisioningConfiguration

Optional. Contains information that is used to redeploy a Virtual Machine after an image has been captured. This element is only used when the PostCaptureAction is set to Reprovision.

TargetImageLabel

Required. Specifies the description of the captured image. The value of this element is only obtained programmatically and does not appear in the Management Portal.

TargetImageName

Required. Specifies the name of the captured image.

ProvisioningConfiguration

Contains information that is used to redeploy a Virtual Machine after an image has been captured.

Element name

Description

ConfigurationSetType

Required. To provision a new Virtual Machine, you must specify one of the following configuration sets:

  • WindowsProvisioningConfiguration

  • LinuxProvisioningConfiguration

ComputerName

Optional in WindowsProvisioningConfiguration. Specifies the computer name for the Virtual Machine. If you do not specify a computer name, one is assigned that is a combination of the deployment name, role name, and identifying number. Computer names must be 1 to 15 characters long.

AdminPassword

Required in WindowsProvisioningConfiguration. Specifies the base-64-encoded string that contains the administrator password to use for the Virtual Machine.

EnableAutomaticUpdates

Optional in WindowsProvisioningConfiguration. Specifies whether automatic updates are enabled for the Virtual Machine.

Possible values are:

  • true

  • false

The default value is true.

TimeZone

Optional in WindowsProvisioningConfiguration. Specifies the time zone for the Virtual Machine.

For a complete list of supported time zone entries, you can:

  • Refer to the values listed in the registry entry HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Time Zones.

  • You can use the tzutil command-line tool to list the valid time.

DomainJoin

Optional in WindowsProvisioningConfiguration. Contains properties that define a domain to which the Virtual Machine will be joined.

StoredCertificateSettings

Optional in WindowsProvisioningConfiguration. Contains a list of service certificates with which to provision to the new Virtual Machine.

WinRM

Optional in WindowsProvisioningConfiguration. Contains configuration settings for the Windows Remote Management service on the Virtual Machine. This enables remote Windows PowerShell.

AdminUsername

Required in WindowsProvisioningConfiguration. Specifies the name of the default administrator account. This is a required parameter after version 2013-03-01.

CustomData

Optional in WindowsProvisioningConfiguration. Specifies a base-64 encoded string of custom data. The base-64 encoded string is decoded to a binary array that is saved as a file on the Virtual Machine. The maximum length of the binary array is 65535 bytes. The file is saved to %SYSTEMDRIVE%\AzureData\CustomData.bin. If the file exists, it is overwritten. The security on directory is set to System:Full Control and Administrators:Full Control.

The CustomData element is only available using version 2013-10-01 or higher.

AdditionalUnattendContent

Optional. Specifies additional base-64 encoded XML formatted information that can be included in the Unattend.xml file, which is used by Windows Setup.

The AdditionalUnattendContent element is only available using version 2014-04-01 or higher.

HostName

Required in LinuxProvisioningConfiguration. Specifies the host name for the Virtual Machine. Host names must be 1 to 64 characters long.

UserName

Required in LinuxProvisioningConfiguration. Specifies the name of a user account to be created in the sudoer group of the Virtual Machine. User account names must be 1 to 32 characters long.

UserPassword

Required in LinuxProvisioningConfiguration. Specifies the password for the user account. Passwords must be 6 to 72 characters long.

DisableSshPasswordAuthentication

Optional in LinuxProvisioningConfiguration. Specifies whether SSH password authentication is disabled. By default this value is set to true.

Possible values are:

  • true

  • false

The default value is true.

SSH

Optional in LinuxProvisioningConfiguration. Specifies the SSH public keys and key pairs to use with the Virtual Machine.

CustomData

Optional in LinuxProvisioningConfiguration. Specifies a base-64 encoded string of custom data. The base-64 encoded string is located in the ovf-env.xml file on the ISO of the Virtual Machine. The file is copied to /var/lib/waagent/ovf-env.xml by the Azure Linux Agent. The Azure Linux Agent will also place the base-64 encoded data in /var/lib/waagent/CustomData during provisioning. The maximum length of the binary array is 65535 bytes.

The CustomData element is only available using version 2013-10-01 or higher.

DomainJoin

Contains properties that define a domain to which the Virtual Machine will be joined.

Element name

Description

Credentials

Optional. Specifies the credentials to use to join the Virtual Machine to the domain.

JoinDomain

Optional. Specifies the domain to join.

MachineObjectOU

Optional. Specifies the Lightweight Directory Access Protocol (LDAP) X 500-distinguished name of the organizational unit (OU) in which the computer account is created. This account is in Active Directory on a domain controller in the domain to which the computer is being joined.

Example:

OU=MyOu,OU=MyParentOu,DC=example.com,DC=MyCompany,DC=com

Credentials

Specifies the credentials to use to join the Virtual Machine to the domain.

Domain

Optional. Specifies the name of the domain used to authenticate an account. The value is a fully qualified DNS domain. If the domains name is not specified, Username must specify the user principal name (UPN) format (user@fully-qualified-DNS-domain) or the fully-qualified-DNS-domain\username format.

Example:

example.com

Username

Required. Specifies a user name in the domain that can be used to join the domain.

Password

Required. Specifies the password to use to join the domain.

StoredCertificateSettings

Contains a list of service certificates with which to provision to the new Virtual Machine. Stored certificate settings reference certificates that already exist in the cloud service. Before you configure the stored certificates for the Virtual Machine, you must call the Add Service Certificate operation or add the certificate by using the Management portal.

Element name

Description

CertificateSetting

Required. Specifies the parameters for the certificate.

StoreLocation

Required. Specifies the certificate store location on the Virtual Machine.

The only supported value is LocalMachine.

StoreName

Required. Specifies the name of the certificate store from which the certificate is retrieved.

For example, “My”.

Thumbprint

Required. Specifies the thumbprint of the certificate. The thumbprint must specify an existing service certificate.

WinRM

Contains configuration settings for the Windows Remote Management service on the Virtual Machine.

Element name

Description

Listeners

Required. Contains a collection of information for enabling remote Windows PowerShell.

Listener

Required. Specifies the protocol and certificate information for the listener.

Protocol

Specifies the protocol of listener.

  • Http

  • Https

The value is case sensitive.

CertificateThumbprint

Optional. Specifies the certificate thumbprint for the secure connection. If this value is not specified, a self-signed certificate is generated and used for the Virtual Machine.

AdditionalUnattendContent

Specifies additional base-64 encoded XML formatted information that can be included in the Unattend.xml file, which is used by Windows Setup.

Element name

Description

PassName

Required. Specifies the name of the pass that the content applies to. The only allowable value is oobeSystem.

ComponentName

Required. Specifies the name of the component to configure with the added content. The only allowable value is Microsoft-Windows-Shell-Setup.

SettingName

Required. Specifies the name of the setting to which the content applies.

Possible values are:

  • FirstLogonCommands

  • AutoLogon

Content

Required. Specifies the base-64 encoded XML formatted content that is added to the unattend.xml file for the specified path and component. The XML must be less that 4 KB and must include the root element for the setting or feature that is being inserted.

SSH

Specifies the SSH public keys and key pairs to use with the Virtual Machine.

Element name

Description

PublicKeys

Optional. Specifies the collection of SSH public keys.

PublicKey

Required. Specifies the public key.

FingerPrint

Required. Specifies the SHA1 fingerprint of an X509 certificate associated with the hosted service that includes the SSH public key.

Path

Required. Specifies the full path of a file, on the Virtual Machine, where the SSH public key is stored. If the file already exists, the specified key is appended to the file.

Example:

/home/user/.ssh/authorized_keys

KeyPairs

Required. Contains a collection of SSH key pairs.

KeyPair

Required. Contains an SSH key pair to be installed on the virtual machine.

FingerPrint

Required. Specifies the SHA1 fingerprint of an X509 certificate that is associated with the cloud service and includes the SSH keypair.

Path

Required. Specifies the full path of a file, on the virtual machine, which stores the SSH private key. The file is overwritten when multiple keys are written to it. The SSH public key is stored in the same directory and has the same name as the private key file with .pub suffix.

Example:

/home/user/.ssh/id_rsa

Response

The response includes an HTTP status code, a set of response headers, and a response body.

Status Code

A successful operation returns status code 202 (Accepted).

Response Headers

The response for this operation includes the following headers. The response may also include additional standard HTTP headers.

Response Header

Description

x-ms-request-id

A value that uniquely identifies a request made against the management service.

Response Body

None.

Remarks

The image that is captured from the Virtual Machine is located in the same storage account its operating system disk. You can find the name of the storage account by looking at the Disks section of the dashboard for the Virtual Machine in the portal.