Serving a Sim on a Mac on the OS Grid
Instructions on setting up OpenSim to run on a Mac and connecting to the OpenSim Grid (OSG)
DATE: January 23, 2011
Comments are welcome
If you read this and you have a better idea, or see an error in my information, please put a comment. I will strike through any incorrect information and add new useful data to that section. If you think I need to add a section or a URL to a section, please let me know via comments. Thank you.
Changes
Yes. I have already made some in the first 24-hours of posting this file. Strike outs mean changed/incorrect/unneeded and underlined is text I have added since the first post.
Introduction
Check http://www.osgrid.org/ for basic information about the OpenSim Grid (OSG)
NOTE: this is not about how to use a viewer to connect to the osgrid (OSG). Anyone can use a compatible viewer (such as Imprudence, Hippo, and others) to visit the OSG. This is for those who want to run their own Sim on their Mac and connect it to the OSG.
This documentation is meant to assist anyone who wishes to use a Mac to serve OpenSim. The instructions are for running OpenSim software version 7.x. Currently, the version I used to do my set up is OSgrid OpenSimulator 0.7.1.dev.9f7b37b
Caveats and disclaimers
I am new to serving a Sim in OSG. It is likely that some of this information will show the gaps in my knowledge. As I learn more, I will try to fill in those gaps and correct this post. It took a long time to research and gather the little that I DO know, so I am posting it in one location online as a starting point for someone who wants to try to serve a Sim on a Mac computer. Most Sims are being served on Windows machines or in other ways (such as virtual servers). I apologize in advance for anything posted here that turns out to be less than perfectly accurate.
Also please note: working directly in Terminal is a powerful, low-level way to communicate with your Mac. I take no responsibility for something that you might do here that could lead to performance issues or data loss. Back up your computer hard drive, keep your back-ups safe, and understand that when you work on this level, there could be risks. But what I have documented here has worked for me. I have run into no performance issues or data loss. What I have NOT done myself, I note in those sections, and give you links for more information. Those links work today but I can’t guarantee they will be working tomorrow. Just use keywords in a search engine to find an updated link if these get stale.
A tip
I would suggest that you take the time to scan this entire post before you start to download and install software. Yes, I am also very impatient, but this is good advice. J I started downloading, installing and playing with software before carefully reading about the process. I started with version 7. It did not immediately work, so I tried version 6. I did not realize that version 6 can’t connect to the grid! I also failed to realize, from various bits of info buried in config file comments and in forum pages, that the latest version of Mono would not work with SQLlite. I did not realize that I could run an earlier version of Mono, so I tried to make MySQL work using MAMP. (This was painful, because I never got it to work perfectly for me!) Then I realized I did not have to do that (yet). Consider this and then scan these instructions to make avoid wasting time and redoing your work. Needless “learning experiences” can suck.
What you need to know
If you wish to run OpenSim on a Mac, you should understand a few things before you begin. First, you will control OpenSim from a command line in the Terminal application. You will have to install:
· Mono software,
· OpenSim software,
· A viewer (or two) that will allow you to connect to the OpenSim Grid as a user, probably Imprudence and/or Hippo for Mac,
· possibly /optionally MySQL, and
· possibly/optionally MAMP (to configure MySQL more easily).
All of this software is free (except for MAMP but there is a free trial version). There is a somewhat steep learning curve to running an OpenSim server, especially if you have never used to using a command line to run software on either a Mac or on any other operating system. However, it is not hard to run OpenSim. You simply need to be patient and willing to troubleshoot potential problems along the way. Once you have it running, it can be very stable. Then you can stop tweaking and start building and having fun. Once it is running, you are mostly just typing “restart” or “save oar.” The hard part is just getting it started and clearing away obstacles to connecting on your network.
NOTE: you CANNOT connect to the grid anymore with any version of OpenSim software earlier than a version 7.x so do not download any earlier versions or follow instructions for set-up that use the 6.x versions. Version 7.x was a mandatory upgrade to get to the grid. (See: http://news.osgrid.org/ )
First, the bad news….
Before you start to download and install this software, assess your potential connection issues. You have to have certain ports open so that you can connect to the grid and so that others can get to your region(s) on the grid. And you have to have a static IP address or have a port forwarding configured so that you can set up OpenSim.
Port Forwarding versus Static TCP IP addresses
You must have a static TCP IP address (or a port forward address) for your computer to place in the Regions.ini file in your OpenSim software. If you do not have a static IP (this would be a number that looks something like “123.1.123.123”) – and many home computers use routers that hand out a dynamic IP address – you will need to set up “port forwarding” in order to make it appear that you have a static IP address. I am not experienced in how to do this, as I did not have this issue. It is crucial to have a static IP or port forwarding set up before you go forward.
How to find out if you have a static IP
Here’s one of several ways to determine your static IP address on your Mac if you do not know it. Go to System Prefs and click on Network. If you have a static IP you will see the numbers on the first tab of information. Put this number into a file as you will need to copy/paste it during set-up later. If your home router is managing your connection you probably have a dynamically assigned IP address and you will need to set up port forwarding.
Port Forwarding
There are plenty of links and resources on how to do this already available online, most of which are focused on Windows solutions. It is not a problem specific to using a Mac to serve Open Sim. Anyone on the grid can give you tech support on this as it is (mostly) the same as for a Windows set-up.
Port forwarding is a way of getting around the problem of not having a static IP address.
Here are some links to instructions about how to set up port forwarding on a Mac:
Here’s a link to a site that will assist you to set up a Dynamic DNS service.
And here is a software solution is specifically for Macs:
When I have to set this up on a mac, I will write my own step by step on how to do this.
Port and Loopback issues
These are connection issues that are not specific to the Mac or to any particular Mac, this is a connection issue that all platforms have with serving OpenSim. Your particular router, your particular Internet Service Provider (ISP) will be key to whether you can get your ports open and your router configured, if necessary, to allow you to server OpenSim software and allow others to connect to your Mac.
Here's a handy way to test to see if anyone can get to your computer on the ports you want open for OSG visitors to your regions. You ping your own machine on your IP or port forward address and watch to see what response you get in the Terminal window. Here's a link on that:
http://www.netfaqs.com/macintosh/Connect/osx/OSXPing/Index.asp
Short version: Open Terminal. Type:
ping 123.1.122.123 [insert your IP address]
OR
ping yourportforward.net [insert your portforward name after setting up port forwarding]
If you see "timeout" messages, your port is closed. If you see other information about the time it took to get through, your port is open. To test this toggle Firewall off and on and you will see this connect/timeout.
Here's a handy way to test to see if anyone can get to your computer on the ports you want open for OSG visitors to your regions. You ping your own machine on your IP or port forward address and watch to see what response you get in the Terminal window. Here's a link on that:
http://www.netfaqs.com/macintosh/Connect/osx/OSXPing/Index.asp
Short version: Open Terminal. Type:
ping 123.1.122.123 [insert your IP address]
OR
ping yourportforward.net [insert your portforward name after setting up port forwarding]
If you see "timeout" messages, your port is closed. If you see other information about the time it took to get through, your port is open. To test this toggle Firewall off and on and you will see this connect/timeout.
Here’s a quote about setting up port and loopback issues from another set up page that is for Windows users: “OpenSimulator by default will use Port 9000 on TCP and UDP; if you are behind a router you need to forward these ports to the machine that will be running the simulator instance. If you don't know how to do this … consult instructions for your router. You will also need to configure your router to enable 'NAT Loopback' - some support this by default, some don't. If yours doesn't, you may be out of luck and will need to host somewhere else.”
Hopefully this will not be a problem for you. Many others have solved this and moved on to serve a Sim. I have no idea what UPD is but I figured out how to open up the ports to get started (just for the time it took to get started). Just turn off your firewall at first to get your ports open for testing and then tighten up your Firewall using a Mac freeware program called WaterRoof which can be downloaded from these two links (and in many other places online):
As for the Nat Loopback issue, you either won’t have this issue or you will, depending upon who provides your Internet service.
Here’s a scary page full of geeky stuff about configuring NAT and Loopback issues and yadda yadda:
Shudder. Let’s move on.
Get an avatar account with the OSG
If you are not already using the OSG, you will also need to have an avatar account with the OS Grid. To set up an account, go to http://www.osgrid.org/index.php/auth/register and put in a user name and password. If you already have a Second Life avatar, I would suggest that you consider registering with your current Second Life name (I would advice choosing a different password for your own security). There are several reasons to do this.
For one, you may wish to connect to friends in both worlds and it is easier if they can find you under the same name. Secondly, if you have a lot of content you have already built in Second Life and you choose to use a program called Second Inventory to export your original content from SL and move it into your OSG inventory, you will have to have the same name for your avatar. (At this time, Second Inventory is not available on the Mac platform.)
Alternate avatar accounts are allowed with OSG, but each avatar account must have its own email address. You may want to set up one alt avatar account to use as a test account for your Sim, so that you can log two avatars to your sim, one from your local machine and one from a remote machine, to see if all if working well (or you could ask a friend to come over and test with you)
OpenSim version 7.x
Setting up OpenSim version 7.x, though it may seem complex, is actually much easier than it was with version 6.x of OpenSim. With version 7.x, a lot of information is already set up for connecting to the grid. In the previous version, you were instructed to set up your system first as a standalone grid. Then you had to change a bunch of information within the OpenSim.ini file to connect to the grid. In version 7.x, it is assumed that you will want to connect directly to the grid so it is already set up that way, saving you some time.
A caveat about inventory content
You may not legally move content purchased in SL to the OSG. Be aware that most of the residents of OSG are experienced with SL. Content you might choose to illegally import to OSG via copybot-style software will be instantly recognized as stolen as most premium hair, clothing, and other content is familiar to those you will meet. This is not a good way to begin your journey through the OSG.
Resources
If you run into technical trouble and need assistance, there are various resources available to you. There are instructions available at osgrid.org, opensimulator.org, and at other locations you can find via keyword searches. There is the forum for the OSGrid. And there is the IRC chat group, where someone may be able to assist you. Finally, you can log on to the OSG and wait in one of the Welcome centers and chat with others who are present. Usually someone will be available who is willing to help with questions to those who are trying to figure out how to set up a sim. However, few have knowledge of how to do this on a Mac. This is not really that much of a problem, as the software runs much the same on Mac, but there can be an initial hesitancy to offer advice when they are not sure about how to help. Be polite and describe whatever connection problem you are having and they may have the information you need.
Terms you may wish to familiarize yourself with:
(note: opensimulator.org is not the same as osgrid.org and not all the information you find there will be relevant to running the OpenSim software and connecting to the OSG.)
Finally, you could go in-world to Lisba or other OSG welcome centers and ask for technical support.
Get your software (OpenSim and Mono, Imprudence, and Hippo)
To run OpenSim on a Mac at its most basic, you will need the OpenSim software and Mono. At this time you can continue to use the SQLite that is bundled with Opensim but you may wish to run a full version of MySQL.
OpenSim software
Download the latest OpenSim software here: http://www.osgrid.org/index.php/downloads (as of 1/23/2011, this was version OSgrid OpenSimulator 0.7.1.dev.9f7b37b but this information may work with subsequent versions. I hope to update this page periodically when new versions are released.)
Mono software
Get Mono version 2.4.2.3, the version that will work with OpenSim 7.x and with its SQLlite. Download the older version of Mono software here: http://www.mono-project.com/OldReleases
(Here’s the “lastest” versions of Mono: http://www.go-mono.com/mono-downloads/download.html ) NOTE: you cannot use the newer version of Mono that is out (at this time of this writing that is Mono 2.4.6 and up). You must run the earlier version, Mono version 2.4.4, or the SQLite will not work. If you are able to set up MySQL then you can use the newer version of Mono. If this bug is fixed, then you might want the newer versions.
OSG Viewers
Viewers for OS Grid: many currently prefer Imprudence, in part because of its built-in Animation Override (AO) software (the current version of OpenSim has a bug with standalone AOs, causing a bizarre symptom: one’s hair appears to be attached to the middle of the screen as a HUD and often the viewer will crash.) But the Hippo viewer is lightweight, stable, and worth using while testing your server set up.
Unzip and install the viewers into your Applications folder.
Both the Imprudence viewer and Hippo viewer for all operating systems can be found on
To set up the viewer to get to the OSG: double click the viewer software. In Imprudence, click “Grid Manager” at the bottom of the screen or in Hippo, click “Grid.” In Grid Manager/Grid, select Add New Grid. Call it OpenSim. Login URL:
http://login.osgrid.org/ Click Get Grid Info. It should fill in automatically.
Installing Mono
First, unpack/unzip Mono and install it. This software will allow you to run exe files without having to run Bootcamp or other Windows emulators. Once you have installed it, there is nothing more you have to do with Mono.
Installing OpenSim
Next, unpack/unzip OpenSim. The folder/directory you need is called bin. You can move the bin folder into your home directory but I chose to place it in the main hard drive. In other words, I did not just drag and drop the bin folder loose into my user folder. I placed it into an invisible folder that is within (Correction. So soon? yep. I put it in an invisible folder called "opt" but some folks don't have that folder. You can put the bin file anywhere in the root. But you will have to adjust my Terminal commands. Where I say "cd /opt/bin" you just say "cd /bin" ) Whatever you choose, make sure you use the root directory of the main hard drive and not your user account's main folder. This allows all accounts to run the software from Terminal. Also, I recommend this because it worked for me and I can’t be certain that it would work just as well for you if you put the bin folder just anywhere on your hard drive. (Added: if you choose to put it in your user directory, I do not know Terminal well enough to tell you how to get over there and run OpenSim, so...these directions work if you put it into you Mac HD main folder, rather than your user account folder.)
Step One: I would suggest that you set your Mac preferences to show hidden files (Added: if and only if you wish to use the invisible "opt" folder to stash your bin folder. I think that the point of this is that you may have other programs that run from a bin folder in your root directory and opt is there to hold optional files, like this OpenSim bin directory.). For instructions on this see: http://www.mactricksandtips.com/2008/04/show-hidden-files.html I used the terminal commands to set my Mac to show hidden files. Various ways to do this are described in the link above but here’s the short version: From Finder, Go/Utilities. Open Terminal. At the command line, type the following:
defaults write com.apple.finder AppleShowAllFiles TRUE
killall Finder
killall Finder
This will show you all of the hidden files and folders on your operating system. If you want to reverse the command later, just go back to Terminal and, again from the command line, type those same commands but replace TRUE with FALSE.
Step Two: now you can see your hidden files. Go to your main hard drive. You will see a folder called “opt.” Open opt. Place the bin folder for OpenSim into opt.
This will allow you to run OpenSim from the command line from any of the user accounts on the Mac. When you run OpenSim, you will open terminal and your first command will always be: cd /opt/bin This will move you to the correct version of the bin directory and it will work for any user account on that Mac. You will command the OpenSim software from there.
Configuring the OpenSim Server
After you put the bin folder into the opt folder, you now will make changes to the files.
The first thing you will need to do..and please note, this is to get you up and running....is to change a file called the Gridcommon.ini file. Uncomment the line below:
CHANGE: ; Include-Storage = "config-include/storage/SQLiteLegacyStandalone.ini";
THIS: Include-Storage = "config-include/storage/SQLiteLegacyStandalone.ini";
This is just a workaround to get your Sim online without having to learn how to set up MySQL. You can use the legacy SQLite database for now and use the version of Mono noted in this blog. The SQLite will hold some local data and the grid database holds the rest. Later you will want to get MySWL up with MAMP but this will solve your initial needs.
Here are other changes that you will need to make to your gridcommon.ini file to connect to the server and yet stick with the older legacy SQLite:
WHERE YOU SEE THIS TYPES OF INFO, CHANGE ALL THESE LINE TO USE THE OSGRID:
AssetServerURI = "http://assets.osgrid.org"
InventoryServerURI = "http://inventory.osgrid.org"
GridServerURI = "http://grid.osgrid.org"
AvatarServerURI = "http://avatar.osgrid.org"
PresenceServerURI = "http://presence.osgrid.org"
UserAccountServerURI = "http://users.osgrid.org"
GridUserServerURI = "http://users.osgrid.org"
AuthenticationServerURI = "http://login.osgrid.org"
FriendsServerURI = "http://friends.osgrid.org"
Make a copy of the RegionConfig.ini.example file, name it Regions.ini or RegionsConfig,ini (does not seem to matter as long as it is in the right location) and place it into the Regions folder in bin. Then configure it in so far as you can.
The first thing you will need to do..and please note, this is to get you up and running....is to change a file called the Gridcommon.ini file. Uncomment the line below:
CHANGE: ; Include-Storage = "config-include/storage/SQLiteLegacyStandalone.ini";
THIS: Include-Storage = "config-include/storage/SQLiteLegacyStandalone.ini";
This is just a workaround to get your Sim online without having to learn how to set up MySQL. You can use the legacy SQLite database for now and use the version of Mono noted in this blog. The SQLite will hold some local data and the grid database holds the rest. Later you will want to get MySWL up with MAMP but this will solve your initial needs.
Here are other changes that you will need to make to your gridcommon.ini file to connect to the server and yet stick with the older legacy SQLite:
WHERE YOU SEE THIS TYPES OF INFO, CHANGE ALL THESE LINE TO USE THE OSGRID:
AssetServerURI = "http://assets.osgrid.org"
InventoryServerURI = "http://inventory.osgrid.org"
GridServerURI = "http://grid.osgrid.org"
AvatarServerURI = "http://avatar.osgrid.org"
PresenceServerURI = "http://presence.osgrid.org"
UserAccountServerURI = "http://users.osgrid.org"
GridUserServerURI = "http://users.osgrid.org"
AuthenticationServerURI = "http://login.osgrid.org"
FriendsServerURI = "http://friends.osgrid.org"
(Version 7 will ask you the right questions and make this file for you, but check the Regions.ini file afterwards to make sure it is correct and to make changes to it if you want to run more than one region.
Here’s the info you will fine in the example Regions.ini file. Later, after you run OpenSim, you will see a copy of this in the Regions folder.
----------------
; * This file must be renamed to RegionConfig.ini and moved to the Regions/
; * subdirectory to work!
; *
; * You can put multiple regions into one file or make one file per region
; * The section name is the region name
; *
[Default Region]
; *
; * You MUST change this! It will NOT be done for you!
; *
RegionUUID = "11111111-2222-3333-4444-555555555555"
Location = "1000,1000"
InternalAddress = "127.0.0.1"
InternalPort = 9000
AllowAlternatePorts = False
ExternalHostName = "SYSTEMIP"
; *
; * Prim data
; * This allows limiting the sizes of prims and the region prim count
; *
; NonphysicalPrimMax = 256
; PhysicalPrimMax = 10
; ClampPrimSize = False
; MaxPrims = 15000
; *
; * Multi-Tenancy. Only set if needed
; *
; ScopeID = "00000000-0000-0000-0000-000000000000"
; *
; * Product name (used in search from viewer 1.23
; *
; RegionType = "Mainland"
------------------------
SQLite versus MySQL
Some prefer the simplicity of running the lightweight SQLlite that is bundled into the OpenSim software. Some prefer to run full on MySQL and will wish to configure their OpenSim Commons.ini file to point to MySQL, as it is said to be more robust and stable. So far I have been running fine using the simple SQLite that came with OpenSim.
However, if you decide to run MySQL, you will probably want a program to help you configure and run it. I would recommend MAMP, which can be run in trial mode for two weeks before purchase. It can be downloaded here:
WARNING: You cannot use the latest version of Mono, SQLite, and the current version of OpenSim software to connect to the grid. The simplest solution at this time is just to run the earlier version of Mono, which allows you to use SQLlite and avoid the whole issue of learning MySQL at the start and having to purchase a program to interface with MySQL. That is what I chose and it is working fine for me (for now).
However, if you decide to use MySQL, here’ the links for that program and to the MAMP software I would recommend to configure and run it:
More links related to MySQL:
NOTE: if you decide to run MySQL, remember that you must make changes to the GridCommon.ini file inside of the config-include folder. You comment out the info about SQLite and you uncomment the lines about MySQL.You also have to set up a data path to your SQL database. More on this later, I am just going to post this with the basic set up using the default, SLQlite set up for now.
Set up your Regions.ini file
Choosing the grid numbers for your region
You must choose some grid coordinates where your region will exist on the OSG grid.
The OSG grid is very large. Wright Plaza, the center of the grid, has the numbers 10000,10000. Be mindful as you choose your grid location. Numbers closest to Wright Plaza are the most likely to already have a Sim on them. Also, you might experience more lag or crashes if you are close to a busy Sim. However, there is a teleport limitation that creates issues that might affect what location on the grid you chose. You cannot teleport to unlimited distances. There is a limit of 4096 grid distance for teleporting. Look for a spot on the grid that is not too busy yet but don't go into the middle of nowhere, either. You can check the osgrid.org site for pages with area that have space. Or you can pick some coordinates off the grid map where there is nothing listed but two 4-digit numbers. Either way, it's a shot in the dark for a spot on the grid.
You may find this glossary page handy. It has information about grid limitations and also defines many terms you will want to know:
You cannot have a set of numbers that is already in use. At this time, it is reasonable to pick number combinations that are not in the most crowded portions of the grid.
For example, you might choose 7095, 7095.
Check this url to see the grid in action. Click on the various locations and observe the numbers that you see. If you make note of empty locations and the numbers that are displayed, you will understand better how to choose which numbers you want on the grid. For example, to set up four regions that will make a box, you look for four regions that touch and note the two number set that is associated with each box. Then you place those numbers in your regions.ini file (see more info on this below). Zoom in on the grid in the URL below and note the numbers. For example, Wright Plaza is 10000, 10000. The grid is like a giant tick-tack-toe board.
A one-region Sim configuration
You should start out with one region and make sure that you have no other bugs in your set up before you consider any other configurations.
Here’s what the regions.ini file should look like for a one-region set up (see below). Type the name of your region into the set of brackets, like Moe is listed here (leave the brackets. For RegionUUID, the server will fill in this information when you log on to the grid successfully. Leave InternalAddress alone. Leave InternalPort alone. Leave AllowAlternatePorts alone. Insert your own static IP or your port forward info where it says 123.1.123.123. Paste in your avatar Key after MasterAvatarUUID.
To obtain your avatar Key, just log to the OSG with your viewer (Imprudence, Hippo, others). With Imprudence, you can go to your own profile, and click “Copy Key.” (not sure but I think that Hippo has that feature also) Then paste that alpha-numeric unique identifier into your Regions.ini file after the line about MasterAvatarUUID. (COMMENT: this info is still correct to get your Key, but it seems that you don't have to have it for the Regions.ini file now.)
[Moe]
RegionUUID =
Location = 6527,6528
InternalAddress = 0.0.0.0
InternalPort = 9000
AllowAlternatePorts = False
ExternalHostName = 123.1.123.123 [or YOURPORTFORWARDINFO.COM]
Other versions/options on that Regions.ini file have you putting in your master avatar’s name and password. NOTE: if you have trouble setting up your sim and need technical assistance, you may want to share your Regions-ini file with a helper via a notecard in-world. Do not forget to take out your password before you share that configuration info with others. It is just as simple to use your avatar key and not put that password there in the first place. When the set-up runs, it will ask you for your name and password, so you don’t need to put it into your Regions.ini file. (Comment: this apparently relates to earlier versions of OpenSim but some may still have this extra info in an older Regions.ini file.)
NOTE: do NOT use 127.0.0.0 where it says 0.0.0.0 or you will fail to connect to the grid.
YOU ARE READY TO RUN OPEN SIM NOW
Running OpenSim for the first time and connecting to the OSG
If you're running OpenSim for the first time then when you start it up it will ask you several questions at the console. These will set up a single region. The configuration will be placed at bin/Regions/Regions.ini which you can then go and edit later on.
Open terminal. At the command line, type:
cd /opt/bin [or if you just put bin loose in the root directory, cd /bin
mono OpenSim.exe
The software will begin to run. This is where the “fun” starts.
Here’s some instructional text from this link (http://opensimulator.org/wiki/Configuration) slightly edited. I am removing any references to versions earlier than version 7. (Note: following information found on opensimulator.org may lead to different results than using information found on osgrid.org)
--------
Many of the questions have defaults. Here are some explanations of the questions asked.
§ New region name - the name for your region. Don't leave this blank!
§ Region UUID - the unique ID of your region. In pretty much all cases you will want to accept the randomly generated default in the square brackets.
§ Region Location - this is the location of the region on the grid. (e.g. 1000,1001). OpenSim regions can be placed anywhere on a 65536 by 65536 grid. [COMMENT: put your two number grid position for your region here]
§ Internal IP address - This should always be 0.0.0.0 (0.0.0.0 means "listen for connections on any interface", basically a wildcard) if you want to access this server from the internet or another server on your internal network, this should be the IP address assigned to the OpenSim Server. You should also set up the server to Use a Static IP address, and not DHCP
§ Internal port - This is the IP port for all incoming client connections. The name is a bit misleading since it will be used externally (by a Second Life viewer, for instance) as well as internally. You can make this any port you want, but it is safe to leave at the default 9000. Each region on your server must have a unique port.
§ Allow alternate ports - This is currently experimental. Please leave it at the default of False.
§ External host name – This should be your static IP address or your port forward info.
§ Master Avatar first name – The first name of the master avatar.
§ Master Avatar last name - The last name of the master avatar.
§ Master Avatar sandbox password - The password of the master avatar.
In OpenSim 0.7 and later, OpenSim asks you questions to set up an estate and an estate manager instead of a region master avatar. The questions are similar but you will not be asked for a UUID.
Don't forget the account details you use to set up the master avatar (in 0.6.9) or the estate manager (in 0.7 and later). Only this user will initially be able to configure the in-world settings for your region.
=========
After you enter this information, you will either connect to the grid, or you will see a bunch of lines of red text and the program will cease to run. The program might crash even before you can finish entering this information. Your troubleshooting begins here. If you don’t understand the error messages in red, it’s time to use Google. Take a sample line of error code and type it into search. Chances are that this will lead you to a page on the OSG wiki or forum pages where someone else got that error. Perhaps the answers they received will help you to troubleshoot your problem and get back on track.
Here are the most likely errors:
You don’t have a static IP Address
See earlier info about setting up port forwarding.
Port 9000 is not open
Your ports aren’t open. The first solution on this one is to turn off your firewall for now and see if you can connect. You can then use freeware such as WaterRoof to tweak your ports and allow you to turn on your firewall again. It is hard to configure your individual ports on your Mac with just the standard Mac firewall settings in System Preferences.
The ports that need to be open are 8000 and 9000. You will also want to open 9001, 9002, and 9003 if you choose to run a four-region Sim.
A loopback error
Sorry, I did not have this issue so I can’t speak to it. See above section on Loopback Issues.
You can log on from a remote machine but not from the local Mac that is running the Sim
This is a loopback issue, see above.
Your router is not allowing the connection
I did not experience this issue and, again it is not specific to running from a Mac. The Loopback and Ports section of this blog (above) have some links related this.
I think that I have it all correctly configured, but I just can’t get on the grid (and I have never yet been on the grid)
Possibly, the set of grid numbers you chose for your region are already in use and the grid info is not updated on the osgrid.org site. (or you typed them wrongly...or something is displaying incorrectly on the grid map.) Choose a different set of grid numbers for your first region and try again. Sometimes that is all you need to do. Once you have those numbers, hopefully this will stay “your” location, but it is trial and error until you get a spot. Don’t give up, try several sets of numbers before you decide that something else MUST be wrong.
Darn it, I have tried EVERYTHING and it says it is running but it is not on the map:
Type "shutdown" in Terminal and then start it again. Log into OSG and check the map. .Type "restart" in Terminal and log onto to OSG and check the Map again. Restart your Mac, restart Terminal, restart OpenSim, log into OSG, and check the Map. Light a candle, go to Lisba or some other welcome center or the IRC chat group and tell them what you are experiencing. Whatever it is, someone has seen it before and eventually you will find them and they will have an answer for you.
Success:
If you are lucky and do not encounter these or other issues, you will see a flood of text run by in Terminal and it will report that it has started the region and report the “heartbeat” on that region. You will then see a terminal prompt and your region should be connected to the grid. And if you are really lucky, when you log to OSG, you will check the Map for your region and it will be there. And it won't be gray. You will teleport to it and suddenly you will be standing on your own tiny little island in OSG. Be wildly happy at this point, invite others over, and crash the Sim. No. Seriously. Back up your bin folder now because it is currently set correctly and you are golden.
Testing your region
Log into the OSG with Hippo or Imprudence and open the Map (don’t bother with the search button, your region is not likely to be listed in Search Places yet). Search the Map, instead, for your region’s name. Hopefully, it will show up there. This is not something that will “take time.’ It will either be there or it won’t. If it is not there, you are not connected to the grid, no matter what your terminal application is telling you. If you do see your region when you search for it in the Map, try to teleport to it. If all is well, you will be standing on a tiny island in the middle of the ocean. You may or may not have neighbors, depending upon where you chose to locate yourself on the grid.
Gray region in Map search, can't teleport in
This could be a sign that you are not really on the grid, even if your region name shows up. But sometimes this is a bug and you can teleport into a gray spot. Eventually the map may display your region in color. Try the restart command and then search the Map again to see if the colored JPG file will turn up on the Map search screen.
Loading an OAR file
At this point, you may wish to download some free OAR files from the Web and load one into your region via the Terminal. Here’s one location where you can find some free oar sample files:
First, place the free sample oar file into the bin folder. Next, do a save on your current oar. At the command line, type:
save oar my.oar
You can reload this oar if you choose to go back to it after loading the sample one. From the command line, type:
load oar sample.oar
Your island will suddenly transform into a new shape with assets that the builder built into that oar file. Have fun playing with sample oars.
Saving your OAR file
When you have made various changes to your terrain and to your first new region and you are about to log out of your Hippo or Imprudence viewer, don’t forget to go to Terminal and save your new oar file. Otherwise, if the software or your machine crashes, you will lose your work. Every time that I go to my regions and make changes that involve the land or my build, I go to Terminal and save the oar for the region where I was working. You never know when a power failure will shut you down and put you back to the last saved version of the oar for that region.
A four-region Sim configuration
Once you have the one region running, you may wish to set up a four-region Sim (or larger but you need to consider what your particular Mac and connection speed is capable of serving). A four-region Sim is pretty standard and most computers can manage to serve that. Some people also choose to set up the four regions as a “megaregion” which requires that the regions be called out in a special way. I did not choose to combine my four regions into a megaregion but I will put in a link to the information on how to do this. The regions.ini file will look like this for a regular (non mega) four-region Sim:
An important tip: use your first, one-region regions.ini file as your template to set up your four-region regions.ini file. You will find that, after you have successfully connected to the grid for your first region, your regions.ini file will now have a very long unique number assigned to that region.
First, duplicate your current, working, one-region Regions.ini file and rename it something like “Regions.ini.ONEREGION” so that you can save that working set up. Then use that duplicated version of the Regions.ini file to create a four-region configuration.
To create your four regions file, first take the set of information and copy it Paste it into the file three more times. You will tweak those new sets of information to create your other three regions.
Copy-paste that long identifier into each of the other three sets of numbers. Then change the LAST number/letter. You may choose any number from 1-9 and any letter from a-g. NOTE: If you choose a letter beyond h, you will NOT be able to connect to the grid.
Change the port info from 9000 to 9001, 9002, and 9003. Each region will be reached via a separate port on your machine. This translates into “turn off your firewall to test this” (lol, you will want to go back and tighten security as soon as you get this to working with the firewall off to protect your machine’s security) or tweak your ports using some freeware or shareware to open up the ports you need your OGS avatar visitors to use to teleport into your regions.
Set up the grid numbers for your other three regions. I am leaving some4-digit number in there down in the 6000 ranges to show you what a “square” four-region set of numbers might look like. To get your numbers, go to the grid on osgrid.org and choose four sets of numbers that form the shape of the region you want to make. (for example, you might not want a square. You might want a long string of islands or some other shape. Choose from open sets of numbers on the grid that are next to each others to form whatever shape you want to make on the grid. Each region will always have two numbers associated with it, as in “1234, 1234” on the grid.
Here’s what a four-region Regions.ini file would look like (Any items in brackets does NOT belong in the file, those are my comments to explain the info.) DO NOT LEAVE MY BRACKETED COMMENTS IN YOUR REGIONS.INI FILE. The file should look more like the one-region example above.
[Moe]
RegionUUID = [copy the info you will find in your Regions.ini file that was placed there when you logged on successfully with the first region. It should be a long string of alpha numeric that is a unique identifier for your first region]
Location = 6527,6528 [your choice of number combos]
InternalAddress = 0.0.0.0 [do NOT change these to 127.0.0.0 these are wildcards.]
InternalPort = 9000
AllowAlternatePorts = False
ExternalHostName = 123.1.123.123 [Put your IP here or your port forward info]
MasterAvatarUUID = [put your avatar’s Key here]
[Larry]
RegionUUID = [copy that same alpha numeric identifier here, but change the last letter/number. It can be anything from 1-9 to a-f. Pick one and use a different last letter or number for each region]
Location = 6527,6527
InternalAddress = 0.0.0.0
InternalPort = 9001
AllowAlternatePorts = False
ExternalHostName = 123.1.123.123
MasterAvatarUUID = [put your avatar’s Key here]
[Curly]
RegionUUID = [ditto, change the last letter/number. It can be anything from 1-9 to a-f.]
Location = 6528,6528
InternalAddress = 0.0.0.0
InternalPort = 9002
AllowAlternatePorts = False
ExternalHostName = 123.1.123.123
MasterAvatarUUID = [put your avatar’s Key here]
[Sue]
RegionUUID = [ditto, change the last letter/number. It can be anything from 1-9 to a-f.]
Location = 6528,6527
InternalAddress = 0.0.0.0
InternalPort = 9003
AllowAlternatePorts = False
ExternalHostName = 123.1.123.123
MasterAvatarUUID = [put your avatar’s Key here]
NOTE: I did not set up a megaregion but if you are interested in doing so, here’a link to some sample files that will help you create a megaregion:
Saving your oar files for regions
Here’s the terminal commands you need to save off separate oar files. For example, four regions named Curly, Larry, Moe, and to be politically correct, Sue.
At the Terminal command prompt:
change region Curly
(The prompt will now show the word Curly before the prompt, so you will know that you are now on that region)
save oar Curly01.oar
change region Larry
save oar Larry01.oar
change region Moe
save oar Moe01.oar
change region Sue
save oar Sue01.oar
THEN, get back to the root of your estate. Type:
change region root
Now you are back to where you want to be for general commands.
You will now have four oar files that contain the configurations for that region. You should periodically save the oar files in order to not lose your work. The oar contains the shape of the land, the land textures, everything that is currently placed on the land, and other information about the region.
Restarting your Sim
You may wish to restart your Sim to get a fresh start or to test to make sure that everything is really working. Go to terminal and, from the root location, type:
restart
This will not shut down your Sim and start from square one. It will clear out some processes. It should bring all of your regions back online in a matter of seconds.
You can also restart by region:
change region Moe
restart region Moe
Staying on the grid in your location
So you want to keep your Sim running. But you need to restart your Mac. I have read that it is best not to do the shutdown command when you need to quit Terminal. Instead, you close the terminal window and stop the process. Then, when your Mac is running again, open a Terminal window and do the usual commands (“cd /opt/bin” and then “mono opensim.exe” to restart your Sim.) I have read that if you use the shutdown command, your regions locations become available in the OSG and someone else could accidentally choose your region locations and take your spot on the grid. This is yet another reason not to try to locate your Sim too close to Wright Plaze and the middle of the grid. If you are a bit further out, you are less likely to lose your spot if you have to be offline for a while.
Protect your Sim
Back up your bin folder periodically. As soon as everything is working perfectly, make a back up of what works, in case you tweak something later and it breaks. Back up your oar files. Also note that the opensim.db file holds everything related to your regions. That file will grow over time and you want to protect that file in order to not lose your set up.
Controlling and commanding OpenSim
You will find many Terminal commands here that will be useful at some point.
HyperGrid
Beyond the OSG is the hypergrid. This is where you are able to jump from the OSG to other VR worlds. Second Life and Reaction Grid are two examples of other VR, 3D worlds. Second Life is an example of what is sometimes called a “walled garden” because Linden Lab owns all of the servers that run Sims and all content is stored within Linden Lab’s servers. The Lindens had a test period where beta testers were able to hyper jump from SL to other grids, but at this time (1/23/2011) that hypergrid connection has been disabled. Reaction Grid and OSG are a part of the hypergrid. One interesting limitation to the hypergrid is that you cannot teleport to unlimited distances on the grid. There is a limit of 4096. Therefore, there are situations where you would have to teleport to a midpoint location and then teleport to your intended destination. This limitation would be a factor in deciding what set of numbers you may wish to pick to locate your Sim on the OSG grid. Some might wish to be near in their grid number to Reaction Grid; some might wish to be closer to the center of the OSG grid.
I have not used Hypergrid yet so I cannot speak about it with any authority. Here are some links about Hypergrid:
Other links of interest to Mac and OSG users:
http://chapter-and-metaverse.blogspot.com/2008/11/installing-opensim.html
Here's another blog with a list of acronyms used for OSG:
http://newgrid.wordpress.com/tutorial-osgrid/dictionar/
Here's another blog with a list of acronyms used for OSG:
http://newgrid.wordpress.com/tutorial-osgrid/dictionar/
NOTE: do NOT use these instructions for setting up OpenSim version 7.x. There may be some tips and tricks here that will enlighten you on the process but you do not need to start out with a standalone system. Also, as noted previously you CANNOT connect to the grid anymore with any version of OpenSim software earlier than a version 7.x.
Remotely restarting the Mac that serves your Sim if it is stopped.
If you set up your Sim to run on a Mac, you may find yourself at a distance from the machine that is running OpenSim. If the Sim stops due to that Mac crashing or freezing or if Screensharing stops working, you may need to remotely restart that Mac and then connect again with Screensharing to restart Terminal and turn the Sim back on. If you set it up correctly in advance, you can restart it from Terminal at another Mac.
Here’s a link that describes various methods of remotely restarting your server Mac:
The short version is that you can use Terminal for free to do the job. Here’s the information, pretty much quoted from the above link:
To set this up in advance, turn on Remote Login (SSH) service on the remote computer (with a strong admin password), and make sure you have a way to access it (forward port 22 on routers and firewalls). In a worst-case scenario, you can use the Terminal application to force a reboot the remote machine.
You must login to an administrator account on the remote Mac. Assume here your remote Mac has an account named remoteuser at address 10.20.30.40:
LocalMac:~ localuser$ ssh -l remoteuser 10.20.30.40 - answer "yes" when asked do you wish to continue connection
- enter the password for remoteuser; the remote Mac's prompt appears
RemoteMac:~ remoteuser$ sudo reboot - you are warned not to abuse the superuser privileges
- enter the remote admin account password
- your SSH session will be disconnected and the remote Mac will reboot
LocalMac:~ localuser$ Connection to 10.20.30.40 closed - wait a minute or two, then try accessing the remote control software again
Running OpenSim as a standalone off the grid
There are instructions on the link below about how to set up OpenSim. These instructions were written for an earlier version of the software. However, if you wish to operate OpenSim in standalone mode, you could read this set of instructions and reverse engineer the settings in your bin folder to run standalone. If you want a standalone, I recommend that you make a duplicate of a fresh bin folder from your zipped files and then configure it as standalone. Do NOT follow these instructions for version 7, you do not need to make these changes to the version 7 of the software:
Comments
Post a Comment