Latest revision as of 02:57, 25 August 2023

How To Run Spice Agent in Alpine

This is a guide on how to run Spice Agent in Alpine Linux 3.12.1-standard.

The Spice Agent can be used to get some additional features when running Alpine Linux in a Qemu/Libvirt VM.

Features

Working:

Client mouse mode
Automatic adjustment of the X-session resolution
Clipboard sharing

Not working:

The State field in Libvirt - it always shows "disconnected", even when it is working

Not tested:

Transferring files
Multiple displays/screens

Before You Start

Most features of the Spice Agent are only useful when running a graphical interface. I roughly followed the AwesomeWM guide, but substituted awesome with i3wm as that has my preference (you have to install i3status manually, and use i3 in the .xinitrc file).

For the Spice Agent to work, don't remove the Channel spice that is automatically added by Libvirt.

Building the Spice Agent

Install the dependencies:

 # apk add alpine-sdk autoconf automake glib-dev libxfixes-dev libxrandr-dev libxinerama-dev spice-protocol alsa-lib-dev dbus-dev libdrm-dev libpciaccess-dev

Get the source code:

 $ git clone https://gitlab.freedesktop.org/spice/linux/vd_agent.git
 $ cd vd_agent
 $ git checkout spice-vdagent-0.20.0

We need this specific version because the newest version requires a newer spice-protocol version than is provided by the repositories (version 0.14.1). If you follow this guide with a later version of Alpine, you may want to get a newer version from git as well.

Build the code (still in the vd_agent directory):

 $ ./autogen.sh
 $ make

Install the program (should be optional when running manually, but I haven't tried it without yet):

 # make install

Running the Spice Agent

Running manually

First start the spice-vdagentd:

 # modprobe uinput
 # mkdir /run/spice-vdagentd
 # spice-vdagentd -d -x -X

You can also remove the lower-case -x flag to deamonize the spice-vdagentd.

Then start the spice-vdagent:

 $ spice-vdagent -x -d

Notice that there is no need to run this last command as root.

Running with init script

This assumes you ran make install at the end of building. If you have not, you'll have to change this accordingly. It also requires that uinput can be loaded with modprobe. If you cannot, look at #Using_the_virt_edition_of_Alpine.

To run with an init script, we will use the Gentoo init script, although we have to change the paths to make it work properly (latest commit is b3b3e1d9a13c389f17e01c78c6c1a996d08420b5 at the time of writing):

 $ wget https://gitweb.gentoo.org/repo/gentoo.git/plain/app-emulation/spice-vdagent/files/spice-vdagent.initd-4
 $ sed 's,/var/run,/run,g;s,/usr/sbin,/usr/local/sbin,g' spice-vdagent.initd-4 > spice-vdagentd

Then we move the file to the right location, change the ownership, make it executable and add it to the default runlevel:

 # mv spice-vdagentd /etc/init.d/
 # chown root:root /etc/init.d/spice-vdagentd
 # chmod +x /etc/init.d/spice-vdagentd
 # rc-update add spice-vdagentd default

The above will start the spice-vdagentd, but not the spice-vdagent. As the spice-vdagent should be started with the de/wm you're using, there is not one general way which works for all setups. If you want to find a way that works for you, the Arch wiki has a decent page on autostarting.

Using the virt edition of Alpine

This currently does not work on the virt edition (version 3.12.1), as it doesn't have uinput enabled in the kernel. However, there are still several ways to get it working.

Run without uinput

You can make the spice-vdagentd work without the uinput module by starting it as follows, but it will disable the cursor while the spice-vdagent is running:

 # mkdir /run/spice-vdagentd
 # spice-vdagentd -d -x -X -u /dev/null -f

Build uinput as module

This material is work-in-progress ...

The following contains all necessary information, but has to be rewritten to be more clear.
(Last edited by Sertonix on 25 Aug 2023.)

Follow the steps in Setup your system and account for building packages and cd to the aports/main/linux-lts directory. Check that the kernel version you've pulled is the same that you're running with uname -r and head APKBUILD. If they mismatch, checkout the aports branch that has the same kernel version. If they are the same, continue with the following steps:

 $ abuild deps
 $ abuild fetch verify
 $ abuild unpack
 $ abuild prepare
 $ cd src/build-virt-x86_64

Now change CONFIG_INPUT_UINPUT from not being included to CONFIG_INPUT_UINPUT=m in the .config file. Then proceed as follows:

 $ make modules_prepare
 $ make drivers/input/misc/uinput.ko

This builds the uinput module in the current directory. Every time you want to use it, you'll have to load it like this (still from aports/main/linux-lts/src/build-virt-x86_64):

 # insmod drivers/input/misc/uinput.ko

After this, you can use the spice agent as described in Running the Spice Agent, except that the modprobe uinput is not necessary.

Alternatively, you can "install" the module by copying it to /lib/modules/`uname -r`/extra (which you'll most likely have to create first) and running depmod (as root). After this, you can load the module normally with modprobe uinput. This is necessary if you want to use the init script as described in #Running_with_init_script.

Rebuild the kernel to include uinput

See Custom_Kernel for pointers on how to build a custom kernel. The option you'll need to change in the config is CONFIG_INPUT_UINPUT.

@@ Line 20: / Line 20: @@
 =Before You Start=
 Most features of the Spice Agent are only useful when running a graphical interface.
-I roughly followed the [[Awesome(wm)_Setup]] guide, but substituted <code>awesome</code> with <code>i3wm</code> as that has my preference (you have to install <code>i3status</code> manually, and use <code>i3</code> in the <code>.xinitrc</code> file).
+I roughly followed the [[AwesomeWM]] guide, but substituted <code>awesome</code> with <code>i3wm</code> as that has my preference (you have to install {{Pkg|i3status}} manually, and use <code>i3</code> in the <code>.xinitrc</code> file).
 For the Spice Agent to work, don't remove the <code>Channel spice</code> that is automatically added by Libvirt.
@@ Line 29: / Line 29: @@
 Get the source code:
-   $ git clone (TODO: LINK TO VDAGENT GIT ON FREEDESKTOP GITLAB)
+   $ git clone <nowiki>https://gitlab.freedesktop.org/spice/linux/vd_agent.git</nowiki>
    $ cd vd_agent
    $ git checkout spice-vdagent-0.20.0
 We need this specific version because the newest version requires a newer <code>spice-protocol</code> version than is provided by the repositories (version 0.14.1). If you follow this guide with a later version of Alpine, you may want to get a newer version from git as well.
-Build the code (still in the <code>vd_agent</code> directory):
+Build the code (still in the {{Path|vd_agent}} directory):
    $ ./autogen.sh
    $ make
-Install the program (should be optional, but I haven't tried it without yet):
+Install the program (should be optional when running manually, but I haven't tried it without yet):
    # make install
 =Running the Spice Agent=
-{{Draft|While this works, it's very rough and the steps need to be performed every time you want to run it. It would be nice to have init scripts to do this.}}
+==Running manually==
 First start the <code>spice-vdagentd</code>:
    # modprobe uinput
@@ Line 54: / Line 54: @@
    $ spice-vdagent -x -d
 Notice that there is no need to run this last command as root.
+==Running with init script==
+''This assumes you ran <code>make install</code> at the end of building. If you have not, you'll have to change this accordingly. It also requires that <code>uinput</code> can be loaded with <code>modprobe</code>. If you cannot, look at [[#Using_the_virt_edition_of_Alpine]].''
+To run with an init script, we will use the Gentoo init script, although we have to change the paths to make it work properly (latest commit is <code>b3b3e1d9a13c389f17e01c78c6c1a996d08420b5</code> at the time of writing):
+  $ wget <nowiki>https://gitweb.gentoo.org/repo/gentoo.git/plain/app-emulation/spice-vdagent/files/spice-vdagent.initd-4</nowiki>
+  $ sed 's,/var/run,/run,g;s,/usr/sbin,/usr/local/sbin,g' spice-vdagent.initd-4 > spice-vdagentd
+Then we move the file to the right location, change the ownership, make it executable and add it to the default runlevel:
+  # mv spice-vdagentd /etc/init.d/
+  # chown root:root /etc/init.d/spice-vdagentd
+  # chmod +x /etc/init.d/spice-vdagentd
+  # rc-update add spice-vdagentd default
+The above will start the <code>spice-vdagentd</code>, but not the <code>spice-vdagent</code>. As the <code>spice-vdagent</code> should be started with the de/wm you're using, there is not one general way which works for all setups. If you want to find a way that works for you, [https://wiki.archlinux.org/title/Autostarting#On_desktop_environment_startup the Arch wiki has a decent page on autostarting].
 =Using the virt edition of Alpine=
-This currently does not work on the virt edition (version 3.12.1), as it doesn't have the <code>uinput</code> module enabled in the kernel.
+This currently does not work on the virt edition (version 3.12.1), as it doesn't have <code>uinput</code> enabled in the kernel. However, there are still several ways to get it working.
-You can still make the <code>spice-vdagentd</code> work by starting it as follows, but it will disable the cursor while the <code>spice-vdagent</code> is running:
+==Run without uinput==
+You can make the <code>spice-vdagentd</code> work without the uinput module by starting it as follows, but it will disable the cursor while the <code>spice-vdagent</code> is running:
    # mkdir /run/spice-vdagentd
    # spice-vdagentd -d -x -X -u /dev/null -f
+==Build uinput as module==
+{{Draft|The following contains all necessary information, but has to be rewritten to be more clear.}}
+Follow the steps in [[Creating_an_Alpine_package#Setup_your_system_and_account|Setup your system and account for building packages]] and cd to the {{Path|aports/main/linux-lts}} directory.
+Check that the kernel version you've pulled is the same that you're running with <code>uname -r</code> and <code>head APKBUILD</code>.
+If they mismatch, checkout the aports branch that has the same kernel version.
+If they are the same, continue with the following steps:
+  $ abuild deps
+  $ abuild fetch verify
+  $ abuild unpack
+  $ abuild prepare
+  $ cd src/build-virt-x86_64
+Now change <code>CONFIG_INPUT_UINPUT</code> from not being included to <code>CONFIG_INPUT_UINPUT=m</code> in the <code>.config</code> file. Then proceed as follows:
+  $ make modules_prepare
+  $ make drivers/input/misc/uinput.ko
+This builds the <code>uinput</code> module in the current directory. Every time you want to use it, you'll have to load it like this (still from {{Path|aports/main/linux-lts/src/build-virt-x86_64}}):
+  # insmod drivers/input/misc/uinput.ko
+After this, you can use the spice agent as described in [[How_to_run_Spice_Agent#Running_the_Spice_Agent|Running the Spice Agent]], except that the <code>modprobe uinput</code> is not necessary.
+Alternatively, you can "install" the module by copying it to {{Path|/lib/modules/`uname -r`/extra}} (which you'll most likely have to create first) and running <code>depmod</code> (as root).
+After this, you can load the module normally with <code>modprobe uinput</code>.
+This is necessary if you want to use the init script as described in [[#Running_with_init_script]].
+==Rebuild the kernel to include uinput==
+See [[Custom_Kernel]] for pointers on how to build a custom kernel. The option you'll need to change in the config is <code>CONFIG_INPUT_UINPUT</code>.
+[[Category:Virtualization]]