Botman Installation Notes on Ubuntu 14.04

NOTE:  This guide is very old and out dated.  I recommend that you contact me if self-hosting a bot is what you want to do. I will replace this with a Docker container.  I don't have an ETA on that at the moment.

* This guide is being updated with ubuntu 14.04 replacing Debian and additional tools and setup instructions for services like webdav, a web based irc client called Shout and more.

I am preparing a ready-made virtual machine which will be available to download as a torrent.  There will be an install script on the VM's desktop where you can enter your server's IP, telnet port and password.  All you will need to do after that is run your new bot.


The bot runs on top of a MUD client called Mudlet which needs a desktop environment.  For best results Ubuntu 14.04 (Linux desktop edition) works very well and has all of the support programs and libraries available.  Mudlet can run on Windows and OSX but currently it can only connect to its database successfully on Linux.  Until the database issue can be solved on Windows, it is not possible to run the bot on Windows or OSX.  I have not tried an OSX install.

I recommend installing a virtual machine (Virtualbox is free) as you can easily backup or clone it, install it on other computers and host many more bots.  The bot doesn't require a lot of resources.  I have found it runs very well with 2-4 processors, 3-4 GB RAM and 40-80 GB virtual harddrive.  One VM can comfortably run 5 bots but you will want at least 80 GB HDD and 4 CPUs.

This guide will focus on setting up Ubuntu 14.04 in Virtualbox.  Virtualbox installs on Windows, Linux and OSX.

To get started you need to download Virtualbox and the 32bit or 64bit desktop version of Ubuntu 14.04.  I have found 14.04 works the best.  I have had problems with newer versions and I am favouring Ubuntu desktop over other linux distributions because of its ease of use and lack of issues during the install process.


Get Virtualbox

Get Ubuntu 14.04 (64bit torrent) or (32bit torrent)


There are guides online for creating a virtual machine and installing Ubuntu.  Make sure you give it enough resources and space.  You can adjust most of these later but you want to allow a large enough virtual harddrive that you won't immediately run out of space.

Step 1 - Setting up a 7 Days to Die Server

It's assumed you will know how to do this on your own. These notes were compiled using a Windows 7 64-bit host and a Ubuntu 14.04 64-bit VM via VirtualBox. 7dtd running on windows while the Ubuntu VM houses all other services related to the bot.

- Download and install the 7dtd Dedicated Server in Steam Tools section, or via SteamCMD.
- Download and install the 7dtd Alloc Mod files (found in "Server Fixes") from here:
- Configure 7dtd server to allow telnet using a port and password of your choice.

Step 2 - Installing Software Dependencies

In the software center, or via apt-get or synaptic, install the following applications:
- bless -- A hex editor for editing Mudlet.
- geany -- Code editor (install the Lua Plugin for Geany as well.)
- mudlet -- MUD client used to run the bot. Make sure to install version 2 as version 3 has/had a crash bug.
- ngIRCd -- An IRC Server, needed for IRC monitoring and command input of the bot. (easiest to use, pre-configured)
- XChat -- An IRC chat client to test the bot's IRC abilities. (you can use any IRC client.)
- mariadb-server -- A better MySQL database server needed for storing bot data.
- phpmyadmin -- A MySQL administration interface accessed via web browser, used for managing bot databases. (Install MariaDB first.)

- lua-filesystem

- lua-sql-mysql

- lua-zip

- lua5.1

- luajit

- gnome-nettool

- openssh-server


Get them all at once with this in terminal:
> sudo apt-get install bless geany geany-plugin-lua mudlet ngircd xchat mysql-server phpmyadmin lua-filesystem lua-sql-mysql lua-zip lua5.1 luajit gnome-nettool openssh-server

I recommend also installing xrdp and the desktop XFCE4
sudo apt-get install xrdp xfce4

Some other tools that are nice to have; mc, htop, putty, meld, znc.
sudo apt-get install mc htop putty meld znc

Step 3 - Editing Mudlet's IRC Connection

Mudlet by default connects to `` and joins the `#mudlet` channel.  The bot is coded to disallow use of the default channel to prevent abuse of their support IRC service. To use the bot's IRC features you must edit the Mudlet binary to change connection settings stored in it, or change the bot code and redirect `` using your hosts file.  The hex edit method is more reliable and customizable.
**In short your options are this:**
1. ) Use a Hex-Editor on the Mudlet binary found as `/usr/games/mudlet` and overwrite the channel and domain name defaults, `#mudlet` and ``.
2. ) Work around defaults by using the `/etc/hosts` file to redirect `` and change `bot_profile.xml` code to allow using #mudlet channel.

Following these notes, with ngircd or another IRC daemon installed, you can simply use `localhost` or `` as the address or domain name to redirect or substitute in your Mudlet edit or the hosts file.
If you opt to edit the mudlet binary, it is recommended to backup both the original binary before edits, and then make another backup of the successfully edit binary in case a future update overwrites the edited binary.  Also if you are going to edit the Mudlet binary, put Bless in overwrite mode because any inserts or deletions will break the Mudlet binary.

Step 4 - Testing Mudlet's Connections

Before you load the bot and make any configuration changes, make a quick test of the mudlet environment.
- Start Mudlet.
- Click the Help icon to test Mudlet's IRC Client is connecting to your local IRC server.
- Click the Connect icon and create a new profile to test the connection from Mudlet to your 7 days server telnet port.

If everything connected correctly you should see the 7dtd telnet output to the Mudlet window, likely asking you for the password.
You can verify the IRC client in mudlet is working by using xchat or another IRC client to watch the IRC channel (#mudlet or whichever you chose) for connection and quit lines.

Step 5 - Setting up the Bot Database

Assuming you have already installed and configured a MySQL server and PhpMyAdmin management interface, you can now create the bot databases.

The bot uses two databases which you can find in `/sql/bots.sql` and `/sql/testbot.sql`
The first database "bots" is used for storing information that many bots may use..
The second database "testbot" is the database used for individual bot data.
You will need to create a user or two users with access to these databases respectively then import/run the SQL for each.
Once done, configure the bot profile with the connection credentials. The bot depends on the databases to function correctly so editing the `bot_profile.xml` file with geany or another editor will save you time.

Step 6 - Configuring the Bot

This step is a bit of a gray area in these notes.
The one configuration required, aside from database settings in step 5, is the telnet password in the login trigger script.  Be sure to change the text sent to your server's password as set in its telnet configurations section.  This can be done while the bot is running, through mudlet, but may also save you time to do it in the bot_profile.xml file before hand.
Other configurations can be set via commands issued over IRC or in game as an admin.

Step 7 - Run and Test ALL THE THINGS!

Making sure to have your edited mudlet profile files in the mudlet-data profile directory, start mudlet and select the "newbot" (as named in the repo, otherwise named as the folder name.)  Set your telnet connection address and port and start the bot.
You should see the bot login, or attempt to.  You can verify the bot has logged in using the IRC, it will tell you.
If the bot login works you'll see it run off some initial commands to gather data about the server and any players.
From here out your bot is working.  It always needs testing, just to be sure.
In mudlet, click on the scripts icon and then click the "errors" icon to the left at the bottom of the list.
Join your 7dtd server and type `/gimme admin` (you should have already been configured as an admin in the servers config files.)
The bot will recognize you as an admin and allow you to use all the commands it has if it is working.
If anything is wrong you will see the errors in the error pane of the scripts window.


Step 8 - Add some port forwarding in Virtualbox.


Step 9 - Enjoy having a cool Bot!

Its simple really :)

Thanks to TheFae for helping write this guide.