Github Discord Change this page

Requirements

Linux Guide

Please note: this guide has been written with the objective of setting up a Linux server running a generic kernel/OS, like Ubuntu/Debian.

This guide file has been written with strict use of the console in mind so it suites both Linux desktop and server users. Linux was made to run command line, so there isn’t an easier, quicker way to do things than the way we are about to do them.

Initial Setup

First, having presumably installed a fresh copy of Linux, we need to update our server so that we can compile AscEmu. This will require several different packages.
For the following commands, log in as the Linux root administrator.

sudo apt-get update && sudo apt-get dist-upgrade
sudo apt-get install g++ git-core git cmake build-essential zlib1g-dev libssl-dev libpcre3-dev libbz2-dev unzip screen

Alternatively if you wish to use Clang instead of gcc compiler.

sudo apt-get install clang

AscEmu supports Clang 16 and higher. By default Debian 12.8 installs Clang 14 so on Debian you must install clang-16 or higher package.

MySQL Setup

You have two options here.

1. Installing MySQL Server

MySQL server packages are not available in default APT repositories in Debian so there are couple things to do first. On other distros skip Debian only commands.

Debian only Download the latest MySQL repository package. Check for the latest version at MySQL APT page.

wget https://dev.mysql.com/get/mysql-apt-config_0.8.33-1_all.deb -O /tmp/mysql-apt-config.deb

Debian only Install the release package and update APT.

sudo DEBIAN_FRONTEND=noninteractive dpkg -i /tmp/mysql-apt-config.deb
sudo apt-get update

First we need to install MySQL into Linux as well as make sure that we have the correct libraries to properly operate it.

sudo apt-get install mysql-server mysql-client libmysqlclient-dev

2. Installing MariaDB Server

First we need to install MariaDB into Linux as well as make sure that we have the correct libraries to properly operate it.

sudo apt-get install mariadb-server mariadb-client libmariadb-dev

Setup MySQL or MariaDB environment

It’s best to not run AscEmu with your MySQL / MariaDB root account so let’s create a new MySQL user which will only have access to your AscEmu MySQL databases.

First, login to MySQL terminal with your MySQL / MariaDB root account.
By default MySQL 8.0 and later / MariaDB 10.4 and later use auth_socket which is a passwordless authentication method for root account.

sudo mysql

Next you will create the MySQL user. Please change the respective usernames and passwords to your own unique variants!

CREATE USER 'your_username'@'%' IDENTIFIED BY 'your_password'
WITH MAX_QUERIES_PER_HOUR 0 MAX_CONNECTIONS_PER_HOUR 0 MAX_UPDATES_PER_HOUR 0 MAX_USER_CONNECTIONS 0;

Let’s create the databases. Again replace your_username with the username you used in the previous step.

CREATE DATABASE `ascemu_world`;
GRANT ALL PRIVILEGES ON ascemu_world.* TO 'your_username'@'%';
CREATE DATABASE `ascemu_char`;
GRANT ALL PRIVILEGES ON ascemu_char.* TO 'your_username'@'%';
CREATE DATABASE `ascemu_logon`;
GRANT ALL PRIVILEGES ON ascemu_logon.* TO 'your_username'@'%';
FLUSH PRIVILEGES;
quit

Optionally if you wish to have remote access to your new MySQL / MariaDB server, open up the MySQL configuration file with your favourite text editor.

MySQL Server:

sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf

MariaDB Server:

sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf

And change the bind-address to 0.0.0.0
If there is no bind-address in the file, your MySQL / MariaDB server should already accept remote connections.

bind-address = 0.0.0.0

Then save and exit the file and restart the MySQL / MariaDB service.

MySQL Server:

sudo /etc/init.d/mysql restart

MariaDB Server:

sudo /etc/init.d/mariadb restart

That’s it! Setting up MySQL / MariaDB and databases is pretty straight forward.

Security and Accounts

Once that is complete, we have the right environment in Linux to compile the server. Before we can compile though we need to address some very serious security issues. Whatever distro you are using, whether your server is private or public.

Please do NOT run your AscEmu server using your root account.

Having said that, lets move on to create a basic account in Linux from which you will run AscEmu. You can name this account anything you would like, but for the sake of standardization, we will name ours ascemu. While still in your root account type:

sudo useradd -m -s /bin/bash ascemu

Next you will create a password for the account with the following command.

sudo passwd ascemu

Once you have created the ascemu user, you will have a new directory in /home/ascemu/. This will be the working root directory for your installation and eventually, for running the server.

In the commands below, ~ is used as a shorthand for the current user’s home directory, which we assume to be /home/ascemu. If for whatever reason you cannot use ~, simply replace it with /home/ascemu.

Getting the Files

First, switch to the AscEmu account, or whichever account you have just created.

sudo su - ascemu

Next, we need to download the AscEmu source files to compile them. Let’s make sure we are in the home directory:

cd ~

I am a fan of organization, so let’s make some directories and organize this mess. We will create an installer, server, and ascemu directory so that we can keep all of our files straight. The installer directory may seem like a waste for now, but it will come into play later when we install the database.

mkdir ~/installer

mkdir ~/server

As you may have guessed, the installer directory will contain AscEmu source files, and the server directory will contain the actual compiled files (like the libraries and binaries) to run the server.
The next step is to download the source files, so we will change to our installer/ascemu_code directory and use git to get the files.

mkdir ~/installer/ascemu_code
cd ~/installer/ascemu_code

With the -b required_branch, you can select a branch (master / develop).

git clone -b master https://github.com/AscEmu/AscEmu.git ~/installer/ascemu_code

Compiling

Once we have the source files we can start compiling AscEmu. The first step is to create a configuration file that will be used to pass the variables to the make file so that AscEmu will compile properly.

mkdir ~/installer/build

cd ~/installer/build

cmake -DCMAKE_INSTALL_PREFIX=~/server -DCMAKE_BUILD_TYPE=Release -DBUILD_WITH_WARNINGS=0 -DBUILD_TOOLS=0 -DASCEMU_VERSION=WotLK ../ascemu_code

If you chose to use Clang compiler you’ll need to add two additional variables to cmake command.
Also, if you had to install i.e. clang-16 instead of default clang package, replace clang with clang-16 and clang++ with clang++-16 in the command.

cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_INSTALL_PREFIX=~/server -DCMAKE_BUILD_TYPE=Release -DBUILD_WITH_WARNINGS=0 -DBUILD_TOOLS=0 -DASCEMU_VERSION=WotLK ../ascemu_code

Here is a quick view of the variables you can include with cmake command:

-DCMAKE_INSTALL_PREFIX = the location where AscEmu binaries are installed
-DCMAKE_BUILD_TYPE = choose from Release or Debug mode
-DBUILD_WITH_WARNINGS = 0 (disabled) or 1 (enabled)
-DBUILD_TOOLS = 0 (disabled) or 1 (enabled)
-DASCEMU_VERSION = choose from Classic, TBC, WotLK, Cata or MoP
-DAE_USE_PCH = 0 (disabled) or 1 (enabled) - Precompiled headers are enabled by default

Then we now simply invoke make and make install to install to the prefix directory.

make && make install

If you have a multicore machine, then you can substitute that final command with this one, where x is equal to the number of cores + 1. For example, with 2 cores x would be 3.
If you want to use all your cores just use a large number like 32.

make -j x && make install

This will not effect your server, this will only tell “make” to compile using all of your available CPU power.

If this last step is successful then you are ready to configure your server and get on your way.

DBC and Map Files

Next you will transfer the DBC and map files over to your server.

Use Wine if you must but preferably a Windows machine to extract the DBC and map files.

mkdir ~/server/dbc

mkdir ~/server/maps

Place the DBC and map files in their respective directories above.
Extracting Vmap and Mmap files is not required but is highly recommended.

Logon Database

Next you must apply base logon database manually because there is one column you must change before running your server.

Login to MySQL. Replace your_username with the username you used in “Setup MySQL / MariaDB environment” section.

mysql -u your_username -p

Select logon database and execute SQL file.

use ascemu_logon;
source ~/server/sql/logon/logon_base.sql

Now you must set a password for logonserver. This is an unique password that prevents unauthorized worldservers to register with your logonserver.
Memorize the password because you’ll need it later.

UPDATE realms SET password="your_password" WHERE id=1;
quit

World Database

AscEmu supports only OneDB world database which is maintained by AscEmu team. OneDB, as the name suggests, has all versions (Classic - Mop) packed into a single database. github.svg Link to Github.

First, switch back to your installer folder and use git to clone the OneDB repository.

cd ~/installer
git clone https://github.com/AscEmu/OneDB.git onedb

Let’s copy the world database to server directory and unzip it.

cp onedb/world_base.zip ~/server/sql/world/
cd ~/server/sql/world
unzip world_base.zip

World database is now ready to be applied.
All future world database updates are added to AscEmu base repository so you don’t need to update your OneDB repository.

Configuration Files

All that is left to do is to create the /configs/ directory and move the configuration files there.

cd ~/server
mkdir configs
mv ~/installer/ascemu_code/configs/*.conf ~/server/configs

Now your configuration files are in the ~/server/configs folder ready to be edited, and used by the AscEmu server.

Use an editor of your choice. Make sure to read all config files at least once, so you know what configuration is where and you don’t end up with an administrator account with default password you didn’t know about ;)

cd ~/server/configs
nano logon.conf
nano world.conf

Configuring logon.conf

Enter your MySQL information you created in MySQL Setup at the the following section.

<LogonDatabase Hostname = "localhost"
Username = "ascemu"
Password = "ascemu"
Name     = "ascemu_logon"
Port     = "3306">

Configuring world.conf

Enter your MySQL information you created in MySQL Setup at the the following section.

<WorldDatabase Hostname = "localhost"
Username = "ascemu"
Password = "ascemu"
Name     = "ascemu_world"
Port     = "3306">

<CharacterDatabase Hostname = "localhost"
Username = "ascemu"
Password = "ascemu"
Name     = "ascemu_char"
Port     = "3306">

Make sure RemotePassword matches the password in realms table in logon database that you set in “Logon Database” section.

<LogonServer Address        = "127.0.0.1"
             Port           = "8093"
             Name           = "Default Logon"
             RealmCount     = "1"
             DisablePings   = "0"
             RemotePassword = "change_me_logon">

Prepare the Binaries

The very last step is to make the AscEmu binaries executable.

cd ~/server
chmod a+x logon
chmod a+x world

That’s it! You should now have a fully functioning copy of AscEmu.
When you first time run the binaries your databases are automatically populated and updated to latest version. This process is fully automated. You can read about it more here.

Applying especially world database or some large updates can take some time.

Using Screen

You may also wish to preserve the AscEmu processes once you’ve logged out of SSH. This can be done using Screen.

The syntax is relatively simple.

screen ./logon

This will run the ‘logon’ program in a new session. To leave this screen and keep it running, press “CTRL + A and then D” to detach.

Next you can start worldserver.

screen ./world

To return to the screen session later on use

screen --list

then type

screen -r ScreenIDHere

You may replace ./world with sh AE_Restarter.sh for example, to run a restart program or even use screen on startup to launch the server.

To do this, you can either use a restart script, cronjob, or if you are working with a desktop Linux environment you can simply use the built in startup application manager(Both Gnome and KDE have these).

If you wish to set up a cronjob, google around - far more documentation is provided for both cron AND Screen then the AscEmu team can provide on these programs.

Sample restart script

#! /bin/bash
while :
do
./world
sleep 150
wait $!
echo Realm went down, restarting!
done

Increase 150 to 250 or 300 to prevent bash from spamming the executable or the script may cause undesired effects if the server refuses to start or has an error.

Save the above script as AE_Restarter.sh and call it using

screen ./AE_Restarter.sh

You are now ready to move on to create an account.

Create an Account

1. Go to your world console and create an account.

createaccount <accountname> <password>

example: createaccount admin adminpassword

2. Change permission(gmlevel) in your world console:

setaccpermission <accountname> <permission>

example: setaccpermission admin az

For further information about access levels, have a look to this page GM Access Levels

Keeping AscEmu updated

Keeping your AscEmu up-to-date is pretty straightforward. You only need to pull new changes from AscEmu repository, compile and start the server.

Again, replace X in make command with a high number if you have a multicore machine.

cd ~/installer/ascemu_code
git pull
cd ~/installer/build
make -j X && make install
cd ~/server

Now you are again ready to start server. Automatic database updater will apply new SQL updates automatically.