Tutorial02

From Osgrid Wiki
Jump to: navigation, search

Ok. We know what an IP address, a server, NAT and port forwarding is. If you missed all that, first go and read all this : http://wiki.osgrid.org/index.php/Tutorial01 as you need to understand what those terms mean and do, before you can proceed. This class is intermediate.

Now, let’s move forward and gather all the things we need to setup our simulator.

--(Note: make sure to read the full contents of this document prior you start “doing things”, it will save you time and frustrations. )-- :


 * Goals for this class : 
 * learning to prepare your local environment for setting up a simulator 
 * collecting the data to install a region
 * Installing your region on OSgrid. 


Pre-Requisites : Before you can install a simulator, you need to check and verify a few things. If you prepare well, you have the least chance on “crashing on startup”. We will inform you of the mandatory requirements, and give some tips. Lets first figure out what we need to run a region.

Useful tools (these come in handy later) :

♦Notepad++, if you don’t have it already, it is an excellent and unmissable tool for reading and editing INI / txt files. https://notepad-plus-plus.org/ If you ever opened a INI file in a random text editor or notepad, you will have found an unreadable unformatted Mess. This will sort things, make them formatted, readable and show if something is enabled or disabled.

♦7zip or any other program which can open compressed files. http://www.7-zip.org/

♦You will also need to have an account setup - Register an account at www.osgrid.org if you don't have one yet! The credentials you use will later be the username and password you will use to get into the grid & your region(s).

Be logged on as Administrator on your pc. Users with limited rights are not allowed to play with servers !

Locate your Internal IP address, public IP address, and Gateway. Write these down. Preferably, set up a static IP address for your network interface card on the machine running the simulator. Make sure you can access your router, have it's IP address and login available. If you have multiple routers, make sure you can access / control all of them. Where possible, we prefer wired connections over any wireless, as this might have limitations.

Opensimulator is a "native .NET framework application. So make sure your computer is up to date, and has all relevant versions of .NET framework (3.5 and 4.5) installed. (Your X:\windows\microsoft.NET\framework folder will show which version(s) you have installed). If you plan to run your sims on a linux distro ( which has no .NET framework), use Mono (app get-mono-complete). to be able to use the current version (0.9.x)

Also mind OpenSim will run on really crappy hardware, but very poorly. A dual core processor, and 2 GB of RAM is a minimum. Especially if you plan to also run a viewer on the same machine. More CPU cores, RAM & bandwidth is better. Much more, is much better.

The Howto

Mind that some of the above pre-requisites and how to obtain the data, are described below . Ok, for now that’s all the preparation we need. ( Yes, what about MySQL ? that we do in Advanced class. For now you get a default region on default SQLlite that comes bundled with OSGrid's default install).

Now first we need the simulator software. It’s downloadable from the OSgrid downloads page. https://www.osgrid.org/?q=node/6

There are various other versions (Opensimulator, DIVA, SOAS, etc.) but these are outside the scope of this class. This class is to teach you to connect a default region to OSgrid, on it’s default database, which is included in the installer. This download is preconfigured for this grid. So don’t download an installer for IE metropolis, or a blank version of opensimulator and try to connect it here, it will fail. HERE is where you download the latest OSG version, nowhere else. Now the OSG download is compressed, so we need to unpack it somewhere.

Don't unpack / install OSG in a very long path : X:\users\3dguru\documents&settings\games\simulators\metaverse\osgrid\2016\march\23rd\orevenlongerpaths\whyisthispathsolong\omgthisisalotoftypinginconsole_to_loadanoar\Bin> is generally inconvenient, and potentially problematic. Its more convenient to use a path like X:\OSgrid\Bin or so. (you see, the long path even runs out of bound in this wiki, now imagine a database full of UUID's with long strings of numbers and data in there too).

Ok. We have the software installed on our PC. If we would start the OpenSim.exe process, it will fire up the server, start a database, read it’s ini files for the configuration, and since there is none yet, it will ask you to provide it with data. Lets first see how we can get all the data the simulator will ask us for. As “new” person, it's hard to prepare for this. Unless you have a tutorial, you're clueless on what to do here. But since we did this before, we can show you the questions to come :

When the simulator starts without a valid region.ini, it’s going to ask you for :

  • Region name
  • UUID for the region
  • Region Location
  • Internal Port
  • Allow alternate ports
  • External hostname
  • Join estate
  • Estate name
  • Estate owner first name
  • Estate owner last name

Now if at startup we feed the opensim.exe process all correct data, it will create a working simulator. If we fail anything here, the simulator will crash at boot, or not work as expected. So let’s try to make sure to get it right at the first go. Typo’s, wrong choices, so much as putting a period where a comma should be or vice versa, will result in failure and you needing to start over from scratch. Here is how we find the answers to above questions of the simulator at first boot:

Region Name The region name needs to be unique. It functions as if it were the "DNS" address of the UUID. A name can therefore only exist 1 time on the grids map. If you enter a name that is already taken, your region will crash at boot. It is possible to use names with a sequence number or whatever. As long as it is unique your good. We can check this by visiting http://map.osgrid.org/ and finding if a name already exists. Region names can be changed as much as you like in bin/regions/Regions.ini.

Region UUID The UUID is a code, which is unique in the world. When it is generated, it uses a machines hardware hash combined with a date timestamp, which enables the random number to be unique ( no two machines can make this number at the same time ). The UUID links everything in OSgrid. It’s the connection to your “spot” in the OSG database more or less. If the UUID is changed / lost, compromised you could potentially lose all your stuff. Do not share or change it. Ever. Now to generate your own UUID which is unique, you can go here : https://www.uuidgenerator.net (version 1 UUID) or use any other tool online. This cannot be changed later ! Also, don’t make one up yourself or edit it, unless you know what you’re doing. (NB; A UUID with a z as character will crash at boot -> its hexadecimals).

Region Location(coordinates) You probably saw on the map in step 1 that you can also see if a location is occupied by a maptile or not. Go and find an open spot, preferably away from others. http://map.osgrid.org/ do NOT build your simulator against obvious “blocks” of regions. You (and them) will download each other’s regions in the viewers if you do, and this can cause lag, loads of log spam. Better be on your own. There’s plenty of space, really. If people run old code, and have configured a megaregion, and you build against it, it will crash both you and the mega, due to CombineContiguousRegions to be enabled in the ini on the mega ( and your attached ). Mind that you put a comma in-between at input. Typo’s or using occupied map spaces will crash your region at startup. A coordinate looks like this : 11016,11017

Internal IP Address This is the local IPv4 address of your PC. By default it is set to 0.0.0.0 ( which listens to the “active adapter”). Especially useful for clients on a DHCP server address. Leaving it at that is BAD PRACTICE. In some setups it’s required, but any network engineer will tell you that if you desire to run a server, you run it on a static IP address. If you don’t, and the IP changes, your clients can no longer connect ! Routers need to be reconfigured, or IP’s need to be renewed, configs need to be adjusted and checked. It’s a nuisance generator if you leave your simulator on a dynamic IP. To obtain your internal IP address you open start/run/cmd and in the resulting shell you type “ipconfig /all”. Find the IPv4 address of your active adapter in there. It is a number that starts with 192.168.x.x or 10.x.x.x or 172.16.x.x on which your PC was set in the pre-requisite steps.

Internal Port This is the port on which your region will be accessible. Regions use UDP ports. The simulator is setup by the installer, and is set to TCP 9000 by default. You can run your region on any port you like. By default the region configuration is set to UDP 9000. Whichever port you choose, you will have to open it in your router / firewall later.

Allow Alternate ports Do we want OSG to negotiate different open ports ? No we don’t. We always want traffic to be sent on specified ports, so we can monitor what’s going on, and we know where to troubleshoot if something failing. I prefer to set this to false. All my other ports happen to be closed.

External Hostname This can be a (DNS name) or an IP address. You can find your IP by going to http://www.osgrid.org/index.php/regionconnect that also happens to have a shortguide of what your reading here, or by visiting http://www.whatismyip.com . If you use a DNS name, don’t put http:// in front. Just the name.

Join estate The estate is a management tool. It groups regions on a simulator level, and you can assign special permissions to people that have estate management rights. You always want to be in an estate. Just hit enter, Yes is default.

Estate Name Pick a name for your estate. Does not have to be unique, but mind is difficult to change later, unless you’re comfortable working inside database tables. Typo’s wont crash you. They just leave you with crappy estate names.

Estate Owner First Name Your first name ( the one you used when you registered an account at OSgrid.org !) Don’t make typo’s in your name as this can give crashes, or extremely hard to track “behavior”.

Estate Owner Last Name Your last name, same as above applies. Mind that if you can’t even spell your own name right, running a server /region might be not your thing in the long run…..


Ok, that’s all the region needs to know. If we feed it correct data, that does not conflict or is incorrect we are good to go. Start opensim.exe. If you’re on windows, your firewall will notify you of a program wanting to allow public access. Click yes to allow. ( If you fail this, you will manually need to make firewall rules). Fill in the answers to the questions with the data you gathered above.

The console will spit a lot of log events. So much, it will scroll. It’s actually setting up the SQL database, writing and updating the tables, and loading modules from the files as pre-configured for use on OSgrid by Mr Banner. You do not have to worry about this process. It’s automatic. In the end, you will look at a console that says “ root>_ “.

Your region should have appeared on the map now. However, despite letting OSG into the firewall, we also need to explain your router, there is a server installed in your IP adress now, listening on port 9000. And the router needs “port forwarding” to understand that all traffic which arrives on its public Ip address on port 9000 needs to be sent to the internal IP address of the machine running your simulator.

To find out how to get in your router, you can use the start / run /cmd / “ ipconfig /all” command. The gateway address is typically the login address of your router. More than often it ends on 1, or 254.

The IP-V4 Address is your current Local IP, and the gateway address is typically the IP that leads to the login of your router. Open it in a browser, and login to it. (so if your gateway is 192.168.1.1 open browser and type http://192.168.1.1 This is the default in many routers but fill in your own ). If it doesn't give a login, try https:// instead of http://

Now a gazillion routers exist, each with a variety of firmware they can use to operate. It is simply impossible to describe all inner workings of every router / firmware, as each manufacturer uses its own. Network protocols are the same globally, but the names (terminology again) defining them may vary.

What you need to do / setup is called Port Forwarding. Mind port forwarding can also be called NAT / Firewall / Access / Public Server / Game settings or whatever. It basically means you have to tell your router, that if any traffic sent from the internet arrives on TCP or UDP port 9000 it has to send it to the internal IP address of your PC.

In some routers you need to add services to be able to open ports. In others you only need to fill in the last digits of an IP and a port. (beginning to understand why that static IP mentioned earlier was a good idea?; some routers require it. They can't open ports to the whole local network, only to specified machines.) Other devices might require a Virtual server for NAT loopback to work. It can be a puzzle if you don’t know what to set where, or have a clue of the possibilities and limitations of your router.

Your router's manual can be found here : http://www.portforward.com If you get stuck with this stuff, get someone more knowledgeable to help / ask. Do not “experiment” inside your router settings. This can potentially “break” things.

Once port forwarding is set, you should be able to teleport to your region. Congrats, and welcome to the OSgrid.

Do NOT be disappointed or thrown off when your setup fails / you can't get to your region. There are only few users that install it "unprepared" and have it working in the 1st go. Next chapter, we will talk about when things not go as described here now. And why that happens. And how we can recognize what’s failing and fix that. Either somethings misconfigured, we ran into some error ( network errors, overlapping regions, or other potential caveats) or we need to finetune things to your specific environment.

If you followed this class and can't wait, the reason your region crashed (the screen probably died / closed / locked before you could see what happened), is logged in OpenSim.log located in your BIN folder. More on that next week....

Linux requirements

You will need to have Mono installed to run OpenSim. This is often available via the package manager. If you need to build a specific version you will need to do it manually. Here is a tutorial: http://nebadon2025.com/opensim/viewtopic.php?f=7&t=44

for debian/ubuntu

   apt-get install mono-complete

for opensuse

   zypper install mono-complete


Mac OS X requirements

You'll need to have Mono to run OpenSim. This can be found at http://www.mono-project.com/download/

Download the Mono release for Mac you wish to use Run the .pkg file and accept the terms of the license. Mono will install.