minecontrol - v1.6.1
--------------------------------------------------------------------------------
A. Overview

Minecontrol is an application that manages and extends Minecraft servers on
GNU/Linux systems. Minecontrol provides a server daemon that implements a simple
text-based protocol that allows for remote administration. The purpose of this
project was to provide a simple and automated way to administer Minecraft
servers on GNULinux systems, while allowing for wrapping of server commands and
providing a mechanism for extending server functionality.

Minecontrol provides a user-oriented approach to Minecraft server
management. This means servers are organized by the system user account that
creates servers. Every system user (with a valid UNIX login) may sign into the
Minecontrol server. Servers created by users are saved in the user's home
directory under "minecraft". When a server process is executed, its UID is set
to the respective user, and the user's local minecraft directory is added to the
authority search paths before system directories. Of course, only one Minecraft
server at a time can use a particular TCP/IP port; so users running simultaneous
servers must do so on different ports.

A user logs in to the minecontrol server using a Minecontrol client software
program. This repository contains a standard command-line interface client
implementation for GNU/Linux systems. Once connected to the server, the client
must then authenticate themselves using the system password of the desired
user. Minecontrol clients encrypt this field using the OpenSSL Crypto
library. Once logged in, a user can issue commands provided by the minecontrol
protocol to start, stop, list, and perform other operations on Minecraft server
processes.

The root user is allowed to administer any running Minecraft servers, and they
can shutdown the Minecontrol server as well remotely. Root users should not
create servers as it would run Minecraft (and any authority programs) as root;
this would be a bad practice.

Minecraft servers are identified by unique names that correspond to the
top-level directory in users' "minecraft" directories that contain the server
data files. When a server is created/restarted, the client may specify Minecraft
server properties. The Minecontrol server will overwrite the server.properties
file with changed properties (if any) each time a server process is
spawned. This is useful especially for changing the network service port to
which the server should bind or the message of the day.

Once a server is started, the Minecontrol server can time the process and send
the server the "stop" command when the time has expired. Optionally a server may
be set to unlimited time, in which case a client must manually stop the
server. Minecontrol always attempts to cleanly shutdown the Minecraft server by
sending it the "stop" command. If the server process is not responding after a
pre-configured timeout, a SIGKILL is sent to the process.  A client may also
extend the running time for a server via the EXTEND protocol command.

The Minecontrol server loads its own settings from the
/etc/minecontrold/minecontrol.init file. This file provides settings that the
Minecontrol server loads each time it starts a new Minecraft server. These
settings include options such as the Java JVM path, command-line profiles to
support multiple versions of Minecraft, the maximum allowed servers at a time,
default timeout for server processes, default server.properties settings to
apply or override, ETC. This file may be modified at any point while a
minecontrol server is running as the server reads the file each time it begins a
new Minecraft server process.

Finally, the Minecontrol server provides a feature for extending the
functionality of Minecraft worlds by wrapping the server console. This component
is called the Minecontrol Authority. See the section on the Minecontrol
Authority for more information.

--------------------------------------------------------------------------------
B. Building

Minecontrol was built for GNU/Linux systems. You will need a C++ compiler with
at least C++11 support to build this project. You will also need several
external library dependencies. The configure scripts will make sure the
dependencies are installed properly on your system. To generate the scripts, run
"autoreconf -i .".

Now you should be able to configure and build in the normal way:

    $ ./configure
    $ make

The following dependencies are required to build:

    OpenSSL
    ncurses
    rlibrary (see https://git.rserver.us/libs/rlibrary.git)

--------------------------------------------------------------------------------
C. Installation and usage

To install the software, run "make install" in the usual way. This will install
"minecontrol" to <PREFIX>/bin and "minecontrold" to <PREFIX>/sbin.

When running "minecontrold" (i.e. the server program), you must run it as root
so that it can verify user passwords. By default, the server will attempt to
become a daemon (i.e. detach itself into a new session in the background.) To
prevent this behavior (e.g. for testing or when running in a container), pass
the --no-daemon flag.

The server will attempt to load the /etc/minecontrold/minecontrol.init file
unless the software was built with MINECONTROL_TEST in which case the current
directory is searched for minecontrol.init.

A server listens on a local domain socket as well as a TCP/IP socket. Use the
"minecontrol" client program to connect. Without arguments, it attempts to
connect locally via the UNIX domain socket.

--------------------------------------------------------------------------------
D. The Minecontrol Authority

Minecontrol provides a component for extending the functionality of Minecraft
servers called the Minecontrol Authority. The Authority is a wrapper for the
Minecraft server console. It allows you to script commands that can process
input from the server logs. This process takes advantage of the fact that a
Minecraft server process logs messages not just to disk but to its standard
output.

Here's how the authority works: Minecontrol creates a pipe for the Minecraft
server's stdout. The Authority reads the log messages, parses them and
simplifies them to a common format. Then the Authority issues a copy
(authoritatively) to a set of satellite processes called "authority
programs". Each running authority program shares a connection to the Minecraft
server's stdin, and it can use this pipe to write commands to the server
console.

    -------------
    | Minecraft | -> "[17:28:53] [Server thread/INFO]: <DatFrogKing> Hello, World!"
    -------------                          |
          ^                                |
          |                                V
     "kill DatFrogKing"
          |                         ---------------
          |                         | Minecontrol |
          |                         ---------------
     "say Hi, DatFrogKing"                 |
          |                                |
          |                                | 
          |                  "chat DatFrogKing Hello, World!"
          |                      |         |            |
          |                      |         |            |
          |                      |         |            |
          |                      V         V            V
          |                    ------   ------        ------
          ^<-------------------| p1 |---| p2 |--------| p3 |
                               ------   ------        ------

A Minecontrol client can execute any number of authority programs using the
protocol. Since all programs share the same output device (i.e. a pipe), they
must perform commands using atomic write operations that do not exceed the
kernel buffer size for atomic pipe write operations.

You can write your own authority programs using the language of your
choice. Note that authority programs run in a constrained environment. The
search path for authority programs is "/usr/lib/minecontrol",
"/usr/local/lib/minecontrol" and "~/minecraft". Programs must be encapsulated
inside a single executable file. If your program requires an interpreter,
include a shebang on the first line. Note that the PATH is set to the authority
search paths: no standard system paths are available so use an absolute
invocation of the interpreter program. For example:

    #!/usr/local/my-custom-builds/python2.7.10/bin/python
    from sys import stdout
    stdout.write("say It works!\n")
    stdout.flush()

When an authority program is launched, its working directory is set to the
subdirectory of "~/minecraft" that contains the Minecraft server's data
files. Standard error is routed to an "errors" file used by Minecontrol for
logging. An authority program can create files in this space but should avoid
overwriting files used by the Minecraft server.

Several repositories exist that contain useful/fun authority programs:

    https://git.rserver.us/minecontrol/auth-progs
    https://git.rserver.us/minecontrol/journal

--------------------------------------------------------------------------------
E. Desiderata

Copyright 2014-2021 Roger Gee.  License GPLv3+: GNU GPL version 3 or later;
  consult <http://gnu.org/licenses/gpl.html>.
Minecontrol is free software: you are free to change and redistribute it.
There is NO WARRANTY and NO SUPPORT to the extent permitted by law.

I welcome bug reports to "Roger Gee" <rpg11a@acu.edu>.

Please respect the Minecraft EULA found here:
 https://account.mojang.com/documents/minecraft_eula