Installing a patch server

Patching the client is a good way to keep it “up to date” with your game server. It's usually a fast and easy process ones configured.

The patching commences when the client(on startup) compares it's own Lirria.version(residing in folder: /unpack or /data) file against the patch server(residing in: /patch_service/patch_game/patch/Lirria.version). IF the patch version(of this file) has a: + value(bigger value), the client then receives the updated content to it's folder: /unpack or /data (or both depending on configuration). It then unpacks the “data” and installs it accordingly to the information given by the “patch”.

To make all this happen, a procedure is needed for creating the files, support for the operations, and even a dedicated service(via Apache) must be in place for the connecting clients.

Your server must have the following packages installed:

1. lzma
2. xdelta

The installation is quite easy, just type the following:

~/$ sudo aptitude install lzma xdelta OR (Ubuntu) ~/$ sudo apt-get install lzma xdelta

Compiling the Nel tools(from Ryzom Core) give us(among other things) two command line utilities named patch_gen and bnp_make . These are the executables we will work with.

It is also necessary to have the .bnp files(which are used to organize the game data). These files are in their turn manipulated by the “bnp_make” executable of Ryzom Core's NeL tools. This section explains in detail the management of .bnp files: Making .bnp data files.

We must first place ourselves in a directory where we can generate the patches. One of these areas will be made public by the Apache server, as a service for the web/game clients.

Create the folder /patch_service in your /home/compil/ directory and move into it:

~/$ mkdir ~/patch_service
~/$ cd ~/patch_service

The following commands will install everything needed for the patch service:

~/patch_service$ patch_gen createNewProduct patch_game/ryzom.xml

If executable(patch_gen) isn't installed globaly, do this:

cp /usr/local/bin/patch_gen /home/compil/patch_service/
 
THEN..
 
./patch_gen createNewProduct patch_game/ryzom.xml

This will set up all the essential files and folders(below):

• patch_service/patch_game/
  • bnp/
  • patch/
  • ref/
  • ryzom.xml

OBS: In this guide as an example, there will only be one file indicated hereafter, called patch_lirria.bnp

Next, create an empty file, which will be used as a index-file for the patches. Name the file after your own shard, followed by “.version”(we will use Lirria as an example here, because it is the name of the Khaganat development shard), and then save it to the patch_game directory:

cd ~/patch_service && touch patch_game/Lirria.version

Now, edit the file: patch_service/patch_game/ryzom.xml :

~/patch_service$ nano patch_game/ryzom.xml

And now, we will simply create the implementation of the file: patch_lirria.bnp , intended for copying into the client data subdirectory: /user to do tests.

Our(DEFAULT) configuration file will look like this:

ryzom.xml

<xml>
	<_Categories>
		<_Category>
			<_Name type="STRING" value="khanat_lirria"/>
			<_IsOptional type="SINT32" value="0"/>
			<_UnpackTo type="STRING" value="./user/"/>
			<_IsIncremental type="SINT32" value="1"/>
			<_Files type="STRING" value="patch_lirria.bnp"/>
		</_Category>
	</_Categories>
	<_IndexFileName type="STRING" value="ryzom.hist"/>
	<_PatchDirectory type="STRING" value="patch_game/patch/"/>
	<_BnpDirectory type="STRING" value="patch_game/bnp/"/>
	<_RefDirectory type="STRING" value="patch_game/ref/"/>
	<_NextVersionFile type="STRING" value="patch_game/Lirria.version"/>
	<_ClientIndexFileName type="STRING" value="ryzom"/>
</xml>

These indicated parameters will gradually increment the content of our .bnp . It will add the new files(and the .bnp files itself), after being downloaded by the client. The “data” will be unpacked in /user and will also overwrite old file versions. This is considered good practice on a testing bases.

Since the system is a “database kind”, we must inform(the database) that we are activating the patch server. To do this, we will use some commands in MySQL.

We will assume that your domain number is 12, otherwise change the value to your liking. First, activate the patch server(by setting the patch_version value to 1 instead of 0): OBS: “0” is default!

USE nel;
UPDATE DOMAIN SET patch_version=1 WHERE domain_id=12;

Then enter the server address in the field patch_urls:

USE nel;
UPDATE DOMAIN SET patch_urls='http://lirria.khaganat.net/patch' WHERE domain_id=12;

Now.. we are gonna create our patch, which will supply the .bnp in its original state to the client. We will reuse the same command, but with a different instruction this time:

~/patch_service$ patch_gen updateProduct patch_game/ryzom.xml

OR(if not global)..

~/patch_service$ ./patch_gen updateProduct patch_game/ryzom.xml

Now, let's continue and create a info file(at the root directory of the patch) that will serve to disseminate information about patched data. This will be a .php file.. and it will be able to receive following client informations:

• version: The patch version ;
• lang: The language of the client ;
• ca: The Shard connection
• startPage : to define

So.. let's create a simple php index file(with html content):

~/patch_service$ nano patch_game/patch/index.php

index.php

<html>
  <head>
   <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  </head>
 <body>
  <h1>New test data</h1>
  <p>An update will now be performed to your client(the /user directory to be exact).
   Please help us test the deployment of our free MMORPG server!!
 </body>
</html>

The content is now ready to be released, and it only remains to let customers know about it.

We will assume that you already have a functional Apache server, and that you just have created a new VirtualHost. If the “home” directory(of the user who manages the server) is named “compil”, it must have these parameters(if not, needed to be adapted according to your own parameters):

Our wish here is to have a simple address(with port for the patch server), which will be in the form of:

http://lirria.khaganat.net:43435
 
(Our game server being installed at): http://lirria.khaganat.net

Firstly, we must install some modules for the Apache server(if not already done in advance):

~/patch_service$ sudo a2enmod proxy
~/patch_service$ sudo a2enmod proxy_http

We then add in the VirtualHost file(listening to port 80) the following line:

ProxyPass       /patch/ http://lirria.khaganat.net:43435/

We then define our dedicated virtual host as follows:

<VirtualHost *:43435>
ServerName lirria.khaganat.net
DocumentRoot /home/compil/patch_service/patch_game/patch/
 
  <Directory "/home/compil/patch_service/patch_game/patch">
     Options -Indexes 
     AllowOverride All
     Require all granted
  </Directory>   
 
</VirtualHost>

OBS: Option -Indexes Blocks the display of default directories for security reasons.

Now open the port 43435 in Apache:

~/sudo nano /etc/apache2/ports.conf

Add the following line:

Listen 43435

Once all this have been completed, we restart the Apache service by typing:

sudo service apache2 restart

And now we need to set the right rights(right? all righty then..). .-)

cd && sudo chown -R compil:www-data patch_service | chmod g+w -R patch_service

We must then notify the customers that the patch number “1” is ready to be distributed. This will be done by using the file Lirria.version located in the directory /patch, served by Apache:

cd ~/patch_service && nano patch_game/patch/Lirria.version

OBS!! It is enough to indicate the values in order(1 - space - 1 - return carriage):

1 1

This will be enough to say that the patch number 1 is ready for patching. In the future, this syntax will change to something even easier, like: “2 to serve the patch 2”.. and so on.

The function of the second digit is to announce itself to the .php page as version , so it simply changes the version number.

For the client to be able to access the patches, there are two solutions.

The better option is to tell the client through it's “client_default.cfg”. Therefore, we will have a look at these lines:

PatchWanted          = 1;
PatchUrl = "http://lirria.khaganat.net:43435";
RingReleaseNotePath = "http://lirria.khaganat.net/patch/index.php";

The last line(in this config file) returns to the file that we created for the: Release Notes.

For the “FV client” to work, it must be compiled with the option: WITH_RYZOM_PATCH.. to be able to access the patch server. IF without any other option indicated, it will automatically connect to the patch server indicated by the server(noted above in the MySQL database).

The client will look for release notes at the following hardcoded addresses:

RingReleaseNotePath = "http://" + WebIgMainDomain + "/releasenotes_ring/index.php";
ReleaseNotePath = "http://" + WebIgMainDomain + "/releasenotes/index.php";

It will therefore be necessary to ensure that the address WebIgMainDomain is correctly entered in the client_default.cfg

IF the FV client has also received the option WITH_RYZOM_CUSTOM_PATCH_SERVER, It will behave like the DEV client… and must therefore be given the necessary lines in its client_default.cfg:

PatchWanted          = 1;
PatchUrl = "http://lirria.khaganat.net:43435";
RingReleaseNotePath = "http://lirria.khaganat.net/patch/index.php";

With this kind of configuration, it is important to make sure that the directory unpack is empty of any file .version or.idx(under the first start) for this first patch to work. Afterwards, the system will keep track of the patches received in this directory, so be sure to leave these files untouched(under otherwise penalty of having to repatch your client of(now) value: 0). With our example, the new elements will automatically decompress in your userdirectory when the client restarts after the download(patching).

Now, all you have to do is to launch your game client and see it patching!!

If you're working from repositories(like us) for server and client updates, you can see this “how to” for being able to quickly create patches when making new data available: Game Data Updates