diff options
| -rw-r--r-- | debian/control | 4 | ||||
| -rw-r--r-- | man/meson.build | 48 | ||||
| -rw-r--r-- | man/minecctl.xml | 280 | ||||
| -rw-r--r-- | man/minecproxy.conf.xml | 209 | ||||
| -rw-r--r-- | meson.build | 1 |
5 files changed, 541 insertions, 1 deletions
diff --git a/debian/control b/debian/control index 6eb6e4d..c3739b6 100644 --- a/debian/control +++ b/debian/control @@ -3,12 +3,14 @@ Section: net Priority: optional Maintainer: David Härdeman <david@hardeman.nu> Build-Depends: debhelper-compat (= 12), + docbook-xsl, libcap-ng-dev, libedit-dev, libsystemd-dev, liburing-dev, meson, - pkg-config + pkg-config, + xsltproc Standards-Version: 4.5.0 Rules-Requires-Root: no Homepage: <insert the upstream URL, if relevant> diff --git a/man/meson.build b/man/meson.build new file mode 100644 index 0000000..88f34ef --- /dev/null +++ b/man/meson.build @@ -0,0 +1,48 @@ +# SPDX-License-Identifier: LGPL-2.1+ + +man_pages = [ + { + 'section': '1', + 'name': 'minecctl', + }, { + 'section': '5', + 'name': 'minecproxy.conf', + } +] + +xsltproc = find_program('xsltproc') + +xsl = 'http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl' +xsl_test = run_command(xsltproc, '--nonet', xsl) +if xsl_test.returncode() != 0 + error('The DocBook XSL stylesheet for "@0@" was not found.'.format(xsl)) +endif + +xsltproc_flags = [ + '--nonet', + '--stringparam', 'man.output.quietly', '1', + '--stringparam', 'funcsynopsis.style', 'ansi', + '--stringparam', 'man.authors.section.enabled', '0', + '--stringparam', 'man.copyright.section.enabled', '0', +] + +xslt_cmd = [xsltproc, xsltproc_flags, '-o', '@OUTPUT0@', xsl, '@INPUT@'] + +foreach man_page: man_pages + section = man_page['section'] + name = man_page['name'] + xml_input = name + '.xml' + man_output = name + '.' + section + + page = custom_target( + man_output, + input: xml_input, + output: man_output, + command: xslt_cmd, + build_by_default: true, + install: true, + install_dir: join_paths(get_option('mandir'), 'man' + section), + ) +endforeach + + diff --git a/man/minecctl.xml b/man/minecctl.xml new file mode 100644 index 0000000..c410d40 --- /dev/null +++ b/man/minecctl.xml @@ -0,0 +1,280 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!-- SPDX-License-Identifier: GPL-2.0 --> + +<refentry id="minecctl"> + + <refentryinfo> + <title>minecctl</title> + <productname>minecproxy</productname> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>David</firstname> + <surname>Härdeman</surname> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>minecctl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>minecctl</refname> + <refpurpose>Interact with Minecraft servers</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>minecctl</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="opt" rep="plain">COMMAND</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + <command>minecctl</command> may be used to communicate with, and + control, Minecraft servers. It can also be used to perform various + checks on <command>minecproxy</command> server configuration files. + </para> + <para> + Commands are usually performed on servers defined by corresponding + configuration files in the <command>minecproxy</command> configuration + directory, but server connection details can also be set manually + to control servers which have no configuration files (see options + <option>-p</option>, <option>-r</option> and <option>-m</option> below). + </para> + </refsect1> + + <refsect1> + <title>Commands</title> + <para>The following commands are understood:</para> + <variablelist> + + <varlistentry> + <term><command>list</command></term> + <listitem><para> + List all known servers (i.e. servers with configuration files). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>lint</command></term> + <listitem><para> + Check the validity of all known server configuration files. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>status</command> <optional>SERVER</optional></term> + <listitem><para> + Show the current status of <replaceable>SERVER</replaceable> + (or all known servers if <replaceable>SERVER</replaceable> + is not specified). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>ping</command> <optional>SERVER</optional></term> + <listitem><para> + Check if <replaceable>SERVER</replaceable> is running + (if <replaceable>SERVER</replaceable> is not specified, it must + be defined via command line options, see options <option>-r</option> + and <option>-m</option> below). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>stop</command> <optional>SERVER</optional></term> + <listitem><para> + Stop <replaceable>SERVER</replaceable> + (if <replaceable>SERVER</replaceable> is not specified, it must + be defined via command line options, see option <option>-r</option> + below). Note that servers with active players will not be + stopped unless forced (i.e. if option <option>-f</option> is used). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>stopall</command></term> + <listitem><para> + Similar to <command>stop</command> but stops <emphasis>all</emphasis> + known servers (including any server specified using the + <option>-r</option> option). Like <command>stop</command>, + servers with active players will not be stopped unless + option <option>-f</option> is used. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>pcount</command> <optional>SERVER</optional></term> + <listitem><para> + Get the current player count for <replaceable>SERVER</replaceable> + using either the <acronym>rcon</acronym> or + <application>minecraft</application> protocol + (if <replaceable>SERVER</replaceable> is not specified, it must + be defined via command line options, see options <option>-r</option> + and <option>-m</option> below). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>console</command> <optional>SERVER</optional></term> + <listitem><para> + Provides an interactive <acronym>rcon</acronym> command + line for <replaceable>SERVER</replaceable> + (if <replaceable>SERVER</replaceable> is not specified, it must + be defined via command line options, see option <option>-r</option> + below). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>cmd</command> <optional>SERVER</optional> <replaceable>CMD</replaceable></term> + <listitem><para> + Send <replaceable>CMD</replaceable> to + <replaceable>SERVER</replaceable> via the + <acronym>rcon</acronym> protocol + (if <replaceable>SERVER</replaceable> is not specified, it must + be defined via command line options, see option <option>-r</option> + below). Note that <replaceable>CMD</replaceable> will be interpreted + as a single command, so e.g. <quote><command>minecctl cmd + <replaceable>SERVER</replaceable> time set day</command></quote> + will be interpreted as a single command. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>cmds</command> <optional>SERVER</optional> <replaceable>CMDS</replaceable></term> + <listitem><para> + Similar to <command>cmd</command> above, but allows multiple commands + to be sent to the server. Use quotes to separate commands, e.g. + <quote><command>minecctl cmds <replaceable>SERVER</replaceable> + <quote>time set day</quote> + <quote>say Enjoy the sun</quote></command></quote>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><optional>SERVER</optional> <replaceable>CMD</replaceable></term> + <listitem><para> + Shorthand for <quote><command>cmd <optional>SERVER</optional> + <replaceable>CMD</replaceable></command></quote>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><optional>SERVER</optional></term> + <listitem><para> + Shorthand for + <quote><command>console <optional>SERVER</optional></command></quote>. + </para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Options</title> + <para>The following options are understood:</para> + <variablelist> + + <varlistentry> + <term><option>-p</option></term> + <term><option>--rcon-password=<replaceable>PASSWORD</replaceable></option></term> + <listitem><para> + Use <replaceable>PASSWORD</replaceable> when + connecting via <acronym>rcon</acronym> to a server. If not set, + the password (if any) from the <replaceable>SERVER</replaceable> + configuration file will be used. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-r</option></term> + <term><option>--rcon-address=<replaceable>ADDRESS</replaceable></option></term> + <listitem><para> + Use <replaceable>ADDRESS</replaceable> when connecting via + <acronym>rcon</acronym> to a server. If not set, the address + (if any) from the <replaceable>SERVER</replaceable> configuration + file will be used. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-m</option></term> + <term><option>--mc-address=<replaceable>ADDRESS</replaceable></option></term> + <listitem><para> + Use <replaceable>ADDRESS</replaceable> when connecting via + the <application>minecraft</application> protocol to a server + (only used for some commands such as <command>pcount</command>, + <command>status</command> and <command>ping</command>). + If not set, the address (if any) from the + <replaceable>SERVER</replaceable> configuration file will be used. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-c</option></term> + <term><option>--cfgdir=<replaceable>DIR</replaceable></option></term> + <listitem><para> + Look for <replaceable>SERVER</replaceable> configuration files + in <replaceable>DIR</replaceable> instead of the default + directory (<filename class="directory">/etc/minecproxy/</filename>). + <!-- FIXME: Add replacement var --> + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-f</option></term> + <term><option>--force</option></term> + <listitem><para> + Normally <command>minecctl</command> will check the current + player count and refuse to stop a server with active players. + This option means that the given server(s) will be stopped + even if there are active players. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-v</option></term> + <term><option>--verbose</option></term> + <listitem><para> + Output extra logging information. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-d</option></term> + <term><option>--debug</option></term> + <listitem><para> + Output debugging information (implies <option>-v</option>). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-h</option></term> + <term><option>--help</option></term> + <listitem><para> + Prints a list of valid options/commands and exits. + </para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>minecproxy</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>minecproxy.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>minecproxy.mcserver</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/minecproxy.conf.xml b/man/minecproxy.conf.xml new file mode 100644 index 0000000..65eaeac --- /dev/null +++ b/man/minecproxy.conf.xml @@ -0,0 +1,209 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!-- SPDX-License-Identifier: GPL-2.0 --> + +<refentry id="minecproxy.conf"> + + <refentryinfo> + <title>minecproxy.conf</title> + <productname>minecproxy</productname> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>David</firstname> + <surname>Härdeman</surname> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>minecproxy.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>minecproxy.conf</refname> + <refpurpose>Basic settings for <command>minecproxy</command></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>minecproxy.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + <filename>minecproxy.conf</filename> provides the ability to + control some basics of <command>minecproxy</command>. + The file is expected to be in the main configuration directory + of <command>minecproxy</command> (see + <citerefentry><refentrytitle>minecproxy</refentrytitle><manvolnum>1</manvolnum></citerefentry>) + and uses a plain text ini-style format simlar to what + <application>systemd</application> uses. + </para> + <para> + The file has a single section titled [MinecProxy], and comments + can be prefixed with <emphasis>#</emphasis>. The defaults should + be fine for the majority of users, meaning that no further + configuration is necessary and this file can be omitted. + </para> + </refsect1> + + <refsect1> + <title>Options</title> + <para>The following options are understood:</para> + <variablelist> + + <varlistentry> + <term><option>IGMP=</option></term> + <listitem><para> + Instead of constanly announcing the configured + <application>Minecraft</application> servers, listen to + the multicase messages sent by <application>Minecraft</application> + clients when they are looking for servers (i.e. joining + a certain multicast group) and only then start sending announce + messages on the local network. This cuts down on the network + traffic (<remark>this feature should be considered + experimental</remark>). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>IGMPIface=</option></term> + <listitem><para> + The name of the network interface (e.g. <quote>eth0</quote> + to use when listening for <acronym>IGMP</acronym> messages + (default: all). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>AnnounceIntervalSec=</option></term> + <listitem><para> + The number of seconds to wait between sending successive + announce messages on the local network. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>ProxyConnectionIntervalSec=</option></term> + <listitem><para> + The number of seconds to wait between performing + connection attempts when a client is connecting to a proxy + type server (see + <citerefentry><refentrytitle>minecproxy.mcserver</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for a discussion of server types). Mostly useful when + <command>minecproxy</command> is in the process of starting + up a server. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>ProxyConnectionAttempts=</option></term> + <listitem><para> + How many connection attempts to perform (with a wait + of <option>ProxyConnectionIntervalSec=</option> seconds in + between each attempt) before giving up. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>SocketDefer=</option></term> + <listitem><para> + Takes a boolean argument specifying whether to set the + <literal>TCP_DEFER_ACCEPT</literal> option on proxy + sockets. Said option allows <command>minecproxy</command> + to defer accepting connections until the client starts + sending data, which conserves resources (see + <citerefentry><refentrytitle>tcp</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for further details). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>SocketFreebind=</option></term> + <listitem><para> + Takes a boolean argument specifying whether to set the + <literal>IP_FREEBIND</literal> option on proxy + sockets. Said option allows <command>minecproxy</command> + to listen to addresses which are not configured at + the time <command>minecproxy</command> is started, which + allows <command>minecproxy</command> to be started before + the network has been configured, at the cost of not being + able to catch incorrectly defined addresses (see + <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for further details). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>SocketKeepalive=</option></term> + <listitem><para> + Takes a boolean argument specifying whether to set the + <literal>SO_KEEPALIVE</literal> option on proxy + sockets. Said option allows <command>minecproxy</command> + to detect dead clients earlier, which might conserve resources (see + <citerefentry><refentrytitle>tcp</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for further details). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>SocketIPTOS=</option></term> + <listitem><para> + Takes a boolean argument specifying whether to set the + <literal>IPTOS_LOWDELAY</literal> option on proxy + sockets. Said option informs the kernel that delays + should be minimized, as the <application>Minecraft</application> + traffic is interactive (see + <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for further details). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>SocketNoDelay=</option></term> + <listitem><para> + Takes a boolean argument specifying whether to set the + <literal>TCP_NODELAY</literal> option on proxy + sockets. Said option allows packets to be forwarded as soon + as possible, which should benefit interactive traffic, such + as <application>Minecraft</application> connections (see + <citerefentry><refentrytitle>tcp</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for further details). + </para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Example</title> +<programlisting> +<![CDATA[ +[MinecProxy] +IGMP=true +IGMPIface=eth0 +AnnounceIntervalSec=5 +ProxyConnectionIntervalSec=3 +ProxyConnectionAttempts=20 +SocketDefer=true +SocketFreebind=true +SocketKeepalive=true +SocketIPTOS=true +SocketNoDelay=true +]]> +</programlisting> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>minecproxy</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>minecctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>minecproxy.mcserver</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/meson.build b/meson.build index 7c7a09c..7f30575 100644 --- a/meson.build +++ b/meson.build @@ -64,4 +64,5 @@ dep_config_h = declare_dependency( subdir('shared') subdir('minecproxy') subdir('minecctl') +subdir('man') |