From 7845369d50b6dda0cae68eeebc5dbb60ceb6b454 Mon Sep 17 00:00:00 2001 From: Griatch Date: Tue, 22 Nov 2022 17:59:39 +0100 Subject: [PATCH] Cleanup of setup doc section --- .../Howtos/Tutorial-Tweeting-Game-Stats.md | 2 +- ...{Grapevine.md => Channels-to-Grapevine.md} | 2 +- .../Setup/{IRC.md => Channels-to-IRC.md} | 2 +- .../Setup/{RSS.md => Channels-to-RSS.md} | 6 +- ...a-to-Twitter.md => Channels-to-Twitter.md} | 53 ++--- ...n-SQL-Server.md => Choosing-a-Database.md} | 42 ++-- docs/source/Setup/Client-Support-Grid.md | 2 +- ...pache-Config.md => Config-Apache-Proxy.md} | 187 ++++++++---------- .../{HAProxy-Config.md => Config-HAProxy.md} | 2 +- docs/source/Setup/Installation-Git.md | 9 +- .../Setup/Installation-Non-Interactive.md | 1 - docs/source/Setup/Installation.md | 25 ++- docs/source/Setup/Online-Setup.md | 89 +++------ docs/source/Setup/Security-Practices.md | 105 ++++++++++ docs/source/Setup/Security.md | 152 -------------- docs/source/Setup/Settings.md | 25 +-- docs/source/Setup/Setup-Overview.md | 21 +- docs/source/_static/nature.css | 14 +- 18 files changed, 311 insertions(+), 428 deletions(-) rename docs/source/Setup/{Grapevine.md => Channels-to-Grapevine.md} (98%) rename docs/source/Setup/{IRC.md => Channels-to-IRC.md} (99%) rename docs/source/Setup/{RSS.md => Channels-to-RSS.md} (92%) rename docs/source/Setup/{How-to-connect-Evennia-to-Twitter.md => Channels-to-Twitter.md} (55%) rename docs/source/Setup/{Choosing-An-SQL-Server.md => Choosing-a-Database.md} (85%) rename docs/source/Setup/{Apache-Config.md => Config-Apache-Proxy.md} (74%) rename docs/source/Setup/{HAProxy-Config.md => Config-HAProxy.md} (99%) create mode 100644 docs/source/Setup/Security-Practices.md delete mode 100644 docs/source/Setup/Security.md diff --git a/docs/source/Howtos/Tutorial-Tweeting-Game-Stats.md b/docs/source/Howtos/Tutorial-Tweeting-Game-Stats.md index 495b3cba82..4baaba4c1c 100644 --- a/docs/source/Howtos/Tutorial-Tweeting-Game-Stats.md +++ b/docs/source/Howtos/Tutorial-Tweeting-Game-Stats.md @@ -2,7 +2,7 @@ This tutorial will create a simple script that will send a tweet to your already configured twitter -account. Please see: [How to connect Evennia to Twitter](../Setup/How-to-connect-Evennia-to-Twitter.md) if you +account. Please see: [How to connect Evennia to Twitter](../Setup/Channels-to-Twitter.md) if you haven't already done so. The script could be expanded to cover a variety of statistics you might wish to tweet about diff --git a/docs/source/Setup/Grapevine.md b/docs/source/Setup/Channels-to-Grapevine.md similarity index 98% rename from docs/source/Setup/Grapevine.md rename to docs/source/Setup/Channels-to-Grapevine.md index b27b735cd3..cf8e322d64 100644 --- a/docs/source/Setup/Grapevine.md +++ b/docs/source/Setup/Channels-to-Grapevine.md @@ -1,4 +1,4 @@ -# Grapevine +# Connect Evennia channels to Grapevine [Grapevine](https://grapevine.haus) is a new chat network for `MU*`*** games. By diff --git a/docs/source/Setup/IRC.md b/docs/source/Setup/Channels-to-IRC.md similarity index 99% rename from docs/source/Setup/IRC.md rename to docs/source/Setup/Channels-to-IRC.md index 37bdb98de3..b2e59650b8 100644 --- a/docs/source/Setup/IRC.md +++ b/docs/source/Setup/Channels-to-IRC.md @@ -1,4 +1,4 @@ -# IRC +# Connect Evennia channels to IRC [IRC (Internet Relay Chat)](https://en.wikipedia.org/wiki/Internet_Relay_Chat) is a long standing chat protocol used by many open-source projects for communicating in real time. By connecting one of diff --git a/docs/source/Setup/RSS.md b/docs/source/Setup/Channels-to-RSS.md similarity index 92% rename from docs/source/Setup/RSS.md rename to docs/source/Setup/Channels-to-RSS.md index 08b2f1cab2..f0d7e213a6 100644 --- a/docs/source/Setup/RSS.md +++ b/docs/source/Setup/Channels-to-RSS.md @@ -1,4 +1,4 @@ -# RSS +# Connect Evennia channels to RSS [RSS](https://en.wikipedia.org/wiki/RSS) is a format for easily tracking updates on websites. The @@ -25,7 +25,7 @@ Start/reload Evennia as a privileged user. You should now have a new command ava @rss2chan = -### Setting up RSS, step by step +## Setting up RSS, step by step You can connect RSS to any Evennia channel, but for testing, let's set up a new channel "rss". @@ -44,4 +44,4 @@ switch: @rss2chan/delete rss = https://github.com/evennia/evennia/commits/master.atom You can connect any number of RSS feeds to a channel this way. You could also connect them to the -same channels as [IRC](./IRC.md) to have the feed echo to external chat channels as well. +same channels as [Channels-to-IRC](./Channels-to-IRC.md) to have the feed echo to external chat channels as well. diff --git a/docs/source/Setup/How-to-connect-Evennia-to-Twitter.md b/docs/source/Setup/Channels-to-Twitter.md similarity index 55% rename from docs/source/Setup/How-to-connect-Evennia-to-Twitter.md rename to docs/source/Setup/Channels-to-Twitter.md index e12d2581f3..e3a9c2e75a 100644 --- a/docs/source/Setup/How-to-connect-Evennia-to-Twitter.md +++ b/docs/source/Setup/Channels-to-Twitter.md @@ -1,24 +1,15 @@ -# How to connect Evennia to Twitter +# Connect Evennia to Twitter -[Twitter](https://en.wikipedia.org/wiki/twitter) is an online social networking service that enables -users to send and read short 280-character messages called "tweets". Following is a short tutorial -explaining how to enable users to send tweets from inside Evennia. +[Twitter](https://en.wikipedia.org/wiki/twitter) is an online social networking service that enables users to send and read short messages called "tweets". Following is a short tutorial explaining how to enable users to send tweets from inside Evennia. ## Configuring Twitter -You must first have a Twitter account. Log in and register an App at the [Twitter Dev -Site](https://apps.twitter.com/). Make sure you enable access to "write" tweets! +You must first have a Twitter account. Log in and register an App at the [Twitter Dev Site](https://apps.twitter.com/). Make sure you enable access to "write" tweets! -To tweet from Evennia you will need both the "API Token" and the "API secret" strings as well as the -"Access Token" and "Access Secret" strings. +To tweet from Evennia you will need both the "API Token" and the "API secret" strings as well as the "Access Token" and "Access Secret" strings. -Twitter changed their requirements to require a Mobile number on the Twitter account to register new -apps with write access. If you're unable to do this, please see [this Dev -post](https://dev.twitter.com/notifications/new-apps-registration) which describes how to get around -it. - -## Install the twitter python module +Twitter changed their requirements to require a Mobile number on the Twitter account to register new apps with write access. If you're unable to do this, please see [this Dev post](https://dev.twitter.com/notifications/new-apps-registration) which describes how to get around it. To use Twitter you must install the [Twitter](https://pypi.python.org/pypi/twitter) Python module: @@ -26,19 +17,18 @@ To use Twitter you must install the [Twitter](https://pypi.python.org/pypi/twitt pip install python-twitter ``` -## A basic tweet command +## Setting up Twitter, step by step -Evennia doesn't have a `tweet` command out of the box so you need to write your own little -[Command](../Components/Commands.md) in order to tweet. If you are unsure about how commands work and how to add -them, it can be an idea to go through the [Adding a Command Tutorial](../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Adding-Commands.md) -before continuing. +### A basic tweet command -You can create the command in a separate command module (something like `mygame/commands/tweet.py`) -or together with your other custom commands, as you prefer. +Evennia doesn't have a `tweet` command out of the box so you need to write your own little [Command](../Components/Commands.md) in order to tweet. If you are unsure about how commands work and how to add them, it can be an idea to go through the [Adding a Command Tutorial](../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Adding-Commands.md) before continuing. +You can create the command in a separate command module (something like `mygame/commands/tweet.py`) or together with your other custom commands, as you prefer. This is how it can look: ```python +# in mygame/commands.tweet.py, for example + import twitter from evennia import Command @@ -87,16 +77,17 @@ class CmdTweet(Command): Be sure to substitute your own actual API/Access keys and secrets in the appropriate places. -We default to limiting tweet access to players with `Developers`-level access *or* to those players -that have the permission "tweet" (allow individual characters to tweet with `@perm/player playername -= tweet`). You may change the [lock](../Components/Locks.md) as you feel is appropriate. Change the overall -permission to `Players` if you want everyone to be able to tweet. +We default to limiting tweet access to players with `Developers`-level access *or* to those players that have the permission "tweet" -Now add this command to your default command set (e.g in `mygame/commands/defalt_cmdsets.py`") and -reload the server. From now on those with access can simply use `tweet ` to see the tweet -posted from the game's Twitter account. +To allow allow individual characters to tweet, set the `tweet` permission with -## Next Steps + perm/player playername = tweet + +You may change the [lock](../Components/Locks.md) as you feel is appropriate. Change the overall permission to `Players` if you want everyone to be able to tweet. + +Now add this command to your default command set (e.g in `mygame/commands/defalt_cmdsets.py`) and `reload` the server. From now on those with access can simply use `tweet ` to see the tweet posted from the game's Twitter account. + +### Next Steps This shows only a basic tweet setup, other things to do could be: @@ -105,6 +96,4 @@ This shows only a basic tweet setup, other things to do could be: * Changing locks to make tweeting open to more people * Echo your tweets to an in-game channel -Rather than using an explicit command you can set up a Script to send automatic tweets, for example -to post updated game stats. See the [Tweeting Game Stats tutorial](../Howtos/Tutorial-Tweeting-Game-Stats.md) for -help. \ No newline at end of file +Rather than using an explicit command you can set up a Script to send automatic tweets, for example to post updated game stats. See the [Tweeting Game Stats tutorial](../Howtos/Tutorial-Tweeting-Game-Stats.md) for help. \ No newline at end of file diff --git a/docs/source/Setup/Choosing-An-SQL-Server.md b/docs/source/Setup/Choosing-a-Database.md similarity index 85% rename from docs/source/Setup/Choosing-An-SQL-Server.md rename to docs/source/Setup/Choosing-a-Database.md index 0dd5fbb5ba..b80cb45cc0 100644 --- a/docs/source/Setup/Choosing-An-SQL-Server.md +++ b/docs/source/Setup/Choosing-a-Database.md @@ -1,4 +1,4 @@ -# Choosing An SQL Server +# Choosing a database This page gives an overview of the supported SQL databases as well as instructions on install: @@ -7,9 +7,7 @@ This page gives an overview of the supported SQL databases as well as instructio - PostgreSQL - MySQL / MariaDB -Since Evennia uses [Django](https://djangoproject.com), most of our notes are based off of what we -know from the community and their documentation. While the information below may be useful, you can -always find the most up-to-date and "correct" information at Django's [Notes about supported +Since Evennia uses [Django](https://djangoproject.com), most of our notes are based off of what we know from the community and their documentation. While the information below may be useful, you can always find the most up-to-date and "correct" information at Django's [Notes about supported Databases](https://docs.djangoproject.com/en/dev/ref/databases/#ref-databases) page. ## SQLite3 @@ -17,39 +15,23 @@ Databases](https://docs.djangoproject.com/en/dev/ref/databases/#ref-databases) p [SQLite3](https://sqlite.org/) is a light weight single-file database. It is our default database and Evennia will set this up for you automatically if you give no other options. SQLite stores the database in a single file (`mygame/server/evennia.db3`). This means it's very easy to reset this -database - just delete (or move) that `evennia.db3` file and run `evennia migrate` again! No server -process is needed and the administrative overhead and resource consumption is tiny. It is also very -fast since it's run in-memory. For the vast majority of Evennia installs it will probably be all +database - just delete (or move) that `evennia.db3` file and run `evennia migrate` again! No server process is needed and the administrative overhead and resource consumption is tiny. It is also very fast since it's run in-memory. For the vast majority of Evennia installs it will probably be all that's ever needed. SQLite will generally be much faster than MySQL/PostgreSQL but its performance comes with two drawbacks: -* SQLite [ignores length constraints by design](https://www.sqlite.org/faq.html#q9); it is possible -to store very large strings and numbers in fields that technically should not accept them. This is -not something you will notice; your game will read and write them and function normally, but this -*can* create some data migration problems requiring careful thought if you do need to change -databases later. -* SQLite can scale well to storage of millions of objects, but if you end up with a thundering herd -of users trying to access your MUD and web site at the same time, or you find yourself writing long- -running functions to update large numbers of objects on a live game, either will yield errors and -interference. SQLite does not work reliably with multiple concurrent threads or processes accessing -its records. This has to do with file-locking clashes of the database file. So for a production -server making heavy use of process- or thread pools (or when using a third-party webserver like -Apache), a proper database is a more appropriate choice. +* SQLite [ignores length constraints by design](https://www.sqlite.org/faq.html#q9); it is possible to store very large strings and numbers in fields that technically should not accept them. This is not something you will notice; your game will read and write them and function normally, but this *can* create some data migration problems requiring careful thought if you do need to change databases later. +* SQLite can scale well to storage of millions of objects, but if you end up with a thundering herd of users trying to access your MUD and web site at the same time, or you find yourself writing long- running functions to update large numbers of objects on a live game, either will yield errors and interference. SQLite does not work reliably with multiple concurrent threads or processes accessing its records. This has to do with file-locking clashes of the database file. So for a production server making heavy use of process- or thread pools, a proper database is a more appropriate choice. ### Install of SQlite3 -This is installed and configured as part of Evennia. The database file is created as -`mygame/server/evennia.db3` when you run +This is installed and configured as part of Evennia. The database file is created as `mygame/server/evennia.db3` when you run evennia migrate -without changing any database options. An optional requirement is the `sqlite3` client program - -this is required if you want to inspect the database data manually. A shortcut for using it with the -evennia database is `evennia dbshell`. Linux users should look for the `sqlite3` package for their -distro while Mac/Windows should get the [sqlite-tools package from this -page](https://sqlite.org/download.html). +without changing any database options. An optional requirement is the `sqlite3` client program - this is required if you want to inspect the database data manually. A shortcut for using it with the +evennia database is `evennia dbshell`. Linux users should look for the `sqlite3` package for their distro while Mac/Windows should get the [sqlite-tools package from this page](https://sqlite.org/download.html). To inspect the default Evennia database (once it's been created), go to your game dir and do @@ -62,6 +44,14 @@ To inspect the default Evennia database (once it's been created), go to your gam This will bring you into the sqlite command line. Use `.help` for instructions and `.quit` to exit. See [here](https://gist.github.com/vincent178/10889334) for a cheat-sheet of commands. +### Resetting SQLite3 database + +To reset your database and start from scratch, simply stop Evennia and delete the `mygame/server/evennia.db3`. Then run `evennia migrate` again. + +```{sidebar} Hint +Make a copy of the `evennia.db3` file once you created your superuser. When you want to reset, you can just stop evennia and copy that file back over `evennia.db3`. That way you don't have to run migrations and create the superuser every time! +``` + ## PostgreSQL [PostgreSQL](https://www.postgresql.org/) is an open-source database engine, recommended by Django. diff --git a/docs/source/Setup/Client-Support-Grid.md b/docs/source/Setup/Client-Support-Grid.md index 3389118e5c..48f21f5323 100644 --- a/docs/source/Setup/Client-Support-Grid.md +++ b/docs/source/Setup/Client-Support-Grid.md @@ -21,7 +21,7 @@ Legend: | [MUSHclient][4] (Win) | 4.94 | NAWS reports full text area | | [Zmud][5] (Win) | 7.21 | *UNTESTED* | | [Cmud][6] (Win) | v3 | *UNTESTED* | -| [Potato][7]_ | 2.0.0b16 | No MXP, MCCP support. Win 32bit does not understand | +| [Potato][7] | 2.0.0b16 | No MXP, MCCP support. Win 32bit does not understand | | | | "localhost", must use `127.0.0.1`. | | [Mudlet][8] | 3.4+ | No known issues. Some older versions showed <> as html | | | | under MXP. | diff --git a/docs/source/Setup/Apache-Config.md b/docs/source/Setup/Config-Apache-Proxy.md similarity index 74% rename from docs/source/Setup/Apache-Config.md rename to docs/source/Setup/Config-Apache-Proxy.md index 5cf052d344..3e55e8c62a 100644 --- a/docs/source/Setup/Apache-Config.md +++ b/docs/source/Setup/Config-Apache-Proxy.md @@ -1,113 +1,27 @@ -# Apache Config +# Configuring an Apache Proxy +Evennia has its own webserver. This should usually not be replaced. But another reason for wanting to use an external webserver like Apache would be to act as a *proxy* in front of the Evennia webserver. Getting this working with TLS (encryption) requires some extra work covered at the end of this page. -**Warning**: This information is presented as a convenience, using another webserver than Evennia's -own is not directly supported and you are on your own if you want to do so. Evennia's webserver -works out of the box without any extra configuration and also runs in-process making sure to avoid -caching race conditions. The browser web client will most likely not work (at least not without -tweaking) on a third-party web server. +```{warning} Possibly outdated +The Apache instructions below might be outdated. If something is not working right, or you use Evennia with a different server, please let us know. +``` -One reason for wanting to use an external webserver like Apache would be to act as a *proxy* in -front of the Evennia webserver. Getting this working with TLS (encryption) requires some extra work -covered at the end of this page. +## Running Apache as a proxy in front of Evennia -Note that the Apache instructions below might be outdated. If something is not working right, or you -use Evennia with a different server, please let us know. Also, if there is a particular Linux distro -you would like covered, please let us know. - -## `mod_wsgi` Setup - -### Install `mod_wsgi` - -- *Fedora/RHEL* - Apache HTTP Server and `mod_wsgi` are available in the standard package -repositories for Fedora and RHEL: - ``` - $ dnf install httpd mod_wsgi - or - $ yum install httpd mod_wsgi - ``` -- *Ubuntu/Debian* - Apache HTTP Server and `mod_wsgi` are available in the standard package -repositories for Ubuntu and Debian: - ``` - $ apt-get update - $ apt-get install apache2 libapache2-mod-wsgi - ``` - -### Copy and modify the VHOST - -After `mod_wsgi` is installed, copy the `evennia/web/utils/evennia_wsgi_apache.conf` file to your -apache2 vhosts/sites folder. On Debian/Ubuntu, this is `/etc/apache2/sites-enabled/`. Make your -modifications **after** copying the file there. - -Read the comments and change the paths to point to the appropriate locations within your setup. - -### Restart/Reload Apache - -You'll then want to reload or restart apache2 after changing the configurations. - -- *Fedora/RHEL/Ubuntu* - ``` - $ systemctl restart httpd - ``` -- *Ubuntu/Debian* - ``` - $ systemctl restart apache2 - ``` - -### Enjoy - -With any luck, you'll be able to point your browser at your domain or subdomain that you set up in -your vhost and see the nifty default Evennia webpage. If not, read the hopefully informative error -message and work from there. Questions may be directed to our [Evennia Community -site](https://evennia.com). - -### A note on code reloading - -If your `mod_wsgi` is set up to run on daemon mode (as will be the case by default on Debian and -Ubuntu), you may tell `mod_wsgi` to reload by using the `touch` command on -`evennia/game/web/utils/apache_wsgi.conf`. When `mod_wsgi` sees that the file modification time has -changed, it will force a code reload. Any modifications to the code will not be propagated to the -live instance of your site until reloaded. - -If you are not running in daemon mode or want to force the issue, simply restart or reload apache2 -to apply your changes. - -### Further notes and hints: - -If you get strange (and usually uninformative) `Permission denied` errors from Apache, make sure -that your `evennia` directory is located in a place the webserver may actually access. For example, -some Linux distributions may default to very restrictive access permissions on a user's `/home` -directory. - -One user commented that they had to add the following to their Apache config to get things to work. -Not confirmed, but worth trying if there are trouble. - - /evennia/game/web"> - Options +ExecCGI - Allow from all - - -## `mod_proxy` and `mod_ssl` setup - -Below are steps on running Evennia using a front-end proxy (Apache HTTP), `mod_proxy_http`, +Below are steps to run Evennia using a front-end proxy (Apache HTTP), `mod_proxy_http`, `mod_proxy_wstunnel`, and `mod_ssl`. `mod_proxy_http` and `mod_proxy_wstunnel` will simply be -referred to as -`mod_proxy` below. +referred to as `mod_proxy` below. ### Install `mod_ssl` -- *Fedora/RHEL* - Apache HTTP Server and `mod_ssl` are available in the standard package -repositories for Fedora and RHEL: +- *Fedora/RHEL* - Apache HTTP Server and `mod_ssl` are available in the standard package repositories for Fedora and RHEL: ``` $ dnf install httpd mod_ssl or $ yum install httpd mod_ssl ``` -- *Ubuntu/Debian* - Apache HTTP Server and `mod_sslj`kl are installed together in the `apache2` -package and available in the -standard package repositories for Ubuntu and Debian. `mod_ssl` needs to be enabled after -installation: +- *Ubuntu/Debian* - Apache HTTP Server and `mod_sslj`kl are installed together in the `apache2` package and available in the standard package repositories for Ubuntu and Debian. `mod_ssl` needs to be enabled after installation: ``` $ apt-get update $ apt-get install apache2 @@ -164,8 +78,81 @@ proxy. You must set the `WEBSOCKET_CLIENT_URL` setting in your `mymud/server/con WEBSOCKET_CLIENT_URL = "wss://external.example.com/ws" ``` -The setting above is what the client's browser will actually use. Note the use of `wss://` is -because our client will be communicating over an encrypted connection ("wss" indicates websocket -over SSL/TLS). Also, especially note the additional path `/ws` at the end of the URL. This is how +The setting above is what the client's browser will actually use. Note the use of `wss://` is because our client will be communicating over an encrypted connection ("wss" indicates websocket over SSL/TLS). Also, especially note the additional path `/ws` at the end of the URL. This is how Apache HTTP Server identifies that a particular request should be proxied to Evennia's websocket -port but this should be applicable also to other types of proxies (like nginx). \ No newline at end of file +port but this should be applicable also to other types of proxies (like nginx). + + +## Run Apache instead of the Evennia webserver + +```{warning} This is not supported, nor recommended. +This is covered because it has been asked about. The webclient would not work. It would also run out-of-process, leading to race conditions. This is not directly supported, so if you try this you are on your own. +``` + +### Install `mod_wsgi` + +- *Fedora/RHEL* - Apache HTTP Server and `mod_wsgi` are available in the standard package +repositories for Fedora and RHEL: + ``` + $ dnf install httpd mod_wsgi + or + $ yum install httpd mod_wsgi + ``` +- *Ubuntu/Debian* - Apache HTTP Server and `mod_wsgi` are available in the standard package +repositories for Ubuntu and Debian: + ``` + $ apt-get update + $ apt-get install apache2 libapache2-mod-wsgi + ``` + +### Copy and modify the VHOST + +After `mod_wsgi` is installed, copy the `evennia/web/utils/evennia_wsgi_apache.conf` file to your +apache2 vhosts/sites folder. On Debian/Ubuntu, this is `/etc/apache2/sites-enabled/`. Make your +modifications **after** copying the file there. + +Read the comments and change the paths to point to the appropriate locations within your setup. + +### Restart/Reload Apache + +You'll then want to reload or restart apache2 after changing the configurations. + +- *Fedora/RHEL/Ubuntu* + ``` + $ systemctl restart httpd + ``` +- *Ubuntu/Debian* + ``` + $ systemctl restart apache2 + ``` + +With any luck, you'll be able to point your browser at your domain or subdomain that you set up in +your vhost and see the nifty default Evennia webpage. If not, read the hopefully informative error +message and work from there. Questions may be directed to our [Evennia Community +site](https://evennia.com). + +### A note on code reloading + +If your `mod_wsgi` is set up to run on daemon mode (as will be the case by default on Debian and +Ubuntu), you may tell `mod_wsgi` to reload by using the `touch` command on +`evennia/game/web/utils/apache_wsgi.conf`. When `mod_wsgi` sees that the file modification time has +changed, it will force a code reload. Any modifications to the code will not be propagated to the +live instance of your site until reloaded. + +If you are not running in daemon mode or want to force the issue, simply restart or reload apache2 +to apply your changes. + +### Further notes and hints: + +If you get strange (and usually uninformative) `Permission denied` errors from Apache, make sure +that your `evennia` directory is located in a place the webserver may actually access. For example, +some Linux distributions may default to very restrictive access permissions on a user's `/home` +directory. + +One user commented that they had to add the following to their Apache config to get things to work. +Not confirmed, but worth trying if there are trouble. + + /evennia/game/web"> + Options +ExecCGI + Allow from all + \ No newline at end of file diff --git a/docs/source/Setup/HAProxy-Config.md b/docs/source/Setup/Config-HAProxy.md similarity index 99% rename from docs/source/Setup/HAProxy-Config.md rename to docs/source/Setup/Config-HAProxy.md index 48c466ad8b..4f681c9132 100644 --- a/docs/source/Setup/HAProxy-Config.md +++ b/docs/source/Setup/Config-HAProxy.md @@ -1,4 +1,4 @@ -# Making Evennia, HTTPS and WSS (Secure Websockets) play nicely together +# Configuring HAProxy A modern public-facing website should these days be served via encrypted connections. So `https:` rather than `http:` for the website and diff --git a/docs/source/Setup/Installation-Git.md b/docs/source/Setup/Installation-Git.md index a253808828..b63c7f1c9d 100644 --- a/docs/source/Setup/Installation-Git.md +++ b/docs/source/Setup/Installation-Git.md @@ -56,9 +56,7 @@ environment is active. You _don't_ need to actually be in or near the `evenv` fo the environment to be active. > Remember that you need to re-activate the virtualenv like this *every time* you -> start a new terminal/console to get access to the Python packages (notably the -> important `evennia` program) you installed in the virtualenv! - +> start a new terminal/console. Otherwise the `evennia` command will not be available. ## Linux Install @@ -152,7 +150,7 @@ Next you can continue initializing your game from the regular [Installation inst ## Windows Install -> If you are running Windows10, consider using the _Windows Subsystem for Linux_ +> If you are running Windows10+, consider using the _Windows Subsystem for Linux_ > ([WSL](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux)) instead. Just set up WSL with an Ubuntu image and follow the Linux install instructions above. The Evennia server itself is a command line program. In the Windows launch @@ -178,8 +176,7 @@ mkdir muddev cd muddev ``` -> Hint: If `cd` isn't working you can use `pushd` instead to force the -> directory change. +> If `cd` isn't working you can use `pushd` instead to force the directory change. Next we fetch Evennia itself: diff --git a/docs/source/Setup/Installation-Non-Interactive.md b/docs/source/Setup/Installation-Non-Interactive.md index 3a056858d3..4d8acefc60 100644 --- a/docs/source/Setup/Installation-Non-Interactive.md +++ b/docs/source/Setup/Installation-Non-Interactive.md @@ -15,5 +15,4 @@ These envvars will only be used on the _very first_ server start and then ignore ``` EVENNIA_SUPERUSER_USERNAME=myname EVENNIA_SUPERUSER_PASSWORD=mypwd evennia start - ``` \ No newline at end of file diff --git a/docs/source/Setup/Installation.md b/docs/source/Setup/Installation.md index a39f091d5a..7e32b83a0c 100644 --- a/docs/source/Setup/Installation.md +++ b/docs/source/Setup/Installation.md @@ -4,14 +4,23 @@ If you are converting an existing game from a previous Evennia version, [see here](./Installation-Upgrade.md). ``` -Installing Evennia doesn't make anything visible online. Apart from installation and updating, you can develop your game without any internet connection. +## Requirements +```{sidebar} Develop in isolation +Installing Evennia doesn't make anything visible online. Apart from installation and updating, you can develop your game without any internet connection if you want to. +``` - Evennia requires [Python](https://www.python.org/downloads/) 3.9, 3.10 or 3.11 (recommended) - Windows: In the installer, make sure you select `add python to path`. If you have multiple versions of Python installed, use `py` command instead of `python` to have Windows automatically use the latest. -- Using a light-weight [Python virtual environment](./Installation-Git.md#virtualenv) is optional, but _highly recommended_ in order to keep your Evennia installation independent from the system libraries. Using virtualenvs is common Python praxis. +- Using a light-weight [Python virtual environment](./Installation-Git.md#virtualenv) is optional, but _highly recommended_ in order to keep your Evennia installation independent from the system libraries. Using virtualenvs like this is common Python praxis. - Don't install Evennia as administrator or superuser. - If you run into trouble, see [installation troubleshooting](./Installation-Troubleshooting.md). +## Install with `pip` + +The fastest way to install Evennia is to use the `pip` installer that comes with Python. +You can also [clone Evennia from github](./Installation-Git.md) or use [docker](./Installation-Docker.md). Some users have also experimented with [installing Evennia on Android](./Installation-Android.md). + + Evennia is managed from the terminal (console/Command Prompt on Windows). Once you have Python, you install Evennia with pip install evennia @@ -25,24 +34,26 @@ To update Evennia later, do pip install --upgrade evennia -> Windows users only: You now need to run `python -m evennia` once. This should permanently make the `evennia` command available in your environment. +```{note} **Windows users only -** +You now need to run `python -m evennia` once. This should permanently make the `evennia` command available in your environment. +``` Once installed, make sure the `evennia` command works. Use `evennia -h` for usage help. If you are using a virtualenv, make sure it's active whenever you need to use the `evennia` command later. -> You can also [clone Evennia from github](./Installation-Git.md) or use [docker](./Installation-Docker.md). Some users have also experimented with [installing Evennia on Android](./Installation-Android.md). - ## Initialize a new game We will create a new "game dir" for you do create your game in. Here (and in the rest of the Evennia documentation) we refer to this game dir as `mygame`, but you should of course name your game whatever you like. +```{sidebar} Game-dir vs game-name +The game-dir you create doesn't have to match the name of your game. You can set the name of your game later by editing `mygame/server/conf/settings.py`. +``` + evennia --init mygame This will create a new folder `mygame` (or whatever you chose) in your current location. This contains empty templates and all the default settings needed to start the server. -> The game dir doesn't need to have the exact same name as your game. You can set the name of your game later by editing `mygame/server/conf/settings.py`. - ## Start the new game cd mygame diff --git a/docs/source/Setup/Online-Setup.md b/docs/source/Setup/Online-Setup.md index 276a53c98e..2c4889e01c 100644 --- a/docs/source/Setup/Online-Setup.md +++ b/docs/source/Setup/Online-Setup.md @@ -1,28 +1,22 @@ # Online Setup -Evennia development can be made without any Internet connection beyond fetching updates. At some -point however, you are likely to want to make your game visible online, either as part opening it to -the public or to allow other developers or beta testers access to it. +Evennia development can be made without any Internet connection beyond fetching updates. At some point however, you are likely to want to make your game visible online, either as part opening it to the public or to allow other developers or beta testers access to it. -## Connecting to Evennia across the Internet +## Connecting to Evennia over the Internet -Accessing your Evennia server from the outside is not hard on its own. Any issues are usually due to the various security measures your computer, network or hosting service has. These will generally (and correctly) block outside access to servers on your machine unless you tell them otherwise. +Accessing your Evennia server from the outside is not hard on its own. Any issues are usually due to the various security measures your computer, network or hosting service has. These will generally (and correctly) block outside access to servers on your machine unless you tell them otherwise. We will start by showing how to host your server on your own local computer. Even if you plan to host your "real" game on a remote host later, setting it up locally is useful practice. We cover remote hosting later in this document. -Out of the box, Evennia uses three ports for outward communication. If your computer has a firewall, -these should be open for in/out communication (and only these, other ports used by Evennia are -internal to your computer only). +Out of the box, Evennia uses three ports for outward communication. If your computer has a firewall, these should be open for in/out communication (and only these, other ports used by Evennia are internal to your computer only). - `4000`, telnet, for traditional mud clients - `4001`, HTTP for the website) - `4002`, websocket, for the web client -Evennia will by default accept incoming connections on all interfaces (`0.0.0.0`) so in principle -anyone knowing the ports to use and has the IP address to your machine should be able to connect to -your game. +Evennia will by default accept incoming connections on all interfaces (`0.0.0.0`) so in principle anyone knowing the ports to use and has the IP address to your machine should be able to connect to your game. ```{sidebar} Closing the log view If you need to close the log-view, use `Ctrl-C`. Use just `evennia --log` on its own to @@ -36,22 +30,14 @@ start tailing the logs again. - Another common problem for not being able to connect is that you are using a hardware router (like a wifi router). The router sits 'between' your computer and the Internet. So the IP you find with Google is the *router's* IP, not that of your computer. To resolve this you need to configure your router to *forward* data it gets on its ports to the IP and ports of your computer sitting in your private network. How to do this depends on the make of your router; you usually configure it using a normal web browser. In the router interface, look for "Port forwarding" or maybe "Virtual server". If that doesn't work, try to temporarily wire your computer directly to the Internet outlet (assuming your computer has the ports for it). You'll need to check for your IP again. If that works, you know the problem is the router. ```{note} -If you need to reconfigure a router, the router's Internet-facing ports do *not* have to have to have the same numbers as your computer's (and Evennia's) ports! For example, you might want -to connect Evennia's outgoing port 4001 to an outgoing router port 80 - this is the port HTTP -requests use and web browsers automatically look for - if you do that you could go to -`http://203.0.113.0` without having to add the port at the end. This would collide with any other -web services you are running through this router though. +If you need to reconfigure a router, the router's Internet-facing ports do *not* have to have to have the same numbers as your computer's (and Evennia's) ports! For example, you might want to connect Evennia's outgoing port 4001 to an outgoing router port 80 - this is the port HTTP requests use and web browsers automatically look for - if you do that you could go to `http://203.0.113.0` without having to add the port at the end. This would collide with any other web services you are running through this router though. ``` ### Settings example -You can connect Evennia to the Internet without any changes to your settings. The default settings -are easy to use but are not necessarily the safest. You can customize your online presence in your -[settings file](./Settings.md#settings-file). To have Evennia recognize changed port settings you have -to do a full `evennia reboot` to also restart the Portal and not just the Server component. +You can connect Evennia to the Internet without any changes to your settings. The default settings are easy to use but are not necessarily the safest. You can customize your online presence in your [settings file](./Settings.md#settings-file). To have Evennia recognize changed port settings you have to do a full `evennia reboot` to also restart the Portal and not just the Server component. -Below is an example of a simple set of settings, mostly using the defaults. Evennia will require -access to five computer ports, of which three (only) should be open to the outside world. Below we +Below is an example of a simple set of settings, mostly using the defaults. Evennia will require access to five computer ports, of which three (only) should be open to the outside world. Below we continue to assume that our server address is `203.0.113.0`. ```python @@ -96,9 +82,7 @@ TELNET_PORTS = [4000] TELNET_INTERFACES = ['0.0.0.0'] ``` -The `TELNET_*` settings are the most important ones for getting a traditional base game going. Which -IP addresses you have available depends on your server hosting solution (see the next sections). -Some hosts will restrict which ports you are allowed you use so make sure to check. +The `TELNET_*` settings are the most important ones for getting a traditional base game going. Which IP addresses you have available depends on your server hosting solution (see the next sections). Some hosts will restrict which ports you are allowed you use so make sure to check. ### Web server @@ -123,6 +107,7 @@ The web server is always configured with two ports at a time. The *outgoing* por default) is the port external connections can use. If you don't want users to have to specify the port when they connect, you should set this to `80` - this however only works if you are not running any other web server on the machine. + The *internal* port (`4005` by default) is used internally by Evennia to communicate between the Server and the Portal. It should not be available to the outside world. You usually only need to change the outgoing port unless the default internal port is clashing with some other program. @@ -143,9 +128,7 @@ WEBSOCKET_CLIENT_URL = "" WEBSOCKET_CLIENT_PORT = 4002 ``` -The websocket-based web client needs to be able to call back to the server, and these settings must -be changed for it to find where to look. If it cannot find the server you will get an warning in -your browser's Console (in the dev tools of the browser), and the client will revert to the AJAX- +The websocket-based web client needs to be able to call back to the server, and these settings must be changed for it to find where to look. If it cannot find the server you will get an warning in your browser's Console (in the dev tools of the browser), and the client will revert to the AJAX- based of the client instead, which tends to be slower. ### Other ports @@ -163,9 +146,7 @@ SSH_INTERFACES = ['0.0.0.0'] AMP_PORT = 4006 ``` -The `AMP_PORT` is required to work, since this is the internal port linking Evennia's -[Server and Portal](../Components/Portal-And-Server.md) components together. The other ports are encrypted ports that may be -useful for custom protocols but are otherwise not used. +The `AMP_PORT` is required to work, since this is the internal port linking Evennia's [Server and Portal](../Components/Portal-And-Server.md) components together. The other ports are encrypted ports that may be useful for custom protocols but are otherwise not used. ### Lockdown mode @@ -177,11 +158,7 @@ again, your game will only be accessible from localhost. ### Registering with the Evennia game directory -Once your game is online you should make sure to register it with the [Evennia Game -Index](http://games.evennia.com/). Registering with the index will help people find your server, -drum up interest for your game and also shows people that Evennia is being used. You can do this -even if you are just starting development - if you don't give any telnet/web address it will appear -as _Not yet public_ and just be a teaser. If so, pick _pre-alpha_ as the development status. +Once your game is online you should make sure to register it with the [Evennia Game Index](http://games.evennia.com/). Registering with the index will help people find your server, drum up interest for your game and also shows people that Evennia is being used. You can do this even if you are just starting development - if you don't give any telnet/web address it will appear as _Not yet public_ and just be a teaser. If so, pick _pre-alpha_ as the development status. To register, stand in your game dir, run @@ -209,38 +186,25 @@ WEBSOCKET_CLIENT_URL = "wss://fqdn:4002" ### Let's Encrypt -[Let's Encrypt](https://letsencrypt.org) is a certificate authority offering free certificates to -secure a website with HTTPS. To get started issuing a certificate for your web server using Let's -Encrypt, see these links: +[Let's Encrypt](https://letsencrypt.org) is a certificate authority offering free certificates to secure a website with HTTPS. To get started issuing a certificate for your web server using Let's Encrypt, see these links: - [Let's Encrypt - Getting Started](https://letsencrypt.org/getting-started/) - - The [CertBot Client](https://certbot.eff.org/) is a program for automatically obtaining a -certificate, use it and maintain it with your website. + - The [CertBot Client](https://certbot.eff.org/) is a program for automatically obtaining a certificate, use it and maintain it with your website. -Also, on Freenode visit the #letsencrypt channel for assistance from the community. For an -additional resource, Let's Encrypt has a very active [community -forum](https://community.letsencrypt.org/). +Also, on Freenode visit the #letsencrypt channel for assistance from the community. For an additional resource, Let's Encrypt has a very active [community forum](https://community.letsencrypt.org/). -[A blog where someone sets up Let's Encrypt](https://www.digitalocean.com/community/tutorials/how- -to-secure-apache-with-let-s-encrypt-on-ubuntu-16-04) +[A blog where someone sets up Let's Encrypt](https://www.digitalocean.com/community/tutorials/how- to-secure-apache-with-let-s-encrypt-on-ubuntu-16-04) -The only process missing from all of the above documentation is how to pass verification. This is -how Let's Encrypt verifies that you have control over your domain (not necessarily ownership, it's -Domain Validation (DV)). This can be done either with configuring a certain path on your web server -or through a TXT record in your DNS. Which one you will want to do is a personal preference, but can -also be based on your hosting choice. In a controlled/cPanel environment, you will most likely have -to use DNS verification. +The only process missing from all of the above documentation is how to pass verification. This is how Let's Encrypt verifies that you have control over your domain (not necessarily ownership, it's Domain Validation (DV)). This can be done either with configuring a certain path on your web server or through a TXT record in your DNS. Which one you will want to do is a personal preference, but can also be based on your hosting choice. In a controlled/cPanel environment, you will most likely have to use DNS verification. ### Relevant SSL Proxy Setup Information -- [Apache webserver configuration](./Apache-Config.md) (optional) -- [HAProxy Config](./HAProxy-Config.md) +- [Apache webserver configuration](./Config-Apache-Proxy.md) (optional) +- [HAProxy Config](./Config-HAProxy.md) ## Hosting Evennia from your own computer -What we showed above is by far the simplest and probably cheapest option: Run Evennia on your own -home computer. Moreover, since Evennia is its own web server, you don't need to install anything -extra to have a website. +What we showed above is by far the simplest and probably cheapest option: Run Evennia on your own home computer. Moreover, since Evennia is its own web server, you don't need to install anything extra to have a website. **Advantages** - Free (except for internet costs and the electrical bill). @@ -255,18 +219,11 @@ and as mentioned, the electrical bill must be considered. - No support or safety - if your house burns down, so will your game. Also, you are yourself responsible for doing regular backups. - Potentially not as easy if you don't know how to open ports in your firewall or router. -- Home IP numbers are often dynamically allocated, so for permanent online time you need to set up a -DNS to always re-point to the right place (see below). -- You are personally responsible for any use/misuse of your internet connection-- though unlikely -(but not impossible) if running your server somehow causes issues for other customers on the -network, goes against your ISP's terms of service (many ISPs insist on upselling you to a business- -tier connection) or you are the subject of legal action by a copyright holder, you may find your -main internet connection terminated as a consequence. +- Home IP numbers are often dynamically allocated, so for permanent online time you need to set up a DNS to always re-point to the right place (see below). - You are personally responsible for any use/misuse of your internet connection-- though unlikely (but not impossible) if running your server somehow causes issues for other customers on the network, goes against your ISP's terms of service (many ISPs insist on upselling you to a business- tier connection) or you are the subject of legal action by a copyright holder, you may find your main internet connection terminated as a consequence. #### Setting up your own machine as a server -[The first section](./Online-Setup.md#connecting-from-the-outside) of this page describes how to do this -and allow users to connect to the IP address of your machine/router. +[The first section](./Online-Setup.md#connecting-to-evennia-over-the-internet) of this page describes how to do this and allow users to connect to the IP address of your machine/router. A complication with using a specific IP address like this is that your home IP might not remain the same. Many ISPs (Internet Service Providers) allocates a *dynamic* IP to you which could change at diff --git a/docs/source/Setup/Security-Practices.md b/docs/source/Setup/Security-Practices.md new file mode 100644 index 0000000000..d6d57ee29a --- /dev/null +++ b/docs/source/Setup/Security-Practices.md @@ -0,0 +1,105 @@ +# Security Hints and Practices + +Hackers these days aren't discriminating, and their backgrounds range from bored teenagers to international intelligence agencies. Their scripts and bots endlessly crawl the web, looking for vulnerable systems they can break into. Who owns the system is irrelevant-- it doesn't matter if it belongs to you or the Pentagon, the goal is to take advantage of poorly-secured systems and see what resources can be controlled or stolen from them. + +If you're considering deploying to a cloud-based host, you have a vested interest in securing your applications-- you likely have a credit card on file that your host can freely bill. Hackers pegging your CPU to mine cryptocurrency or saturating your network connection to participate in a botnet or send spam can run up your hosting bill, get your service suspended or get your address/site +blacklisted by ISPs. It can be a difficult legal or political battle to undo this damage after the +fact. + +As a developer about to expose a web application to the threat landscape of the modern internet, +here are a few tips to consider to increase the security of your Evennia install. + +## Know your logs +In case of emergency, check your logs! By default they are located in the `server/logs/` folder. +Here are some of the more important ones and why you should care: + +* `http_requests.log` will show you what HTTP requests have been made against Evennia's built-in webserver (TwistedWeb). This is a good way to see if people are innocuously browsing your site or trying to break it through code injection. +* `portal.log` will show you various networking-related information. This is a good place to check for odd or unusual types or amounts of connections to your game, or other networking-related issues-- like when users are reporting an inability to connect. +* `server.log` is the MUX administrator's best friend. Here is where you'll find information pertaining to who's trying to break into your system by guessing at passwords, who created what objects, and more. If your game fails to start or crashes and you can't tell why, this is the first place you should look for answers. Security-related events are prefixed with an `[SS]` so when there's a problem you might want to pay special attention to those. + +## Disable development/debugging options + +There are a few Evennia/Django options that are set when you first create your game to make it more obvious to you where problems arise. These options should be disabled before you push your game into production-- leaving them on can expose variables or code someone with malicious intent can easily abuse to compromise your environment. + +In `server/conf/settings.py`: + + # Disable Django's debug mode + DEBUG = False + # Disable the in-game equivalent + IN_GAME_ERRORS = False + # If you've registered a domain name, force Django to check host headers. Otherwise leave this as-is. + # Note the leading period-- it is not a typo! + ALLOWED_HOSTS = ['.example.com'] + +## Handle user-uploaded images with care + +If you decide to allow users to upload their own images to be served from your site, special care must be taken. Django will read the file headers to confirm it's an image (as opposed to a document or zip archive), but [code can be injected into an image file](https://insinuator.net/2014/05/django-image-validation-vulnerability/) *after* the headers that can be interpreted as HTML and/or give an attacker a web shell through which they can access +other filesystem resources. + +[Django has a more comprehensive overview of how to handle user-uploaded files](https://docs.djangoproject.com/en/dev/topics/security/#user-uploaded-content-security), but +in short you should take care to do one of two things: + +* Serve all user-uploaded assets from a *separate* domain or CDN (*not* a subdomain of the one you already have!). For example, you may be browsing `reddit.com` but note that all the user-submitted images are being served from the `redd.it` domain. There are both security and performance benefits to this (webservers tend to load local resources one-by-one, whereas they will request external resources in bulk). +* If you don't want to pay for a second domain, don't understand what any of this means or can't be bothered with additional infrastructure, then simply reprocess user images upon receipt using an image library. Convert them to a different format, for example. *Destroy the originals!* + +## Disable the web interface (if you only want telnet) + +The web interface allows visitors to see an informational page as well as log into a browser-based telnet client with which to access Evennia. It also provides authentication endpoints against which an attacker can attempt to validate stolen lists of credentials to see which ones might be shared by your users. Django's security is robust, but if you don't want/need these features and fully intend +to force your users to use traditional clients to access your game, you might consider disabling +either/both to minimize your attack surface. + +In `server/conf/settings.py`: + + # Disable the Javascript webclient + WEBCLIENT_ENABLED = False + # Disable the website altogether + WEBSERVER_ENABLED = False + +## Change your ssh port + +Automated attacks will often target port 22 seeing as how it's the standard port for SSH traffic. Also, many public wifi hotspots block ssh traffic over port 22 so you might not be able to access your server from these locations if you like to work remotely or don't have a home internet connection. + +If you don't intend on running a website or securing it with TLS, you can mitigate both problems by changing the port used for ssh to 443, which most/all hotspot providers assume is HTTPS traffic and allows through. + +(Ubuntu) In /etc/ssh/sshd_config, change the following variable: + + # What ports, IPs and protocols we listen for + Port 443 + +Save, close, then run the following command: + + sudo service ssh restart + +## Set up a firewall + +Ubuntu users can make use of the simple ufw utility. Anybody else can use iptables. + + # Install ufw (if not already) + sudo apt-get install ufw + +UFW's default policy is to deny everything. We must specify what we want to allow through our firewall. + + # Allow terminal connections to your game + sudo ufw allow 4000/tcp + # Allow browser connections to your website + sudo ufw allow 4001/tcp + +Use ONE of the next two commands depending on which port your ssh daemon is listening on: + + sudo ufw allow 22/tcp + sudo ufw allow 443/tcp + +Finally: + + sudo ufw enable + +Now the only ports open will be your administrative ssh port (whichever you chose), and Evennia on 4000-4001. + +## Use an external webserver / proxy + +There are some benefits to deploying a _proxy_ in front of your Evennia server; notably it means you can serve Evennia website and webclient data from an HTTPS: url (with encryption). Any proxy can be used, for example: + + -[HaProxy](./Config-HAProxy.md) + -[Apache as a proxy](./Config-Apache-Proxy.md) + - Nginx + - etc. \ No newline at end of file diff --git a/docs/source/Setup/Security.md b/docs/source/Setup/Security.md deleted file mode 100644 index 10236956d6..0000000000 --- a/docs/source/Setup/Security.md +++ /dev/null @@ -1,152 +0,0 @@ -# Security - -Hackers these days aren't discriminating, and their backgrounds range from bored teenagers to -international intelligence agencies. Their scripts and bots endlessly crawl the web, looking for -vulnerable systems they can break into. Who owns the system is irrelevant-- it doesn't matter if it -belongs to you or the Pentagon, the goal is to take advantage of poorly-secured systems and see what -resources can be controlled or stolen from them. - -If you're considering deploying to a cloud-based host, you have a vested interest in securing your -applications-- you likely have a credit card on file that your host can freely bill. Hackers pegging -your CPU to mine cryptocurrency or saturating your network connection to participate in a botnet or -send spam can run up your hosting bill, get your service suspended or get your address/site -blacklisted by ISPs. It can be a difficult legal or political battle to undo this damage after the -fact. - -As a developer about to expose a web application to the threat landscape of the modern internet, -here are a few tips to consider to increase the security of your Evennia install. - -## Know your logs -In case of emergency, check your logs! By default they are located in the `server/logs/` folder. -Here are some of the more important ones and why you should care: - -* `http_requests.log` will show you what HTTP requests have been made against Evennia's built-in -webserver (TwistedWeb). This is a good way to see if people are innocuously browsing your site or -trying to break it through code injection. -* `portal.log` will show you various networking-related information. This is a good place to check -for odd or unusual types or amounts of connections to your game, or other networking-related -issues-- like when users are reporting an inability to connect. -* `server.log` is the MUX administrator's best friend. Here is where you'll find information -pertaining to who's trying to break into your system by guessing at passwords, who created what -objects, and more. If your game fails to start or crashes and you can't tell why, this is the first -place you should look for answers. Security-related events are prefixed with an `[SS]` so when -there's a problem you might want to pay special attention to those. - -## Disable development/debugging options -There are a few Evennia/Django options that are set when you first create your game to make it more -obvious to you where problems arise. These options should be disabled before you push your game into -production-- leaving them on can expose variables or code someone with malicious intent can easily -abuse to compromise your environment. - -In `server/conf/settings.py`: - - # Disable Django's debug mode - DEBUG = False - # Disable the in-game equivalent - IN_GAME_ERRORS = False - # If you've registered a domain name, force Django to check host headers. Otherwise leave this -as-is. - # Note the leading period-- it is not a typo! - ALLOWED_HOSTS = ['.example.com'] - -## Handle user-uploaded images with care -If you decide to allow users to upload their own images to be served from your site, special care -must be taken. Django will read the file headers to confirm it's an image (as opposed to a document -or zip archive), but [code can be injected into an image -file](https://insinuator.net/2014/05/django-image-validation-vulnerability/) *after* the headers -that can be interpreted as HTML and/or give an attacker a web shell through which they can access -other filesystem resources. - -[Django has a more comprehensive overview of how to handle user-uploaded -files](https://docs.djangoproject.com/en/dev/topics/security/#user-uploaded-content-security), but -in short you should take care to do one of two things-- - -* Serve all user-uploaded assets from a *separate* domain or CDN (*not* a subdomain of the one you -already have!). For example, you may be browsing `reddit.com` but note that all the user-submitted -images are being served from the `redd.it` domain. There are both security and performance benefits -to this (webservers tend to load local resources one-by-one, whereas they will request external -resources in bulk). -* If you don't want to pay for a second domain, don't understand what any of this means or can't be -bothered with additional infrastructure, then simply reprocess user images upon receipt using an -image library. Convert them to a different format, for example. *Destroy the originals!* - -## Disable the web interface -The web interface allows visitors to see an informational page as well as log into a browser-based -telnet client with which to access Evennia. It also provides authentication endpoints against which -an attacker can attempt to validate stolen lists of credentials to see which ones might be shared by -your users. Django's security is robust, but if you don't want/need these features and fully intend -to force your users to use traditional clients to access your game, you might consider disabling -either/both to minimize your attack surface. - -In `server/conf/settings.py`: - - # Disable the Javascript webclient - WEBCLIENT_ENABLED = False - # Disable the website altogether - WEBSERVER_ENABLED = False - -## Change your ssh port -Automated attacks will often target port 22 seeing as how it's the standard port for SSH traffic. -Also, -many public wifi hotspots block ssh traffic over port 22 so you might not be able to access your -server from these locations if you like to work remotely or don't have a home internet connection. - -If you don't intend on running a website or securing it with TLS, you can mitigate both problems by -changing the port used for ssh to 443, which most/all hotspot providers assume is HTTPS traffic and -allows through. - -(Ubuntu) In /etc/ssh/sshd_config, change the following variable: - - # What ports, IPs and protocols we listen for - Port 443 - -Save, close, then run the following command: - - sudo service ssh restart - -## Set up a firewall -Ubuntu users can make use of the simple ufw utility. Anybody else can use iptables. - - # Install ufw (if not already) - sudo apt-get install ufw - -UFW's default policy is to deny everything. We must specify what we want to allow through our -firewall. - - # Allow terminal connections to your game - sudo ufw allow 4000/tcp - # Allow browser connections to your website - sudo ufw allow 4001/tcp - -Use ONE of the next two commands depending on which port your ssh daemon is listening on: - - sudo ufw allow 22/tcp - sudo ufw allow 443/tcp - -Finally: - - sudo ufw enable - -Now the only ports open will be your administrative ssh port (whichever you chose), and Evennia on -4000-4001. - -## Use an external webserver -Though not officially supported, there are some benefits to [deploying a webserver](./Apache-Config.md) -to handle/proxy traffic to your Evennia instance. - -For example, Evennia's game engine and webservice are tightly integrated. If you bring your game -down for maintenance (or if it simply crashes) your website will go down with it. In these cases a -standalone webserver can still be used to display a maintenance page or otherwise communicate to -your users the reason for the downtime, instead of disappearing off the face of the earth and -returning opaque `SERVER NOT FOUND` error messages. - -Proper webservers are also written in more efficient programming languages than Python, and while -Twisted can handle its own, putting a webserver in front of it is like hiring a bouncer to deal with -nuisances and crowds before they even get in the door. - -Many of the popular webservers also let you plug in additional modules (like -[mod_security](https://en.wikipedia.org/wiki/ModSecurity) for Apache) that can be used to detect -(and block!) malicious users or requests before they even touch your game or site. There are also -automated solutions for installing and configuring TLS (via [Certbot/Let's -Encrypt](https://en.wikipedia.org/wiki/Let%27s_Encrypt)) to secure your website against hotspot and -ISP snooping. diff --git a/docs/source/Setup/Settings.md b/docs/source/Setup/Settings.md index 1c91aa0c3f..4d549f7549 100644 --- a/docs/source/Setup/Settings.md +++ b/docs/source/Setup/Settings.md @@ -1,4 +1,4 @@ -# Game Settings and Configuration directory +# Changing Game Settings Evennia runs out of the box without any changes to its settings. But there are several important ways to customize the server and expand it with your own plugins. @@ -25,11 +25,9 @@ You should never edit `evennia/settings_default.py`. Rather you should copy&past variables you want to change into your `settings.py` and edit them there. This will overload the previously imported defaults. -> Warning: It may be tempting to copy everything from `settings_default.py` into your own settings -file. There is a reason we don't do this out of the box though: it makes it directly clear what -changes you did. Also, if you limit your copying to the things you really need you will directly be -able to take advantage of upstream changes and additions to Evennia for anything you didn't -customize. +```{warning} Don't copy everything! +It may be tempting to copy *everything* from `settings_default.py` into your own settings file just to have it all in one place. Don't do this. By copying only what you need, you can easier track what you changed. +``` In code, the settings is accessed through @@ -41,9 +39,7 @@ In code, the settings is accessed through servername = settings.SERVER_NAME ``` -Each setting appears as a property on the imported `settings` object. You can also explore all -possible options with `evennia.settings_full` (this also includes advanced Django defaults that are -not touched in default Evennia). +Each setting appears as a property on the imported `settings` object. You can also explore all possible options with `evennia.settings_full` (this also includes advanced Django defaults that are not touched in default Evennia). > When importing `settings` into your code like this, it will be *read only*. You *cannot* edit your settings from your code! The only way to change an Evennia setting is @@ -85,12 +81,5 @@ services to the Server instead. More info can be found Some other Evennia systems can be customized by plugin modules but has no explicit template in `conf/`: -- *cmdparser.py* - a custom module can be used to totally replace Evennia's default command parser. -All this does is to split the incoming string into "command name" and "the rest". It also handles -things like error messages for no-matches and multiple-matches among other things that makes this -more complex than it sounds. The default parser is *very* generic, so you are most often best served -by modifying things further down the line (on the command parse level) than here. -- *at_search.py* - this allows for replacing the way Evennia handles search results. It allows to -change how errors are echoed and how multi-matches are resolved and reported (like how the default -understands that "2-ball" should match the second "ball" object if there are two of them in the -room). \ No newline at end of file +- *cmdparser.py* - a custom module can be used to totally replace Evennia's default command parser. All this does is to split the incoming string into "command name" and "the rest". It also handles things like error messages for no-matches and multiple-matches among other things that makes this more complex than it sounds. The default parser is *very* generic, so you are most often best served by modifying things further down the line (on the command parse level) than here. +- *at_search.py* - this allows for replacing the way Evennia handles search results. It allows to change how errors are echoed and how multi-matches are resolved and reported (like how the default understands that "2-ball" should match the second "ball" object if there are two of them in the room). \ No newline at end of file diff --git a/docs/source/Setup/Setup-Overview.md b/docs/source/Setup/Setup-Overview.md index 099fb1fccb..0fc5b2a4bd 100644 --- a/docs/source/Setup/Setup-Overview.md +++ b/docs/source/Setup/Setup-Overview.md @@ -24,14 +24,11 @@ Start-Stop-Reload Settings Settings-Default -Choosing-An-SQL-Server -Evennia-Game-Index -IRC -Grapevine -RSS -How-to-connect-Evennia-to-Twitter -Client-Support-Grid - +Choosing-a-Database +Channels-to-IRC +Channels-to-Grapevine +Channels-to-RSS +Channels-to-Twitter ``` ## Going public @@ -39,9 +36,11 @@ Client-Support-Grid ```{toctree} :maxdepth: 2 +Evennia-Game-Index Online-Setup -Security -HAProxy-Config -Apache-Config +Client-Support-Grid +Security-Practices +Config-HAProxy +Config-Apache ``` \ No newline at end of file diff --git a/docs/source/_static/nature.css b/docs/source/_static/nature.css index 8d20cda367..35e200921a 100644 --- a/docs/source/_static/nature.css +++ b/docs/source/_static/nature.css @@ -83,9 +83,21 @@ blockquote { font-style: italic; color: #797979; background-color: #e1e8e2; - padding: 3px; border: 1px solid #c7cdc8; padding-left: 14px; + padding-right: 15px; + margin-left: 0; + width: 96%; + border-left-style: dotted; + border-left-width: medium; +} + +blockquote:before { + content: "!"; + float: left; + font-size: 230%; + opacity: 0.3; + padding-right: 5px; } div.sphinxsidebar {