Extensions:Uni-Verse/Verse Reference Server

Introduction

This page describes the "reference server", which is a Verse server implementation developed in parallel with the Verse API, by the same developers. The reference server is supposed to be normative in behavior, although it is not always totally in synch with the specification.

Running the Server

The Verse server is a command-line program, without a graphical user interface. You simply start it, and it will immediately begin listening for incoming connections on a network socket. Here is how a typical invocation looks:

 $ verse

If you don't ask it to do otherwise, the Verse server will start listening for UDP packets on its default port. The port number currently used by Verse is 4950.

Note: This is not an official, registered, port number. While currently un-registered as far as we know, it is possible that it will get assigned to someone in the future, in case Verse will need to change.

You can use the following command line options to control the server's operation:

-h

Print a help text, that shows all supported options.

-ms

Enables master server communications to the default, built-in address. Use the -h option to learn what this address is. Please note that master server communication is disabled by default.

-ms:ip=IP[:PORT]

Sets a new address to use for master server communication. This also implies -ms, i.e. the server will try to register itself with the given master server. For details on the protocol used to do this, please see the spec.

-ms:de=DESC

Sets the description to use for this server, when registering with the the master server. This is only used if master server communication is actually enabled. The description is expected to be a human-readable string, like "A test server, run on a cable modem, and offline during local daytime" or something.

-ms:ta=TAGS

Sets the tags to use for this server, when registering with the the master server. This is only used if master server communication is actually enabled. The tags consists of a comma-separated list of single words. Each word must begin with a letter, and contain only letters, digits, or underscore characters. For instance: home,r6p1,linux,sweden,open.

-port=PORT

Use the indicated port number, rather than the default. Note that ports below 1024 are generally off-limits to ordinary users. Running Verse on such a port is not recommended.

-version

Prints the version string of the server to the terminal, and then exits (successfully). See below for information how the version string is constructed.

For example, here is how to start the server, register it with the default master server, and run on port number equal to 16333:

 $ server -ms -port=16333

Here is a more complicated example, that uses an explicit master server address, and also sets both the description and tags:

 $ server -ms:ip=master.example.net -ms:de="A test server, for the documentation" -ms:ta=example,docs

Options can occur in any order, with later options overriding earlier ones, in case of conflicts.

Release Labeling

Verse uses a simple two-level numbering scheme to identify releases. There is a "release number", and a "patch level" on each release. The intent is that within a release, the API does not change and neither should the network protocol. Between releases, we might improve the API which will require application programmers to update their code to stay in sync. We can do non-API-altering changes within a release by increasing the patch level, for bug fixing and other things.

The symbols V_RELEASE_NUMBER and V_RELEASE_PATCH are integer literals that hold the values for the API you have, and can be used (and displayed) in application source code as you see fit. There is also a string, V_RELEASE_LABEL, which is sometimes used.

To form a complete Verse version number, the above-mentioned symbols are to be combined like so: "r<V_RELEASE_NUMBER>p<V_RELEASE_PATCH><V_RELEASE_LABEL>". So, the following variable values:

• V_RELEASE_VERSION = 2
• V_RELEASE_PATCH = 51
• V_RELEASE_LABEL = "foo"

Would generate the version string "r2p51foo".