-
Notifications
You must be signed in to change notification settings - Fork 0
Setup Guide
This document outlines how to configure VotifierPlugin for a variety of different configurations. It should be used by server administrators looking to set up VotifierPlugin on their network.
This document uses the terms token and key. These are two separate terms,
and it is important to understand the differences.
Keys in terms of VotifierPlugin refer to the old Votifier style RSA keys. They
are typically distributed as a pair of files - a public and private key. When
dealing with RSA keys, you can share your public key with server lists, but make
sure to keep your private key safe with you. You can find these keys
auto-generated under plugins/(Nu)Votifier/rsa/, where your public key is
named public.key, while your private key is labeled private.key. Make sure
not to separate the two, as they only work together as a pair.
Tokens in terms of VotifierPlugin refer to a new short string of characters. This string of characters is secret, and should never be exposed to anyone but you or server lists which support VotifierPlugin voting (check with the server list first). Tokens are most commonly used internally within a network for use when using the proxy vote forwarding method.
These instructions apply to users setting up a single server to accept votes from a server list. In most cases, these are the steps you want to follow.
To install VotifierPlugin, you should get a copy from one of the following locations:
- Github - Official release location
The VotifierPlugin jar should then be placed within the plugins/ folder of your
Minecraft server. When you then start your server, VotifierPlugin will generate
the necessary configuration and initial keys for you.
By default, VotifierPlugin generates a configuration that is already suitable for a single-server configuration. However, you may need to change the port VotifierPlugin listens on, if you use a shared host or run multiple servers on the same machine.
You can then add your server to server lists using the port you configured while also supplying your public key. At this point, you should be able to send a test vote to your server!
Once you've verified VotifierPlugin can accept votes from your server lists, you'll need to set up a vote listener. See the next section for more details.
The port must be between 1 and 65535 and not in use by any other service,
including the port of the server VotifierPlugin will be running on. For example,
if Minecraft is running on the default port (25565), you cannot set port also
to 25565.
Depending on your host and if you have a dedicated IP, you might have to change
the ip value. Usually, the default of 0.0.0.0 works.
Once you've installed and configured VotifierPlugin, you'll need to install a vote listener. VotifierPlugin does not include any listeners by default - this is left up to plugins to do. We've included a partial list of listeners for Bukkit-based servers and Sponge.
Here is a partial list of well-known vote listeners for Bukkit servers (Spigot, Paper, ...):
- SuperbVote
- Enjin
- VotingPlugin
- UltimateVotes (paid)
- VoteParty (paid)
If none of these suit you, there are plenty of listeners you can search for.
A well-known choice is SeriousVote, check Sponge ore's website for alternatives.
If you have more than one server and are using a Minecraft proxy (such as BungeeCord or Velocity), you'll need to follow these instructions.
When running a single-proxy network, VotifierPlugin acts as a both a vote receiver (from voting websites) as well as a vote forwarder (emitting events for proxy based vote listeners). VotifierPlugin's vote forwarding logic is advanced enough to be used in a wide variety of ways.
VotifierPlugin should be installed on each of the servers you wish to process votes on, as well as the proxy server. The proxy's VotifierPlugin server will act as the public facing Votifier instance, where as the Minecraft servers will instead receive votes forwarded from the proxy's VotifierPlugin.
Like the single server installation, you can download VotifierPlugin at any one of the following locations:
- Github - Official release location
The same JAR works for both proxies and servers.
Likewise, you'll also want a vote listener on each server - check the section for single-server setups for some well-known choices.
The plugin should then be placed in the plugins/ directory of the proxy server
as well as each of the Minecraft servers.
In the next sections, we'll discuss the two forms of vote forwarding supported by VotifierPlugin: plugin messaging based forwarding and proxy forwarding. You should pay very close attention to these two sections as they contain crucial information for configuring forwarding.
If you have just one proxy, plugin messaging-based vote forwarding is the easiest way to set up vote forwarding. With some exceptions, plugin messaging-based vote forwarding can work in multi-proxy networks.
Before you continue, make sure your backend servers can only be accessed by your proxy (no direct connections!) or a malicious attacker could spam your server with votes. VotifierPlugin protects this channel but only if every connection goes through your proxy.
Now you can configure each of the Minecraft servers to accept votes from the plugin
messaging channel. Open each of the servers' VotifierPlugin configurations. Each one
should have method under the forwarding configuration section set to pluginMessaging.
Since we are receiving forwarded votes through plugin messaging and not through network
ports, we should set port on each of the Minecraft servers to -1. This will disable
VotifierPlugin's port, while still allowing it to receive forwarded plugin messaging votes.
Now with the server configuration completed, we will configure the proxy. Open the proxy's
VotifierPlugin plugin (found under the plugins/VotifierPlugin/ directory, called config.yml for
BungeeCord, and config.toml for Velocity). Then apply the following changes:
- Set
portshould be to an unbound port. The default8192works well, however you may have to change it depending on your hosting provider. - Set
methodunderforwardingtopluginMessaging.
This sets up a basic default setup that forwards all votes sent to the proxy to each Minecraft server connected to the proxy (all servers you can get to when typing /server). You may want to change this, but if the default configuration is acceptable you may skip the next section.
By default, VotifierPlugin forwards all votes sent to the proxy to each Minecraft server
connected to the proxy. You can manually exclude some of these servers by first
uncommenting excludedServers, then adding the server's name to the excludedServers
list. VotifierPlugin will not send votes to any server on this list. Likewise, if
you only send the vote to the server the player joined, these servers are ignored.
VotifierPlugin can also selectively send the vote to only the server which the player has
joined. This option can be turned on by setting onlySendToJoinedServer to true. When
this option is on, the vote will attempt to go to the server which the player is currently
on. If the player is offline, then VotifierPlugin will then attempt to send the vote to
the joinedServerFallback. If the vote cannot be sent to the joinedServerFallback,
then the vote is saved in the cache until the vote can be sent to the joinedServerFallback
server - note this will not send it to the next server the player joins! If you do not want
a fallback server and would rather the vote be applied when the player next joins, set
joinedServerFallback to ''. This will cause VotifierPlugin to save the vote until the player
joins again.
By default, votes are saved for 10 days in the cache. This time can be increased
or decreased by changing the cacheTime field. This number can be as high or low
as you want. It is measured in days within the cache. This is valid for both the
file and memory cache.
In more complex network situations, it may be required to instead use the proxy based vote forwarding. This configuration is less flexible and more difficult to set up properly - most people should use plugin messaging based forwarding. Proxy based forwarding does not support vote caching or advanced forwarding configurations. If you cannot use plugin messaging forwarding, then the following section will describe how to set up proxy based vote forwarding. If you still require advanced forwarding features or more advanced behaviors, it may be worthwhile to write your own plugin to perform the proper forwarding logic (you will know if you need to do this).
In proxy based vote forwarding, one of your proxy servers acts as the head vote receiver. This server will be the one you configure the voting websites to vote to. You can set up multiple vote receivers and load balance between them, however this configuration has limited benefit and is probably more work than it is worth. Instead of communicating through plugin messaging like the plugin messaging forwarding strategy, proxy forwarding instead acts like a voting website to each of the backend servers and duplicates the vote it receives to each of the backend servers it is configured with.
First, we will set up all of the Minecraft servers before setting up the head
vote receiver. For each of the servers, VotifierPlugin should be configured to bind
to an unused port. This port must be valid. If you have multiple Votifiers on
the same IP/server, make sure that the port which you are using between
VotifierPlugin instances are different. Remember the port number as we will need
it later to insert into the proxy VotifierPlugin configuration. In addition to the
port number, you will also need the default token - this is the string auto
generated by VotifierPlugin under the default key under tokens. Since we are using
proxy forwarding, change disable-v1-protocol to true - we will only be using the
new VotifierPlugin protocol within our network (vote receiver -> minecraft server).
Once all configured, that is all we need to do. The rest of the defaults will work.
Now we will configure the vote receiving VotifierPlugin proxy server. The port
should be configured as described many times above, being a unique port. Instead
of setting method to pluginMessaging like above, we will set method to
proxy. This will tell VotifierPlugin that we instead want to proxy the votes
instead of forward them through plugin messaging channels.
The last step is to set up the proxy forwaring settings. Under the proxy
section is a place to enter each server. Create a unique name for each of the
server's you will be forwarding votes to. The default proxy VotifierPlugin
configuration already has two Minecraft servers filled in - Hub and Hub2. You
should replace these with your own servers - the names of the servers do not
matter. Under each of these servers, we need to configure address, port, and
token. address is the IP address of the Bukkit/Sponge server. This may be
localhost or 127.0.0.1 if the Minecraft server is on the same physical
server as the vote receiving VotifierPlugin server. port is the port of the
Bukkit/Sponge VotifierPlugin server. token is the default token of the
Bukkit/Sponge VotifierPlugin server. This can be found within its configuration,
usually under the token section. Once the servers are configured, VotifierPlugin
will forward all votes it receives to the servers configured under the proxy
section.
If you find you don't know what is wrong, remember to check the console logs in each of the
server's running VotifierPlugin.
For very large/busy servers, there's an hidden configuration to "quiet" those debug logs.
For Bukkit and Sponge, you may reload VotifierPlugin through the /nvreload command
in your server console only - this command will not work in-game by design. Make sure to
ensure that it completed correctly before assuming VotifierPlugin works!
For Bungee and Velocity, the command is /pnvreload.
For Bukkit and Sponge, you may simulate a vote through the /testvote command.
For Bungee and Velocity, the command is /ptestvote.
If you find you have messed up VotifierPlugin beyond repair, you can grab a default configuration from the following locations (depending on the server it is installed on):
You can also regenerate this configuration by deleting the old configuration and restarting the server.