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.

The Skytap Command Line Interface (CLI) public template is deprecated.

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, and n to exit the prompt. Example: cli prompt

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, US-Virginia-M-1, EMEA, APAC-2, AUS-Sydney, or CAN-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 of running, suspended, stopped (shut down), or halted (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, US-Virginia-M-1, EMEA, APAC-2, AUS-Sydney, or CAN-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, US-Virginia-M-1, EMEA, APAC-2, AUS-Sydney, or CAN-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 user name 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 of running, suspended, stopped (shut down), or halted (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 user name and password set.

  • region:templateregion

    One of US-West, US-Central,US-East, US-East-2, US-Virginia-M-1, EMEA, APAC-2, AUS-Sydney, or CAN-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 user name and password set.

  • region:templateregion

    One of US-West, US-Central,US-East, US-East-2, US-Virginia-M-1, EMEA, APAC-2, AUS-Sydney, or CAN-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 createRequired 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, or aes 256.

  • phase_1_hash_algorithm:md5

    Phase 1 hash algorithm; either md5 or sha1.

  • 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, or modp1536. Note that modp768 is not available for route-based VPNs.

  • phase_2_encryption_algorithm:3des

    Phase 2 encryption algorithm; one of 3des, aes, or aes 256.

  • phase_2_authentication_algorithm:hmac_md5

    Phase 2 authentication algorithm; either hmac_md5 or hmac_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, or modp1536. Required if phase_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, or unique.

  • 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, or aes 256.

  • phase_1_hash_algorithm:md5

    Phase 1 hash algorithm; either md5 or sha1.

  • 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, or modp1536. Note that modp768 is not available for route-based VPNs.

  • phase_2_encryption_algorithm:3des

    Phase 2 encryption algorithm; one of 3des, aes, or aes 256.

  • phase_2_authentication_algorithm:hmac_md5

    Phase 2 authentication algorithm; either hmac_md5 or hmac_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, or modp1536. Required if phase_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, or unique.

  • 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, or restricted_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, or restricted_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 user name.

--api-token=API-TOKEN

Skytap API token. See Finding your user name 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.

Copyright © 2020 Skytap, Inc. | Privacy Policy | Terms of Service | Support