From dd81adc5657d9cad5a3daa68b275277feb57b10b Mon Sep 17 00:00:00 2001 From: Louis Moureaux Date: Sun, 21 Aug 2022 19:16:52 +0200 Subject: [PATCH 1/8] Add a page for Freeciv21 usage on servers The goal of this page is to give server admins most relevant information in a single location, with pointers to detailed information when it makes sense. --- docs/General/index.rst | 1 + docs/General/on-the-server.rst | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+) create mode 100644 docs/General/on-the-server.rst diff --git a/docs/General/index.rst b/docs/General/index.rst index e38ae2241a..dd665619c9 100644 --- a/docs/General/index.rst +++ b/docs/General/index.rst @@ -10,6 +10,7 @@ the FAQ and installation instructions go here. install.rst windows-install.rst modpack-installer.rst + on-the-server.rst :maxdepth: 1 Manuals diff --git a/docs/General/on-the-server.rst b/docs/General/on-the-server.rst new file mode 100644 index 0000000000..fc6870ef0b --- /dev/null +++ b/docs/General/on-the-server.rst @@ -0,0 +1,20 @@ +Freeciv21 on the Server +*********************** + +In order to play Freeciv21 on the network, one machine needs to act as the *server*: the state of +the game lives on the server and players can connect to play. There are many ways to operate such a +server; this page gives an introduction to the topic. + +In order to run a server, you need a computer that other players can reach over the network. If +you're planning to play at home, this can usually be any machine connected to your WiFi or local +cabled network. Otherwise, the easiest is to rent a small server from a hosting provider. We +strongly recommend that you choose a Linux-based server, as that is what we have experience with. +You will need the ability to run your own programs on the server, so SSH access is a must. Apart +from that, Freeciv21 is quite light on resources so you will hardly hit the limits of even the +cheapest options. + +Whether you choose to use your own machine or to rent one, the basic principle of operating a +server is the same: you need to run a program called ``freeciv21-server`` for as long as the game +will last. This program will wait for players to connect and handle their moves in the exact same +way as in a single player game. In fact, Freeciv21 always uses a server, even when there is only +one player! From 3a7b29336dfe946423209974cac26c4bd8294210 Mon Sep 17 00:00:00 2001 From: Louis Moureaux Date: Sun, 21 Aug 2022 19:27:58 +0200 Subject: [PATCH 2/8] Document installation on a server --- docs/General/on-the-server.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/General/on-the-server.rst b/docs/General/on-the-server.rst index fc6870ef0b..f56cfc6988 100644 --- a/docs/General/on-the-server.rst +++ b/docs/General/on-the-server.rst @@ -18,3 +18,11 @@ server is the same: you need to run a program called ``freeciv21-server`` for as will last. This program will wait for players to connect and handle their moves in the exact same way as in a single player game. In fact, Freeciv21 always uses a server, even when there is only one player! + +Installation +============ + +Installing Freeciv21 on a server is done the normal way, as documented in :doc:`/General/install`. +Because the official packages come with the complete game, they will pull a number of dependencies +that are normally not used on servers (for instance, a display server). This software is installed +for packaging reasons, but will not be used. From 469f6cafdd0a1a96df450f9c7258cf3f99c398f0 Mon Sep 17 00:00:00 2001 From: Louis Moureaux Date: Sun, 21 Aug 2022 19:45:35 +0200 Subject: [PATCH 3/8] Add basic notes about starting the server They may get expanded later --- docs/General/on-the-server.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/General/on-the-server.rst b/docs/General/on-the-server.rst index f56cfc6988..6d2f8fb7f4 100644 --- a/docs/General/on-the-server.rst +++ b/docs/General/on-the-server.rst @@ -26,3 +26,24 @@ Installing Freeciv21 on a server is done the normal way, as documented in :doc:` Because the official packages come with the complete game, they will pull a number of dependencies that are normally not used on servers (for instance, a display server). This software is installed for packaging reasons, but will not be used. + +Starting the Server +=================== + +Once Freeciv21 is installed, it's immediately ready to run a simple server, which one can do by +running the following command: + +.. code-block:: sh + + freeciv21-server + +This starts a server listening on the port traditionally used for Freeciv21, 5556. You can provide +a custom port number by passing it to the ``-p`` argument: + +.. code-block:: sh + + freeciv21-server -p 5000 + +A server started with this command can be reached by pointing the game to port 5000 of your domain +name. We suggest to start the server from within a terminal multiplexer such as ``tmux`` or +``screen``, which will let it run independently. From b43324ac527027b01b6fe225b47514b42d9a7cc9 Mon Sep 17 00:00:00 2001 From: Louis Moureaux Date: Sun, 21 Aug 2022 19:46:35 +0200 Subject: [PATCH 4/8] Add copyright info to docs/General/on-the-server.rst --- docs/General/on-the-server.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/General/on-the-server.rst b/docs/General/on-the-server.rst index 6d2f8fb7f4..cfc4ad4de2 100644 --- a/docs/General/on-the-server.rst +++ b/docs/General/on-the-server.rst @@ -1,3 +1,7 @@ +.. + SPDX-License-Identifier: GPL-3.0-or-later + SPDX-FileCopyrightText: 2022 louis94 + Freeciv21 on the Server *********************** From 62c859c946ea94236b0257b5211d750f56fa9eec Mon Sep 17 00:00:00 2001 From: Louis Moureaux Date: Sun, 21 Aug 2022 20:27:48 +0200 Subject: [PATCH 5/8] Document user permissions This duplicates /help cmdlevel a bit, but is well-fitted on the "Freeciv21 on the Server" page. --- docs/General/on-the-server.rst | 39 ++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/docs/General/on-the-server.rst b/docs/General/on-the-server.rst index cfc4ad4de2..39e70bf6d1 100644 --- a/docs/General/on-the-server.rst +++ b/docs/General/on-the-server.rst @@ -51,3 +51,42 @@ a custom port number by passing it to the ``-p`` argument: A server started with this command can be reached by pointing the game to port 5000 of your domain name. We suggest to start the server from within a terminal multiplexer such as ``tmux`` or ``screen``, which will let it run independently. + +User Permissions +================ + +Freeciv21 supports several access levels for players connected to a server, restricting which +commands they are allowed to run: + +``none`` + The user may not issue any command. + +``info`` + The user may use informational commands only. + +``basic`` + The user may use informational commands as well as commands affecting the game. Commands + affecting the game start a vote if more than one user is connected. + +``ctrl`` + Same as ``basic``, but the vote is bypassed for commands affecting the game. + +``admin`` + May use any command, except for ``quit``, ``rfcstyle``, and ``write``. This includes + potentially destructive commands such as ``save`` and ``fcdb`` --- use with care. + +``hack`` + May use all commands without restriction. + +By default, users connected to your server have access level ``basic``. This can be changed using +the ``cmdlevel`` command:: + + cmdlevel info new + +This command would grant access level ``info`` to any newly connecting player. A few more options +are available; please refer to the documentation of ``cmdlevel`` for more information. + +.. note:: + The ``take`` and ``observe`` commands require access level ``info`` only. Their use can be + restricted using the ``allowtake`` server option or, in more advanced setups, using the + ``user_take`` :doc:`fcdb ` hook. From 0d52d525dc1f6fd4e0dc812b410c7ae8422e5cc3 Mon Sep 17 00:00:00 2001 From: Louis Moureaux Date: Sun, 21 Aug 2022 21:02:20 +0200 Subject: [PATCH 6/8] Add notes about setting up auth The fcdb docs need to be reviewed... --- docs/General/on-the-server.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/General/on-the-server.rst b/docs/General/on-the-server.rst index 39e70bf6d1..59a01e6d52 100644 --- a/docs/General/on-the-server.rst +++ b/docs/General/on-the-server.rst @@ -90,3 +90,20 @@ are available; please refer to the documentation of ``cmdlevel`` for more inform The ``take`` and ``observe`` commands require access level ``info`` only. Their use can be restricted using the ``allowtake`` server option or, in more advanced setups, using the ``user_take`` :doc:`fcdb ` hook. + +Authentication +============== + +By default, Freeciv21 servers are open to anyone without any sort of authentication. It is +possible to make Freeciv21 ask for a password. There is also a built-in registration procedure +with which one can create an account and set a password. + +Authentication needs vary greatly depending on what you do with your server. If you use passwords +merely to prevent players from peeking on each other, you may be fine with a very basic setup. If +you are planning to run a full-scale server allowing registration through a website, you will +need much more advanced settings. Freeciv21 ought to support all use cases within a unified +interface. To allow for the necessary flexibility, authentication support is implemented using a +Lua script. + +See the :doc:`fcdb documentation ` for more information about setting up +authentication. From 15ffc343d0299088ef836c2427024bfceb8551a7 Mon Sep 17 00:00:00 2001 From: Louis Moureaux Date: Tue, 23 Aug 2022 02:13:43 +0200 Subject: [PATCH 7/8] Fc21 on the Server: Review comments part I See #1304. --- docs/General/on-the-server.rst | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/docs/General/on-the-server.rst b/docs/General/on-the-server.rst index 59a01e6d52..f482143138 100644 --- a/docs/General/on-the-server.rst +++ b/docs/General/on-the-server.rst @@ -5,23 +5,22 @@ Freeciv21 on the Server *********************** -In order to play Freeciv21 on the network, one machine needs to act as the *server*: the state of +In order to play Freeciv21 over the network, one machine needs to act as the *server*: the state of the game lives on the server and players can connect to play. There are many ways to operate such a -server; this page gives an introduction to the topic. +server. This page gives an introduction to the topic. In order to run a server, you need a computer that other players can reach over the network. If -you're planning to play at home, this can usually be any machine connected to your WiFi or local +you are planning to play at home, this can usually be any machine connected to your WiFi or local cabled network. Otherwise, the easiest is to rent a small server from a hosting provider. We strongly recommend that you choose a Linux-based server, as that is what we have experience with. You will need the ability to run your own programs on the server, so SSH access is a must. Apart -from that, Freeciv21 is quite light on resources so you will hardly hit the limits of even the +from that, Freeciv21 is quite light on resources, so you will hardly hit the limits of even the cheapest options. Whether you choose to use your own machine or to rent one, the basic principle of operating a server is the same: you need to run a program called ``freeciv21-server`` for as long as the game will last. This program will wait for players to connect and handle their moves in the exact same -way as in a single player game. In fact, Freeciv21 always uses a server, even when there is only -one player! +way as in a single player game. In fact, Freeciv21 uses an internal server for single player games! Installation ============ @@ -34,23 +33,23 @@ for packaging reasons, but will not be used. Starting the Server =================== -Once Freeciv21 is installed, it's immediately ready to run a simple server, which one can do by +Once Freeciv21 is installed, it is immediately ready to run a simple server, which one can do by running the following command: .. code-block:: sh - freeciv21-server + $ freeciv21-server -This starts a server listening on the port traditionally used for Freeciv21, 5556. You can provide +This command will start a server on the default port for Freeciv21, which is 5556. You can provide a custom port number by passing it to the ``-p`` argument: .. code-block:: sh - freeciv21-server -p 5000 + $ freeciv21-server -p 5000 -A server started with this command can be reached by pointing the game to port 5000 of your domain -name. We suggest to start the server from within a terminal multiplexer such as ``tmux`` or -``screen``, which will let it run independently. +A server started with this command can be reached by pointing the game to port 5000 of your of your +machine's IP address or hostname. We suggest to start the server from within a terminal multiplexer +such as ``tmux`` or ``screen``, which will let it run independently. User Permissions ================ @@ -83,8 +82,8 @@ the ``cmdlevel`` command:: cmdlevel info new -This command would grant access level ``info`` to any newly connecting player. A few more options -are available; please refer to the documentation of ``cmdlevel`` for more information. +This command grants access level ``info`` to any newly connecting player. A few more options are +available; please see ``help cmdlevel`` for more information. .. note:: The ``take`` and ``observe`` commands require access level ``info`` only. Their use can be From 3c97c0fb49b4fb09f3f7a5c3101852f9f6b92b79 Mon Sep 17 00:00:00 2001 From: Louis Moureaux Date: Tue, 23 Aug 2022 02:37:48 +0200 Subject: [PATCH 8/8] "Fc21 on the Server" is based on experience from running lt.net This resolves the reference to the first "we" in the text, which was previously somewhat ambiguous. See #1304. --- docs/General/on-the-server.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/General/on-the-server.rst b/docs/General/on-the-server.rst index f482143138..9c82c7673a 100644 --- a/docs/General/on-the-server.rst +++ b/docs/General/on-the-server.rst @@ -7,7 +7,8 @@ Freeciv21 on the Server In order to play Freeciv21 over the network, one machine needs to act as the *server*: the state of the game lives on the server and players can connect to play. There are many ways to operate such a -server. This page gives an introduction to the topic. +server. This page gives an introduction to the topic, guided by the experience gathered by running +the `Longturn `_ website. In order to run a server, you need a computer that other players can reach over the network. If you are planning to play at home, this can usually be any machine connected to your WiFi or local