= Investigating shared clipboard problems on X11 guests or hosts =

If you are having problems with !VirtualBox's shared clipboard functionality and are using either an X11-based host system or an X11-based guest then it is possible to enable logging functionality which will give you a glimpse into what is happening inside.  (Before doing this, check that the shared clipboard is actually enabled of course.  And be sure that you understand that X11 has two - or three - different clipboards, of which we only proxy one.)  This glimpse will be from the point of view of the X11 clipboard component, so if you are for example running a Windows guest on a Linux host, you will see when the host component thinks that the guest component has asked for the clipboard contents, but not directly when an application on the guest has asked the guest component for data.

'''Important note: Make sure to check first that no third-party clipboard managers (like parcellite) are running anymore, neither on the host nor on the guest side. Some of those are known to cause trouble with !VirtualBox's shared clipboard functionality.'''

For background, the shared clipboard mechanism is made up of a component running on the host and one running on the guest which communicate using !VirtualBox's host-to-guest communication mechanism.  The host component represents all applications running on the guest and vice versa.  Some examples of what this means are:

 * if an application on the guest takes ownership of the clipboard there, the host component takes ownership of the clipboard on the host.  If an application on the host asks it what data formats it has on offer, the host component asks the guest component which asks the owner application on the guest, and the host component returns this information.
 * If an application on the host asks for data from the clipboard, the host component asks the guest component which asks the owner application.
 * If an application on the host then takes ownership of the clipboard on the host, the host component tells the guest component which takes over ownership of the guest clipboard from the application which had it.

The sort of information that you will see will include:

 * The component is starting or stopping.
 * An application has asked the component what data formats the shared clipboard has on offer.
 * An application has asked for clipboard data.
 * The other component has announced that it an application at its end is taking control of the clipboard, so this component should take control of the clipboard at its end to represent the remote application.
 * An application at this end has taken control of the clipboard, so this component has relinquished control and asked the other end to take control over the clipboard there to represent the application.

== Enabling logging on the host component == #HostLogging

To tell the host clipboard component on an X11-based host to add information to the virtual machine log file, run !VirtualBox from the command line with the environment variable
{{{
VBOX_RELEASE_LOG=+shared_clipboard.e.l.f
}}}
set (see the description of the [wiki:VBoxLogging logging facility] for more background).

== Enabling logging in the guest component == #GuestLogging

On X11-based guest systems, the main part of the guest component is a daemon application (one which is started once and usually never stops, carrying on its work in the background) called !VBoxClient.  You can see whether or not it is running (it should be) using the `ps` command:
{{{
$ ps -Af | grep VBoxClient
[...]
user   122 [...] /usr/bin/VBoxClient --display
user   123 [...] /usr/bin/VBoxClient --display
user   124 [...] /usr/bin/VBoxClient --clipboard
user   125 [...] /usr/bin/VBoxClient --clipboard
[...]
}}}
To get it to produce logging, you can stop it (in this example, the process IDd are 124 and 125, so you would execute
{{{
$ kill 124 125
}}}
and restart it (as the logged on user) with the `VBOX_RELEASE_LOG_DEST` environment variable set to point to a file, with `VBOX_RELEASE_LOG=+all.e.l.f` and with the `-d` flag which tells it not to become a daemon and disappear into the background:
{{{
$ VBOX_RELEASE_LOG_DEST=file=/tmp/clipboard.log VBOX_RELEASE_LOG=+all.e.l.f VBoxClient -d --clipboard
}}}
Now the logging will go to a file called `/tmp/clipboard.log` on the guest.