Scroll to navigation

VNCDOTOOL(1) VNCDoTool VNCDOTOOL(1)

NAME

vncdotool - VNCDoTool Documentation

INTRODUCTION

https://pypi.python.org/pypi/vncdotool
Python Versions



Actions StatusReadTheDocsCode style: black.SH VNCDOTOOL

vncdotool is a command line VNC client. It can be useful to automating interactions with virtual machines or hardware devices that are otherwise difficult to control.

It's under active development and seems to be working, but please report any problems you have.

Quick Start

To use vncdotool you will need a VNC server. Most virtualization products include one, or use RealVNC, TightVNC or clone your Desktop using x11vnc.

Once, you have a server running you can install vncdotool from pypi:

pip install vncdotool


and then send a message to the vncserver with:

vncdo -s vncserver type "hello world"


The vncserver argument needs to be in the format address[:display|::port]. For example:

# connect to 192.168.1.1 on default port 5900
vncdo -s 192.168.1.1 type "hello world"
# connect to localhost on display :3 (port 5903)
vncdo -s localhost:3 type "hello world"
# connect to myvncserver.com on port 5902 (two colons needed)
vncdo -s myvncserver.com::5902 type "hello world"
# connect via IPv6 to localhost on display :3 (port 5903)
vncdo -s '[::1]:3' type "hello IPv6"
#         ^   ^ mind those square brackets around the IPv6 address


You can also take a screen capture with:

vncdo -s vncserver capture screen.png


More documentation can be found on Read the Docs.

Feedback

If you need help getting VNCDoTool working try the community at _Stackoverflow

Patches, and ideas for improvements are welcome and appreciated, via _GitHub issues. If you are reporting a bug or issue please include the version of both vncdotool and the VNC server you are using it with.

Acknowledgements

Thanks to Chris Liechti, techtonik and Todd Whiteman for developing the RFB and DES implementations used by vncdotool. Also, to the TigerVNC project for creating a community focus RFB specification document

INSTALLATION

vncdotool is available on PyPI, so in most cases you should be able to simply run:

pip install vncdotool


vncdotool relies on a number of libraries, the two major ones are PIL, the Python Imaging Library and Twisted, an asynchronous networking library. While vncdotool should work with any recent version of these libraries sometimes things break. If you are having issues getting things to work you can try using a stable set of libraries and if you aren't already using it, and you should be, use a virtualenv.:

pip install virtualenv
virtualenv venv-vncdotool
# XXX requirements.txt from vncdotool source tree
pip install -r requirements.txt
pip install -e .


Windows

If you are not familiar with Python, the most reliable way to install vncdotool is to use binary packages.

1.
Download Python, current 64-bit Windows Version, from Official Python website https://www.python.org/downloads/
2.
Start the installation > On the first screen of the installer...
  • Check the box for "Add Python to PATH",
  • Any other check boxes can be left checked or unchecked per their default
  • Click "Customize installation"
  • On the Optional Features install page, no changes are needed
  • Make sure the boxes for "Install for all users" and "Add Python to environment variables" are checked
  • Uncheck "Precompile standard library" unless needed for other projects
  • Any other check boxes can be left checked or unchecked per their default


•
Click "Install" at the bottom



3.
  • Type "PowerShell" (without quotes) in the search field of the Windows taskbar
  • Click "Run as administrator" in the right pane above the search field
  • Type or paste each of the following lines below, pressing Enter after each line and waiting for each line to process (change “Python39” to different version as applicable):

[Environment]::SetEnvironmentVariable("Path", "$env:Path;C:\Program Files\Python39\;C:\Program Files\Python39\Scripts\", "User")
python -m pip install --upgrade pip
pip install vncdotool




4.
At a Powershell prompt:

vncdo.exe --server som.eip.add.res type "Hello World"


5.
If Hello World shows up on the remote machine that has a VNC server running then its time to celebrate. Otherwise, first check you can connect from your local machine to the remote using a normal GUI VNC Client. Once you get the normal GUI client working try vncdotool again and if you still have problems try the community at _Stackoverflow.



USAGE

Basic Usage

Once installed you can use the vncdotool command to send key-presses. Alphanumerics are straightforward just specify the character. For other keys longer names are used:

> vncdo key a
> vncdo key 5
> vncdo key .
> vncdo key enter
> vncdo key shift-a
> vncdo key ctrl-C
> vncdo key ctrl-alt-del


To type longer strings when entering data or commands you can use the type c command, which does not support special characters:

> vncdo type "hello world"


You can control the mouse pointer with move and click commands. NOTE, you should almost always issue a move before a click, as in:

> vncdo move 100 100 click 1


The following would seem to be equivalent but would actually click at (0, 0). This occurs due to how click events are encoded by VNC, meaning you need to initialise the position of the mouse.:

> vncdo move 100 100
> vncdo click 1


If you have the Python Imaging Library (Pillow) installed you can also make screen captures of the session:

> vncdo capture screenshot.png


With Pillow installed, you can wait for the screen to match a known image:

> vncdo expect somescreen.png 0


Putting it all together you can specify multiple actions on a single command line. You could automate a login with the following:

> vncdo type username key enter expect password_prompt.png
> vncdo type password move 100 150 click 1 expect welcome_screen.png


Sometimes you only care about a portion of the screen, in which case you can use rcapture and rexpect. For instance, if your login window appears at x=100, y=200 and is 400 pixels wide by 250 high you could do:

> vncdo rcapture region.png 100 200 400 250
> vncdo rexpect region.png 100 200 0


Running Scripts

For more complex automation you can read commands from stdin or a file. The file format is simply a collection of actions:

> echo "type hello" | vncdo -


Or if you had a file called login.vdo with the following content:

# select the name text box, enter your name and submit
move 100 100 click 1 type "my name" key tab key enter
# grab the result
capture screenshot.png


You could run it with the following command:

> vncdo login.vdo


Creating Scripts

While you can create scripts by hand it can often be a time consuming process. To make the process easier vncdotool provides a log mode that allows a user to record a VNC session to a script which is playable by vncdo. vnclog act as a man-in-the-middle to record the VNC commands you issue with a client. So you will have your vnclog connect to your server and your viewer connect to vnclog

vncviewer ---> vnclog ---> vncserver


For best results be sure to set your vncviewer client to use the RAW encoding. Others encoding may work but are not fully supported at this time.

The quickest way to get started is to run:

> vnclog --viewer vncviewer keylog.vdo


For more control you can launch the viewer separately but be sure to connect to the correct ports:

> vnclog keylog.vdo
> vncviewer localhost:2  # do something and then exit viewer
> vncdo keylog.vdo


By running with --forever vnclog will create a new file for every client connection and record each clients activity. This can be useful for quickly recording a number of testcases.:

> vnclog --forever --listen 6000 /tmp
> vncviewer localhost::6000
# do some stuff then exit and start new session
> vncviewer localhost::6000
# do some other stuff
> ls /tmp/*.vdo


EMBEDDING IN PYTHON APPLICATIONS

vncdotool is built with the Twisted framework, as such it best intergrates with other Twisted Applications Rewriting your application to use Twisted may not be an option, so vncdotool provides a compatibility layer. It uses a separate thread to run the Twisted reactor and communicates with the main program using a threadsafe Queue.

To use the synchronous API you can do the following:

from vncdotool import api
client = api.connect('vncserver', password=None)


The first argument passed to the connect method is the VNC server to connect to, and it needs to be in the format address[:display|::port]. For example:

# connect to 192.168.1.1 on default port 5900
client = api.connect('192.168.1.1', password=None)
# connect to localhost on display :3 (port 5903)
client = api.connect('localhost:3', password=None)
# connect to myvncserver.com on port 5902 (two colons needed)
client = api.connect('myvncserver.com::5902', password=None)


You can then call any of the methods available on vncdotool.client.VNCDoToolClient and they will block until completion. For example:

client.captureScreen('screenshot.png')
client.keyPress('enter')
client.expectScreen('login_success.png', maxrms=10)


It is possible to set a per-client timeout in seconds to prevent calls from blocking indefinitely.

client.timeout = 10
try:


    client.captureScreen('screenshot.png')
except TimeoutError:


    print('Timeout when capturing screen')


In case of too many timeout errors, it is recommended to reset the client connection via the disconnect and connect methods.

The vncdotool.client.VNCDoToolClient supports the context manager protocol.

with api.connect('vnchost:display') as client:


    client.captureScreen('screenshot.png')


The synchronous API can be used to automate the starting of a Virtual Machine or other application:

vmtool.start('myvirtualmachine.img')
client.connect('vmaddress::5950')
client.expectScreen('booted.png')
for k in 'username':


    client.keyPress(k)
client.keyPress('enter')
for k in 'password':


    client.keyPress(k)
client.keyPress('enter')
client.expectScreen('loggedin.png')
client.disconnect()
# continue with your testing session or other work


COMMAND REFERENCE

click BUTTON

capture FILENAME.PNG

drag X Y

expect FILENAME.PNG FUZZ

key KEY

keydown KEY

keyup KEY

move X Y

mousedown BUTTON

mousemove X Y

mouseup BUTTON

pause SECONDS

rcapture FILENAME.PNG X Y W H

rexpect FILENAME.PNG X Y FUZZ

type STRING

RELEASE HISTORY

1.2.0 (2023-06-06)

•
fixes for api.shutdown and disconnect raise exceptions, #256



1.1.0 (2023-04-01)

Huge thanks to @pmhahn for single handedly driving conversion to modern Python3, as well as cleaning up a ton of outstanding issues.

  • [BREAKING] drop python 2.x support, thanks @pmhahn
  • Use built-in Unittest and mock for testing
  • PEP-484 type hinting, thanks @pmhahn
  • Doc improvements, thanks @luke-jr, @pmhahn, @samiraguiar
  • Test for byte handling, thanks @ponty, refs #177
  • Internal implementation of DES replaced by PyCrotodomeX
  • Support for Apple Remote Desktop (ARD), thanks @andywgrant, @pmhahn
  • Support for pseudo-encoding LastRec, thanks @pmhahn
  • Support for Extended QEMU Key Events, thanks @pmhahn
  • Support IPv6 addresses for server connection, thanks @pmhahn
  • Bugfix, use configured log outputs over stdout, thanks @pevogam
  • Bugfix, handle invalid password, thanks @dozysun
  • Bugfixes for loggingproxy, thanks @joachimmetz, @pmhahn, @guicho271828



1.0.0 (2020-04-10)

  • add ZRLE encoding, thanks Adrian Weiler
  • drop python2 support
  • fix mouseDrag behaviour, thanks Samir Aguiar



0.13.0 (2019-11-21)

  • new flag --incremental-refreshes, increased compatibility of capture, thanks Amir Rossert
  • exit non-zero and print to stderr for unknown commands, thanks Amir Rossert



0.12.1 (2018-12-06)

  • bugfix expectRegion to use cropped images for compare, thanks Michael Fürnschuß
  • direct support for building RPMs, thanks Plamen Dimitrov



0.12.0 (2018-04-07)

  • connect via UNIX sockets, thanks Matteo Cafasso
  • bugfix, XTightVNC initial connection, thanks Antti Kervinen



0.11.2 (2017-09-24)

•
fix version metadata, thanks Kevin Gottsman



0.11.1 (2017-07-23)

  • add api.client.disconnect()
  • fix python2.x compatibility, thanks Ostrosablin Vitaly



0.11.0 (2017-06-09)

  • enable PSEUDO_DESKTOP_SIZE_ENCODING by default to allow desktop resizing, thanks rebasegod
  • python 3.0 support, thanks jamtwister
  • added pastefile command, thanks Rogan Dawes
  • debian packaging improvements, thanks Alexander Kläser
  • fix loggingproxy, thanks Matthias Weckbecker



0.10.0 (2016-03-03)

  • drop official 2.6 support, it'll probably work for a while still
  • use frombytes rather than fromstring for compatibility with PIL
  • vnclog works with password protected servers using --password-required
  • exit more reliably after an error
  • use increatmental frameBufferUpdateRequests, appears to be compatible with more servers
  • include basic version negotiation with servers, thanks Ezra Bühler



0.9.0 (2015-05-08)

  • add special keys [~!@#$%^&*()_+{}|:"<>?] to --force-caps, for servers that don't handle them, Tyler Oderkirk, Aragats Amirkhanyan
  • improve vnclog performance with TCP_NODELAY, Ian Britten
  • by default pause 10ms between sending commands, better compatibility with servers
  • better handle screen resizing, Daniel Stelter-Gliese
  • API, fix deadlocks due to threaded init of PIL, thanks Antti Kervinen
  • API, support password protected server, thanks Antti Kervinen
  • API, able to connect to multiple servers, Daniel Stelter-Gliese
  • drop official support for py2.4 and py2.5
  • use Pillow rather than PIL



Thanks to Jan Sedlák, Daniel Stelter-Gliese, Antti Kervinen, Anatoly Techtonik, Tyler Oderkirk and Aragats Amirkhanyan for helping make this release possible

0.8.0 (2013-08-06)

  • improved documentation using sphinx
  • regional capture and expect that operate on a portion of the display
  • --force-caps, better compatibility when sending UPPERCASE to servers
  • --timeout, exit with an error after a given number of seconds
  • experimental synchronous API for easier integration with non-Twisted apps



0.3.0 (2012-12-22)

  • main program renamed to vncdo, vncdotool continues an alias for now
  • use host:display, host::port syntax like other vnc tools, removed -d
  • read/play commands from stdin or file
  • vnclog, creates scripts from captured interactive sessions
  • better control over mouse in screen captures with --nocursor and --localcursor
  • mousemove, sleep command aliases to match xdotool
  • keyup/keydown commands for more control over keypresses
  • send SetEncodings on connect, thanks Matias Suarez for fix
  • debian packaging
  • type "Hello World" now preserves capitalization
  • basic compatibility with VNC 4.0 servers, found in some KVMs
  • improved frameUpdate handling
  • --warp to replay script faster than real-time
  • --delay, insert a delay between sending commands



0.2.0 (2012-08-07)

  • add pause, mouseup, mousedown, drag commands
  • only require Twisted 11.1.0, so we can have py2.4 support
  • vncdotool type -something now works
  • no longer silently fail for unsupported image formats





0.1.1 (2011-05-18)

  • add PIL to requires
  • fix bug where incorrect mouse button is sent



0.1.0 (2011-03-03)

  • first release
  • commands: press, type, move, click, capture, expect



CONTRIBUTING

Code and Issue tracking is provided by Github. There is also a mailing list setup via Google Groups.

CODE DOCUMENTATION

client Module

  • Index
  • Module Index
  • Search Page

AUTHOR

Marc Sibson

COPYRIGHT

2024, Marc Sibson

March 16, 2024 0.9