jump to navigation

OpenSimulator’s login process and common login problems May 26, 2011

Posted by justincc in opensim, opensim-arch, opensim-tech-basics, secondlife, viewers, virtual-environments, virtual-worlds.


Today I’m going to write about how a viewer logs in to an OpenSimulator grid.  This is a considerably more complicated process than a simple website login.  If you ever need to find out why login isn’t working it really helps to know what’s going on under the hood.


For simplicity’s sake, we’ll look at the standalone case, where all the regions and grid services are running under a single OpenSim.exe process.

Step 1: As the first step for logging in, the viewer sends an XMLRPC message to the Login Service URI containing the name, password, viewer version and other details.  The -loginuri parameter on the command line that tells the viewer where the login service is (here it’s and the port number is 9000).  In viewers such as Imprudence the viewer’s grid manager can fetch this information from the grid info XML that the grid advertises at a well known URL.

Step 2: The login service uses these details to check that the password is correct.  If it is then it looks up the simulator that the user should be placed in (e.g. last or home).  In this case there’s only one region called “My Region”.  The login service will generate a random ‘circuit code’ and ask the simulator to record this code and set up an ‘agent’ in My Region.  The agent represents a user in an OpenSim region.

Step 3: Once the simulator has generated the agent, it returns a randomly generated ‘circuit code’ to the login service.  The login service will package this up together with the IP and port address of the region and return it to the viewer in a reply XMLRPC message.  The login service gets the region’s IP address and port from the ExternalHostName and InternalPort entries in the bin/config-include/Regions.ini file (config files there can also have other names as long as they end with .ini).  In this case the entry is

[My Region]
RegionUUID = dd5b77f8-bf88-45ac-aace-35bd76426c81
Location = 1000,1000
InternalPort = 9000
ExternalHostName =

The host name here is (same as the login service since we’re on a standalone) and the internal port is 9000.  But in this case it specifies the port that the client should use for UDP messages between itself and the simulator (we’ll ignore HTTP capabilities in this post).  The ExternalHostName can also be SYSTEMIP, in which case the default IP of the machine hosting the simulator is used (which would also be

Step 4: When the viewer receives the XMLRPC reply, it extracts the circuit code, simulator ip and port.  To make first contact with the simulator, it sends it a UseCircuitCode UDP message containing the circuit code.  The simulator compares this against the circuit code that the Login Service gave it for that client.  If they match then the simulator sends back and Ack packet and the two start talking to each other (i.e. the simulator gets sent terrain, object and texture information and can move around the region).  If they don’t match then the simulator logs a warning and ignores the UseCircuitCode message.


Whew, quite a process, eh?  As you can imagine, there’s a lot that can go wrong.  Let’s go through the possible problems.

Viewer has wrong loginuri

This is an easy one.  If the viewer is trying to login with the wrong uri (e.g. in the example above) or wrong port (e.g. 9001) then you’ll get something like an “Unable to connect to grid” – nothing will ever reach the Login Service.

Viewer has wrong login credentials

Another easy one.  The Login Service will reject the credentials and tell the viewer, which will display a “Could not authenticate your avatar” message.

A firewall prevents the Login Service from replying to the viewer

In this case the viewer can send some initial TCP packets to the Login Service but can’t get anything back.  As above, the viewer will present an “Unable to connect to grid” message but this time after a longer pause until it times out on the Login Service connection.

Viewer receives misconfigured external host name from Regions.ini

Now it gets more complicated.  Suppose that instead of putting in the My Region config I accidentally put instead, which is a machine that doesn’t exist on my network.

[My Region]
RegionUUID = dd5b77f8-bf88-45ac-aace-35bd76426c81
Location = 1000,1000
InternalPort = 9000
ExternalHostName =

In this case, the first part of the login process works okay and the progress bar moves along in the viewer.  But when the Login Service returns the simulator information to the viewer, it returns the ExternalHostName of instead of  The viewer will make a number of attempts to contact this non-existent simulator for the second part of the login, and so appear to hang for a while on a message such as “Waiting for region handshake…” before failing with a “We’re having trouble connecting…”

In this case, since has no machine a simple ping will reveal the mistake.  If there is a machine at that address or it’s the port number that is wrong then things are more complicated.  It’s difficult to diagnose problems here since UDP messages are connectionless, unlike TCP.  If you have a utility like netcat available on the viewer machine, you can try sending nonsense to the address and port given in Regions.ini.  For instance, above we could do

echo “foo” | nc -u 9000

and the simulator would print out a “Malformed data” message.

Viewer can’t reach region external host name

Now let’s suppose that the ExternalHostName and InternalPort are correct, but the viewer can’t reach that address for some reason (e.g. UDP messages to that port are blocked by a firewall).  You’ll see exactly the same symptoms as if the host name is misconfigured.  The diagnostics are also the same, with the addition that you need to thoroughly check your firewall and other network settings.

You can also see this if you’ve specified a public IP for ExternalHostName but you’re attempting a connection from within your LAN and your router does not support NAT loopback.  The easiest solution is to get a router that does support NAT loopback though you might also want to try the workarounds listed on that wiki page.

A firewall prevents the simulator from replying to the viewer

Unlike the firewall blocking the login service reply above, this time the first part of the login process will complete correctly and the simulator will even receive the UseCircuitCode message.  However, the Ack that it replies with (and any other UDP messages) is blocked by a firewall.  In the simulator log you will see messages such as

[LLUDPSERVER]: Ignoring a repeated UseCircuitCode from
2c3b8307-e257-4d1e-b12f-76f2b8f50ee9 at
for circuit 546230463

as the viewer resends the UseCircuitCode packet another 3 times (while it displays the “Waiting for region handshake…” message.  Eventually, the viewer gives up and displays the “We’re having trouble connecting…” message.  In this case, you need to carefully check that your firewall allows outbound UDP messages from the simulator to the viewer’s IP address.


As you can see, the login process is complicated.  Much of this complexity exists so that in grid mode simulators can be hosted on different machines to the login service.

In grid mode, all of the above information still applies, with the addition that the login service and simulators communicate over a network rather than within a single process.  This is another point of failure.  If there’s a problem here then you should see an error in the login service log and the viewer will return with a “Unable to connect to grid” message.



1. Vanish - May 26, 2011

Thanks a lot Justin, this is highly, highly interesting. Do any similar explanations exist about the hypergrid protocol? I’ve been interested in that for quite a while, but couldn’t find anything about the exchanged and cached data when hypergridding.

Anyway, again thanks a lot for some great and useful instructions.


2. justincc - May 26, 2011

Thanks very much Vanish.

You might want to read Diva’s draft Hypergrid paper at http://dl.dropbox.com/u/18483217/hypergrid-draft.pdf

It also just so happens that I intend to start doing some hypergridding soon. Shockingly, though I’m really interested in it, all I’ve had time to do up till now is read some documents and code. I’ll be looking to write some blog posts as I explore.

3. André - May 26, 2011

Great blog..!!! with this, people have “some” clue on how opensimulator works and what happens after you press “login”….

maybe also make a “error list”, a list with errors opensimulator can give and what they mean.

opensim Troubleshooting sites:
http://chapter-and-metaverse2.blogspot.com/ (some info outdated)

if you find more, please add (opensim 7.xx only) thanks


4. Fleep Tuque - May 26, 2011

Hi Justin, thanks for this terrific post!

As a side note, institutions that do 1 to 1 NATing where each machine on the network has both an internal and an external IP address will also appear to hang on “Waiting for region handshake…” before failing with a “We’re having trouble connecting…” message. In that situation, it appears no matter what information is put into the region.ini file, the UDP packets will contain the internal IP address of the region server, which of course will never work for clients connecting from outside the network.

In our case we had to move the region server(s) into the DMZ (and hence send UDP packets with an external IP address) in order for them to be accessible from off campus. Hope that saves someone else a headache! 🙂

5. Neil Canham - May 26, 2011

Great post Justin! This kind of detail is absolutely invaluable, both to let us sort our own problems out and to point other people at when they have issues.

6. Ener Hax - May 27, 2011

phew, that’s over my head but what is not over my head is being able to see that this is serious stuff made possible by you and the other developers – and for that, i am grateful – thank you Justin for explaining this! =)

7. AdelleF - May 27, 2011

Very nice article, Justin! One thing I would like to add (and has been a great diagnostic tool for me over the years) is using the ‘simstatus’ url for checking TCP connectivity over the internet to a remote simulator, such as this: http://opensim.dreamtechnologies.co.uk:9000/simstatus/

When the url is used in a web browser it will verify that the relevant port is open to the internet/LAN and that proper NAT routing is working and no firewall blocks are in place on the specified port. It also verifies the url/IP address for the simulator is correct. When used you should see ‘OK’ on the browser, anything else and there would be a problem with TCP communications.

Obviously this only works for TCP and not UDP, but is still a very easy and handy tool. It has also shown up (once to my knowledge) when an ISP has blocked port 9000, for some strange reason.

8. justincc - May 28, 2011

Thanks for the feedback folks.

@Fleep – Yeah, in reality there are many reasons why the packets from the simulator may not get to or be usable by the client. I’ve wrestled with NAT myself.

@AdelleF – Thanks a lot! I had completely forgotten about that status URL! It is handy.

Yeah, validating UDP connectivity is much trickier than TCP due to it’s statelessness.

9. Gaga - May 28, 2011

Thank you Justin. It’s great when a developer takes the time to explain technical things in every day language, and with diagrams. I hope one day you or perhaps Diva will explain Hypergrid in every day language for us too. I have looked at the Opensim files in the past and tried to visualize them as a pack of cards spread out on a table using symbols to represent processes and arrows to point out the path of activity. I confess I only have a limited understanding of the script language but I gain a deeper understanding following diagrams and flow charts.

Thank you again.

10. OpenSimulator Login, Anmelde Prozess | Grid Berlin Blog - May 29, 2011

[…] nahe gebracht zu haben, den Justin in seinem Blog so gut beschrieben hat. Wie immer kann er unter OpenSimulator’s login process and common login problems nochmal genau nachgelesen […]

11. Alien Creeps TD Hack - September 8, 2014

Hello There. I found your blog using msn. This is an extremely well written article.

I’ll make sure to bookmark it and come back to read more of your useful info.

Thanks for the post. I will certainly comeback.

12. cervical collar pediatric dentist - June 27, 2015

cervical collar pediatric dentist

OpenSimulator’s login process and common login problems | justincc’s opensim blog

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: