CollabVM Server 1.x/Getting Started

This page will help you get started with CollabVM Server v1.x.

If you have any problems or need support, please email [email protected] or go to the #support channel in the CollabVM Discord.

Requirements

It is recommended you have the following:

  • Operating system*:
  • A Linux-based distro that is updatable past the year 2014 by any means (even compiling).
  • A sizable amount of RAM free (>128MB, 2GB recommended)
  • Processor:
  • Can it run QEMU with (optional, if supported) acceleration?, x86-based processors recommended, as most VMs you'd probably want to host are x86-based (x86_64/amd64 applies).
  • Networking (If wanting to host publically):
  • Configurable networking system that allows ports to be opened. In general, you want at least >10mbps upload, Guacamole/WebSockets+HTTP+VNC is one heavy protocol.
  • If you have less than 100~ MBPS of upload speed, it is highly recommended to use a JPEG version of collab-vm-server 1.x.
  • Disk Space: 40~MB for collab-vm-server, you'll probably want MUCH more if you actually want to host some VMs though (>4GB).
  • QEMU: Version 0.10 is apparently supported, I haven't tried it myself, but 2.10?/3.x/latest work as well, of course, later QEMU versions can take it's own toll on performance, so choose what you need.
  • The QEMU version needs to be command-line based (No GUI-based QEMUs I've seen have replicated QEMU's argument set), and has the features:
  • VNC (for connecting to the VMs for display), QMP (for resets and other required interactions between collab-vm-server and the QEMU process(es).)
  • Minimum (release, excluding RC's) version for QEMU on Windows is 2.6.0.

*Preferably with KVM support, or is bootable, can also be Windows if absolutely needed.

Preparing

Downloading

The first step is to download collab-vm-server.

You can either compile it yourself, or use the already premade binaries. If you need instructions on how to compile collab-vm-server, refer to this for further instruction, but for now, we will focus on downloading the server instead.

The premade binaries are available on this page. These comes in binaries for Linux for 64-bit systems, and older versions also have support for 32-bit. Various users have confirmed that it does run on other architectures, but this isn't officially supported. It also comes with a Windows binary, and there have also been reports that it runs on Mac OS X.

Make sure to download the latest version, which is 1.2.11 right now. Older versions except 1.2.10 are not supported and will not be given security updates or technical support.

Installing

Once the server has been downloaded (Assuming you may have downloaded the pre-compiled version), you may need to download a few dependencies on Linux. On Windows it should come with all the DLLs that you need.

If you are running a version below 1.2.8, and you are on a modern version of Ubuntu/Debian (i.e. Debian 10, Ubuntu 20.04), you will need to make a symbolic link to libvncclient like this:

  • 64-bit: sudo ln -s /usr/lib/x86_64-linux-gnu/libvncclient.so.1 /usr/lib/x86_64-linux-gnu/libvncclient.so.0
  • 32-bit: sudo ln -s /usr/lib/i386-linux-gnu/libvncclient.so.1 /usr/lib/i386-linux-gnu/libvncclient.so.0
  • ARM: sudo ln -s /usr/lib/arm-linux-gnueabihf/libvncclient.so.1 /usr/lib/arm-linux-gnueabihf/libvncclient.so.0

Remember, the above ONLY applies if you are using a collab-vm-server executable that is BELOW 1.2.8.

Webapp

The next thing to do is to grab the CollabVM Web App. You can grab it here.

Keep in mind, that you do not necessarily have to get the webapp, you only need it so people (and you) have an accessible way of accessing your VMs, otherwise you can simply use someone else's webapp to connect to your own server. The server will function perfectly fine without the webapp.

But if you do need/want the webapp for whatever reason, you can follow all instructions on the page to build the Web App (it's very simple).

NOTE: The above requires Node.JS, so if you don't want to use it, you may want to avoid this step!

Running

Once that's done, its time to start the server, on both Windows and Linux, the process is like this:

./collab-vm-server 6004

You can swap out "6004" with any port you want. It does not have to be a specific port, however, on most operating systems (mostly unix-compactible) root/superuser is required for ports below 1024.


Final Touches

Once it has ran, the first thing you should immediately do is open your browser and head to /admin/config.html (Default has index.html in /admin broken) - e.g. localhost:6004/admin/config.html, and type in the password "collabvm". THIS SHOULD PROBABLY BE CHANGED IMMEDIATELY!! Unless you have the server isolated to just localhost (yourself), this will leave your server VULNERABLE (CollabVM allows running arbitrary commands, for starting VMs). Changing the password is simple - open the admin panel, click the checkbox under "Change Password", type in a secure password and hit "Change Password".

Next, it's time to configure your VMs. To see all the options you can utilize, click here.

Note that CollabVM Server 1.x only supports QEMU, and does not support VirtualBox or VMWare without using a very bad hack.

RapidJSON Bugfix

Windows bug: Due to an unescaped parsing problem with RapidJSON, Windows (or anyone that wants to use a \ or " in their VM arguments) users must use double backslashes like this when using a Start Command, or they will get an error:

C:\\Program Files\\qemu\\qemu-system-x86_64.exe

If you don't have QEMU, please see this page to learn how to install it.

Fin!

Once you've configured everything, hit "Save VM" and start it. If everything was configured correctly, everything should start up and you should be connected automatically. If there's an error, check the terminal CollabVM Server is running on for any errors.