{"id":30237673,"url":"https://github.com/devopshq/vspheretools","last_synced_at":"2025-08-15T02:07:27.473Z","repository":{"id":62587904,"uuid":"59217473","full_name":"devopshq/vspheretools","owner":"devopshq","description":"vSphereTools is a set of scripts from DevOpsHQ to support working with vSphere and virtual machines (VMs) on it, which are based on the pysphere library.","archived":false,"fork":false,"pushed_at":"2018-10-12T09:52:56.000Z","size":667,"stargazers_count":19,"open_issues_count":1,"forks_count":3,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-07-26T08:51:20.842Z","etag":null,"topics":["cli","command-line-tool","iac","routines","teamcity","teamcity-metarunners","virtualization","vsphere","vspheretools"],"latest_commit_sha":null,"homepage":"http://devopshq.github.io/vspheretools/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devopshq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-05-19T15:07:47.000Z","updated_at":"2025-04-06T13:53:50.000Z","dependencies_parsed_at":"2022-11-03T22:43:00.127Z","dependency_job_id":null,"html_url":"https://github.com/devopshq/vspheretools","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/devopshq/vspheretools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devopshq%2Fvspheretools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devopshq%2Fvspheretools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devopshq%2Fvspheretools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devopshq%2Fvspheretools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devopshq","download_url":"https://codeload.github.com/devopshq/vspheretools/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devopshq%2Fvspheretools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270511293,"owners_count":24597666,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-15T02:00:12.559Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command-line-tool","iac","routines","teamcity","teamcity-metarunners","virtualization","vsphere","vspheretools"],"created_at":"2025-08-15T02:07:24.978Z","updated_at":"2025-08-15T02:07:27.450Z","avatar_url":"https://github.com/devopshq.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vspheretools\n\n[![vspheretools build status](https://travis-ci.org/devopshq/vspheretools.svg)](https://travis-ci.org/devopshq/vspheretools) [![vspheretools code quality](https://api.codacy.com/project/badge/Grade/185f7c8a13c84f88bf8b93280e457ffc)](https://www.codacy.com/app/tim55667757/vspheretools/dashboard) [![vspheretools code coverage](https://api.codacy.com/project/badge/Coverage/185f7c8a13c84f88bf8b93280e457ffc)](https://www.codacy.com/app/tim55667757/vspheretools/dashboard) [![vspheretools on PyPI](https://img.shields.io/pypi/v/vspheretools.svg)](https://pypi.python.org/pypi/vspheretools) [![vspheretools license](https://img.shields.io/pypi/l/vspheretools.svg)](https://github.com/devopshq/vspheretools/blob/master/LICENSE)\n\n\n***Russian README: https://github.com/devopshq/vspheretools/blob/master/README_RUS.md*** \n\n***Index:***\n- [Introduction](#Chapter_1)\n    - [Environment requirements](#Chapter_1_1)\n    - [Setup](#Chapter_1_2)\n- [Console mode](#Chapter_2)\n    - [Options](#Chapter_2_1)\n    - [Commands](#Chapter_2_2)\n    - [Usage examples](#Chapter_2_3)\n- [vspheretools and TeamCity metarunners](#Chapter_3)\n    - [How to add vspheretools-metarunners](#Chapter_3_1)\n- [API usage](#Chapter_4)\n    - [Global variables](#Chapter_4_1)\n    - [API methods](#Chapter_4_2)\n- [Troubleshooting](#Chapter_5)\n\n\n# Introduction \u003ca name=\"Chapter_1\"\u003e\u003c/a\u003e\n**vSphereTools** - vSphereTools is a set of scripts from DevOpsHQ to support working with vSphere and virtual machines (VMs) on it, which are based on the pysphere library. These scripts were written for the purpose of integrating vSphere with TeamCity through meta-runners. It is also possible to use the vSphereTools tools from the console or by importing the necessary modules and methods into their projects.\n\nHow does it work? Let see the process scheme below.\n\n![vSphereTools work process](vspheretools.png \"vSphereTools work process\")\n\n\n## Environment requirements \u003ca name=\"Chapter_1_1\"\u003e\u003c/a\u003e\n\n1. The service account for access to the vSphere, whose login and password you will substitute in scripts. Only letters and numbers are recommended in login and password.\n2. From the machine where you are running scripts vSphere and the ESX must be available.\n3. The VMvare Tools tool should be installed on the VM (VM -\u003e Guest -\u003e Install / Upgrade VMvare Tools context menu).\n4. On the machine where you are running scripts, Python 2 *, version 2.7 or later is installed.\n\n\n## Setup \u003ca name=\"Chapter_1_2\"\u003e\u003c/a\u003e\n\n1. Download vSphereTools from the git repository: https://github.com/devopshq/vspheretools and unpack it to some directory.\n2. Either you can install the tool through pip:\n\n    pip install vspheretools\n\n\n# Console mode \u003ca name=\"Chapter_2\"\u003e\u003c/a\u003e\n\nUse (if you did not install the tool via pip, but simply downloaded and unpacked):\n\n    python -m vspheretools [options] [command]\n\nIf the tool is installed via pip, then simply type:\n\n    vspheretools [options] [command]\n\nIt is possible to specify many options and only one command to be executed on the Sphere.\n\nIn the examples below, we will assume that vspheretools is installed via pip and the keyword python omited.\n\n\n## Options \u003ca name=\"Chapter_2_1\"\u003e\u003c/a\u003e\n\n    -s SERVER_NAME, --server SERVER_NAME - Specify a cluster on the vSphere server. For example, vcenter-01.example.com.\n\n    -l USERLOGIN, --login USERLOGIN - Specify the login of the user who has the rights to work with the project on the Sphere. The default value is undefined.\n\n    -p USERPASSWORD, --password USERPASSWORD - Specify the user password. The default value is undefined.\n\n    -n VM_NAME, --name VM_NAME - Specify the name of the VM with which to perform the actions. The default value is undefined.\n\n    -gl GUESTLOGIN, --guest-login GUESTLOGIN - Specify the user login for the OS installed on the VM. The default value is undefined.\n\n    -gp GUESTPASSWORD, --password GUESTPASSWORD - Specify the user password for the OS installed on the VM. The default value is undefined.\n\n    -d CLONE_DIRECTORY, --clone-dir CLONE_DIRECTORY - Specify the name of the directory in the Sphere to which the user has the write permission. The default value is the \"Clones\" directory - it must be created on the Sphere.\n\n    -t TIMEOUT_SEC, --timeout TIMEOUT_SEC - Specify the timeout in seconds for certain operations. The default value is 300s.\n\n\n## Commands \u003ca name=\"Chapter_2_2\"\u003e\u003c/a\u003e\n\n    --status - Get the status of the VM, given by the --name key. The available statuses are: 'POWERING ON', 'POWERING OFF', 'SUSPENDING', 'RESETTING', 'BLOCKED ON MSG', 'REVERTING TO SNAPSHOT', 'UNKNOWN'.\n\n    --start - Start the VM, given by the --name key.\n\n    --start-wait - Start the VM, given by the --name key, and wait until the OS is fully loaded. The timeout is specified by the --timeout key.\n\n    --stop - Stop the VM, given by the --name key.\n\n    --snapshots - Display the list of snapshots for the VM, specified by the --name key.\n\n    --create-snapshot SNAPSHOT_NAME - Create a named snapshot for the VM.\n\n    --revert-to-current-snapshot - Revert VM to the current (active) snapshot.\n\n    --revert-to-snapshot SNAPSHOT_NAME - Revert VM to the named snapshot.\n\n    --properties - Display the list of available VM properties.\n\n    --get-ip - Display the IP address of the VM if it has it.\n\n    --set-ip-into-teamcity-param TEAMCITY_PARAMETER - Write the TEAMCITY_PARAMETER with the ip-address of the VM. By default, TEAMCITY_PARAMETER name is \"vm_ip\".\n\n    --clone CLONE_NAME - Clone VM to the directory defined by --clone-dir key.\n\n    --delete - Deletes the VM. Before deleting, it is checked that the VM is off, and if not, it is attempted to stop it, then delete it. ATTENTION! Be careful with this option! \n\n    --upload-file SCR DST REWRITE - Copies a local file to the VM. The full paths of both files must be specified. REWRITE = True is specified to overwrite an existing file.\n\n    --download-file SCR DST REWRITE - Copies a file from the VM to the specified local path. The full paths of both files must be specified. REWRITE = True is specified to overwrite an existing file.\n\n    --mkdir DIR_PATH CREATESUBS - Creates the specified directory on the VM. If CREATESUBS = True, then all intermediate subdirectories are created.\n\n    --execute PROGRAM ARGS ENV CWD PYTHONBIN WAIT - Starts the specified PROGRAM on the VM and returns its PID. ARGS - list of additional parameters, separated by commas. ENV - environment variables NAME:VALUE, separated by commas. CWD is the working directory of the program. PYTHONBIN - the full path to the python 2.* on the VM. WAIT or no the end of the program after is starts.\n\n\n## Usage examples \u003ca name=\"Chapter_2_3\"\u003e\u003c/a\u003e\n\nIf spaces are used in the input parameters, then use theirs value with double quotes, e.g. \"VM name with space\"\n\nGet the current VM status:\n\n    vspheretools --server vcenter-01.example.com --login \u003cDomain_account\u003e --password \u003cuserpass\u003e --name \u003cfull_VM_name\u003e --status\n\nStart VM:\n\n    vspheretools --server vcenter-01.example.com --login \u003cDomain_account\u003e --password \u003cuserpass\u003e --name \u003cfull_VM_name\u003e --start\n\nStart VM and wait until guest OS loaded with 5 minute timeout:\n\n    vspheretools --server vcenter-01.example.com --login \u003cDomain_account\u003e --password \u003cuserpass\u003e --name \u003cfull_VM_name\u003e --timeout 300 --start-wait\n\nStop VM:\n\n    vspheretools --server vcenter-01.example.com --login \u003cDomain_account\u003e --password \u003cuserpass\u003e --name \u003cfull_VM_name\u003e --stop\n \nGet VM snapshots:\n\n    vspheretools --server vcenter-01.example.com --login \u003cDomain_account\u003e --password \u003cuserpass\u003e --name \u003cfull_VM_name\u003e --snapshots\n\nCreate named snapshot of the VM state:\n\n    vspheretools --server vcenter-01.example.com --login \u003cDomain_account\u003e --password \u003cuserpass\u003e --name \u003cfull_VM_name\u003e --create-snapshot name=\"Snapshot name\" rewrite=True fail-if-exist=False\n\nRevert VM to the current (active) snapshot:\n\n    vspheretools --server vcenter-01.example.com --login \u003cDomain_account\u003e --password \u003cuserpass\u003e --name \u003cfull_VM_name\u003e --revert-to-current-snapshot\n \nRevert VM to the named snapshot:\n\n    vspheretools --server vcenter-01.example.com --login \u003cDomain_account\u003e --password \u003cuserpass\u003e --name \u003cfull_VM_name\u003e --revert-to-snapshot \u003cfull_snapshot_name\u003e\n\nGet VM properties:\n\n    vspheretools --server vcenter-01.example.com --login \u003cDomain_account\u003e --password \u003cuserpass\u003e --name \u003cfull_VM_name\u003e --properties\n\nGet an ip-address of the VM with 10 seconds timeout:\n\n    vspheretools --server vcenter-01.example.com --login \u003cDomain_account\u003e --password \u003cuserpass\u003e --name \u003cfull_VM_name\u003e --timeout 10 --get-ip\n \nGet an ip-address of the VM and save it to the TeamCity \"vm_ip\"-named parameter with 10 seconds timeout:\n\n    vspheretools --server vcenter-01.example.com --login \u003cDomain_account\u003e --password \u003cuserpass\u003e --name \u003cfull_VM_name\u003e --timeout 10 --set-ip-into-teamcity-param vm_ip\n  \nCreate VM clone:\n\n    vspheretools --server vcenter-01.example.com --login \u003cDomain_account\u003e --password \u003cuserpass\u003e --name \u003cfull_VM_name\u003e --clone-dir Clones --clone new_clone_name\n \nDelete VM:\n\n    vspheretools --server vcenter-01.example.com --login \u003cDomain_account\u003e --password \u003cuserpass\u003e --name \u003cfull_VM_name\u003e --delete\n \nCopy local file to VM:\n\n    vspheretools --server vcenter-01.example.com --login \u003cDomain_account\u003e --password \u003cuserpass\u003e --name \u003cfull_VM_name\u003e -gl \u003cguest-login\u003e -gp \u003cguest-password\u003e --upload-file \u003csource_file\u003e \u003cdestination_file\u003e True\n\nCopy file from VM to the local path:\n\n    vspheretools --server vcenter-01.example.com --login \u003cDomain_account\u003e --password \u003cuserpass\u003e --name \u003cfull_VM_name\u003e -gl \u003cguest-login\u003e -gp \u003cguest-password\u003e --download-file \u003csource_file\u003e \u003cdestination_file\u003e\n \nCreate a directory and all intermediate subdirectories (by default):\n\n    vspheretools --server vcenter-01.example.com --login \u003cDomain_account\u003e --password \u003cuserpass\u003e --name \u003cfull_VM_name\u003e -gl \u003cguest-login\u003e -gp \u003cguest-password\u003e --mkdir \u003cdir_path\u003e\n \nStart the Windows console with options:\n\n    vspheretools --server vcenter-01.example.com --login \u003cDomain_account\u003e --password \u003cuserpass\u003e --name \u003cfull_VM_name\u003e -gl \u003cguest-login\u003e -gp \u003cguest-password\u003e --execute program=\"C:\\Windows\\System32\\cmd.exe\" args=\"/T:Green /C echo %aaa% \u0026 echo %bbb%\" env=\"aaa:10, bbb:20\" cwd=\"C:\\Windows\\System32\" pythonbin=\"c:\\python27\\python.exe\" wait=True\n\n\n# vspheretools and TeamCity metarunners \u003ca name=\"Chapter_3\"\u003e\u003c/a\u003e\n\nTo work with the Sphere in TemCity, you can add the following metarunners:\n\n* DevOps-runner: vspheretools - Show VM status\n* DevOps-runner: vspheretools - Start VM\n* DevOps-runner: vspheretools - Start VM and waiting until guest OS started\n* DevOps-runner: vspheretools - Stop VM\n* DevOps-runner: vspheretools - Show VM snapshots\n* DevOps-runner: vspheretools - Create VM snapshot\n* DevOps-runner: vspheretools - Revert VM to current snapshot\n* DevOps-runner: vspheretools - Revert VM to named snapshot \n* DevOps-runner: vspheretools - Show VM properties\n* DevOps-runner: vspheretools - Show VM ip-address\n* DevOps-runner: vspheretools - Set VM ip-address into TC parameter\n* DevOps-runner: vspheretools - Clone VM into directory\n* DevOps-runner: vspheretools - Delete VM\n* DevOps-runner: vspheretools - Upload file to VM\n* DevOps-runner: vspheretools - Download file from VM\n* DevOps-runner: vspheretools - Create directory on VM\n* DevOps-runner: vspheretools - Execute command on VM\n\n\n## How to add vspheretools-metarunners \u003ca name=\"Chapter_3_1\"\u003e\u003c/a\u003e\n\n* Install (or copy) xml metarunners from vspheretools-metarunners directory on your TeamCity admin page: https://[teamcity_server]/admin/editProject.html?projectId=_Root\u0026tab=metaRunner (Administration - Root project - Meta-Runners)\n* Create new VCS from vspheretools project: https://github.com/devopshq/vspheretools\n* Attach new VCS to your TeamCity project and set up checkout rules: \n+:.=\u003e%default_devops_tools_path_local%/vspheretools\n* Create variable default_devops_tools_path_local in your TeamCity project and set value, e.g. \"devops-tools\". It is local path for devops-tools repository.\n\n\n# API usage \u003ca name=\"Chapter_4\"\u003e\u003c/a\u003e\n\nMake import of the vspheretools module. When using the module, you need to determine the basic constants. Let's consider the simplest examples:\n\n    from vspheretools import VSphereTools as vs\n\n    version = vs.Version()\n    print(version)\n\n    vs.VC_SERVER = r\"VSPHERE NAME\"\n    vs.VC_LOGIN = r\"VSPHERE USER LOGIN\"\n    vs.VC_PASSWORD = r\"PASSWORD\"\n    vs.VM_NAME = r\"VIRTUAL MACHINE\"\n\n    sphere = vs.Sphere()\n\n    sphere.VMStatus()\n\nThe remaining variables and commands that you can use to work through the API are shown below.\n\n\n## Global variables \u003ca name=\"Chapter_4_1\"\u003e\u003c/a\u003e\n\n    VC_SERVER = r\"vcenter-01.example.com\"\n\n    VC_LOGIN = r\"login\"\n\n    VC_PASSWORD = r\"password\"\n\n    VM_NAME = r\"VM name\"\n\n    VM_GUEST_LOGIN = r\"os_login\"\n\n    VM_GUEST_PASSWORD = r\"os_password\"\n\n    VM_CLONES_DIR = \"Clones\"\n\n    OP_TIMEOUT = 300\n\nTo work with the sphere, you need to initialize any variable of the Sphere() class, which initializes the connection to the Sphere, the necessary cluster and the virtual machine, and contains the basic methods.\n\n\n## API methods \u003ca name=\"Chapter_4_2\"\u003e\u003c/a\u003e\n\n    VMStatus() - State of the VM_NAME virtual machine\n\n    VMStart() - Start VM_NAME virtual machine with POWERED OFF status\n    \n    VMStartWait() - Start VM_NAME virtual machine with POWERED OFF status and wait until OS loaded\n\n    VMStop() - Stop VM_NAME virtual machine with POWERED ON status\n\n    GetVMProperties() - Get dictionary with properties of VM_NAME virtual machine\n\n    GetVMSnapshotsList() - list of virtual machine snapshot instances\n\n    CreateVMSnapshot() - Create named snapshot of the VM_NAME virtual machine\n\n    GetVMIPaddress() - Return an ip-address of VM_NAME virtual machine\n\n    SetVMIPaddressIntoTeamCityParameter(paramName) - Get an ip-address of the VM and save it to the TeamCity \"vm_ip\"-named parameter\n\n    VMRevertToCurrentSnapshot() - Revert VM_NAME virtual machine to current (active) snapshot\n\n    VMRevertToSnapshot(snapshotName) - Revert VM_NAME virtual machine to snapshotName snapshot\n\n    CloneVM(cloneName) - Cloning VM_NAME virtual machine to the VM_CLONES_DIR directory\n\n    DeleteVM() - Delete VM_NAME virtual machine\n\n    CopyFileIntoVM(srcFile, dstFile, overwrite) - Copy from local srcFile path to dstFile on VM\n\n    CopyFileFromVM(srcFile, dstFile, overwrite) - Copy from VM srcFile to local dstFile path\n\n    MakeDirectoryOnVM(dirPath, createSubDirs) - Create dirPath directory on VM\n\n    ExecuteProgramOnVM(\\*\\*kwargs) - Run program with some parameters on VM. Arguments: program e.g. r\"C:\\Windows\\System32\\cmd.exe\"; args e.g. r\"/T:Green /C echo %aaa% \u0026 echo %bbb%\"; env e.g. r\"aaa:10, bbb:20\"; cwd e.g. r\"C:\\Windows\\System32\\\"\n\n\n# Troubleshooting \u003ca name=\"Chapter_5\"\u003e\u003c/a\u003e\n\n**1. If you see errors in the log:**\n\n    VSphereTools.py       [Line:89] ERROR     [2015-08-28 16:48:44,490] Can not connect to vSphere! server = vcenter-01.example.com,\n    VIApiException: [InvalidLoginFault]: Cannot complete login due to an incorrect user name or password,\n    pysphere.resources.vi_exception.VIApiException: [GuestOperationsUnavailableFault]: The guest operations agent could not be contacted.\n\nand other authorization problems: check that you correctly specify the login and password: the domain login should look like: domain\\login, e.g. .\\administartor for the local administrator. The password and the login should not contain special characters or be escaped with quotes.\n\n**2. ValueError**\n\nIf you see an error in the log similar to:\n\n    exitCode = sphere.ExecuteProgramOnVM(**dict(kw.split('=') for kw in args.execute))\n    ValueError: dictionary update sequence element #3 has length 4; 2 is required\n\nthen check the \"Command-line arguments\" field is correct. Separate variables are separated by commas! \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevopshq%2Fvspheretools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevopshq%2Fvspheretools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevopshq%2Fvspheretools/lists"}