# +++++++++++++++++++++++ License and Conditions +++++++++++++++++++++++++ # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2 of the License, or # (at your option) any later version. # # A copy of this license was supplied with SAGLU in the # file COPYING. Alternatively, a copy may be obtained from # Free Software Foundation, Inc., 59 Temple Place - Suite 330, # Boston, MA 02111-1307, USA. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ # # Copyright 2005, Centre for Advanced Internet Architectures, # Swinburne University of Technology, http://caia.swin.edu.au # # Author: Ian Leeder i_leeder@hotmail.com SAGLU - The Self-Adjusting Game Lagging Utility ----------------------------------------------- Copyright (c) Swinburne University, Australia, January 2005 www.swin.edu.au The software was written for the Centre for Advanced Internet Architectures, a department of Swinburne University, Australia. We can be found on the web at www.caia.swin.edu.au. Table of Contents -------------------- 1. Introduction 1.1 What does SAGLU do?? 1.2 What do I need? 1.3 Can I use SAGLU for other games/OS's? 2. Instructions 2.1 Unpacking and Installing 2.2 What is the install script doing? 2.3 Configuring FreeBSD 2.4 For the advanced user 3. Using SAGLU 3.1 Running the server 3.2 What ipfw rules does SAGLU create 3.3 Does SAGLU remove all these ipfw rules? 4. Contact us -------------------- 1. INTRODUCTION ==================== 1.1 What does SAGLU do -------------------- This software was written for research purposes, however it would still be very useful to any multiplayer game administrator. It is well understood (especially by gamers) that a higher delay (ping) means your reaction times (and hence game-playing ability) are limited. When playing against players with a lesser delay, that is unfair. SAGLU aims to make multiplayer game servers fair again. This is achieved through "latency balancing", or ensuring that all players have an equal ping. This has been proven to increase "fairness". 1.2 What do I need? -------------------- First and foremost (in SAGLU's current implementation), you'll need a machine running FreeBSD, a free OS available over the Internet (with little effort SAGLU could be adapted to run under Linux, see Section 4.). Check out their home page (www.freebsd.org) for more info on where to get a copy of FreeBSD from, and how to install it. 1.3 Can I use SAGLU for other games/OS's? -------------------- Yes! Thanks to SAGLU's object-oriented design, it is a simple matter to extend the functionality of SAGLU. With a little C++ knowledge, it would be a trivial matter to extend this software to run under Linux using any traffic shaping software (eg. nistnet). Or you could write in an additional game type if you know the game server commands/output format. However we don't currently have the time or resources to implement every possibility for every OS. As such, this entire readme (and install.sh script) assumes FreeBSD running ipfw and dummynet. 2. INSTRUCTIONS ==================== The install script should take care of all this for you (for help on getting the install script started, see 2.1). If the install script runs successfully, you can skip to Section 3 - Using SAGLU. Note: There is an optional step which the installation will not attempt, which involves recompiling the kernel. Adding the line "options HZ=1000" will allow a much greater time resolution, meaning dummynet will be able to apply delays with a 1ms accuracy (instead of 10ms). 2.1 Unpacking and Installing -------------------- After you have downloaded the saglu.tar.gz file, type tar -xzf saglu.tar This will extract all the files in the saglu tar file to the current working directory. Change into the new directory created. This application uses the standard makefile format, and it will have to be run as root. The first step is to type "./configure". This will install SAGLU to the default directory (/usr/bin). If you wish to specify a directory, type "./configure --prefix=" where is where you wish SAGLU to be installed. Then type "make install" and follow any directions. If everything worked, you can skip to Section 3 - Using SAGLU. 2.2 What is the install script doing? -------------------- As part of "make install", a second install script is run, "install.sh". This script ensures that ipfw and dummynet are installed, and that the correct group has permission to run ipfw. If ipfw is not loaded, the lines firewall_enable="YES" and firewall_type="/etc/ipfw.rules" are appended to /etc/rc.conf, and the file /etc/ipfw.rules is created with the contents: # Default to allow instead of deny add 65534 allow all from any to any as most times ipfw defaults to blocking all traffic, a real nuisance if this is being run remotely. If dummynet is not loaded, the line 'dummynet_load="YES"' is appended to /boot/loader.conf, and dummynet is loaded with kldload dummynet (this will also load ipfw). The script then sets the permissions for /sbin/ipfw with the line: chmod 4750 /sbin/ipfw and changes the group ownership with: chown root:$input /sbin/ipfw where $input is the user's input. 2.3 Configuring FreeBSD -------------------- The SAGLU server will require 2 modules from FreeBSD: ipfw and dummynet. ipfw is an IP FireWall configuration utility, and dummynet allows for the "piping" of matching traffic flows. These pipes can be configured to apply arbitrary delays (amongst other things). If you are unsure of whether these modules have been loaded, run: kldstat You should see something similar to this: Id Refs Address Size Name 1 6 0xc0100000 40ddc4 kernel 2 2 0xc050e000 75e0 ipfw.ko 3 1 0xc0516000 ac2c agp.ko 4 1 0xc1037000 7000 linprocfs.ko 5 1 0xc10ab000 6000 dummynet.ko 6 1 0xc10bd000 14000 linux.ko The important lines are obviously ipfw.ko and dummynet.ko. If ipfw hasn't been loaded, do this: make sure that in your /etc/rc.conf file there are (at least) these lines: firewall_enable="YES" firewall_type="/etc/ipfw.rules" The type may be something else, it's up to you. The file ipfw.rules file must contain any rules you want to add at startup (ie, the default ipfw.rules only contains "add 65534 allow all from any to any" to change to default behaviour to accept) If dummynet hasn't loaded, add this line to your /boot/loader.conf file: dummynet_load="YES" The last thing to do is set the permissions for ipfw, so that it can be executed by users other than root, but not have global permissions. chmod 4750 /sbin/ipfw chown root: /sbin/ipfw This will make ipfw executable by users in the group , and it will execute as root. 2.4 For the advanced user -------------------- There are a few points to take note of, particularly with the installation script. - It became apparent during testing that even if you have both ipfw_enable="YES" at the top of the /boot/loader.conf file, and dummynet_enable="YES" at the bottom of the /boot/loader.conf file, dummynet would not load at startup. We attributed this to a race condition. We have since discovered that it is sufficient to have the lines firewall_enable="YES" and firewall_type="/etc/ipfw.rules" in your /etc/rc.conf file. The install script will put these lines there. Also, it is unnecessary to have the line ipfw_load="YES" in /boot/loader.conf, as when FreeBSD sees firewall_enable="YES" in /etc/rc.conf, it will automatically load ipfw. - If you know anything about firewalls, feel free to configure ipfw to your tastes. The install script simply moves a file named ipfw.rules to /etc/, and in /etc/rc.conf, it adds the line firewall_type="/etc/ipfw.rules". Now everytime the system reboots, it loads a set of rules from /etc/ipfw.rules. The only rule in ipfw.rules is "add 65534 allow all from any to any", an easy way to change the default to allow, instead of deny. 3. USING SAGLU ==================== SAGLU must be run on a gateway machine between the game server and the lan/internet. This could be a seperate machine, or more likely the same machine as the game server. This way SAGLU can intercept and delay game traffic. Note: Packet flows from the localhost to the localhost will hit the ipfw rule twice (even with src and dst ports specified, see http://info.iet.unipi.it/~luigi/ip_dummynet/), resulting in double the delay being applied). That means that if someone is playing a game client on the same machine as the game server, whatever delay SAGLU deems necessary will be inadvertantly doubled (you'll have double the ping of the slowest player on the game server). We advise against running a game client on the same machine as the server. SAGLU assumes a dedicated server is running. If a game client has started the server, no traffic is created for that client and SAGLU cannot compensate for the unfairness (the client that is running the server will have a 0ms ping). 3.1 Running the server -------------------- The SAGLU server must be run with a configuration file, given as a command line options. A sample config file has been supplied in the /etc/sample.conf You must rewrite this file to contain the details of your game server. Then when starting SAGLU, you need to supply this (changed) file as a command line parameter. The command line arguments for SAGLU are as follows: /bin/saglu.sh [logfile] If no logfile is specified, a default logfile is written to /tmp/saglu.log SAGLU will then run as a background process, without requiring any input from the user. To end the server, use a regular kill pid, and it will clean up after itself. The pid is shown after starting the server (ie, [1] 3500, where 3500 is the pid), or it can be found by typing ps. Note: Since all messages are output to the logfile, you will not receive visible warning if there were errors parsing the config file. Check /var/saglu.log after starting SAGLU each time, until you are confident you have it configured correctly. 3.2 What ipfw rules does SAGLU create -------------------- The range of rule numbers that SAGLU will use are configurable in the config file. The first line must specify a starting rule number, followed by the total number of rules desired. Note: Ensure that the total number of rules required will be sufficient for the amount of players/game servers running. 3.3 Does SAGLU remove all these ipfw rules? -------------------- Short answer is yes. Hopefully, it will always remove all the rules it creates. I've attempted to catch any shutdown signals, in order to get SAGLU to clean up after itself. On FreeBSD, the signals it successfully caught and handled were: kill -2 pid kill -15 pid and kill pid (which is the same as kill -15 pid, a TERM signal) If you want to kill the SAGLU server in other ways, do so at your own risk, but it probably won't remove all rules. If the SAGLU server crashes abnormally, or for some reason does not remove all the rules, do an: ipfw l which will list all the ipfw rules (ipfw l is short of ipfw list), and then do an: ipfw del ruleno where ruleno is the rule number that you want to remove. If you are really finicky, you can remove the pipes that were created (but without the rule, won't be used). To see what pipes SAGLU has created, you can do an: ipfw pipe l Now you can delete pipes with: ipfw pipe ruleno del or ipfw pipe del ruleno but NOT ipfw del pipe ruleno 4. CONTACT US ==================== If you have any questions, email me (Ian Leeder) at i_leeder@hotmail.com.