UserVM Handbook

Revision as of 00:19, 14 February 2023 by Elijah (talk | contribs)

Welcome to the official guide on setting up a UserVM.

Prerequisites

You'll need:

  • A machine with decent specs (8GB of RAM and a modern CPU, probably)
  • A Linux distribution; You can pick any mainstream distro, for the purposes of this guide I recommend either Debian/Devuan or Arch/Artix. I recommend the OpenRC versions (Devuan/Artix) but that's just preference, pick what you're comfortable with. Yes, Ubuntu will work, it's terrible though
  • Basic knowledge of how computers and Linux systems work. We aren't going to hold your hand, you need to be comfortable with a command line
  • A few hours

Compiling the server

Install Git

First up make sure you have git installed:

sudo pacman -S --needed git # Arch
sudo apt install git # Debian

Prepare the server

Now let's clone the source. This is assuming you're in your home directory but you can clone it wherever

git clone https://github.com/computernewb/collabvm-1.2.ts.git
cd collabvm-1.2.ts

Next, we need to install Node.js, as well as the server dependencies. First, node:

sudo apt install npm nodejs # Debian
sudo pacman --needed -S npm nodejs # Arch

Then install dependencies

npm i

Finally, build the server

npm run build

Set up your VM

Now is a good time to get your VM set up. Currently, the only supported hypervisor is QEMU. We have many guides on this wiki for setting up different OSes in QEMU, check them out here. Here are some ideas to make your VM interesting:

  • A funny wallpaper
  • Development software (Visual Studio, etc.)
  • Some games
  • Some harmless malware (for the love of god no GDI rapists)

Configuration

Now we need to fill out the config file for your VM. Copy config.example.toml to config.toml, and open it in an editor.

SHA256 hash of your admin password. Can be generated with the command printf "<your admin password"> | sha256sum -. Make sure this is something hard to guess as anyone with this password could execute arbitrary commands on your server.
Config valueExplanation
hostHost IP for the server to bind to. 99% of the time this will be 127.0.0.1 on proxied instances and 0.0.0.0 on non-proxied (see below)
portPort for your server to bind to. This must be different for each VM you host, and cannot be the same as any other server running on your system (see the output of ss -tuln to see what ports are used)
proxyingIf your server will be behind a reverse proxy, usually Nginx. This isn't a requirement, however, we recommend you do so for things like SSL support, and minimizing the number of ports open on your server. This requires additional configuration of your web server. If you edit this, make sure to go back and update host accordingly
proxyAllowedIpsIPs allowed to reverse proxy your server. Can be ignored if you're not using proxying mode. 99% of the time, this will just be 127.0.0.1
qemuArgsCommand line to launch QEMU with. You'll have this from setting up your VM earlier. If you're not sure, check out the QEMU guides linked above
vncPortPort to be used internally for VNC. Must be at least 5900. You don't need to pay too much attention to this unless you're running multiple VMs (In which case just increment the port by 1 for each VM)
snapshotsWhether or not your VM should have vote resets, and reset to its initial state on server restart. If you disable this on a public VM, prepare for it to get trashed quickly.
qmpSockDirDirectory for QEMU to put its QMP socket for internal use. This can stay default unless you have a special reason to change it
nodeA unique ID for your VM. Your VM will be directly accessible at https://computernewb.com/collab-vm/user-vm/#>this id>. You should take care to name this something separate from any other VM on the UserVM roster, or your VM might be unaccessible
displaynameVM title that shows up in the list. Format with HTML
motdMessage of the day, displayed when someone joins your VM. Format with HTML
bancmdCommand to be run when you click the ban button. By default this adds a non-persistent iptables rule, but we recommend you change this
moderatorEnabledWhether or not the moderator rank is enabled, in addition to Admin.
usernameblacklistArray of usernames the server should not allow
maxChatLengthMax amount of characters a user can send in a chat message. Further characters will be truncated.
automuteWhether or not the server should automatically mute users who spam messages. You can also specify how many messages within how many seconds should trigger the mute.
tempMuteTimeHow long a temporary mute lasts
turnTimeHow long a turn lasts
voteTimeHow long a vote to reset lasts, before results are tallied
voteCooldownHow long before another reset vote can be started after one ends
adminpass
modpassSHA256 hash of your mod password. Generated same as admin. Does nothing if the moderator rank is not enabled.
moderatorPermissionsControls the individual actions a moderator can do. Each one is described below. Does nothing if the moderator rank is not enabled.
restoreReset the VM back to it's initial state.
rebootReboot the VM
banBan a user from your VM
forcevoteForcibly pass or cancel a vote to reset
muteMute a user, preventing them from chatting or taking turns
kickKick a user from the VM
bypassturnJump to the front of the turn queue, as well as clear the turn queue and end individual turns
renameRename another user
grabipGet the IP address of another user
xssSend a raw (not HTML-sanitized) chat message, allowing the execution of arbitrary scripts on another user's browser. Admins will not be affected by XSS messages sent by mods.