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:
|
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:
|
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:
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:
|
Optional in WindowsProvisioningConfiguration. Contains properties that define a domain to which the Virtual Machine will be joined. |
|
Optional in WindowsProvisioningConfiguration. Contains a list of service certificates with which to provision to the new Virtual Machine. |
|
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:
The default value is true. |
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.
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:
|
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.