DOCSEARCHbyAlgolia
Submit Docs

vncdotool Documentation

repository·main·Indexed 19 days ago

https://github.com/sibson/vncdotool

A command-line VNC client and Python library designed to automate interactions with virtual machines or hardware devices via the VNC protocol. It provides capabilities for simulating keyboard and mouse input, capturing screenshots, and performing image-based screen verification (expect). The tool includes the vncdo command for executing automation scripts and vnclog for recording VNC sessions into playable .vdo files.

Tokens
5.4K
Snippets
37
Records
38
Agent score
65%

What's inside vncdotool

  1. Record VNC sessions using vnclog

    main

    The vnclog tool acts as a man-in-the-middle to record VNC commands from a client session into a playable script (.vdo file). This is useful for creating automation scripts by recording manual actions.

    Workflow

    1. Setup: vncviewer $\rightarrow$ vnclog $\rightarrow$ vncserver.
    2. Recording: Use vnclog to intercept the connection.
    3. Playback: Use vncdo to play back the recorded .vdo file.

    Note: For best results, configure your vncviewer client to use RAW encoding, as other encodings may not be fully supported.

    Recording Modes

    • Standard: Launch vnclog and then connect your viewer to the port provided.
    • Forever Mode: Use the --forever flag to make vnclog listen continuously. It will create a new .vdo file for every new client connection, which is ideal for recording multiple test cases.
    # Quick start: record a session directly
vnclog --viewer vncviewer keylog.vdo

# Manual control: launch logger, then connect viewer separately
vnclog keylog.vdo
vncviewer localhost:2

# Continuous recording: listen on port 6000 and save files to /tmp
vnclog --forever --listen 6000 /tmp

  2. Run automation scripts with vncdo

    main

    For complex automation, you can chain multiple actions together in a single command or use external files.

    Chaining Actions

    You can specify multiple actions on one line to perform sequences like login flows: vncdo type username key enter expect password_prompt.png

    Running from Files or Stdin

    Create a text file (e.g., script.vdo) containing a list of actions (one per line or grouped). You can run these files directly or pipe commands into vncdo using - to represent stdin.

    # Pipe commands via stdin
echo "type hello" | vncdo -

# Run a script file
vncdo login.vdo

  4. Embed vncdotool in Python applications

    main

    vncdotool is built on the Twisted framework. For non-Twisted applications, it provides a synchronous compatibility layer that runs the Twisted reactor in a separate daemon thread and communicates with your main program via a thread-safe Queue.

    Important: Explicit Shutdown Required

    Because the Twisted reactor spawns non-daemon worker threads, your application will not terminate automatically when the main thread finishes. You must call vncdotool.api.shutdown explicitly to stop the reactor and allow the process to exit.

    Note on Context Managers: When using api.connect as a context manager, the reactor is not shut down at the end of the with block. This design choice allows you to reuse the API multiple times within the same process, but it means you still must call vncdotool.api.shutdown manually when your application is finished with all VNC operations.

    from vncdotool import api

try:
    client = api.connect('vncserver', password=None)
    # ... perform tasks ...
finally:
    api.shutdown()

  5. Install vncdotool via pip

    main

    The simplest way to install vncdotool is via PyPI using pip.

    Note that vncdotool depends on Pillow (Python Imaging Library) and Twisted (an asynchronous networking library). If you encounter issues with recent versions of these dependencies, consider using a virtual environment to manage a stable set of libraries.

    pip install vncdotool

  6. Install vncdotool on Windows

    main

    For Windows users, the most reliable method is to use binary packages via a Python installation.

    1. Python Installation Steps

    1. Download the current 64-bit Windows version from python.org.
    2. During installation:
      • Check "Add Python to PATH".
      • Click "Customize installation".
      • On the Advanced Options page, Check "Install for all users" and "Add Python to environment variables".
      • Uncheck "Precompile standard library" (optional).
      • Click "Install".

    2. Configuration and Installation

    Open an elevated Windows PowerShell console (Run as Administrator) and execute the following commands (replace Python39 with your specific installed version, e.g., Python311):

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

    3. Verification

    Run the following command to verify the installation works by sending a type command to a remote server:

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

  8. Install vncdotool in a virtual environment

    main

    To avoid dependency conflicts with Pillow or Twisted, it is recommended to use a virtual environment. You can install vncdotool from the source tree using the following steps:

    1. Install virtualenv.
    2. Create a new virtual environment.
    3. Install requirements and the package in editable mode.
    pip install virtualenv
virtualenv venv-vncdotool
pip install -r requirements.txt
pip install -e .

  9. Quick Start with vncdotool

    main

    You can use vncdotool to connect to VNC servers using various addressing formats. The tool supports IP addresses, hostnames, and display numbers (ports).

    Common connection patterns include:

    • Standard IP and Port: Connect to an IP on the default port 5900.
    • Display Numbers: Use a colon followed by the display number (e.g., :3 maps to port 5903).
    • Hostname and Custom Port: Specify the hostname and the exact port.
    • IPv6: When using IPv6 addresses, you must wrap the address in square brackets [].
    # Connect to 192.168.1.1 on default port 5900
vncdotool connect 192.168.1.1

# Connect to localhost on display :3 (port 5903)
vncdotool connect localhost:3

# Connect to myvncserver.com on port 5902
vncdotool connect myvncserver.com:5902

# Connect via IPv6 to localhost on display :3 (port 5903)
vncdotool connect [::1]:3

  10. Run functional tests

    main

    Functional tests require libvncserver/examples to be available in your system PATH. You can either manually update your path or use the provided make targets to set up the environment and run the tests.

    Option 1: Use the automated make target:

    make test-func

    Option 2: Manually configure the path and run via unittest:

    make libvnc-examples
export PATH="$PATH:.vncdo/libvncserver-LibVNCServer-0.9.14/examples"
python -m unittest discover tests/functional

  11. Use VNCDoToolClient as a context manager

    main

    The vncdotool.client.VNCDoToolClient supports the context manager protocol, allowing for cleaner resource management during a session.

    from vncdotool import api

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

  12. Configure timeouts and handle TimeoutError

    main

    To prevent blocking calls from hanging indefinitely, you can set a per-client timeout in seconds on the VNCDoToolClient instance. If a command exceeds this duration, a TimeoutError is raised.

    If you encounter frequent TimeoutError exceptions, it is recommended to reset the connection by calling client.disconnect() and then re-establishing it with api.connect().

    client.timeout = 10
try:
    client.captureScreen('screenshot.png')
except TimeoutError:
    print('Timeout when capturing screen')