Bureaucrats, Check users, Interface administrators, Push subscription managers, Suppressors, Administrators
415
edits
CollabVM 1.2 Protocol Reference: Difference between revisions
no edit summary
No edit summary |
No edit summary |
||
| (16 intermediate revisions by the same user not shown) | |||
|
Assigned usernames are, by convention, <code>guest</code> followed by five random digits. However, the server may use whatever format it pleases.
==
All messages on the CollabVM protocol are UTF-8 string arrays encoded in Guacamole Format, detailed in the Design section of the [https://guacamole.apache.org/doc/0.9.5/gug/guacamole-protocol.html Guacamole 0.9.5 Manual, Chapter 9]. Servers '''SHOULD''' drop the connection if the client sends a message not conforming to this.
Every message consists of an "opcode" at position zero, followed by zero to unlimited parameters.
== nop ==
<tr><td>Parameter 3</td><td>A Base64-encoded thumbnail for the VM. Will be either PNG or JPEG depending on the server implementation. This can be determined through magic numbers.</td></tr>
</table>
=== Request a username ===
Before connecting, the client must now obtain a username.
==== Request ====
<table class="wikitable">
<tr><td>Opcode</td><td><code>rename</code></td></tr>
<tr><td>Parameter 1</td><td><b>(OPTIONAL)</b> The username requested by the client. May be omitted if the client has no preference. The server is under no obligation to respect this and may provide a guest username for a multitude of reasons</td></tr>
</table>
==== Response ====
The server will respond with a [[#Client Renamed|Client Renamed]] event, however with one key difference: The status will always be <code>0</code> (success), even if the requested username was not available for whatever reason. In this case, a guest username is assigned.
=== Connect to a VM ===
Possible statuses:
<table class="wikitable">
<tr><th>Value</th><th>Status</th></tr>
</td></tr>
<tr><td>1</td><td>The connection was successful and the client is now connected to the VM.</td></tr>
</table>
After successfully connecting to a VM, the client will begin to recieve messages as normal, and may send messages.
</table>
===
Sent to announce the screen size of the VM. This will be sent after connecting and after any resolution change on the VM.
<table class="wikitable">
<tr><td>Opcode</td><td><code>size</code></td></tr>
<tr><td>Parameter 1</td><td><code>0</code></td></tr>
<tr><td>Parameter 2</td><td>Screen width</td></tr>
<tr><td>Parameter 3</td><td>Screen height</td></tr>
</table>
=== Framebuffer Update ===
Sent to update the VM screen. The server will send one initial message containing the entire screen on connection, and after that will send a dirty rect for each update
<table class="wikitable">
<tr><td>Opcode</td><td><code>png</code></td></tr>
<tr><td>Parameter 1</td><td><code>0</code></td></tr>
<tr><td>Parameter 2</td><td><code>0</code></td></tr>
<tr><td>Parameter 3</td><td>X-axis position of the rectangle</td></tr>
<tr><td>Parameter 4</td><td>Y-axis position of the rectangle</td></tr>
<tr><td>Parameter 5</td><td>The base64-encoded rectangle. Despite the name of the opcode, this may be either PNG or JPEG and can be determined through magic numbers or headers.</td></tr>
</table>
Sent when a Vote-for-reset on the VM updates
<table class="wikitable">
<tr><td>Opcode</td><td><code>vote</code></td></tr>
<tr><td>Parameter 1</td><td>The status of the vote. See below for values</td></tr>
<tr><td>Parameter 2</td><td>Amount of time left on the vote in milliseconds. If the above status was 3 (cooldown), this is the amount of time before the client can start a vote.</td></tr>
<tr><td>Parameter 3</td><td>The number of users who have voted in favor of resetting the VM</td></tr>
<tr><td>Parameter 4</td><td>The number of users who have voted against resetting the VM</td></tr>
</table>
Possible vote statuses:
<table class="wikitable">
<tr><th>Value</th><th>Status</th></tr>
<tr><td>0</td><td>The vote has started. The yes and no parameters may not be specified, and in such case should be assumed to be zero.</td></tr>
<tr><td>1</td><td>The vote count has updated.</td></tr>
<tr><td>2</td><td>The vote has ended. No other parameters will be given.</td></tr>
<tr><td>3</td><td>Sent if the client tried to start a vote, however there is an active cooldown. Only the time parameter is given.</td></tr>
</table>
=== Turn queue update ===
Indicates an update of the VM's turn queue
<table class="wikitable">
<tr><td>Opcode</td><td><code>turn</code></td></tr>
<tr><td>Parameter 1</td><td>How much time is left on the current user's turn in milliseconds.</td></tr>
<tr><td>Parameter 2</td><td>The amount of users in the queue.</td></tr>
<tr><td>Parameter 3-?</td><td>Each username in the queue given as separate parameters</td></tr>
<tr><td>End parameter</td><td>How much longer until the client will get a turn in milliseconds. Only sent if the client is waiting.</td></tr>
</table>
== Client-to-Server Opcodes ==
These opcodes may be sent by the client at any time after the handshake to perform various actions
=== Account Login ===
Used to log in with a CollabVM account. This should only be sent if the server announced authentication using the <code>auth</code> opcode during the handshake phase. Sending this opcode otherwise is undefined behavior.
==== Request ====
<table class="wikitable">
<tr><td>Opcode</td><td><code>login</code></td></tr>
<tr><td>Parameter 1</td><td>A session token OR bot token obtained from the authentication server announced during handshake.</td></tr>
</table>
==== Response ====
<table class="wikitable">
<tr><td>Opcode</td><td><code>login</code></td></tr>
<tr><td>Parameter 1</td><td>Login status. <code>0</code> for error, <code>1</code> for success.</td></tr>
<tr><td>Parameter 2</td><td>Human-readable error. Only sent if status was <code>0</code></td></tr>
</table>
After a successful login, the client should expect to be renamed and have their rank updated by the server.
=== Rename ===
Used to change the client's username. This opcode is not available on servers that use account authentication, and the server will respond with an error.
==== Request ====
<table class="wikitable">
<tr><td>Opcode</td><td><code>rename</code></td></tr>
<tr><td>Parameter 1</td><td>The username requested by the client. If omitted, the server will reassign a guest username.</td></tr>
</table>
==== Response ====
The server will respond with a [[#Client Renamed|Client Renamed]] event.
=== Send Chat ===
Send a public chat message to the server.
<table class="wikitable">
<tr><td>Opcode</td><td><code>chat</code></td></tr>
<tr><td>Parameter 1</td><td>Chat message to send</td></tr>
</table>
=== Take turn ===
Request a turn on the VM.
<table class="wikitable">
<tr><td>Opcode</td><td><code>turn</code></td></tr>
<tr><td>Parameter 1</td><td><code>1</code> to take a turn, <code>0</code> to cancel your turn. If not specified, the server will infer <code>1</code>.</td></tr>
</table>
=== Mouse Instruction ===
Send a mouse update to the VM. Only effective if the client has the turn or is an Admin. This opcode has no response.
<table class="wikitable">
<tr><td>Opcode</td><td><code>mouse</code></td></tr>
<tr><td>Parameter 1</td><td>X position of the mouse pointer on the VM screen</td></tr>
<tr><td>Parameter 2</td><td>Y position of the mouse pointer on the VM screen</td></tr>
<tr><td>Parameter 3</td><td>Bitmask of mouse buttons being held. See [https://github.com/rfbproto/rfbproto/blob/master/rfbproto.rst#pointerevent Remote Framebuffer Protocol§PointerEvent]</td></tr>
</table>
=== Keyboard Instruction ===
Send a keyboard update to the VM. Only effective if the client has the turn or is an Admin. This opcode has no response.
<table class="wikitable">
<tr><td>Opcode</td><td><code>key</code></td></tr>
<tr><td>Parameter 1</td><td>Key symbol for the key being pressed as a base-10 integer. See [https://cgit.freedesktop.org/xorg/proto/x11proto/tree/keysymdef.h keysymdef.h] for a list (values are in hex and must be converted to base 10)</td></tr>
<tr><td>Parameter 2</td><td><code>1</code> to press the key, <code>0</code> to release.</td></tr>
</table>
=== Vote-for-reset ===
Vote for or against resetting the VM to snapshot.
<table class="wikitable">
<tr><td>Opcode</td><td><code>vote</code></td></tr>
<tr><td>Parameter 1</td><td><code>1</code> to vote in favor of a reset, <code>0</code> to vote against a reset. If there is no active vote, <code>1</code> is used to start one, while <code>0</code> has no effect.</td></tr>
</table>
== Admin Opcodes ==
These opcodes may be sent to perform administration actions on the VM.
=== Staff Login ===
Used to log in as an Admin or Moderator on the VM using a staff password. This opcode is disabled if the VM uses Account Authentication, in which case the [[#Account Login|Account Login]] opcode should be used instead.
==== Request ====
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>2</code></td></tr>
<tr><td>Parameter 2</td><td>The staff password</td></tr>
</table>
==== Response ====
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>0</code></td></tr>
<tr><td>Parameter 2</td><td>Status of the login. See below for possible values.</td></tr>
<tr><td>Parameter 3</td><td>[[#Permissions|Permissions]] integer defining available moderation actions. Only sent if status is <code>3</code></td></tr>
</table>
Status can be one of the following:
<table class="wikitable">
<tr><th>Value</th><th>Status</th></tr>
<tr><td>0</td><td>
<tr><td>1</td><td>
<tr><td>
</table>
After successfully logging in, the server will also send a new [[#New User(s)|New User]] event to announce your rank change.
=== QEMU Monitor ===
Used to send a [https://qemu-project.gitlab.io/qemu/system/monitor.html QEMU Monitor] command to the VM. Only Admins may use this opcode.
====
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>5</code></td></tr>
<tr><td>Parameter 2</td><td>Command to send to QEMU</td></tr>
</table>
====
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>2</code></td></tr>
<tr><td>Parameter 2</td><td>Response from QEMU</td></tr>
</table>
=== Restore VM ===
Restore the VM to snapshot without a vote.
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>8</code></td></tr>
</table>
===
Reboot the VM.
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>10</code></td></tr>
</table>
===
Ban a user. The actual backend behavior here is dependent on server implementation. Usually this runs a command set in configuration.
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>12</code></td></tr>
<tr><td>Parameter 2</td><td>Username to ban</td></tr>
</table>
=== Force vote ===
Forcibly end a vote-for-reset with the specified outcome
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>13</code></td></tr>
<tr><td>Parameter 2</td><td><code>1</code> to pass the vote and reset the VM, <code>0</code> to fail the vote</td></tr>
</table>.
=== Mute ===
Mute a user
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>14</code></td></tr>
<tr><td>Parameter 2</td><td>Username to mute</td></tr>
<tr><td>Parameter 3</td><td><code>0</code> for temporary mute, <code>1</code> for permanent. Temporary mute duration is left up to the server and is usually configurable.</td></tr>
</table>
=== Kick ===
Disconnect a user from the VM.
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>15</code></td></tr>
<tr><td>Parameter 2</td><td>Username to kick</td></tr>
</table>
=== End turn ===
End a user's turn, or forfeit their spot in the queue.
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>16</code></td></tr>
<tr><td>Parameter 2</td><td>Username to end turn</td></tr>
</table>
=== Clear turn queue ===
Clear the turn queue
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>17</code></td></tr>
<tr><td>Parameter 2</td><td>VM Node ID to clear the turn queue of</td></tr>
</table>
=== Rename user ===
Change another user's name.
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>18</code></td></tr>
<tr><td>Parameter 2</td><td>User to rename</td></tr>
<tr><td>Parameter 3</td><td>New username</td></tr>
</table>
=== Grab IP ===
Grab a user's IP Address
==== Request ====
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>19</code></td></tr>
<tr><td>Parameter 2</td><td>User to IP grab</td></tr>
</table>
==== Response ====
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>19</code></td></tr>
<tr><td>Parameter 2</td><td>User whose IP was grabbed</td></tr>
<tr><td>Parameter 3</td><td>The requested IP address</td></tr>
</table>
=== Bypass turn queue ===
Jump directly in front of the queue and take the turn.
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>20</code></td></tr>
</table>
=== Send raw message ===
Send a raw (XSS) message to the chat, bypassing HTML sanitization and character limits. When a moderator sends a raw message, admins will still receive a sanitized version for security reasons.
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>21</code></td></tr>
<tr><td>Parameter 2</td><td>Raw message to send</td></tr>
</table>
=== Toggle turns ===
Prevent or allow non-staff to take turns on the VM
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>22</code></td></tr>
<tr><td>Parameter 2</td><td><code>1</code> to enable turns, <code>0</code> to disable them.</td></tr>
</table>
=== Indefinite turn ===
Jump directly to the front of the turn queue and take a turn that does not end until you disconnect or end it manually.
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>23</code></td></tr>
</table>
=== Hide screen ===
Hide or show the VM screen from non-staff.
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>24</code></td></tr>
<tr><td>Parameter 2</td><td><code>1</code> to show the screen, <code>0</code> to hide it.</td></tr>
</table>
=== Send system message ===
Send a raw (XSS) message as a system message from the server.
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>25</code></td></tr>
<tr><td>Parameter 2</td><td>System message to send</td></tr>
</table>
= Rank =
CollabVM has four ranks:
<tr><td>2</td><td>Admin</td><td>Has all permissions on the VM.</td></tr>
<tr><td>3</td><td>Moderator</td><td>Permissions vary depending on server configuration. Even with all permissions granted moderators can still not use the QEMU monitor.</td></tr>
</table>
= Permissions =
When logging in as a Moderator, permissions are defined by a bitmask that can contain the following values:
<table class="wikitable">
<tr><th>Value</th><th>Description</th></tr>
<tr><td>1</td><td>Reset the VM back to it's initial state.</td></tr>
<tr><td>2</td><td>Reboot the VM</td></tr>
<tr><td>4</td><td>Ban a user from your VM</td></tr>
<tr><td>8</td><td>Forcibly pass or cancel a vote to reset</td></tr>
<tr><td>16</td><td>Mute a user, preventing them from chatting or taking turns</td></tr>
<tr><td>32</td><td>Kick a user from the VM</td></tr>
<tr><td>64</td><td>Jump to the front of the turn queue, as well as clear the turn queue and end individual turns</td></tr>
<tr><td>128</td><td>Rename another user</td></tr>
<tr><td>256</td><td>Get the IP address of another user</td></tr>
<tr><td>512</td><td>Send 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.</td></tr>
</table>
| |||