Archived - Installing and Removing ThousandEyes X Virtual Framebuffer on Enterprise Agents

With the release of te-browserbot 2.0, X Virtual Framebuffer is baked into the containerized runtime environment used by page load and transaction tests, so te-xvfb is no longer a requirement or suggested dependency of te-browserbot. This article is only applicable to agents running te-browserbot version 1.

For your convenience, ThousandEyes provides a wrapper of the X Virtual Framebuffer (Xvfb) installation package for installation on ThousandEyes Enterprise Agents. This wrapper is distributed as a Linux package called te-xvfb, and is included with all Enterprise Agent installations by default.

This article describes when you might need te-xvfb, and how to opt in or out of having it installed on ThousandEyes Enterprise Agents.

What Is Xvfb?

"Xvfb is an X server that can run on machines with no display hardware and no physical input devices. It emulates a dumb framebuffer using virtual memory". You can read more about X Virtual Framebuffer here.

Do I Need to Install Xvfb?

Xvfb is not required for most browser-based test configurations, but there are notable exceptions.

If you are using Kerberos authentication or Proxy Auto-Configuration (PAC) for page load or transaction browser-based tests, you must install the ThousandEyes X Virtual Framebuffer on your Enterprise Agents.

When a browser-based test requiring Xvfb runs on an agent without Xvfb, an "X11 Service is not running" error is visible in the test's views.

Installing Enterprise Agents with X Virtual Framebuffer

Installing an Enterprise Agent with Xvfb requires no additional effort:

  • Linux package agents will come installed with te-xvfb unless the -W flag is passed to the script

  • Appliance (e.g. TEVA, TEPA, HyperV, etc.) images include te-xvfb.

  • Docker images include te-xvfb.

Installing Enterprise Agents without X Virtual Framebuffer

Linux Package Installation

Copy and run the following commands:

curl -Os
chmod +x

Appliance Installation

  1. Install the appliance as normal.

  2. Unlock your appliance.

  3. Run the following command:

    apt-get remove --purge te-xvfb

Docker Installation

ThousandEyes does not distribute a Docker image that excludes Xvfb. To exclude Xvfb from a Docker agent installation, you must build a custom Docker image based on the standard ThousandEyes image:

  1. Create a Dockerfile that conforms to the following template:

    FROM thousandeyes/enterprise-agent:latest
    RUN rm -rf /etc/service/te-xvfb
  2. Build and push your custom Docker image.

  3. Deploy a Docker agent using your customer Docker image in place of thousandeyes/enterprise-agent.

Removing X Virtual Framebuffer from Existing ThousandEyes Agents

Once your agent has upgraded to a version of te-browserbot that no longer depends on te-xvfb (1.146 or greater), take the following installation-specific steps:

Linux Package

Distributions Using apt (e.g. Ubuntu)

Run the following command:

apt-get remove --purge te-xvfb

Distributions Using yum (e.g. CentOS and RHEL)

Run the following command:

yum remove te-xvfb


  1. Unlock your appliance.

  2. Run the following command:

    apt-get remove --purge te-xvfb


You can remove X Virtual Framebuffer, but its removal will not persist across container restarts. We recommend re-installing the agent using a custom Docker image, as described above.

Troubleshooting "X11 Service is not running"

If you encounter this error message, you can confirm that Xvfb is installed and running by checking its status:

Linux Package and Appliance Installation Types

systemctl status te-browserbot-xvfb

Docker Installation Type

sv status te-xvfb

Last updated