zeuz Multiplayer Operations documentation

Welcome to the zeuz Multiplayer Operations documentation. Here, you'll find the zuez User Manual and API reference. You can also check out the Helpdesk and Knowledge Base.

User Manual    API Reference

Relay Server

zeuzrelay provides an UDP relay server to connect multiple game clients behind restrictive NATs. It can be found in the bin_* folders in the Omnibus package.

There are three modes of operation

  1. free mode
  2. client-authorized
  3. control-authorized

1. free mode

In free mode anyone sending UDP packets to an open port of the relay will be accepted as client until clientsmax is reached. All incoming UDP packets are relayed to all clients on the same port. This is the default mode.

Example

zeuzrelay -portmin=20000 -portmax=29999 -clientsmax=8

This opens 10.000 ports beginning at port 20000. On each port 8 clients can connect.

2. client-authorized

In client-authorized mode clients will only be accepted, if they send a packet prefixed with the clienttoken. The clienttoken is stripped from the UDP packet and the remainder (if any) is being relayed. Clients are allowed to prefix all packets with the clienttoken but only one is needed. The client can verify a working relay and its authorization status by sending a pingtoken, this will not be relayed to any other client but returned to the sender.

The optimal connection start would be sending: clienttoken+pingtoken+some_message, the relay will answer with some_message, if the client is allowed to connect.

Example

zeuzrelay -portsingle=8081 -clienttoken=v8aQhj4n02jvW -pingtoken=_ping_

A single port is opened, clients can connect prefixing their packets with v8aQhj4n02jvW and can receive a ping by prefixing with _ping

3. control-authorized

In control-authorized mode a third party is authorizing clients by talking to the relay on the same port as a client. The controller needs to prefix its control message with controltoken followed by one or more command.

Commands

Command

Description

x

resets the port

a

followed by a zero terminated sequence denominating a client-token, adding a new client

r

followed by a zero terminated sequence denominating a client-token, removing a client

The relay will answer with ok or err if clientsmax is exceeded or a command is unknown. A client can connect here exactly like in client-authorized mode, only it has its own token instead of a shared one.

Example

zeuzrelay -portsingle=8081 -controltoken=v8aQhj4n02jvW

A single port is opened, controllers can authorize clients by using v8aQhj4n02jvW and clients can connect prefixing their packets with a server provided client-token.

Addressing mode

Clients prefix their packet with a single byte address as client index to send to. The relay prefixes every packet with the source address. (except ping-pong). Index 0 is broadcast, 1 is the first client and so on.

Channeling mode

Each port is subdivided in arbitrary channels, after sending a clienttoken a channeltoken of 8 bytes must follow. Using a random channeltoken per game allows allocation-less usage of the relay.

Server-Client mode

Instead of peer to peer a server-client mode is available, the server identifies itself with the servertoken and always gets the first address index.

Command line parameters

Parameter

Description

portmin

low port number of port range to open (default: 20000)

portmax

high port number of port range to open (default: 60000)

portsingle

open just a single port

porttimeout

timeout to drop all clients from one port (default: 120 seconds)

clientsmax

maximum allowed clients per port (default: 32)

controltoken

token for control-authorized mode

clienttoken

token for client-authorized mode

servertoken

token for server-client mode

pingtoken

packet will not be relayed, but returned to sender

addressing

prefix packets with index address

channeling

subdivide ports into channels

clienttimeout

Client automatically disconnects, if it has not send any token in this duration (default: 60 seconds)

Updated 6 months ago


Relay Server


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.