This tutorial intends to explain how to simply run Opensimulator in virtual worlds. In this document we will use the preset OSgrid opensim version though the procedure can be used for any grid and Opensim version. OpenSimulator is an open source server used for hosting virtual worlds. It will host a virtual world and manage requests from and to remote users for accessing land and objects through a 3D viewer like Firestorm for example. This tutorial uses Windows operating system.
Note: this tutorial does not intend by any means to document every
details neither every ways to run Opensimulator but is oriented toward
basics required elements for running it. Some details and more
advanced features are omitted to keep the tutorial as simple as
possible. It is possible however to extend the software capabilities
once you are more familiar with core ones.
While the opensimulator software can be downloaded from Opensimulator main site we will use the OSgrid one since it is preset for including the grid's addresses and other settings. The file can be downloaded here.
Note:
Opensim requires .Net Runtime files to run. Depending of version and
operating system you might need to download prerequisites, like for
example the dotnet
8.x runtime if you want to use the dotnet8 binary version of
Opensim. Here for example we have the SDK 8.0 Installer for Windows 64
bit operating system:
Install if needed .Net Runtime files before continuing.
Once open zip file downloaded (ex: osgrid-opensim-version number.zip) extract it to a folder on your computer drive:
While you can always use default Windows Notepad text editor we recommend to use a more powerful tool like the free multi-purpose Notepad++ text and code editor. This software includes line numbers in editor window, syntax highlighting, advanced replacement functions and much more:
Opensim requires open ports to enable communication between server and client (user's viewer), which are:
A port is a dedicated channel used to make computers communicate. While some available ports are open by default many are not and we must open them (port forwarding). More details on ports are available here.
If we have more than one region and/or server then we need to add other ports for all.
By default Opensim uses 9000 for server port and we must add one for our region(s), which can be any available port number we want (like 9001). If we want to change server port then we must go into bin \OpenSim.ini file at [Network] section, uncomment (remove semicolon at line beginning) the [http_listener_port = 9000] line and specify another number instead:
Once specified in settings we also need to port forward those ports in internet router. We can generally access router through our web browser by typing one of those common addresses:
Look at you router's guide and/or ask information to your internet provider if needed. Once you see the router's page you will need to enter user name and password to access router's settings. Look for the port forwarding section. This is where we can add our desired ports, like 9000 for server and 9001 for our region. Add port and give a name, select your computer (IP), write number in port range, use both TCP and UDP protocol then apply:
(Note: picture above is just an example but most routers will have a similar user interface for port forwarding.)
It is possible to specify multiple ports into a single line by writing a range instead a single number, like 9000-9010, which will enable all ports from 9000 to 9010.
Opensim comes with many ini files used to control server's behaviors. We will focus on few ones to edit.
Required changes
...\bin\Regions\Regions.ini
[YourRegionName]
RegionUUID = 7D35886C-9954-4C2A-8203-DEBF5C9D2571
Location = 88888,999
InternalAddress = 0.0.0.0
InternalPort = YourPortNumber
AllowAlternatePorts = False
ExternalHostName = your WAN IP or domain name
You can run multiple regions on same server by adding another section in Regions.ini. You need to change region name, RegionUUID, Location and InternalPort settings.
Available locations are shown in OSGrid's web site large map or quick map:
If you want to make a VAR region then you must add region dimensions in meters after location in file, like this example:
Location = 88888,999
SizeX = 1024
SizeY = 1024
Dimension must be a 256 multiple and X and Y must be same (square
region).
...\bin\OpenSim.ini
http_listener_port at [Network] section: required Opensim port for communicating with client (viewer). By default it is set to 9000; uncomment the line in order to have:
http_listener_port = 9000
It is important to remember that each Opensim server instance and each region must have a distinct and dedicated port. In order to do that choose different port numbers and make sure you port forward those in your router.
Optional changes
Other settings can be found in Databases and Advanced features section. OSgrid's wiki page includes a tutorial on Opensim configuration here.
By default Opensim uses an included SQLite file database to store information related to server's region(s). SQLite has the advantage of being simple to install and work with. While it suits well for a simple standalone region it will be better to upgrade to a server database, which can hold more regions and delivers faster responses.
Opensim supports many databases including:
While SQLite is the default database engine we will use in this tutorial MariaDB; others could be used including MySQL where MariaDB is based on.
Unlike SQLite which comes embedded in opensim directory we need to install server database. MariaDB is free, open source and can be downloaded there: https://mariadb.org/.
Note: if you already have a region running on SQLite you should make an OAR backup in order to restore it into other database.
Once MariaDB installed we have database server running by default in background. Keep default options when installing software.
MariaDB in Windows Services:
We will now use included HeidiSQ client to create an empty Opensim database; it brings a convenient way to manage database through a visual interface instead using a command console.
The MariaDB console:
Launch HeidiSQL through the start menu:
Enter a new session in root folder as MariaDB type and name it then enter
user name and password. Default user can be "root" and type a password and
make sure to remember it.
Leave the Hostname / IP to 127.0.0.1, which is equal to 'localhost', meaning that database server running on current computer and not on a remote machine.
Once session created we can open and create a new database and name it "opensim_db1" for example.
Please take not that procedure is mostly same with other databases servers and clients (MySQL Workbench, DBeaver, etc).
Once database created we can close HeidiSQL client. MariaDB server is running by default in background and our newly created database will have its default tables built by opensim when we will start it. Before starting we must edit the [GridDommon.ini] file to make Opensim connect to MariaDB (or MySQL) database instead SQLite default file:
Open ini file with Windows Notepad or even better Notepad++ available here. Notepad++ is a text editor that supports syntax highlighting, line numbers, advanced search and many more functions.
...\bin\config-include\GridCommon.ini
Comment there - ie add ";" at beginning of line:
Uncomment:
ConnectionString = "Data Source=localhost*;Database=YourDatabaseName;User ID=YourID;Password=YourPassword;Old Guids=true;SslMode=None;"
*localhost if you run database on same comp as Opensim server; if not you need to specify server address.
More information on database setting can be found here.
Since we have defined our region(s) in Regions.ini and wrote our database settings in GridCommon.ini we are now ready to start OpenSimulator and complete the connection to the grid.
We start server by running OpenSim.exe file in the bin folder or you can make a shortcut on desktop for more convenience. You will probably be prompted by Windows firewall who will block network access unless you authorize it, which of course you must do:
(Autoriser l'accès => Allow access)
Once authorized the firewall will remember your decision for the Opensim instance in the current folder.
When asked to create a new estate just take default name by pressing Enter key:
Enter owner name after; type carefully your first and last avatar name that you have previously registered in OSGrid site ([create an account] on main page). Type first name then [Enter] then do same with last name.
Once done the server should complete loading and connecting to the grid. When initialization is completed the console should display [Logins Enabled] with cursor waiting on region line:
The server is ready and region is visible in viewer when you log to grid from any region:
You can now teleport to region and are now ready to build:
In case of error have a look at the Troubleshooting section.
Further notes on running Opensim can be found there (credits to Alexis001 Resident).
Opensim comes with various server command functions including saving and restoring region, user inventory, manipulating land, etc.
We have two files types:
Saving an OAR
change region [name of your region] -> press enter and console should confirm that region is selected
Then type:
save oar [path-to-oar] -> console will display message once OAR completed
Note: if you don't specify a path the oar will be saved by default
in the Opensim bin folder.
change region [name of your region]
load oar [path-to-oar]
Saving an IAR
save iar <first> <last> <inventory path> <password> [<archive path>]
example: save iar John Doe /* 1234abc
Restoring an IAR
load iar [-m|--merge] <user-name> <path> <password> [<filename>]
example: load iar --merge John Doe/ 1234abc user-inventory.iar
It is possible to back up and restore multiple regions in a batch procedure; see this link: http://opensimulator.org/wiki/Backing_Up_WIN.
Examples:
Put a file named "backup.txt" in the BIN directory; containing instructions like this:
change region RegionName1
save oar
C:\Opensim_Backup\RegionName1\RegionName1.oar
change region RegionName2
save oar
C:\Opensim_Backup\RegionName1\RegionName2.oar
Call the backup.txt from console using: command-script backup.txt - (assuming backup.txt is in bin folder; if not then you must specify the full path to file)
Note:create your empty backup directories in
Windows Explorer before using command-script in
console.
Procedure for restoring is similar, using a file named "restore.txt":
change region RegionName1
load oar
C:\Opensim_Backup\RegionName1\RegionName1.oar
change region RegionName2
load oar
C:\Opensim_Backup\RegionName1\RegionName2.oar
Call the restore.txt from console using:
command-script restore.txt
OpenSim includes many server commands for manipulating your Sim; a
complete list can be found online at : http://opensimulator.org/wiki/Server_Commands.
Examples :
quit
Closes simulator and remove registered region from grid.
terrain fill 21
Flatten the entire terrain to the specified height in meters above the
sea bed. 20m is sea level, so terrain fill 21 will flatten your land to
just above sea level.
terrain elevate 5
Raises the current heightmap by the specified amount.
terrain load D:/Temp/bigcanyon2.png
Loads a terrain from a specified file, using a digital elevation model
(DEM). The file size must fit selected region size where each pixel
equals to one meter. For example a regular region will take a 256 x 256
pixels file, a 3x3 VAR region 768 X 768 pixels etc:
Errors in opensim.log
Opensim has a log file named OpenSim.log located in the Bin folder, which stores every events from the console, including errors and messages before crashes. Here we have some examples:
Other
The server opens and the region is visible on map but you can't access it through your viewer while someone else is able to go. This failure may happen if you are running both server and viewer on same computer and when your router doesn't support loopback, not permitting to have server and viewer communicating on the same machine. If it is the case then installing Microsoft Loopback Adapter software can fix the problem.
You can find a complete tutorial in Osgrid wiki here and another one there.
Once done you need to configure your TCP/IPv4 internet protocol with your WAN IP address, which can be found there: ShowMyIPAddress, WhatIsMyIP, or WanIP.
Upgrading to a new Opensim version can be a bit tedious but it is recommended to do so since new functionalities and bug fixes will likely come with it. It is possible however to automate settings changes instead doing manually each time. While it is possible to replace new .ini files with previous ones you have edited it is less recommended unless you compare files before and make sure no new settings have appeared in .ini files. Another approach would be to edit new files instead replacing it. For those interested i share here a Python file that can be used for automating task there: scr_Opensim_Updater.
Replacements:
...\bin\opensim.ini
...\bin\OpenSimDefaults.ini
=> (2023-04-19 - actually not present in osgrid's version ini
file; Lightshare enabled by default)
...\bin\OpenSim.exe.config
...\bin\config-include\FlotsamCache.ini
...\bin\config-include\osslEnable.ini -> For enabling
special avatar animation like dance ball add those lines:
There are many other parameters not described here but user can have a look in all .ini files and read included notes for every settings.
-------------------------
Enjoy and have fun!
Jeff
