Provided by: vncdotool_1.2.0-2_all 
NAME
vncdotool - VNCDoTool Documentation
INTRODUCTION
target https://pypi.python.org/pypi/vncdotool
alt 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
•
On the Advanced Options page...
• 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.
Open an elevated Windows PowerShell console:
• 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
•
bugfixes, thanks Christopher Holm for reporting
• 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