Add some man pages

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')