Get Metadata About a Running VM

CloudShare enables you to retrieve useful metadata parameters from a currently-running VM via a simple API call.

Accessing VM metadata can provide key data, which can be used in custom scripts that you execute while an environment is running.

Note

To enable execution of custom scripts whenever an environment is created, contact CloudShare at support@cloudshare.com.

Using the Metadata Provider

There are two ways to invoke the CloudShare metadata provider with your VM:

Add the desired metadata command to a custom script or batch file that will be executed by the VM.
Open a browser tab in the running VM and enter the desired command into the address bar as a URL.

The metadata provider API can only execute from inside a running VM with a network connection.

For either of these methods, the basic metadata provider call is:

https://metadata.cloudshare.com/api/v3/unauthenticated/metadata

You can request that only selected data be returned by the metadata provider by adding specific parameters to the command line. See the complete list of available parameters here.

Sample from a Windows Powershell Script

From Powershell, use the Invoke-WebRequest command, for example:

PS C:\Users\Adminstrator> Invoke-WebRequest https://metadata.cloudshare.com/api/v3/unauthenticated/metadata

This example will return a detailed HTTP response that includes all content from metadata provider:

StatusCode        : 200
StatusDescription : OK
Content           : {"machine-hostname": "D7269590243","machine-fqdn":"uvo1q5bardqu896vodb.vm.cld.sr","machine-fqdn-webaccess":"uvo1q5bardqu896vodb.env.cloudshare.com","machine-vanity-name-generic":"Training7","machine-internal-ip": "10.164.85.38","machine-id": "MCoa0S6q0f-GyTSRjxu7tFnA2","machine-name": "Windows Server 2019 Standard","env-id":"ENLjPZPxkVvjYbTeHhGPlSNQ2","env-name": "Training 7","env-owner-email":"praveengupta@3dportals.com","env-owner-id": "USf6aALaE_bfBrAcL2o1ikBg2","class-id":null,"env-region": 0}
RawContent        : HTTP/1.1 200 OK
                   Pragma: no-cache
                   X-XSS-Protections: 1; mode=block
                   X-Content-Type-Options: nosniff
                   Content-Length: 471
                   Cache-Control: no-cache
                   Content-Type: text/plain; charset=utf-8
                   Date: Wed, 1...
Forms             :
Headers           : {[Pragma, no-cache], [X-XSS-Protections, 1; mode=block], [X-Content-Type-Options, nosniff], [Content-Length, 471]...}
Images            : {}
InputFields       : {}
Links             : {}
ParsedHtml        : System.__ComObject
RawContentLength  : 471

To parse the content portion from the metadata provider, use the following command:

PS C:\Users\Administrator> (Invoke-WebRequest https://metadata.cloudshare.com/api/v3/unauthenticated/metadata).Content

In this example, only the content is returned:

{"machine-hostname": "D7269590243","machine-fqdn": "uvo1q5bardqu896vodb.vm.cld.sr","machine-fqdn-webaccess": "uvo1q5bardqu896vodb.env.cloudshare.com","machine-vanity-name-generic": "Training7","machine-internal-ip": "10.164.85.38","machine-id": "MCoa0S6q0f-GyTSRjxu7tFnA2","machine-name": "Windows Server 2019 Standard","env-id": "ENLjPZPxkVvjYbTeHhGPlSNQ2","env-name": "Training 7","env-owner-email": "praveengupta@3dportals.com","env-owner-id": "USf6aALaE_bfBrAcL2o1ikBg2","class-id": null,"env-region": 0}

Note

Should you encounter SSL errors when running the CloudShare metadata provider command in a script, run the following commands prior to invoking the metadata provider:

$AllProtocols = [System.Net.SecurityProtocolType]'Ssl3,Tls,Tls11,Tls12'
[System.Net.ServicePointManager]::SecurityProtocol = $AllProtocols

From a Browser Tab

Enter the metadata provider call directly in the address bar as a URL, for example:
```
https://metadata.cloudshare.com/api/v3/unauthenticated/metadata/env-owner-email
```
The command response is displayed as plain text directly in the browser window:

Note that this example returns only the metadata parameter that was specified in the call.

Returning Specific VM Data with the Metadata Provider

You can return any of the following data elements from your running VM by adding a specific parameter to your metadata provider call.

The format for requesting a specific parameter with the call is:

https://metadata.cloudshare.com/api/v3/unauthenticated/metadata/[parameter name]

For an example, see above.

Data Element	Parameter Name
VM Host Name	machine-hostname
VM Fully Qualified Domain Name (FQDN)	machine-fqdn
Web Access Address of the VM as FQDN	machine-fqdn-webaccess
VM Vanity Name	machine-vanity-name-generic
VM Internal IP	machine-internal-ip
VM Unique ID	machine-id
VM Name	machine-name
Current Environment Unique ID	env-id
Current Environment Name	env-name
Email of Current Environment Owner	env-owner-email
Unique ID of Current Environment Owner	env-owner-id
Unique ID of the Current Class	class-id
Region ID of the Current Environment	env-region

For additional information about using the metadata provider, contact CloudShare support.

Comments

1 comment

Robin Johnston

July 14, 2025 16:16
zero useful information here, how about something we could set outwith the vm such as class id or a url etc
0

Comment actions Permalink

Please sign in to leave a comment.

Access Your Environment

Note

Using the Metadata Provider

Note

Returning Specific VM Data with the Metadata Provider

Related articles