<commit_before>= Knife vSphere
{<img src="https://travis-ci.org/chef-partners/knife-vsphere.svg?branch=master" alt="Build Status" />}[https://travis-ci.org/chef-partners/knife-vsphere]

= DESCRIPTION:

This is an Chef Knife plugin to interact with VMware's vSphere. This plugin currently supports the following:

Listings:

- VMs
- Folders
- Templates
- Datastores
- VLANs (currently requires distributed vswitch)
- Resource Pools and Clusters
- Customization Specifications
- Hosts in a Pool or Cluster

VM Operations:

- Power on/off
- Clone (with optional chef bootstrap and run list)
- Delete
- VMDK addition
- Migrate
- Connect/disconnect network

Clone-specific customization options (for linux guests):

- Destination folder
- CPU core count
- Memory size
- DNS settings
- Hostname / Domain name
- IP addresses / default gateway
- vlan (currently requires distributed vswitch)
- datastore
- resource pool

For Windows guests we can run sysprep

= INSTALLATION:

    gem install knife-vsphere

= CONFIGURATION:

For initial development, the plugin targets all communication at a vCenter instance rather than at specific hosts. Only named user authentication is currently supported; you can add the credentials to your <tt>knife.rb</tt> file:

    knife[:vsphere_host] = "vcenter-hostname"
    knife[:vsphere_user] = "privileged username"
    knife[:vsphere_pass] = "<PASSWORD>"
    knife[:vsphere_dc] = "your-datacenter"

The vSphere password can also be stored in a base64 encoded version (to visually obfuscate it) by prepending 'base64:' to your encoded password. For example:

    knife[:vsphere_pass] = "base64:Zm<PASSWORD>=="

If you get the following error, you may need to disable SSL certificate checking:
ERROR: OpenSSL::SSL::SSLError: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed
    knife[:vsphere_insecure] = true

Credentials can also be specified on the command line for multiple VSphere servers/data centers

= Getting help

If the software isn't behaving the way you think, or you're having trouble doing something, we're happy to help. Try this checklist:

- Are you running the latest version? <tt>gem list knife-vsphere</tt>. You can always upgrade with <tt>gem install knife-vsphere</tt>
- Try running the same command with <tt>-VV</tt> to add additional logging messages
- Are there any errors in the vSphere console or logs?
- Search for known issues at https://github.com/chef-partners/knife-vsphere/issues

If you're still having problems, head on over to the issues[https://github.com/chef-partners/knife-vsphere/issues] page and create a new issue. Please include:
- A description of what you are trying to do, what you are seeing
- The version number of knife-vsphere and of vSphere itself
- The exact command you're running and the output (sanitize anything you don't want public!)

= SUBCOMMANDS:

This plugin provides the following Knife subcommands.  Specific command options can be found by invoking the subcommand with a <tt>--help</tt> flag

== knife vsphere vm list [-r, --recursive [--only-folders]]

Enumerates the Virtual Machines registered in the target datacenter. Only name is currently displayed.
    -r, --recursive    - Recurse down through sub-folders to the specified folder
    --only-folders     - Print only folder names. Implies recursive

== knife vsphere vm find --pool POOL CRITERIA FIELDS

Search for Virtual Machines matching criteria in the specified pool and display selected fields
CRITERIA:
    --match-ip IP                match ip
    --match-name VMNAME          match name
    --match-os OS                match os
    --match-tools TOOLSSTATE     match tools state
    --powered-off                Show only stopped machines
    --powered-on                 Show only started machines
FIELDS:
    --alarms                     show alarm status
    --cpu                        Show cpu
    --esx-disk                   Show esx disks
    --full-path                  Show full path
    --hostname                   show hostname
    --ip                         Show ip
    --os                         show os details
    --os-disks                   Show os disks
    --ram                        Show ram
    --snapshots                  Show snapshots
    --tools                      show tools status

     knife vsphere vm find --snapshots --full-path --pool XXX-YYYY --cpu --ram --esx-disk --os-disk --os --match-name my_machine_1 --alarms --tools --ip --match-ip 123 --match-tools toolsOk

== knife vsphere vm state [-s STATE, --state STATE] [-w PORT, --wait-port PORT] [-g, --shutdown] [-r, --recursive]

Manage power state of a virtual machine.
	-s STATE, --state STATE    - The power state to transition the VM into; one of on|off|suspended|reboot
	-w PORT, --wait-port PORT  - Wait for VM to be accessible on a port
	-g, --shutdown             - Guest OS shutdown
    -r, --recursive            - Recurse down through sub-folders to the specified folder
== knife vsphere pool list

Enumerates the Resource Pools and Clusters registered in the target datacenter.

== knife vsphere template list

Enumerates the VM Templates registered in the target datacenter. Only name is currently displayed.

== knife vsphere customization list

Enumerates the customization specifications registered in the target datacenter. Only name is currently displayed.

== knife vsphere vm clone <new vm name> --template <source template name> --cspec <customization_spec>

    knife vsphere vm clone NewNode --template UbuntuTemplate --cspec StaticSpec \
        --cips 192.168.0.99/24,192.168.1.99/24 \
        --chostname NODENAME --cdomain NODEDOMAIN

   --random-vmname - Creates a random VMNAME starts with vm-XXXXXXXX
   --random-vmname-prefix - Change the VMNAME prefix
   --dest-folder FOLDER - The folder into which to put the cloned VM
   --datastore STORE    - The datastore into which to put the cloned VM
   --datastorecluster STORE - The datastorecluster into which to put the cloned VM
   --resource-pool POOL|CLUSTER - The resource pool into which to put the cloned VM. Also accepts a cluster name.
   --template TEMPLATE - The source VM / Template to clone from
   --cspec CUST_SPEC - The name of any customization specification to apply
   --disable-customization FALSE - by default conventions will be applied to the customization specification (see below).  Disable these convention with this switch
   --cplugin CUST_PLUGIN_PATH - Path to plugin that implements KnifeVspherePlugin.customize_clone_spec and/or KnifeVspherePlugin.reconfig_vm
   --cplugin-data CUST_PLUGIN_DATA - String of data to pass to the plugin.  Use any format you wish.
   --cvlan CUST_VLANS - Comma-delimited list of VLAN names for the network adapters to join
   --cips CUST_IPS - Comma-delimited list of CIDR IPs for customization, or *dhcp* to configure that interface to use DHCP
   --cgw CUST_GW - CIDR IP of gateway for customization
   --chostname CUST_HOSTNAME - Unqualified hostname for customization
   --cdomain CUST_DOMAIN - Domain name for customization
   --ctz CUST_TIMEZONE - Timezone invalid 'Area/Location' format
   --ccpu CUST_CPU_COUNT - Number of CPUs
   --cram CUST_MEMORY_GB - Gigabytes of RAM
   --start - Start the VM after cloning.
   --bootstrap - Bootstrap the VM after cloning. Implies --start
   --fqdn SERVER_FQDN - Fully qualified hostname for bootstrapping
   --ssh-user USERNAME - SSH username
   --ssh-password PASSWORD - SSH password
   --ssh-port PORT - SSH port
   --identity-file IDENTITY_FILE - SSH identity file used for authentication
   --node-name NAME - The Chef node name for your new node
   --hint HINT_NAME[=HINT_FILE] Specify Ohai Hint to be set on the bootstrap target.  Use multiple --hint options to specify multiple hints.
   --prerelease - Install the pre-release chef gems
   --bootstrap-version VERSION - The version of Chef to install
   --bootstrap-proxy PROXY_URL - The proxy server for the node being bootstrapped
   --bootstrap-vault-file VAULT_FILE - A JSON file with a list of vault(s) and item(s) to be updated
   --bootstrap-vault-json VAULT_JSON - A JSON string with the vault(s) and item(s) to be updated
   --bootstrap-vault-item VAULT_ITEM - A single vault and item to update as "vault:item"
   --distro DISTRO - Bootstrap a distro using a template
   --template-file TEMPLATE - Full path to location of template to use
   --run-list RUN_LIST - Comma separated list of roles/recipes to apply
   --secret-file SECRET_FILE - A file containing the secret key to use to encrypt data bag item values
   --no-host-key-verify - Disable host key verification
   --json-attributes - A JSON string to be added to the first run of chef-client
   --disable-customization - Disable default customization
   --sysprep_timeout TIMEOUT - Wait TIMEOUT seconds for sysprep event before continuing with bootstrap

Clones an existing VM template into a new VM instance, optionally applying an existing customization specification.  If customization arguments such as --chost and --cdomain are specified, or if the customization sepcification fetched from VSphere is considered, a default customization specification will be attempted.  For windows, a sysprep based unattended customization in workgroup mode will be attempted (host name being the VM name unless otherwise specified).  For linux, a fixed named customization using the vmname as the host name unless otherwise specified.  These customization specification defaults can be disabled using the --disable-customization switch and the --cspec specified as-is.

NOTE!  if you are specifying a --cspec and the cloning process appears to not be properly applying the spec as defined on VSphere, consider using the --disable-customization as the conventions described above could be erroneously interfering with the spec as defined on VSphere.

Customization specifications can also be specified in code using the --cplugin and/or --cplugin-data arguments.  Below are examples of the potential implementations that woudl be saved to an rb file and passed in the --cplugin argument.

# cplugin_example.rb

    class KnifeVspherePlugin
      def data=(cplugin_data)
        # Parse your cplugin_data from the format of your choosing.
      end

      # optional
      def customize_clone_spec(src_config, clone_spec)
        # Customize the clone spec as you see fit.
        return customized_clone_spec
      end

      # optional
      def reconfig_vm(target_vm)
        # Do anything you want in here with the cloned VM.
      end
    end

# cplugin_example.rb for cloning a Windows template to VM

    require 'rbvmomi'

    class KnifeVspherePlugin
      attr_accessor :data

      def customize_clone_spec(src_config, clone_spec)

        if File.exists? data
          customization_data = JSON.parse(IO.read(data))
        else
          abort "Customization plugin data file #{data} not accessible"
        end

        cust_guiUnattended = RbVmomi::VIM.CustomizationGuiUnattended(
          :autoLogon => false,
          :autoLogonCount => 1,
          :password => <PASSWORD>,
          :timeZone => customization_data['timeZone']
        )
        cust_identification = RbVmomi::VIM.CustomizationIdentification(
          :domainAdmin => nil,
          :domainAdminPassword => <PASSWORD>,
          :joinDomain => nil
        )
        cust_name = RbVmomi::VIM.CustomizationFixedName(
          :name => customization_data['host_name']
        )
        cust_user_data = RbVmomi::VIM.CustomizationUserData(
          :computerName => cust_name,
          :fullName => customization_data['fullName'],
          :orgName => customization_data['orgName'],
          :productId => customization_data['windows_key']
        )
        cust_sysprep = RbVmomi::VIM.CustomizationSysprep(
          :guiUnattended => cust_guiUnattended,
          :identification => cust_identification,
          :userData => cust_user_data
        )
        dhcp_ip = RbVmomi::VIM.CustomizationDhcpIpGenerator
        cust_ip = RbVmomi::VIM.CustomizationIPSettings(
          :ip => dhcp_ip
        )
        cust_adapter_mapping = RbVmomi::VIM.CustomizationAdapterMapping(
          :adapter => cust_ip
        )
        cust_adapter_mapping_list = [cust_adapter_mapping]
        global_ip = RbVmomi::VIM.CustomizationGlobalIPSettings
        customization_spec = RbVmomi::VIM.CustomizationSpec(
          :identity => cust_sysprep,
          :globalIPSettings => global_ip,
          :nicSettingMap => cust_adapter_mapping_list
        )
        clone_spec.customization = customization_spec
        puts "New clone_spec object :\n #{YAML::dump(clone_spec)}"
        clone_spec
      end

      def reconfig_vm (target_vm)
        puts "In reconfig_vm method.  No actions implemented.."
      end
    end


# json data file

    {
        "fullName": "Your Company Inc.",
        "orgName": "Your Company Inc.",
        "windows_key": "<KEY>",
        "host_name": "foo_host",
        "timeZone": "100"
    }


The <tt>--bootstrap-vault-*</tt> options can be used to send <tt>chef-vault</tt> items to be updated during the hand-off to <tt>knife bootstrap</tt>.

Example using <tt>--bootstrap-vault-json</tt>:

    knife vsphere vm clone NewNode UbuntuTemplate --cspec StaticSpec \
        --cips 192.168.0.99/24,192.168.1.99/24 \
        --chostname NODENAME --cdomain NODEDOMAIN \
        --start true --bootstrap true \
        --bootstrap-vault-json '{"passwords":"default","appvault":"credentials"}'


== knife vsphere vm toolsconfig PROPERTY VALUE [--empty]
    --empty           - allows clearing string properties

Sets properties in tools property.
See \"https://www.vmware.com/support/developer/vc-sdk/visdk25pubs/ReferenceGuide/vim.vm.ToolsConfigInfo.html\" for available properties and types.

Examples:
    knife vsphere vm toolsconfig myvirtualmachine syncTimeWithHost false
    knife vsphere vm toolsconfig myvirtualmachine pendingCustomization -e

== knife vsphere vm delete VMNAME [--purge]

Deletes an existing VM, removing it from vSphere inventory and deleting from disk, optionally deleting it from Chef as well.
    --purge           - Delete the client and node from Chef as well

== knife vsphere vm snapshot VMNAME (options)
    --list            - List the current tree of snapshots
    --create SNAPSHOT - Create a new snapshot off of the current snapshot
    --remove SNAPSHOT - Remove a named snapshot.
    --revert SNAPSHOT - Revert to a named snapshot.
    --revert-current  - Revert to current snapshot.
    --start           - Indicates whether to start the VM after a successful revert
    --wait            - Indicates whether to wait for creation/removal to complete
    --find            - Find the VM instead of specifying the folder with -F
    --dump-memory     - Dump the memory when creating the snapshot (default: false)
    --quiesce         - Quiesce the VM before snapshotting (default: false)

Manages the snapshots for an existing VM, allowing for creation, removal, and reverting of snapshots.

== knife vsphere vm cdrom VMNAME (options)
    --datastore DATASTORE - Datastore the image is stored in
    --iso                 - Path and filename of the ISO
    --attach              - Attach the iso immediately
    --disconnect          - Disconnect any iso currently attached
    --recursive           - Search for the VM recursivly
    --folder              - Search for the VM in the specified folder
    --on_boot BOOL        - Set the Attach On Boot Boolean

== knife vsphere vm disk extend VMNAME SIZE (options)
    --diskname DISKNAME - The name of the disk that will be extended (use when vm has multiple disks)

Note: SIZE is in kilobytes

== knife vsphere vm disk list VMNAME

Lists the disks attached to VMNAME

== knife vsphere datastore list

Lists all known datastores with capacity and usage

== knife vsphere datastore maxfree [--regex]

Gets the datastore with the most free space
    --regex           - Pattern to match the datastore name

== knife vsphere datastore file DATASTORE (options)

Uploads files to a datastore and downloads files from a datastore
    --upload-file       - Upload specified local file to remote
    --download-file     - Download specified remote file to local
    --remote-file FILE  - Remote file name and path
    --local-file FILE   - Local file name and path

== knife vsphere datastorecluster list

Lists all known datastorecluster with capacity and usage

== knife vsphere datastorecluster maxfree [--regex]

Gets the datastorecluster with the most free space
    --regex           - Pattern to match the datastore name

== knife vsphere vm execute VMNAME COMMAND [ARGUMENTS] --exec-user USER --exec-passwd <PASSWORD>WD [ --exec-dir DIRECTORY ]

Executes a program on the guest. Requires vCenter 5.0 or higher.

Command path must be absolute. For Linux guest operating systems,
/bin/bash is used to start the program. For Solaris guest operating
systems, /bin/bash is used to start the program if it
exists. Otherwise /bin/sh is used.

Arguments are optional, and allow for redirection in Linux and Solaris.

  --exec-user USERNAME - The username on the guest to execute as.
  --exec-passwd <PASSWORD> - The password for the user executing as.
  --exec-dir DIRECTORY - Optional: Working directory to execute in. Will default to $HOME of user.

== knife vsphere vm vmdk add VMNAME SIZE

Adds VMDK to VM.

Optional arguments

  --vmdk-type TYPE - VMDK type, "thick" or "thin", defaults to "thin"

== knife vsphere vm markastemplate VMNAME --folder FOLDER

Will traverse the folder tree looking for the VM by name.  By default the folder inspected with be the root folder.  <tt>--folder</tt> should be specified if traversing should be in some other folder than the root.  Once found the VM will be converted into a template.  This means the VM will become a template and no longer be available as a Virtual Machine.  The name given to the template will be the name of VM from which it was created.
 
== knife vsphere hosts list --pool POOL

Lists all hosts in given Pool


== knife vsphere vm migrate VMNAME (options)

Migrate VM to resource pool/datastore/host.
Resource pool and datastore are mandatory.

    --folder FOLDER                   - folder in which to search for VM
    --resource-pool POOL        - destination resource pool
    --dest-host HOST            - destination host (optional)
    --dest-datastore DATASTORE  - destination datastore, accesible to HOST
    --priority PRIORITY         - migration priority (optional, default defaultPriority )



== knife vsphere vm net STATE VMNAME

Set networking state for VMNAME by connecting/disconnecting network interfaces.
Posible states are up/down.

== knife vsphere vm wait sysprep VMNAME

Wait for vm finishing Sysprep

    --sleep SLEEP      - The time in seconds to wait between queries for CustomizationSucceeded event. Default: 60 seconds
    --timeout TIMEOUT  - The timeout in seconds before aborting. Default: 300 seconds

== knife vsphere cpu ratio [CLUSTER] [HOST]

Lists the ratio between assigned virtual CPUs and physical CPUs on all hosts.

    knife vsphere cpu ratio
    Output:
    ### Cluster Cluster1 ###
    host1.domain.com: 1.8125
    host2.domain.com: 2.40625
    host3.domain.com: 1.8125

    ### Cluster Cluster2 ###
    host4.domain.com: 1.8125
    host5.domain.com: 2.40625

== knife vsphere vlan list

Lists all the VLANs in the datacenter

== knife vsphere vlan create NAME VLAN_ID [--switch DSSWITCH]

Creates a vlan (port group on a distributed virtual switch) with the given name and
VLAN ID. If you have multiple distributed switches then use the <tt>--switch</tt>
option to set the switch

= Developing, or using the latest code

The master version of this code may be ahead of the gem itself. If it's in master you
can generally consider it ready to use. To use master instead of what's published on
Ruby gems:

  gem uninstall knife-vsphere
  git clone <EMAIL>:ezrapagel/knife-vsphere.git # or your fork
  cd knife-vsphere
  rake build                                           # Take note of the version
  gem install pkg/knife-vsphere-1.1.1.gem              # Use the version above

If you are doing development, then you can run the plugin out of a checked out copy of
the source:

  bundle install # only needs to be done once

  bundle exec knife vsphere ...

= LICENSE:

Authors:: <NAME> <<EMAIL>>
          <NAME> <<EMAIL>>
          <NAME> <<EMAIL>>
          <NAME> <<EMAIL>>
          <NAME> <<EMAIL>>
          <NAME> <<EMAIL>>
          <NAME> <<EMAIL>>
          <NAME>

Copyright:: Copyright (c) 2011-2013 <NAME>

VMware vSphere is a trademark of VMware, Inc.

License:: Apache License, Version 2.0

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Software changes provided by N<NAME> at Dell SecureWorks. For more
information on Dell SecureWorks security services please browse to
http://www.secureworks.com

Copyright 2015 Dell SecureWorks
<commit_msg>Minor doc update to make `state` more obvious<commit_after>= Knife vSphere
{<img src="https://travis-ci.org/chef-partners/knife-vsphere.svg?branch=master" alt="Build Status" />}[https://travis-ci.org/chef-partners/knife-vsphere]

= DESCRIPTION:

This is an Chef Knife plugin to interact with VMware's vSphere. This plugin currently supports the following:

Listings:

- VMs
- Folders
- Templates
- Datastores
- VLANs (currently requires distributed vswitch)
- Resource Pools and Clusters
- Customization Specifications
- Hosts in a Pool or Cluster

VM Operations:

- Power on/off
- Clone (with optional chef bootstrap and run list)
- Delete
- VMDK addition
- Migrate
- Connect/disconnect network

Clone-specific customization options (for linux guests):

- Destination folder
- CPU core count
- Memory size
- DNS settings
- Hostname / Domain name
- IP addresses / default gateway
- vlan (currently requires distributed vswitch)
- datastore
- resource pool

For Windows guests we can run sysprep

= INSTALLATION:

    gem install knife-vsphere

= CONFIGURATION:

For initial development, the plugin targets all communication at a vCenter instance rather than at specific hosts. Only named user authentication is currently supported; you can add the credentials to your <tt>knife.rb</tt> file:

    knife[:vsphere_host] = "vcenter-hostname"
    knife[:vsphere_user] = "privileged username"
    knife[:vsphere_pass] = "<PASSWORD>"
    knife[:vsphere_dc] = "your-datacenter"

The vSphere password can also be stored in a base64 encoded version (to visually obfuscate it) by prepending 'base64:' to your encoded password. For example:

    knife[:vsphere_pass] = "<PASSWORD>=="

If you get the following error, you may need to disable SSL certificate checking:
ERROR: OpenSSL::SSL::SSLError: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed
    knife[:vsphere_insecure] = true

Credentials can also be specified on the command line for multiple VSphere servers/data centers

= Getting help

If the software isn't behaving the way you think, or you're having trouble doing something, we're happy to help. Try this checklist:

- Are you running the latest version? <tt>gem list knife-vsphere</tt>. You can always upgrade with <tt>gem install knife-vsphere</tt>
- Try running the same command with <tt>-VV</tt> to add additional logging messages
- Are there any errors in the vSphere console or logs?
- Search for known issues at https://github.com/chef-partners/knife-vsphere/issues

If you're still having problems, head on over to the issues[https://github.com/chef-partners/knife-vsphere/issues] page and create a new issue. Please include:
- A description of what you are trying to do, what you are seeing
- The version number of knife-vsphere and of vSphere itself
- The exact command you're running and the output (sanitize anything you don't want public!)

= SUBCOMMANDS:

This plugin provides the following Knife subcommands.  Specific command options can be found by invoking the subcommand with a <tt>--help</tt> flag

== knife vsphere vm list [-r, --recursive [--only-folders]]

Enumerates the Virtual Machines registered in the target datacenter. Only name is currently displayed.
    -r, --recursive    - Recurse down through sub-folders to the specified folder
    --only-folders     - Print only folder names. Implies recursive

== knife vsphere vm find --pool POOL CRITERIA FIELDS

Search for Virtual Machines matching criteria in the specified pool and display selected fields
CRITERIA:
    --match-ip IP                match ip
    --match-name VMNAME          match name
    --match-os OS                match os
    --match-tools TOOLSSTATE     match tools state
    --powered-off                Show only stopped machines
    --powered-on                 Show only started machines
FIELDS:
    --alarms                     show alarm status
    --cpu                        Show cpu
    --esx-disk                   Show esx disks
    --full-path                  Show full path
    --hostname                   show hostname
    --ip                         Show ip
    --os                         show os details
    --os-disks                   Show os disks
    --ram                        Show ram
    --snapshots                  Show snapshots
    --tools                      show tools status

     knife vsphere vm find --snapshots --full-path --pool XXX-YYYY --cpu --ram --esx-disk --os-disk --os --match-name my_machine_1 --alarms --tools --ip --match-ip 123 --match-tools toolsOk

== knife vsphere vm state [-s STATE, --state STATE] [-w PORT, --wait-port PORT] [-g, --shutdown] [-r, --recursive]

Manage power state of a virtual machine, aka turn it off and on

	-s STATE, --state STATE    - The power state to transition the VM into; one of on|off|suspended|reboot
	-w PORT, --wait-port PORT  - Wait for VM to be accessible on a port
	-g, --shutdown             - Guest OS shutdown
  -r, --recursive            - Recurse down through sub-folders to the specified folder

== knife vsphere pool list

Enumerates the Resource Pools and Clusters registered in the target datacenter.

== knife vsphere template list

Enumerates the VM Templates registered in the target datacenter. Only name is currently displayed.

== knife vsphere customization list

Enumerates the customization specifications registered in the target datacenter. Only name is currently displayed.

== knife vsphere vm clone <new vm name> --template <source template name> --cspec <customization_spec>

    knife vsphere vm clone NewNode --template UbuntuTemplate --cspec StaticSpec \
        --cips 192.168.0.99/24,192.168.1.99/24 \
        --chostname NODENAME --cdomain NODEDOMAIN

   --random-vmname - Creates a random VMNAME starts with vm-XXXXXXXX
   --random-vmname-prefix - Change the VMNAME prefix
   --dest-folder FOLDER - The folder into which to put the cloned VM
   --datastore STORE    - The datastore into which to put the cloned VM
   --datastorecluster STORE - The datastorecluster into which to put the cloned VM
   --resource-pool POOL|CLUSTER - The resource pool into which to put the cloned VM. Also accepts a cluster name.
   --template TEMPLATE - The source VM / Template to clone from
   --cspec CUST_SPEC - The name of any customization specification to apply
   --disable-customization FALSE - by default conventions will be applied to the customization specification (see below).  Disable these convention with this switch
   --cplugin CUST_PLUGIN_PATH - Path to plugin that implements KnifeVspherePlugin.customize_clone_spec and/or KnifeVspherePlugin.reconfig_vm
   --cplugin-data CUST_PLUGIN_DATA - String of data to pass to the plugin.  Use any format you wish.
   --cvlan CUST_VLANS - Comma-delimited list of VLAN names for the network adapters to join
   --cips CUST_IPS - Comma-delimited list of CIDR IPs for customization, or *dhcp* to configure that interface to use DHCP
   --cgw CUST_GW - CIDR IP of gateway for customization
   --chostname CUST_HOSTNAME - Unqualified hostname for customization
   --cdomain CUST_DOMAIN - Domain name for customization
   --ctz CUST_TIMEZONE - Timezone invalid 'Area/Location' format
   --ccpu CUST_CPU_COUNT - Number of CPUs
   --cram CUST_MEMORY_GB - Gigabytes of RAM
   --start - Start the VM after cloning.
   --bootstrap - Bootstrap the VM after cloning. Implies --start
   --fqdn SERVER_FQDN - Fully qualified hostname for bootstrapping
   --ssh-user USERNAME - SSH username
   --ssh-password PASSWORD - <PASSWORD>
   --ssh-port PORT - SSH port
   --identity-file IDENTITY_FILE - SSH identity file used for authentication
   --node-name NAME - The Chef node name for your new node
   --hint HINT_NAME[=HINT_FILE] Specify Ohai Hint to be set on the bootstrap target.  Use multiple --hint options to specify multiple hints.
   --prerelease - Install the pre-release chef gems
   --bootstrap-version VERSION - The version of Chef to install
   --bootstrap-proxy PROXY_URL - The proxy server for the node being bootstrapped
   --bootstrap-vault-file VAULT_FILE - A JSON file with a list of vault(s) and item(s) to be updated
   --bootstrap-vault-json VAULT_JSON - A JSON string with the vault(s) and item(s) to be updated
   --bootstrap-vault-item VAULT_ITEM - A single vault and item to update as "vault:item"
   --distro DISTRO - Bootstrap a distro using a template
   --template-file TEMPLATE - Full path to location of template to use
   --run-list RUN_LIST - Comma separated list of roles/recipes to apply
   --secret-file SECRET_FILE - A file containing the secret key to use to encrypt data bag item values
   --no-host-key-verify - Disable host key verification
   --json-attributes - A JSON string to be added to the first run of chef-client
   --disable-customization - Disable default customization
   --sysprep_timeout TIMEOUT - Wait TIMEOUT seconds for sysprep event before continuing with bootstrap

Clones an existing VM template into a new VM instance, optionally applying an existing customization specification.  If customization arguments such as --chost and --cdomain are specified, or if the customization sepcification fetched from VSphere is considered, a default customization specification will be attempted.  For windows, a sysprep based unattended customization in workgroup mode will be attempted (host name being the VM name unless otherwise specified).  For linux, a fixed named customization using the vmname as the host name unless otherwise specified.  These customization specification defaults can be disabled using the --disable-customization switch and the --cspec specified as-is.

NOTE!  if you are specifying a --cspec and the cloning process appears to not be properly applying the spec as defined on VSphere, consider using the --disable-customization as the conventions described above could be erroneously interfering with the spec as defined on VSphere.

Customization specifications can also be specified in code using the --cplugin and/or --cplugin-data arguments.  Below are examples of the potential implementations that woudl be saved to an rb file and passed in the --cplugin argument.

# cplugin_example.rb

    class KnifeVspherePlugin
      def data=(cplugin_data)
        # Parse your cplugin_data from the format of your choosing.
      end

      # optional
      def customize_clone_spec(src_config, clone_spec)
        # Customize the clone spec as you see fit.
        return customized_clone_spec
      end

      # optional
      def reconfig_vm(target_vm)
        # Do anything you want in here with the cloned VM.
      end
    end

# cplugin_example.rb for cloning a Windows template to VM

    require 'rbvmomi'

    class KnifeVspherePlugin
      attr_accessor :data

      def customize_clone_spec(src_config, clone_spec)

        if File.exists? data
          customization_data = JSON.parse(IO.read(data))
        else
          abort "Customization plugin data file #{data} not accessible"
        end

        cust_guiUnattended = RbVmomi::VIM.CustomizationGuiUnattended(
          :autoLogon => false,
          :autoLogonCount => 1,
          :password => <PASSWORD>,
          :timeZone => customization_data['timeZone']
        )
        cust_identification = RbVmomi::VIM.CustomizationIdentification(
          :domainAdmin => nil,
          :domainAdminPassword => nil,
          :joinDomain => nil
        )
        cust_name = RbVmomi::VIM.CustomizationFixedName(
          :name => customization_data['host_name']
        )
        cust_user_data = RbVmomi::VIM.CustomizationUserData(
          :computerName => cust_name,
          :fullName => customization_data['fullName'],
          :orgName => customization_data['orgName'],
          :productId => customization_data['windows_key']
        )
        cust_sysprep = RbVmomi::VIM.CustomizationSysprep(
          :guiUnattended => cust_guiUnattended,
          :identification => cust_identification,
          :userData => cust_user_data
        )
        dhcp_ip = RbVmomi::VIM.CustomizationDhcpIpGenerator
        cust_ip = RbVmomi::VIM.CustomizationIPSettings(
          :ip => dhcp_ip
        )
        cust_adapter_mapping = RbVmomi::VIM.CustomizationAdapterMapping(
          :adapter => cust_ip
        )
        cust_adapter_mapping_list = [cust_adapter_mapping]
        global_ip = RbVmomi::VIM.CustomizationGlobalIPSettings
        customization_spec = RbVmomi::VIM.CustomizationSpec(
          :identity => cust_sysprep,
          :globalIPSettings => global_ip,
          :nicSettingMap => cust_adapter_mapping_list
        )
        clone_spec.customization = customization_spec
        puts "New clone_spec object :\n #{YAML::dump(clone_spec)}"
        clone_spec
      end

      def reconfig_vm (target_vm)
        puts "In reconfig_vm method.  No actions implemented.."
      end
    end


# json data file

    {
        "fullName": "Your Company Inc.",
        "orgName": "Your Company Inc.",
        "windows_key": "<KEY>",
        "host_name": "foo_host",
        "timeZone": "100"
    }


The <tt>--bootstrap-vault-*</tt> options can be used to send <tt>chef-vault</tt> items to be updated during the hand-off to <tt>knife bootstrap</tt>.

Example using <tt>--bootstrap-vault-json</tt>:

    knife vsphere vm clone NewNode UbuntuTemplate --cspec StaticSpec \
        --cips 192.168.0.99/24,192.168.1.99/24 \
        --chostname NODENAME --cdomain NODEDOMAIN \
        --start true --bootstrap true \
        --bootstrap-vault-json '{"passwords":"default","appvault":"credentials"}'


== knife vsphere vm toolsconfig PROPERTY VALUE [--empty]
    --empty           - allows clearing string properties

Sets properties in tools property.
See \"https://www.vmware.com/support/developer/vc-sdk/visdk25pubs/ReferenceGuide/vim.vm.ToolsConfigInfo.html\" for available properties and types.

Examples:
    knife vsphere vm toolsconfig myvirtualmachine syncTimeWithHost false
    knife vsphere vm toolsconfig myvirtualmachine pendingCustomization -e

== knife vsphere vm delete VMNAME [--purge]

Deletes an existing VM, removing it from vSphere inventory and deleting from disk, optionally deleting it from Chef as well.
    --purge           - Delete the client and node from Chef as well

== knife vsphere vm snapshot VMNAME (options)
    --list            - List the current tree of snapshots
    --create SNAPSHOT - Create a new snapshot off of the current snapshot
    --remove SNAPSHOT - Remove a named snapshot.
    --revert SNAPSHOT - Revert to a named snapshot.
    --revert-current  - Revert to current snapshot.
    --start           - Indicates whether to start the VM after a successful revert
    --wait            - Indicates whether to wait for creation/removal to complete
    --find            - Find the VM instead of specifying the folder with -F
    --dump-memory     - Dump the memory when creating the snapshot (default: false)
    --quiesce         - Quiesce the VM before snapshotting (default: false)

Manages the snapshots for an existing VM, allowing for creation, removal, and reverting of snapshots.

== knife vsphere vm cdrom VMNAME (options)
    --datastore DATASTORE - Datastore the image is stored in
    --iso                 - Path and filename of the ISO
    --attach              - Attach the iso immediately
    --disconnect          - Disconnect any iso currently attached
    --recursive           - Search for the VM recursivly
    --folder              - Search for the VM in the specified folder
    --on_boot BOOL        - Set the Attach On Boot Boolean

== knife vsphere vm disk extend VMNAME SIZE (options)
    --diskname DISKNAME - The name of the disk that will be extended (use when vm has multiple disks)

Note: SIZE is in kilobytes

== knife vsphere vm disk list VMNAME

Lists the disks attached to VMNAME

== knife vsphere datastore list

Lists all known datastores with capacity and usage

== knife vsphere datastore maxfree [--regex]

Gets the datastore with the most free space
    --regex           - Pattern to match the datastore name

== knife vsphere datastore file DATASTORE (options)

Uploads files to a datastore and downloads files from a datastore
    --upload-file       - Upload specified local file to remote
    --download-file     - Download specified remote file to local
    --remote-file FILE  - Remote file name and path
    --local-file FILE   - Local file name and path

== knife vsphere datastorecluster list

Lists all known datastorecluster with capacity and usage

== knife vsphere datastorecluster maxfree [--regex]

Gets the datastorecluster with the most free space
    --regex           - Pattern to match the datastore name

== knife vsphere vm execute VMNAME COMMAND [ARGUMENTS] --exec-user USER --exec-passwd <PASSWORD>WD [ --exec-dir DIRECTORY ]

Executes a program on the guest. Requires vCenter 5.0 or higher.

Command path must be absolute. For Linux guest operating systems,
/bin/bash is used to start the program. For Solaris guest operating
systems, /bin/bash is used to start the program if it
exists. Otherwise /bin/sh is used.

Arguments are optional, and allow for redirection in Linux and Solaris.

  --exec-user USERNAME - The username on the guest to execute as.
  --exec-passwd <PASSWORD> - The password for the user executing as.
  --exec-dir DIRECTORY - Optional: Working directory to execute in. Will default to $HOME of user.

== knife vsphere vm vmdk add VMNAME SIZE

Adds VMDK to VM.

Optional arguments

  --vmdk-type TYPE - VMDK type, "thick" or "thin", defaults to "thin"

== knife vsphere vm markastemplate VMNAME --folder FOLDER

Will traverse the folder tree looking for the VM by name.  By default the folder inspected with be the root folder.  <tt>--folder</tt> should be specified if traversing should be in some other folder than the root.  Once found the VM will be converted into a template.  This means the VM will become a template and no longer be available as a Virtual Machine.  The name given to the template will be the name of VM from which it was created.
 
== knife vsphere hosts list --pool POOL

Lists all hosts in given Pool


== knife vsphere vm migrate VMNAME (options)

Migrate VM to resource pool/datastore/host.
Resource pool and datastore are mandatory.

    --folder FOLDER                   - folder in which to search for VM
    --resource-pool POOL        - destination resource pool
    --dest-host HOST            - destination host (optional)
    --dest-datastore DATASTORE  - destination datastore, accesible to HOST
    --priority PRIORITY         - migration priority (optional, default defaultPriority )



== knife vsphere vm net STATE VMNAME

Set networking state for VMNAME by connecting/disconnecting network interfaces.
Posible states are up/down.

== knife vsphere vm wait sysprep VMNAME

Wait for vm finishing Sysprep

    --sleep SLEEP      - The time in seconds to wait between queries for CustomizationSucceeded event. Default: 60 seconds
    --timeout TIMEOUT  - The timeout in seconds before aborting. Default: 300 seconds

== knife vsphere cpu ratio [CLUSTER] [HOST]

Lists the ratio between assigned virtual CPUs and physical CPUs on all hosts.

    knife vsphere cpu ratio
    Output:
    ### Cluster Cluster1 ###
    host1.domain.com: 1.8125
    host2.domain.com: 2.40625
    host3.domain.com: 1.8125

    ### Cluster Cluster2 ###
    host4.domain.com: 1.8125
    host5.domain.com: 2.40625

== knife vsphere vlan list

Lists all the VLANs in the datacenter

== knife vsphere vlan create NAME VLAN_ID [--switch DSSWITCH]

Creates a vlan (port group on a distributed virtual switch) with the given name and
VLAN ID. If you have multiple distributed switches then use the <tt>--switch</tt>
option to set the switch

= Developing, or using the latest code

The master version of this code may be ahead of the gem itself. If it's in master you
can generally consider it ready to use. To use master instead of what's published on
Ruby gems:

  gem uninstall knife-vsphere
  git clone <EMAIL>:ezrapagel/knife-vsphere.git # or your fork
  cd knife-vsphere
  rake build                                           # Take note of the version
  gem install pkg/knife-vsphere-1.1.1.gem              # Use the version above

If you are doing development, then you can run the plugin out of a checked out copy of
the source:

  bundle install # only needs to be done once

  bundle exec knife vsphere ...

= LICENSE:

Authors:: <NAME> <<EMAIL>>
          <NAME> <<EMAIL>>
          <NAME> <<EMAIL>>
          <NAME> <<EMAIL>>
          <NAME> <<EMAIL>>
          <NAME> <<EMAIL>>
          <NAME> <<EMAIL>>
          <NAME>

Copyright:: Copyright (c) 2011-2013 <NAME>

VMware vSphere is a trademark of VMware, Inc.

License:: Apache License, Version 2.0

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Software changes provided by <NAME> at Dell SecureWorks. For more
information on Dell SecureWorks security services please browse to
http://www.secureworks.com

Copyright 2015 Dell SecureWorks

{'fraction_non_alphanumeric': 0.07021098225513484, 'fraction_numerical': 0.005775231707885054, 'mean_word_length': 2.923168280650466, 'pattern_counts': {'":': 14, '<': 119, '<?xml version=': 0, '>': 159, 'https://': 10, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 8, 'substrings_counts': 2, 'word_list_counts': {'cursed_substrings.json': 12, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '284557', 'n_tokens_mistral': 12211, 'n_tokens_neox': 11626, 'n_words': 5022}