Skytap Command Line Interface Reference
This document contains the supported commands, parameters, and global options available in the Skytap CLI. For instructions about installing and getting started with the CLI, see Getting Started with the Skytap Command Line Interface.
Contents
How to add parameters to a request
Some supported commands have required or optional parameters. You can provide these parameters in one of three ways:
-
Add the parameter(s) to the command using the
--param
option.Each parameter should be formatted as a
key:value
pair.Examples:
skytap asset update 1234 --param=name:isov2
skytap configuration create --param=template_id:12345 --param=target_region:US-East --param="name:New Environment"
If the value contains a space character, put quotation marks around the key:value pair. Example:
--param="name:New Environment"
-
Include a parameter file with the request.
Example command:
skytap configuration create --params-file=/Users/Docs/Documents/params.json
Example contents of
params.json
:{ "template_id": 12345, "name": "New Environment", "target_region": "US-East" }
-
Respond to interactive prompts from the CLI. Include required parameters or the Skytap CLI prompts you for them. Type
y
to add new parameters, andn
to exit the prompt. Example:
Supported commands and parameters
Assets
Description
Command syntax
Example
List assets you have access to
skytap asset index
skytap asset index
Get information about an asset
skytap asset show ID#
Replace ID#
with the ID number of the asset (example: 1234).
skytap asset show 1234
Update an asset name
skytap asset update ID#
Replace ID#
with the ID number of the asset (example: 1234).
Required parameter:
-
name:newname
Human-readable name for the asset.
skytap asset update 1234 --param=name:isov2
Replace ID#
with the ID number of the asset (example: 1234).
Delete an asset
skytap asset destroy ID#
Replace ID#
with the ID number of the asset (example: 1234).
skytap asset destroy 1234
Environments
Throughout the Skytap CLI commands, environments are referred to as ‘configurations.’ Skytap no longer uses the term ‘configurations’ in the web interface; however, it has been maintained in the CLI for backward-compatibility.
Description
Command
Example
List environments you have access to
skytap configuration index
skytap configuration index
Get information about an environment
skytap configuration show ID#
Replace ID#
with the ID number of the environment (example: 1234).
skytap configuration show 1234
Create an environment
skytap configuration create
Required parameter:
-
Either:
template_id:ID#
ID of the template to copy.
configuration_id:ID#
ID of the environment to copy.
Optional parameters:
-
name:newname
Name of the new environment.
-
vm_ids:[ID#,ID#]
Subset of one or more VMs to include in the environment. Must be contained within square brackets and comma-separated, without whitespace. All other VMs are excluded (can only be used when creating an environment from a template).
-
target_region:region
One of
US-West
,US-Central
,US-East
,US-East-2
,EMEA
,APAC-2
,AUS-Sydney
, orCAN-Toronto
. If this parameters is not included, the environment is created in the same region as the template or environment it is being created from.
skytap configuration create --param=template_id:2222 --param=target_region:US-West
Start or stop an environment
skytap configuration update ID#
Replace ID#
with the ID number of the environment (example: 12345).
Required parameter:
runstate:runstate
One ofrunning
,suspended
,stopped
(shut down), orhalted
(forcibly power off).
skytap configuration update 1234 --param=runstate:running
Update an environment
skytap configuration update ID#
Replace ID#
with the ID number of the environment (example: 1234).
Optional parameters:
-
name:newname
Human-readable name for the environment.
-
template_id:ID#
ID of the template to copy into the environment; this adds the template VMs to the environment.
-
vm_ids:[ID#,ID#]
Subset of one or more VMs to include in the environment. Must be contained within square brackets and comma-separated, without whitespace. All other VMs are excluded (can only be used when copying a template into an environment).
-
suspend_on_idle:300
Number of seconds the environment can be idle before the environment automatically suspends.
-
owner:ID#
ID of the user to whom the environment will be reassigned (requires administrator privileges).
-
routable_configuraton:true
If true, Skytap allows traffic between all networks in the environment.
-
disable_internet:false
If true, Skytap disables outbound Internet traffic for all VMs in the environment.
skytap configuration update 1234 --param="name:Web App Stack -- Updated 2016-05-20"
Delete an environment
skytap configuration destroy ID#
Replace ID#
with the ID number of the environment (example: 1234).
skytap configuration destroy 1234
Templates
Description
Command
Example
List templates you have access to
skytap template index
skytap template index
Get information about a template
skytap template show ID#
Replace ID#
with the ID number of the template (example: 1234).
skytap template show 1234
Save an environment as a template
skytap template create
header
Required parameter:
-
configuration_id:ID#
ID of the environment from which to create a template.
Optional parameters:
-
name:newname
Name of the new template.
-
description:description
Description of the template.
-
vm_instance_multiselect:[ID#,ID#]
Subset of one or more VMs to include in the template. Must be contained within square brackets and comma-separated, without whitespace. All other VMs are excluded.
-
network_multiselect:[ID#,ID#]
Subset of one or more networks to include in the template. Must be contained within square brackets and comma-separated, without whitespace. All other networks are excluded.
-
publish_sets:false
If false, exclude sharing portals from the template. If this is not specified, sharing portals are included by default.
-
target_region:region
One of
US-West
,US-Central
,US-East
,US-East-2
,EMEA
,APAC-2
,AUS-Sydney
, orCAN-Toronto
. If this parameters is not included, the template is created in the same region as the environment from which it is being created.
skytap template create --param=configuration_id:2222
Copy a template
skytap template create
Required parameter:
-
template_id:ID#
ID of the template to copy.
Optional parameters:
-
name:newname
Name of the new template.
-
target_region:region
One of
US-West
,US-Central
,US-East
,US-East-2
,EMEA
,APAC-2
,AUS-Sydney
, orCAN-Toronto
. If this parameters is not included, the template is created in the same region as the environment from which it is being created.
skytap template create --param=template_id:2222 --param=target_region:US-West
Update a template
skytap template update ID#
Replace ID#
with the ID number of the template (example: 1234).
Optional parameters:
-
name:newname
Name for the template.
-
description:description
Description for the template.
-
owner:ID#
ID of the user to whom the template will be reassigned (requires administrator privileges).
-
reassign_context:ID#
Used with
owner:ID#
above; if the user is a restricted user in Skytap, you must also provide a project ID; the restricted user must be a manager or editor in this project. -
tags:tag1, tag2, tag3
Comma-separated list of tags to attach to the template. This replaces any other tags attached to the template.
skytap template update 1234 --param=name:webstacktemplate_2016-05-20
Delete a template
skytap template destroy ID#
Replace ID#
with the ID number of the template (example: 1234).
skytap template destroy 1234
VMs
Description
Command
Example
Upload a VM to Skytap from a local directory
skytap vm upload FILE
- Replace
FILE
with the name of a VM directory or VM file. The file must be one of the following archive types: .tgz .tar.gz .tbz .tbz2 .tar.bz2 .tar .ova .ovf .7z .7z.001 .zip - The contents of the archive file must contain a VMware image in VMX/VMDK or OVF/VMDK format.
The VM upload action streamlines the process of importing VM into Skytap from your local file system. The CLI creates an import job, uploads the VM to the Skytap FTP repository, and then creates a Skytap template based on the VM. To manage the import process yourself (or if to upload the VMs from a different machine), can use the actions for Import a VM (listed further below).
skytap vm download 12346 12347--dir=/Users/Docs/VMs
Get information about a VM
skytap vm show ID#
Replace ID#
with the ID number of the VM (example: 12345).
skytap vm show 12345
View VM credentials
skytap credential index /vms/VMID#
Replace VMID#
with the ID number of the VM (example: 12345).
skytap credential index /vms/12345
Copy a VM to another region
It is easier to copy VMs to another region via the UI or API. For instructions, see Copying an environment to another region and Copying a template to another region.
For information about how to do this through the REST API, see Copy environment to another region and Copy template to another region.
N/A
Create VM credentials
skytap credential create /vms/VMID#
Replace VMID#
with the ID number of the VM (example: 12345).
Required parameter:
text:username/password
Saved username and password set.
skytap credential create /vms/12345 --param=text:admin/adminpw
Start or stop a VM
skytap vm update ID#
Replace ID#
with the ID number of the VM (example: 12345).
Required parameter:
runstate:runstate
One ofrunning
,suspended
,stopped
(shut down), orhalted
(forcibly power off).
skytap vm update 12345 --param=runstate:running
Load ISO in a VM
skytap vm update ID#
Replace ID#
with the ID number of the VM (example: 12345).
Required parameter:
asset_id:ID#
ID of the asset. Must be an ISO file.
skytap vm update 12345 --param=asset_id:1010
Download a Skytap VM to a local directory
skytap vm download ID# --dir=DIR
- Replace
ID#
with the ID number of one or more Skytap VMs (example: 12345 or 12346 123457). The VMs must be in a template that you own. - Replace DIR with a directory on the computer you are using the Skytap CLI from.
The VM download action streamlines the process of exporting a VM from Skytap to your local file system. The CLI creates the export job and downloads the VM from the Skytap FTP repository to a local directory. To manage the export process yourself (or to export the VMs to different machine), use the actions for Export a VM (listed further below).
skytap vm download 12346 12347--dir=/Users/Docs/VMs
Delete VM credentials
skytap credential destroy /vms/VMID# ID#
Replace VMID#
with the ID number of the VM (example: 12345) and ID#
with the ID of the credential (example: 2
).
skytap credential destroy /vms/12345 2
Delete a VM
skytap vm destroy ID#
Replace ID#
with the ID number of the VM (example: 12345).
skytap vm destroy 12345
Imports
Description
Command syntax
Example
List import jobs you have access to
skytap import index
skytap import index
Get information about an import job
skytap import show ID#
Replace ID#
with the ID number of the import job (example: 1234).
skytap import show 1234
Create an import job
skytap import create
Required parameters:
-
template_name:name
Name of the new template that is created from the import job.
-
template_description:description
Description of the template.
-
network_domain:domainname
Domain name for the network in the new template.
-
network_subnet:10.0.0.0/24
Subnet for the network in the new template.
-
interface_ip:10.0.0.1
IP address of the VM in the new template.
-
interface_hostname:host
Hostname of the VM in the new template.
Optional parameters:
-
credentials:username/password
Saved username and password set.
-
region:templateregion
One of
US-West
,US-Central
,US-East
,US-East-2
,EMEA
,APAC-2
,AUS-Sydney
, orCAN-Toronto
.
After you create the import job, upload the VM to the Skytap FTP server using the credentials provided by the CLI. After the file is uploaded, start the import job using the command listed below.
skytap import create --param=template_name:WebServer --param=template_description:imported on 05/20/2016 --param=network_domain:example.com --param=network_subnet:10.0.0.0/24 --param=interface_ip:10.0.0.1 --param=interface_hostname:host1
Start an import job
skytap import update ID# --param=status:processing
Replace ID#
with the ID number of the import job (example: 1234).
skytap import update 1234 --param=status:processing
Update an import job
skytap import update ID#
Replace ID#
with the ID number of the import job (example: 1234).
Optional parameters:
-
template_name:name
Name of the new template that is created from the import job.
-
template_description:description
Description of the template.
-
network_domain:domainname
Domain name for the network in the new template.
-
network_subnet:10.0.0.0/24
Subnet for the network in the new template.
-
interface_ip:10.0.0.1
IP address of the VM in the new template.
-
interface_hostname:host
Hostname of the VM in the new template.
-
credentials:username/password
Saved username and password set.
-
region:templateregion
One of
US-West
,US-Central
,US-East
,US-East-2
,EMEA
,APAC-2
,AUS-Sydney
, orCAN-Toronto
.
skytap import update ID# --param=template_name:newname
Exports
Description
Command syntax
Example
List export jobs you have access to
skytap export index
skytap export index
Get information about an export job
skytap export show ID#
Replace ID#
with the ID number of the export job (example: 1234).
skytap export show 1234
Create an export job
skytap export create
Required parameter:
-
vm_id:ID#
ID of a VM in a template.
After you create the export job, download the VM from the Skytap FTP server using the credentials provided by the CLI.
skytap export create --param=vm_id:1111
Delete an export job
skytap export destroy ID#
Replace ID#
with the ID number of the export job.
skytap export destroy 1234
Public IPs
Description
Command syntax
Example
List public IP addresses you have access to
skytap ip index
skytap ip index
Attach a public IP to a VM
skytap ip create
Required parameters:
-
vm_id:ID#
ID of the VM to which the public IP should be attached.
-
ip:10.0.0.0
Public IP address.
-
interface_id:ID#
ID of the network adapter on the VM.
skytap ip create --param=vm_id:1234 --param=ip:10.0.0.0 --param=interface_id:1111
VPNs
Description
Command
Example
List VPNs you have access to
skytap vpn index
skytap vpn index
Get information about a VPN
skytap vpn show ID#
Replace ID#
with the ID number of the VPN (example: 12345).
skytap vpn show 12345
Create a VPN
skytap vpn create
Required parameters:
-
name:name
Name of the VPN.
-
remote_peer_ip:199.199.199.199
A routable IP address on the external network. Typically a network device configured to communicate with the Skytap peer IP.
-
local_peer_ip:188.188.188.188
A routable, public IP address exposed by the Skytap infrastructure.
-
local_subnet:10.0.0.0/24
Range of virtual environment IP addresses that should route traffic through the VPN to the external endpoint.
-
phase_1_encryption_algorithm:3des
Phase 1 encryption algorithm; one of
3des
,aes
, oraes 256
. -
phase_1_hash_algorithm:md5
Phase 1 hash algorithm; either
md5
orsha1
. -
phase_1_pre_shared_key:secretkey
Phase 1 preshared key; this is a text string up to 128 characters, used to validate endpoints before protocol negotiation.
-
phase_1_sa_lifetime:28800
Value (in seconds) for the Phase 1 Security Association (SA) lifetime. Must be an integer between 1 and 2,147,483,647, inclusive.
-
phase_1_dh_group:modp1024
Name of phase 1 Diffie Hellman group; one of
modp768
,modp1024
, ormodp1536
. Note that modp768 is not available for route-based VPNs. -
phase_2_encryption_algorithm:3des
Phase 2 encryption algorithm; one of
3des
,aes
, oraes 256
. -
phase_2_authentication_algorithm:hmac_md5
Phase 2 authentication algorithm; either
hmac_md5
orhmac_sha1
. -
phase_2_perfect_forward_secrecy:true
If true, perfect forward secrecy (PFS) should be used.
-
phase_2_pfs_group:modp1024
PFS group; one of
modp768
,modp1024
, ormodp1536
. Required ifphase_2_perfect_forward_secrecy
is being used. -
phase_2_sa_lifetime:28800
Value (in seconds) for the Phase 2 Security Association (SA) lifetime. Must be an integer between 1 and 2,147,483,647, inclusive.
-
sa_policy_level:require
Security policy level; must be one of
null
,require
, orunique
. -
dpd_enabled:false
If true, dead peer detection is enabled.
Optional parameter:
maximum_segment_size
Maximum segment size (MSS); if provided, must be between 536 and 1460, inclusive.
skytap vpncreate --param=name:CorpNet --param=email:dglass@example.com --param=remote_peer_ip:199.199.199.199 --param=local_peer_ip:188.188.188.188 --param=local_subnet:10.0.0.0/24 --param=phase_1_encryption_algorithm:3des --param=phase_1_hash_algorithm:md5 --param=phase_1_pre_shared_key:secretkey --param=phase_1_sa_lifetime:28800 --param=phase_1_dh_group:modp1024 --param=phase_2_encryption_algorithm:3des --param=phase_2_authentication_algorithm:hmac_md5 --param=phase_2_perfect_forward_secrecy:true --param=phase_2_pfs_group:modp1024 --param=phase_2_sa_lifetime:28800 --param=sa_policy_level:require --param=dpd_enabled:false
Enable a VPN
skytap vpn update ID#
Replace ID#
with the ID number of the VPN (example: 12345).
Required parameters:
enabled:true
If true, the VPN is enabled and traffic flows through the VPN.
skytap vpn update --param=name:CorpNetSourceControl
Create a VPN
skytap vpn update
Optional parameters:
-
enabled:true
If true, the VPN is enabled and traffic flows through the VPN.
-
name:name
Name of the VPN
-
remote_peer_ip:199.199.199.199
A routable IP address on the external network. Typically a network device configured to communicate with the Skytap peer IP.
-
local_peer_ip:188.188.188.188
A routable, public IP address exposed by the Skytap infrastructure. Use the acquire command to acquire one.
-
local_subnet:10.0.0.0/24
Range of virtual environment IP addresses that should route traffic through the VPN to the external endpoint.
-
phase_1_encryption_algorithm:3des
Phase 1 encryption algorithm; one of
3des
,aes
, oraes 256
. -
phase_1_hash_algorithm:md5
Phase 1 hash algorithm; either
md5
orsha1
. -
phase_1_pre_shared_key:secretkey
Phase 1 preshared key; this is a text string up to 128 characters, used to validate endpoints before protocol negotiation.
-
phase_1_sa_lifetime:28800
Value (in seconds) for the Phase 1 Security Association (SA) lifetime. Must be an integer between 1 and 2,147,483,647, inclusive.
-
phase_1_dh_group:modp1024
Name of phase 1 Diffie Hellman group; one of
modp768
,modp1024
, ormodp1536
. Note that modp768 is not available for route-based VPNs. -
phase_2_encryption_algorithm:3des
Phase 2 encryption algorithm; one of
3des
,aes
, oraes 256
. -
phase_2_authentication_algorithm:hmac_md5
Phase 2 authentication algorithm; either
hmac_md5
orhmac_sha1
. -
phase_2_perfect_forward_secrecy:true
If true, perfect forward secrecy (PFS) should be used.
-
phase_2_pfs_group:modp1024
PFS group; one of
modp768
,modp1024
, ormodp1536
. Required ifphase_2_perfect_forward_secrecy
is being used. -
phase_2_sa_lifetime:28800
Value (in seconds) for the Phase 2 Security Association (SA) lifetime. Must be an integer between 1 and 2,147,483,647, inclusive.
-
sa_policy_level:require
Security policy level; must be one of
null
,require
, orunique
. -
dpd_enabled:false
If true, dead peer detection is enabled.
-
maximum_segment_size
Maximum segment size (MSS); if provided, must be between 536 and 1460, inclusive.
skytap vpn update --param=name:CorpNetSourceControl
Delete a VPN
skytap vpn destroy ID#
Replace ID#
with the ID number of the VM (example: 12345).
skytap vpn destroy 12345
Users
Description
Command
Example
List users
skytap user index
skytap user index
Get information about a user
skytap user show ID#
Replace ID#
with the ID number of the user (example: 1234).
skytap user show 1234
Create a user
skytap user create
Required parameters:
-
login_name:username
Username for the new user.
-
email:user@example.com
Email address for the new user.
-
first_name:Debra
First name for the new user.
-
last_name:Glass
Last name for the new user.
Optional parameters:
-
title:jobtitle
Job title for the new user.
-
login_password:password
Password for the new user. If omitted, the user is asked to enter a password during activation.
-
verify_password:password
Password for the new user. Must be provided if
login_password
is present -
time_zone:timezone
Time zone for the new user. If omitted, the time zone is set to Pacific Time (US & Canada). For a list of time zones, see Time zones and UTC offsets.
-
wants_email:true
If true, the new user chooses to receive product marketing updates and feedback requests.
-
has_public_library:true
If true, the user can access the Skytap public templates and public assets.
-
can_import:true
If true, the user can import VMs.
-
can_export:true
If true, the user can export VMs.
-
account_role:standard_user
One of
admin
,user_manager
,standard_user
, orrestricted_user
; if omitted, the user is a standard user.
skytap user create --param=login_name:debra_glass --param=email:dglass@example.com --param=first_name:Debra --param=last_name:Glass
Update a user
skytap user update ID#
Replace ID#
with the ID number of the user (example: 1234).
Optional parameters:
-
login_name:username
Username for the user.
-
email:user@example.com
Email address for the user.
-
first_name:Debra
First name for the user.
-
last_name:Glass
Last name for the user.
-
title:jobtitle
Job title for the user.
-
login_password:password
(JSON) or
password:password
(xml)Password for the user.
-
verify_password:password
(JSON)
Password for the user. Must be provided if
login_password
is present -
time_zone:timezone
Time zone for the user. If omitted, the time zone is set to Pacific Time (US & Canada). For a list of time zones, see Time zones and UTC offsets.
-
wants_email:true
If true, the new user chooses to receive product marketing updates and feedback requests.
-
has_public_library:true
If true, the user can access the Skytap public templates and public assets.
-
can_import:true
If true, the user can import VMs.
-
can_export:true
If true, the user can export VMs.
-
account_role:standard_user
One of
admin
,user_manager
,standard_user
, orrestricted_user
.
skytap user update 1234 --param=name:webstacktemplate_2016-05-20
Delete a user
skytap user destroy ID#
Replace ID#
with the ID number of the user (example: 1234).
skytap user destroy 1234
Global options
The following global options can be added to any Skytap command or specified in the Skytap CLI Ruby gem configuration file ( ~/.skytaprc
).
Option
Description
--base-url=BASE-URL
By default, this is set to https://cloud.skytap.com.
--username=USERNAME
Skytap username.
--api-token=API-TOKEN
Skytap API token. See Finding your username and API security token. If you do not have an API token, use your account password instead.
--http-format=HTTP-FORMAT
HTTP request and response format.
Options:
- json
- xml
By default, this is set to json.
--log-level=LOG-LEVEL
Output verbosity.
Options:
- quiet
- info
- verbose
By default, this is set to info.
--params-file=PARAMS-FILE
File containing the request parameters. This file must contain either XML or JSON text, depending on the specified HTTP format.
--param=PARAM
Request parameters in key:value
pair format.
--param=key1:value1 --param=key2:value2
--help
Display the help message for a command.
--version
Display the CLI version.
--colorize
--no-colorize
Do or do not colorize output. By default, output is colorized.
--verify-certs
--no-verify-certs
Do or do not verify HTTPS certificates.
By default, HTTPS certificates are verified.
--ask
--no-ask
Do or do not ask for parameters interactively.
By default, the CLI asks for parameters interactively.